Pre-launch — Gluecron is in final validation. Public signups and git hosting for non-owner users open after launch review.
ccantynz/Gluecron.com
CodeIssuesDiscussionsWikiPull RequestsProjectsCommitsActionsReleasesContributorsPulse● GatesSecuritySettingsDeploymentsPipelineInsightsAgents✨ Explain✨ Ask AI✨ Workspace✨ Spec✨ Tests▓ Debt Map✨ NL Search🏛 Archaeology
Blame · Line-by-line history

SETUP-GUIDE.txt

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/SETUP-GUIDE.txt
SETUP-GUIDE.txtBlame413 lines · 1 contributor
Normal viewRaw
8d2847bClaude1================================================================================
2GLUECRON — COMPLETE SETUP & ARCHITECTURE GUIDE FOR ALECRAE
3================================================================================
4
5PREREQUISITES
6-------------
7curl -fsSL https://bun.sh/install | bash
8sudo apt install git
9Sign up at https://neon.tech for PostgreSQL
10
11CLONE & INSTALL
12---------------
13git clone https://github.com/ccantynz-alt/Gluecron.com.git
14cd Gluecron.com
15bun install
16
17ENVIRONMENT FILE (.env)
18-----------------------
19DATABASE_URL=postgresql://user:password@host/gluecron
20GIT_REPOS_PATH=./repos
21PORT=3000
22GATETEST_URL=https://gatetest.ai/api/scan/run
23GATETEST_API_KEY=
24GATETEST_CALLBACK_SECRET=
25GATETEST_HMAC_SECRET=
26CRONTECH_DEPLOY_URL=https://crontech.ai/api/trpc/tenant.deploy
27ANTHROPIC_API_KEY=
28EMAIL_PROVIDER=log
29EMAIL_FROM=gluecron <no-reply@gluecron.local>
30RESEND_API_KEY=
31APP_BASE_URL=http://localhost:3000
32
33DATABASE SETUP
34--------------
35bun run db:migrate
36bun run db:studio
37
38RUN
39---
40bun dev (hot-reload dev server on port 3000)
41bun test (1448 tests must pass)
42bun start (production mode)
43
44VERIFICATION
45------------
46bun install
47bun run db:migrate
48mkdir -p repos
49bun test
50bun dev
51curl http://localhost:3000/health
52curl http://localhost:3000/explore
53
54================================================================================
55ARCHITECTURE
56================================================================================
57
58src/index.ts Bun HTTP server entry point
59src/app.tsx Hono app — middleware + all 87 route mounts
60
61src/db/schema.ts Drizzle ORM — ALL tables
62src/db/index.ts Lazy DB connection (proxy pattern)
63src/db/migrate.ts Migration runner
64
65src/git/repository.ts Git plumbing (tree, blob, commits, diff, branches, blame, search, raw, listTreeRecursive, aheadBehind, diffNumstat)
66src/git/protocol.ts Smart HTTP protocol (pkt-line, clone/push)
67
68src/hooks/post-receive.ts GateTest + Crontech webhooks on every git push
69
70src/middleware/auth.ts softAuth (optional) + requireAuth (required)
71src/middleware/rate-limit.ts Token-bucket rate limiter (X-RateLimit-* headers)
72src/middleware/request-context.ts X-Request-Id + request timing
73
74src/views/layout.tsx HTML shell + dark theme CSS + auth-aware nav
75src/views/components.tsx RepoHeader, RepoNav, RepoCard, FileTable, DiffViewer
76src/views/reactions.tsx ReactionsBar (no-JS compatible)
77
78src/lib/ 80 pure helper modules (IO-free, fully testable)
79src/routes/ 87 Hono route files
80src/__tests__/ 75 test files, 1448 tests
81drizzle/ 37 SQL migration files
82
83================================================================================
84COMPONENT CHECKLIST (DEPENDENCY ORDER)
85================================================================================
86
87INFRASTRUCTURE (must work first)
88 1. Bun runtime — install Bun, verify bun --version
89 2. PostgreSQL / Neon — get a DATABASE_URL, verify connectivity
90 3. Git CLI — git --version must be 2.x+
91 4. Run migrations — bun run db:migrate (37 migrations)
92 5. Create repos/ directory — mkdir -p repos
93 6. Verify health — curl http://localhost:3000/health
94
95CORE FEATURES
96 7. Auth — register/login/logout, bcrypt passwords, 30-day sessions
97 8. Repositories — create, clone, push (Smart HTTP protocol)
98 9. File browser — tree view, blob view, syntax highlighting
9910. Commits — log, diff, blame
10011. Issues — CRUD, comments, labels, close/reopen
10112. Pull requests — create, review, merge (merge/squash/rebase), close
10213. Webhooks — HMAC-signed POST on push/issue/PR/star events
10314. Fork — full repo fork via git clone --bare
10415. Search — global search (repos, users, issues, PRs)
10516. Dashboard — personal feed
10617. Explore — discover public repos
107
108CI/CD & SECURITY
10918. GateTest integration — scan on every push, callback webhook
11019. Workflow runner — .gluecron/workflows/*.yml auto-discovery
11120. Security scanner — secret detection in push payloads
11221. Code scanning UI — vulnerability dashboard
11322. Branch protection — required reviews, status checks
11423. Rulesets — granular per-branch rules
115
116AI FEATURES (require ANTHROPIC_API_KEY)
11724. AI code review — automatic review comments on PRs
11825. AI code explain — /:owner/:repo/explain
11926. AI changelog — auto-generated release notes
12027. Copilot completions — POST /api/copilot/completions
12128. Semantic search — embeddings-based code search
12229. AI test generator — generate test skeletons
12330. AI assistant — /ask chat interface
124
125PLATFORM FEATURES
12631. Organizations + teams — multi-user access control
12732. OAuth provider — third-party app authorization
12833. 2FA / TOTP — time-based one-time passwords
12934. Passkeys / WebAuthn — hardware key auth
13035. Personal access tokens — SHA-256 hashed API keys
13136. Notifications — inbox with unread count
13237. Email notifications — Resend integration
13338. Releases + tags — semantic versioning, asset uploads
13439. Package registry — npm-compatible publish/install
13540. Pages / static hosting — deploy from branch
13641. Wiki — per-repo documentation
13742. Discussions — threaded Q&A
13843. Gists — shareable code snippets
13944. Projects — kanban boards
14045. Merge queue — automated merge sequencing
141
142INSIGHTS & ANALYTICS (J-series beyond-parity)
14346. Insights dashboard — green rate, contributors, commit graph
14447. Repository pulse — activity summary with rolling window
14548. Response time metric — p50/p90 time-to-first-response
14649. PR lead-time metric — created-to-merged percentiles
14750. PR size distribution — XS/S/M/L/XL classification
14851. Language breakdown — stacked bar + per-language table
14952. Size audit — largest files + directory breakdown
15053. Branch staleness — fresh/aging/stale/abandoned classification
15154. Stale issue detector — open issues past threshold
15255. Issue duplicate suggestions — token-Jaccard similarity
15356. Contribution heatmap — GitHub-style calendar
15457. Traffic analytics — views, clones, referrers
15558. Atom feeds — commits/releases/issues.atom
156
157================================================================================
158KEY LIB MODULES (src/lib/)
159================================================================================
160
161config.ts Environment config
162auth.ts Password hashing (bcrypt), session tokens
163cache.ts LRU cache + cached() helper
164highlight.ts Syntax highlighting (40+ languages)
165markdown.ts Markdown rendering (GFM)
166ai-client.ts Anthropic SDK wrapper
167ai-review.ts AI code review
168ai-explain.ts AI code explanation
169ai-completion.ts Copilot completions
170gate.ts GateTest CI integration
171security-scan.ts Secret scanner
172workflow-parser.ts Actions-equivalent YAML parser
173workflow-runner.ts Workflow execution engine
174dep-updater.ts Dependabot-equivalent
175oauth.ts OAuth 2.0 provider
176totp.ts 2FA / TOTP
177webauthn.ts WebAuthn / passkey
178graphql.ts GraphQL schema
179email.ts Email sending
180notify.ts Notification fan-out
181orgs.ts Organizations + teams
182packages.ts npm-compatible registry
183pages.ts Static hosting
184merge-queue.ts Merge queue
185rulesets.ts Repository rulesets
186branch-protection.ts Branch protection
187branch-rename.ts Branch rename with cascades
188branch-age.ts Branch staleness analysis
189issue-query.ts GitHub-style search DSL
190issue-similarity.ts Duplicate detection
191issue-templates.ts Issue/PR templates
192close-keywords.ts Fixes #N auto-close
193code-suggestions.ts Suggestion block apply
194codeowners-lint.ts CODEOWNERS validator
195release-notes.ts Changelog generator
196response-time.ts Time-to-first-response (J25)
197pr-lead-time.ts PR lead-time (J29)
198pr-size.ts PR size distribution (J32)
199language-stats.ts Language breakdown (J30)
200repo-size.ts Size audit (J31)
201repo-pulse.ts Activity summary
202stale-issues.ts Stale issue detector
203atom-feed.ts Atom feed renderer
204audit-csv.ts CSV export (RFC 4180)
205badge.ts SVG badges
206community.ts Health scorecard
207contribution-heatmap.ts Contribution calendar
208deps.ts Dependency graph
209advisories.ts Security advisories
210sso.ts Enterprise SSO
211mirrors.ts Repository mirroring
212symbols.ts Symbol navigation
213traffic.ts Traffic analytics
214billing.ts Usage tracking
215marketplace.ts App marketplace
216
217================================================================================
218KEY ROUTES (src/routes/)
219================================================================================
220
221git.ts Smart HTTP clone/push
222api.ts REST API (repo CRUD)
223auth.tsx Register, login, logout
224web.tsx File browser, commits, diffs (catch-all)
225issues.tsx Issue tracker
226pulls.tsx Pull requests
227editor.tsx Web file editor
228compare.tsx Branch comparison
229settings.tsx User settings
230repo-settings.tsx Repository settings
231insights.tsx Insights dashboard
232workflows.tsx CI/CD runner
233packages.tsx Package registry UI
234pages.tsx Static hosting
235discussions.tsx Discussions
236wikis.tsx Wiki
237gists.tsx Gists
238projects.tsx Projects
239orgs.tsx Organizations
240admin.tsx Admin panel
241billing.tsx Billing UI
242graphql.ts GraphQL endpoint
243marketplace.tsx App marketplace
244languages.tsx Language breakdown (J30)
245repo-size.tsx Size audit (J31)
246pr-size.tsx PR size distribution (J32)
247pr-lead-time.tsx PR lead-time (J29)
248response-time.tsx Response-time (J25)
249branch-age.tsx Branch staleness (J27)
250pulse.tsx Repository pulse (J18)
251
252================================================================================
253JSON CONFIGURATION (save as gluecron-setup.json)
254================================================================================
255
256{
257 "project": {
258 "name": "gluecron",
259 "version": "0.1.0",
260 "description": "AI-native code intelligence platform",
261 "repository": "https://github.com/ccantynz-alt/Gluecron.com"
262 },
263 "runtime": {
264 "engine": "bun",
265 "minimumVersion": "1.3.0",
266 "entryPoint": "src/index.ts"
267 },
268 "framework": {
269 "name": "hono",
270 "version": "^4.7.0",
271 "jsx": "react-jsx",
272 "jsxImportSource": "hono/jsx",
273 "rendering": "server-side (SSR)"
274 },
275 "database": {
276 "orm": "drizzle-orm",
277 "dialect": "postgresql",
278 "provider": "neon-serverless",
279 "schemaFile": "src/db/schema.ts",
280 "migrationsDir": "drizzle/",
281 "migrationCount": 37,
282 "connectionPattern": "lazy-proxy"
283 },
284 "git": {
285 "protocol": "smart-http",
286 "reposPath": "./repos",
287 "storageFormat": "bare",
288 "protocolFile": "src/git/protocol.ts",
289 "plumbingFile": "src/git/repository.ts"
290 },
291 "typescript": {
292 "target": "ES2022",
293 "module": "ES2022",
294 "moduleResolution": "bundler",
295 "strict": true,
296 "types": ["bun-types"]
297 },
298 "testing": {
299 "runner": "bun:test",
300 "totalTests": 1448,
301 "testFiles": 75,
302 "testDir": "src/__tests__/",
303 "pattern": "**/*.test.ts",
304 "command": "bun test"
305 },
306 "integrations": {
307 "gatetest": {
308 "purpose": "CI security scanning on every git push",
309 "endpoint": "https://gatetest.ai/api/scan/run",
310 "callbackEndpoint": "/api/v1/gate-runs",
311 "authMethod": "HMAC"
312 },
313 "crontech": {
314 "purpose": "Auto-deploy on push to main",
315 "endpoint": "https://crontech.ai/api/trpc/tenant.deploy"
316 },
317 "anthropic": {
318 "purpose": "AI features (review, explain, copilot, search, tests, chat)",
319 "sdk": "@anthropic-ai/sdk ^0.88.0",
320 "gracefulDegradation": true,
321 "fallbackBehavior": "returns placeholder strings when no API key"
322 },
323 "resend": {
324 "purpose": "Transactional email delivery",
325 "fallbackProvider": "log"
326 }
327 },
328 "auth": {
329 "passwordHashing": "bcrypt",
330 "sessionDuration": "30 days",
331 "cookieBased": true,
332 "supportedMethods": [
333 "password",
334 "totp-2fa",
335 "webauthn-passkeys",
336 "oauth-apps",
337 "personal-access-tokens",
338 "enterprise-sso-oidc"
339 ]
340 },
341 "architecture": {
342 "layers": {
343 "entry": ["src/index.ts"],
344 "app": ["src/app.tsx"],
345 "middleware": ["src/middleware/auth.ts", "src/middleware/rate-limit.ts", "src/middleware/request-context.ts"],
346 "routes": "src/routes/ (87 files)",
347 "views": ["src/views/layout.tsx", "src/views/components.tsx", "src/views/reactions.tsx"],
348 "lib": "src/lib/ (80 pure helper modules)",
349 "db": ["src/db/schema.ts", "src/db/index.ts", "src/db/migrate.ts"],
350 "git": ["src/git/repository.ts", "src/git/protocol.ts"],
351 "hooks": ["src/hooks/post-receive.ts"]
352 },
353 "patterns": {
354 "pureFirst": "Business logic in src/lib/ as pure functions. Routes are thin shells.",
355 "neverFiveHundred": "Every route wraps resolveRepo in try/catch -> null -> 404.",
356 "internalReExports": "Every lib module exports __internal for testing.",
357 "softAuth": "Read-only routes use softAuth. Write routes use requireAuth.",
358 "mountOrder": "Static paths mount BEFORE dynamic /:number routes in app.tsx."
359 }
360 },
361 "commands": {
362 "install": "bun install",
363 "dev": "bun dev",
364 "start": "bun start",
365 "test": "bun test",
366 "dbMigrate": "bun run db:migrate",
367 "dbGenerate": "bun run db:generate",
368 "dbStudio": "bun run db:studio"
369 },
370 "environment": {
371 "required": ["DATABASE_URL"],
372 "optional": [
373 "GIT_REPOS_PATH (default: ./repos)",
374 "PORT (default: 3000)",
375 "ANTHROPIC_API_KEY (unlocks AI features)",
376 "GATETEST_URL",
377 "GATETEST_API_KEY",
378 "GATETEST_CALLBACK_SECRET",
379 "GATETEST_HMAC_SECRET",
380 "CRONTECH_DEPLOY_URL",
381 "EMAIL_PROVIDER (log | resend)",
382 "EMAIL_FROM",
383 "RESEND_API_KEY",
384 "APP_BASE_URL"
385 ]
386 },
387 "featureCounts": {
388 "routes": 87,
389 "libModules": 80,
390 "dbMigrations": 37,
391 "testFiles": 75,
392 "totalTests": 1448,
393 "totalExpects": 3810
394 },
395 "lockedComponents": [
396 "src/db/schema.ts",
397 "src/git/repository.ts",
398 "src/git/protocol.ts",
399 "src/hooks/post-receive.ts",
400 "src/views/layout.tsx",
401 "src/views/components.tsx",
402 "src/middleware/auth.ts",
403 "src/lib/config.ts",
404 "src/lib/auth.ts",
405 "src/lib/gate.ts",
406 "src/lib/security-scan.ts",
407 "BUILD_BIBLE.md"
408 ]
409}
410
411================================================================================
412END OF GUIDE
413================================================================================