# gluecron

AI-native code intelligence platform — git hosting, automated CI, and push-time gate enforcement.

## Source of truth: Gluecron (not GitHub)

This repository self-hosts on Gluecron itself. The canonical remote is
`https://gluecron.com/ccantynz/Gluecron.com.git`. GitHub is a 7-day
fallback mirror only.

**For any AI session working in this repo:**

- Use the Gluecron MCP server. It is declared in `.mcp.json` at the
  repo root (project scope — this is the file Claude Code actually
  loads MCP servers from, on both web/cloud sessions and the CLI; the
  old `mcpServers` block in `.claude/settings.json` was never read).
  Tools: `gluecron_create_pr`, `gluecron_merge_pr`,
  `gluecron_create_issue`, `gluecron_comment_pr`, etc. See
  `src/lib/mcp-tools.ts` for the full 15-tool surface.
- **Cloud (web) sessions:** the clone comes from the GitHub mirror and
  `git push` to origin goes through the GitHub proxy. To run a PR
  through Gluecron: (1) push the feature branch to origin as usual,
  (2) also push it to the canonical remote —
  `git push https://x:${GLUECRON_PAT}@gluecron.com/ccantynz/Gluecron.com.git HEAD:<branch>`
  (requires `gluecron.com` in the environment's network allowlist) —
  then (3) open the PR with `gluecron_create_pr`. If gluecron.com is
  unreachable, fall back to GitHub and say so in the session.
- Do NOT call any `mcp__github__*` write tool. The settings file's
  `permissions.deny` already blocks them; if you encounter a deny
  error, switch to the equivalent `gluecron_*` tool.
- The `.claude/skills/gluecron-pr`, `gluecron-issue`, and
  `gluecron-review` skills are the highest-leverage entry points for
  routine work. Invoke them when the user mentions a PR, an issue,
  or wants a second AI review pass.
- Auth: the `GLUECRON_PAT` env var holds the user's personal access
  token. If it's missing, prompt the user to generate one at
  `/settings/tokens` (admin scope required for the merge tools).

**Deploys are self-driven now.** Push to `main` and
`src/hooks/post-receive.ts` fires `scripts/self-deploy.sh` directly —
no GitHub Actions involvement. The live site reflects the push in
~25 seconds. Watch `/admin/deploys` for the live step stream.

## READ FIRST — every session

**`BUILD_BIBLE.md` is mandatory reading for every Claude agent before any code changes.**

It contains:
- Agent policy (do-not-undo rule, continuous-build rule)
- GitHub parity scorecard (what's shipped vs missing)
- Numbered build plan (Blocks A–H)
- Locked components that cannot be altered without owner permission
- Session workflow

Do not skip it. Do not refactor locked files. Do not stop mid-block.

## Stack

- **Runtime:** Bun
- **Framework:** Hono (with JSX for server-rendered views)
- **Database:** Drizzle ORM + Neon (PostgreSQL)
- **Git:** Smart HTTP protocol via git CLI subprocesses

## Development

```bash
bun install        # install dependencies
bun dev            # start dev server (hot reload)
bun test           # run tests
bun run db:migrate # run database migrations
```

## Architecture

> Note (2026-06-10): the tree below is illustrative, not exhaustive — the
> platform has grown to ~190 route files in `src/routes/` and 161 tables in
> `src/db/schema.ts`. `BUILD_BIBLE.md` §2 is the authoritative feature map.

```
src/
  index.ts                Entry point (Bun server)
  app.tsx                 Hono app composition + error handlers
  lib/
    config.ts             Environment config (getters, reads env at access time)
    auth.ts               Password hashing (bcrypt), session tokens
    highlight.ts          Syntax highlighting (highlight.js, 40+ languages)
    markdown.ts           Markdown rendering (GFM + syntax highlighting)
  db/
    schema.ts             Drizzle schema (all tables)
    index.ts              Lazy DB connection (proxy pattern)
    migrate.ts            Migration runner
  git/
    repository.ts         Git operations (tree, blob, commits, diff, branches, blame, search, raw)
    protocol.ts           Smart HTTP protocol (pkt-line, service RPC)
  hooks/
    post-receive.ts       GateTest + optional deploy webhook on push
  middleware/
    auth.ts               softAuth + requireAuth middleware
  routes/
    git.ts                Git HTTP endpoints (clone/push)
    api.ts                REST API (repo CRUD, setup)
    auth.tsx              Register, login, logout (web + API)
    web.tsx               Web UI (file browser, commits, diffs, search, blame, raw)
    issues.tsx            Issue tracker (CRUD, comments, close/reopen)
    pulls.tsx             Pull requests (create, review, merge, close)
    editor.tsx            Web file editor (create/edit via git plumbing)
    compare.tsx           Branch comparison (diff + commit list)
    settings.tsx          User settings (profile, SSH keys)
    repo-settings.tsx     Repository settings (description, visibility, delete)
    webhooks.tsx          Webhook management + delivery engine
    fork.ts               Repository forking
    explore.tsx           Explore/discover public repos
    tokens.tsx            Personal access tokens
    contributors.tsx      Contributor list + commit activity graph
  views/
    layout.tsx            HTML shell + CSS (dark theme) + auth-aware nav
    components.tsx        UI components (file table, commit list, diff viewer, etc.)
```

## Database Schema

- `users` — accounts with bcrypt password hashing
- `sessions` — cookie-based auth sessions (30 day expiry)
- `repositories` — repos with fork tracking, star/fork/issue counts
- `stars` — user-repo star relationships
- `issues` — issue tracker with open/closed state
- `issue_comments` — threaded comments on issues
- `labels` + `issue_labels` — issue categorization
- `pull_requests` — PRs with base/head branches, open/closed/merged state
- `pr_comments` — PR comments with AI review flag + file/line annotations
- `activity_feed` — event log for repos
- `webhooks` — registered webhook URLs with HMAC secret + event filtering
- `api_tokens` — personal access tokens with SHA-256 hashing
- `repo_topics` — repository tags for discoverability
- `ssh_keys` — user SSH public keys

## Integrations

- **GateTest (optional):** third-party security scanner. When `GATETEST_URL` is set, `git push` POSTs to it; inbound results accepted at `POST /api/hooks/gatetest`.
- **Outbound deploy webhook (optional):** when `VAPRON_DEPLOY_URL` is set (legacy `CRONTECH_DEPLOY_URL` honored), pushes to the default branch POST to Vapron (formerly Crontech).
- **Webhooks:** POST to user-registered URLs on push/issue/PR/star events with HMAC signatures.

## Environment Variables

See `.env.example` for required variables. Key ones:
- `DATABASE_URL` — Neon PostgreSQL connection string
- `GIT_REPOS_PATH` — directory for bare git repos (default: `./repos`)
- `PORT` — HTTP port (default: 3000)

## Deployment

- **Primary target:** Fly.io — the repo ships a ready `fly.toml` (release command runs `bun run db:migrate`, `gluecron_repos` volume mounted at `/app/repos`).
- **Other hosts:** a `Dockerfile` is in the repo, so any standard Docker host works.
- **Database:** Neon PostgreSQL (direct connection via `DATABASE_URL`).
- See DEPLOY.md for full deployment instructions.

## Skills available for this project

Claude Code skill bundle for the Gluecron MCP write surface lives in
`.claude/skills/`. The install script (`scripts/install.sh`) copies these
into `~/.claude/skills/` so they are available across all projects:

- **`gluecron-pr`** — open, list, fetch, comment on, merge, or close pull
  requests on a Gluecron-hosted repository.
- **`gluecron-issue`** — create, list, comment on, close, or reopen issues
  on a Gluecron-hosted repository.
- **`gluecron-review`** — act as a secondary AI code reviewer on a
  Gluecron PR; complements the built-in `src/lib/ai-review.ts` pass.

All three skills drive the K1 MCP write tools defined in
`src/lib/mcp-tools.ts` (`gluecron_create_issue`, `gluecron_create_pr`,
`gluecron_merge_pr`, etc.). They auto-invoke when the active repo's
origin URL contains `gluecron.com` or matches `$GLUECRON_HOST`.