Pre-launch — Gluecron is in final validation. Public signups and git hosting for non-owner users open after launch review.
ccantynz/Gluecron.com
CodeIssuesPull RequestsActionsSecurityInsightsSettings
✨ AI
ExplainAsk AIWorkspaceSpec to PRTestsNL SearchDebt MapArchaeology
More
CommitsDiscussionsWikiProjectsReleasesContributorsPulseGatesDeploymentsPipelineAgents
Blame · Line-by-line history

CLAUDE.md

Each line is annotated with the commit that last touched it. Click any SHA to jump to that commit and see the surrounding change.

Gluecron.com/CLAUDE.md
CLAUDE.mdBlame191 lines · 3 contributors
Normal viewRaw
fc1817aClaude1# gluecron
2
90fa787Claude3AI-native code intelligence platform — git hosting, automated CI, and push-time gate enforcement.
fc1817aClaude4
5472beaccanty labs5## Source of truth: Gluecron (self-canonical, no GitHub mirror)
3b99c5fTest User6
5472beaccanty labs7This repository self-hosts on Gluecron itself. The one canonical remote is
8`https://gluecron.com/ccantynz/Gluecron.com.git`. **Gluecron is self-canonical:
9there is no GitHub mirror or fallback.** Durability comes from the offsite
10backup (`scripts/backup-offsite.sh` → rclone), not from GitHub. A fresh host
11re-seeds from a restored backup (`scripts/restore.sh`), never from GitHub.
12(Cutover status + operator steps: `docs/CUTOVER_RUNBOOK.md`.)
3b99c5fTest User13
14**For any AI session working in this repo:**
15
4cd9a67Claude16- Use the Gluecron MCP server. It is declared in `.mcp.json` at the
17 repo root (project scope — this is the file Claude Code actually
18 loads MCP servers from, on both web/cloud sessions and the CLI; the
19 old `mcpServers` block in `.claude/settings.json` was never read).
20 Tools: `gluecron_create_pr`, `gluecron_merge_pr`,
3b99c5fTest User21 `gluecron_create_issue`, `gluecron_comment_pr`, etc. See
22 `src/lib/mcp-tools.ts` for the full 15-tool surface.
5472beaccanty labs23- Push the feature branch straight to the canonical remote —
4cd9a67Claude24 `git push https://x:${GLUECRON_PAT}@gluecron.com/ccantynz/Gluecron.com.git HEAD:<branch>`
25 (requires `gluecron.com` in the environment's network allowlist) —
5472beaccanty labs26 then open the PR with `gluecron_create_pr`. There is no GitHub fallback;
27 if gluecron.com is unreachable, stop and surface it rather than pushing
28 to GitHub.
3b99c5fTest User29- Do NOT call any `mcp__github__*` write tool. The settings file's
30 `permissions.deny` already blocks them; if you encounter a deny
31 error, switch to the equivalent `gluecron_*` tool.
32- The `.claude/skills/gluecron-pr`, `gluecron-issue`, and
33 `gluecron-review` skills are the highest-leverage entry points for
34 routine work. Invoke them when the user mentions a PR, an issue,
35 or wants a second AI review pass.
36- Auth: the `GLUECRON_PAT` env var holds the user's personal access
37 token. If it's missing, prompt the user to generate one at
38 `/settings/tokens` (admin scope required for the merge tools).
39
ab45e6accanty labs40**Deploys are self-driven now.** Push to the canonical Gluecron remote
41and `src/hooks/post-receive.ts` fires `scripts/self-deploy.sh` directly.
42The live site reflects the push in ~25 seconds. Watch `/admin/deploys`
43for the live step stream.
44
45**Server:** `gluecron.com` → `66.42.121.161` (VPS, not Fly.io or Hetzner —
46both are decommissioned). Working tree lives at `/opt/gluecron` on that box.
47
48**To deploy:**
49```bash
50git push gluecron main
51# or first-time setup:
52git remote add gluecron https://x:${GLUECRON_PAT}@gluecron.com/ccantynz/Gluecron.com.git
53```
54
5472beaccanty labs55**Do NOT use Vercel** — it has been disconnected. The old GitHub repo
56(`ccantynz-alt/Gluecron.com`) is being retired: frozen read-only now, deleted
57after a 30-day safety window. It is NOT a mirror and pushing there does nothing
58— use the canonical Gluecron remote only.
3b99c5fTest User59
9ab6971Claude60## READ FIRST — every session
61
62**`BUILD_BIBLE.md` is mandatory reading for every Claude agent before any code changes.**
63
64It contains:
65- Agent policy (do-not-undo rule, continuous-build rule)
66- GitHub parity scorecard (what's shipped vs missing)
67- Numbered build plan (Blocks A–H)
68- Locked components that cannot be altered without owner permission
69- Session workflow
70
71Do not skip it. Do not refactor locked files. Do not stop mid-block.
72
fc1817aClaude73## Stack
74
75- **Runtime:** Bun
76- **Framework:** Hono (with JSX for server-rendered views)
77- **Database:** Drizzle ORM + Neon (PostgreSQL)
78- **Git:** Smart HTTP protocol via git CLI subprocesses
79
80## Development
81
82```bash
83bun install # install dependencies
84bun dev # start dev server (hot reload)
85bun test # run tests
86bun run db:migrate # run database migrations
87```
88
89## Architecture
90
74a8784Claude91> Note (2026-06-10): the tree below is illustrative, not exhaustive — the
92> platform has grown to ~190 route files in `src/routes/` and 161 tables in
93> `src/db/schema.ts`. `BUILD_BIBLE.md` §2 is the authoritative feature map.
94
fc1817aClaude95```
96src/
43de941Claude97 index.ts Entry point (Bun server)
98 app.tsx Hono app composition + error handlers
99 lib/
100 config.ts Environment config (getters, reads env at access time)
101 auth.ts Password hashing (bcrypt), session tokens
102 highlight.ts Syntax highlighting (highlight.js, 40+ languages)
103 markdown.ts Markdown rendering (GFM + syntax highlighting)
fc1817aClaude104 db/
43de941Claude105 schema.ts Drizzle schema (all tables)
106 index.ts Lazy DB connection (proxy pattern)
107 migrate.ts Migration runner
fc1817aClaude108 git/
43de941Claude109 repository.ts Git operations (tree, blob, commits, diff, branches, blame, search, raw)
110 protocol.ts Smart HTTP protocol (pkt-line, service RPC)
fc1817aClaude111 hooks/
90fa787Claude112 post-receive.ts GateTest + optional deploy webhook on push
43de941Claude113 middleware/
114 auth.ts softAuth + requireAuth middleware
fc1817aClaude115 routes/
43de941Claude116 git.ts Git HTTP endpoints (clone/push)
117 api.ts REST API (repo CRUD, setup)
118 auth.tsx Register, login, logout (web + API)
119 web.tsx Web UI (file browser, commits, diffs, search, blame, raw)
120 issues.tsx Issue tracker (CRUD, comments, close/reopen)
121 pulls.tsx Pull requests (create, review, merge, close)
122 editor.tsx Web file editor (create/edit via git plumbing)
123 compare.tsx Branch comparison (diff + commit list)
124 settings.tsx User settings (profile, SSH keys)
125 repo-settings.tsx Repository settings (description, visibility, delete)
126 webhooks.tsx Webhook management + delivery engine
127 fork.ts Repository forking
128 explore.tsx Explore/discover public repos
129 tokens.tsx Personal access tokens
130 contributors.tsx Contributor list + commit activity graph
fc1817aClaude131 views/
43de941Claude132 layout.tsx HTML shell + CSS (dark theme) + auth-aware nav
133 components.tsx UI components (file table, commit list, diff viewer, etc.)
fc1817aClaude134```
135
43de941Claude136## Database Schema
137
138- `users` — accounts with bcrypt password hashing
139- `sessions` — cookie-based auth sessions (30 day expiry)
140- `repositories` — repos with fork tracking, star/fork/issue counts
141- `stars` — user-repo star relationships
142- `issues` — issue tracker with open/closed state
143- `issue_comments` — threaded comments on issues
144- `labels` + `issue_labels` — issue categorization
145- `pull_requests` — PRs with base/head branches, open/closed/merged state
146- `pr_comments` — PR comments with AI review flag + file/line annotations
147- `activity_feed` — event log for repos
148- `webhooks` — registered webhook URLs with HMAC secret + event filtering
149- `api_tokens` — personal access tokens with SHA-256 hashing
150- `repo_topics` — repository tags for discoverability
151- `ssh_keys` — user SSH public keys
152
fc1817aClaude153## Integrations
154
90fa787Claude155- **GateTest (optional):** third-party security scanner. When `GATETEST_URL` is set, `git push` POSTs to it; inbound results accepted at `POST /api/hooks/gatetest`.
9ecf5a4Claude156- **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).
90fa787Claude157- **Webhooks:** POST to user-registered URLs on push/issue/PR/star events with HMAC signatures.
fc1817aClaude158
159## Environment Variables
160
161See `.env.example` for required variables. Key ones:
162- `DATABASE_URL` — Neon PostgreSQL connection string
163- `GIT_REPOS_PATH` — directory for bare git repos (default: `./repos`)
164- `PORT` — HTTP port (default: 3000)
fc0785eClaude165
166## Deployment
167
ab45e6accanty labs168- **Production server:** `66.42.121.161` (`gluecron.com`) — VPS running Bun directly via systemd.
169- **Deploy trigger:** `git push gluecron main` → `post-receive.ts` → `scripts/self-deploy.sh` → systemd reload.
170- **Fly.io:** decommissioned (fly.toml kept for reference, not active).
171- **Vercel:** disconnected — do not reconnect.
90fa787Claude172- **Database:** Neon PostgreSQL (direct connection via `DATABASE_URL`).
ab45e6accanty labs173- **Logs:** `/var/log/gluecron-self-deploy.log` on the server; live stream at `/admin/deploys`.
43095dcClaude174
175## Skills available for this project
176
177Claude Code skill bundle for the Gluecron MCP write surface lives in
178`.claude/skills/`. The install script (`scripts/install.sh`) copies these
179into `~/.claude/skills/` so they are available across all projects:
180
181- **`gluecron-pr`** — open, list, fetch, comment on, merge, or close pull
182 requests on a Gluecron-hosted repository.
183- **`gluecron-issue`** — create, list, comment on, close, or reopen issues
184 on a Gluecron-hosted repository.
185- **`gluecron-review`** — act as a secondary AI code reviewer on a
186 Gluecron PR; complements the built-in `src/lib/ai-review.ts` pass.
187
188All three skills drive the K1 MCP write tools defined in
189`src/lib/mcp-tools.ts` (`gluecron_create_issue`, `gluecron_create_pr`,
190`gluecron_merge_pr`, etc.). They auto-invoke when the active repo's
191origin URL contains `gluecron.com` or matches `$GLUECRON_HOST`.