From 7dae48697aed20fc1bb57109b96d163b93ed1886 Mon Sep 17 00:00:00 2001 From: ZTatman Date: Sun, 16 Aug 2026 19:32:41 -0400 Subject: [PATCH] chore: clean up project structure and remove dead code - Delete broken Dockerfile (referenced non-existent packages/service) - Delete unused @firebreak/shared package - Delete unused crypto.ts, aiofiles dependency, stale static assets - Delete .tmp/embargo-test/ scaffold with hardcoded secrets - Move packages/cli/ to cli/ (flat structure, no packages/ dir) - Rename myst config example and UI design doc - Update docs to fix stale path references (packages/service/*, Pico CSS, SQLModel) - Remove stale agents.md entries (process.exit, ORM session leak) - Clean up tsconfig references and pnpm workspace config --- Dockerfile | 24 -------------- agents.md | 28 +++++----------- {packages/cli => cli}/package.json | 0 {packages/cli => cli}/src/cli-router.ts | 0 {packages/cli => cli}/src/commandRegistry.ts | 0 .../cli => cli}/src/commands/config/init.ts | 0 .../cli => cli}/src/commands/config/view.ts | 0 {packages/cli => cli}/src/commands/verify.ts | 0 {packages/cli => cli}/src/index.ts | 0 {packages/cli => cli}/src/utils/config.ts | 0 .../cli => cli}/src/utils/forgejo-checks.ts | 0 {packages/shared => cli}/tsconfig.json | 3 +- ...t-ui-design.md => 2026-05-15-ui-design.md} | 0 docs/plans/auth-deployment-design.md | 33 +++++++------------ docs/plans/phase-1-design.md | 17 +++------- ...ple.json => firebreak.config.example.json} | 0 packages/cli/src/utils/crypto.ts | 5 --- packages/cli/tsconfig.json | 9 ----- packages/shared/package.json | 19 ----------- packages/shared/src/constants.ts | 1 - packages/shared/src/index.ts | 3 -- packages/shared/src/types.ts | 10 ------ pnpm-lock.yaml | 4 +-- pnpm-workspace.yaml | 2 +- tsconfig.base.json | 4 +-- tsconfig.json | 3 +- web/app/static/img/firebreak-logo-black.svg | 3 -- .../static/img/firebreak-logo-cream-red.svg | 14 -------- web/pyproject.toml | 1 - web/uv.lock | 11 ------- 30 files changed, 29 insertions(+), 165 deletions(-) delete mode 100644 Dockerfile rename {packages/cli => cli}/package.json (100%) rename {packages/cli => cli}/src/cli-router.ts (100%) rename {packages/cli => cli}/src/commandRegistry.ts (100%) rename {packages/cli => cli}/src/commands/config/init.ts (100%) rename {packages/cli => cli}/src/commands/config/view.ts (100%) rename {packages/cli => cli}/src/commands/verify.ts (100%) rename {packages/cli => cli}/src/index.ts (100%) rename {packages/cli => cli}/src/utils/config.ts (100%) rename {packages/cli => cli}/src/utils/forgejo-checks.ts (100%) rename {packages/shared => cli}/tsconfig.json (61%) rename docs/plans/{2026-05-15-myst-ui-design.md => 2026-05-15-ui-design.md} (100%) rename examples/{myst.config.example.json => firebreak.config.example.json} (100%) delete mode 100644 packages/cli/src/utils/crypto.ts delete mode 100644 packages/cli/tsconfig.json delete mode 100644 packages/shared/package.json delete mode 100644 packages/shared/src/constants.ts delete mode 100644 packages/shared/src/index.ts delete mode 100644 packages/shared/src/types.ts delete mode 100644 web/app/static/img/firebreak-logo-black.svg delete mode 100644 web/app/static/img/firebreak-logo-cream-red.svg diff --git a/Dockerfile b/Dockerfile deleted file mode 100644 index 57a95f7..0000000 --- a/Dockerfile +++ /dev/null @@ -1,24 +0,0 @@ -FROM node:22-alpine - -WORKDIR /app - -COPY package*.json pnpm-lock.yaml pnpm-workspace.yaml ./ -COPY packages/service/package*.json ./packages/service/ -COPY packages/shared/package*.json ./packages/shared/ -COPY tsconfig.base.json ./ - -RUN npm install -g pnpm - -RUN pnpm install --frozen-lockfile - -COPY . . - -RUN pnpm -r --filter @firebreak/service build - -ENV PORT=3000 - -EXPOSE 3000 - -USER node - -CMD ["pnpm", "--filter", "@firebreak/service", "start"] diff --git a/agents.md b/agents.md index ffce1d3..db9f5fe 100644 --- a/agents.md +++ b/agents.md @@ -27,59 +27,47 @@ This file is the single source of truth for codebase obstacles, oddities, and th ## Documented obstacles ### TypeScript composite builds fail with no output -**Area:** packages/cli/tsconfig.json, tsconfig.base.json +**Area:** cli/tsconfig.json, tsconfig.base.json **Obstacle:** When `composite: true` is set in tsconfig, TypeScript requires proper project references to build. The CLI package was building but producing no output files, causing "cannot find module" errors. -**Solution:** Remove `composite: true` from packages/cli/tsconfig.json. Also removed `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` from tsconfig.base.json as they caused strict type issues with dynamic config objects. +**Solution:** Remove `composite: true` from cli/tsconfig.json. Also removed `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` from tsconfig.base.json as they caused strict type issues with dynamic config objects. **Preference:** Use simple tsconfig without composite mode for CLI package. ### verify.ts overly complex abstraction -**Area:** packages/cli/src/commands/verify.ts +**Area:** cli/src/commands/verify.ts **Obstacle:** Code had too many layers: collectResults → addResult (inner function) → displayDiagnosticResults/verifyResults. Made it hard to trace and debug. **Solution:** Rewrote to be flatter: verifyCommand → runDiagnosticMode/runVerifyMode. Used simple inline logic instead of adding functions for everything. **Preference:** KISS - keep functions small but avoid over-abstraction. ### Error messages in forgejo-checks too generic -**Area:** packages/cli/src/utils/forgejo-checks.ts +**Area:** cli/src/utils/forgejo-checks.ts **Obstacle:** Network errors showed "fetch failed" with no context. HTTP errors showed just status codes. Not actionable for users. **Solution:** Added getErrorMessage() helper to detect: timeouts, connection refused, host not found. Improved HTTP error messages to include status text. Added context prefixes like "cannot reach server", "cannot connect to API". **Preference:** Actionable messages that tell users what to fix. ### ENV_MAPPING duplicated inline in verify.ts -**Area:** packages/cli/src/commands/verify.ts +**Area:** cli/src/commands/verify.ts **Obstacle:** Had duplicate object with same keys as ENV_MAPPING from config.ts. Two sources of truth. **Solution:** Import ENV_MAPPING and use it. Change display to show env var names (SNAKE_CASE) instead of internal keys. **Preference:** Single source of truth in config.ts. ### Display verbiage redundancy -**Area:** packages/cli/src/commands/verify.ts +**Area:** cli/src/commands/verify.ts **Obstacle:** Displayed "MYST_PUBLIC_URL set" - "set" is redundant, icon already shows status. -**Solution:** Just show env var name, remove "set". Shows "MYST_PUBLIC_URL configured" or "MYST_PUBLIC_URL missing". +**Solution:** Just show env var name, remove "set". **Preference:** Cleaner, let icon indicate status. ### loadConfig returning wrong type for error case -**Area:** packages/cli/src/commands/verify.ts +**Area:** cli/src/commands/verify.ts **Obstacle:** loadConfig() threw error when .env not found, but caught and re-threw in verifyCommand. This caused process to exit with stack trace instead of clean message. **Solution:** Return null on ENOENT, handle null in verifyCommand. Return type: `Record | null`. **Preference:** Explicit null handling over exceptions for user-facing errors. -### process.exit(0) prevents finally blocks -**Area:** CLI commands using process.exit() -**Obstacle:** process.exit(0) stops execution immediately, never runs cleanup code. -**Solution:** Use process.exitCode = 1 and return instead of process.exit(). -**Preference:** Set exitCode and return to allow cleanup. - ### Logout cookie not reaching browser **Area:** web/app/routers/auth.py, web/app/auth/session.py **Obstacle:** `revoke_session` set cookies on the injected `Response` parameter, but the logout handler returned a new `RedirectResponse` — so `Set-Cookie` was discarded. **Solution:** Create `RedirectResponse` first, then pass it into `revoke_session`. Same pattern used in `callback_forgejo` for `create_session`. **Preference:** Pass the actual response object that will be returned. -### Dashboard leaking ORM session object -**Area:** web/app/main.py -**Obstacle:** `/dashboard` returned the full ORM `Session` object (`sess`), leaking `token_hash`, `revoked_at`, etc. to the client. -**Solution:** Return a plain dict with only safe fields: `user_id`, `display_name`, `email`, `session_id`, `created_at`. -**Preference:** Never return ORM objects directly in API responses. - ### crypto.py decrypt functions kept proactively **Area:** web/app/auth/crypto.py **Obstacle:** CodeRabbit flagged missing decryption functions and key validation. Added `decrypt_token`/`decrypt_optional` + key format validation in `fernet_from_encryption_key`. diff --git a/packages/cli/package.json b/cli/package.json similarity index 100% rename from packages/cli/package.json rename to cli/package.json diff --git a/packages/cli/src/cli-router.ts b/cli/src/cli-router.ts similarity index 100% rename from packages/cli/src/cli-router.ts rename to cli/src/cli-router.ts diff --git a/packages/cli/src/commandRegistry.ts b/cli/src/commandRegistry.ts similarity index 100% rename from packages/cli/src/commandRegistry.ts rename to cli/src/commandRegistry.ts diff --git a/packages/cli/src/commands/config/init.ts b/cli/src/commands/config/init.ts similarity index 100% rename from packages/cli/src/commands/config/init.ts rename to cli/src/commands/config/init.ts diff --git a/packages/cli/src/commands/config/view.ts b/cli/src/commands/config/view.ts similarity index 100% rename from packages/cli/src/commands/config/view.ts rename to cli/src/commands/config/view.ts diff --git a/packages/cli/src/commands/verify.ts b/cli/src/commands/verify.ts similarity index 100% rename from packages/cli/src/commands/verify.ts rename to cli/src/commands/verify.ts diff --git a/packages/cli/src/index.ts b/cli/src/index.ts similarity index 100% rename from packages/cli/src/index.ts rename to cli/src/index.ts diff --git a/packages/cli/src/utils/config.ts b/cli/src/utils/config.ts similarity index 100% rename from packages/cli/src/utils/config.ts rename to cli/src/utils/config.ts diff --git a/packages/cli/src/utils/forgejo-checks.ts b/cli/src/utils/forgejo-checks.ts similarity index 100% rename from packages/cli/src/utils/forgejo-checks.ts rename to cli/src/utils/forgejo-checks.ts diff --git a/packages/shared/tsconfig.json b/cli/tsconfig.json similarity index 61% rename from packages/shared/tsconfig.json rename to cli/tsconfig.json index 7a46543..677d4f4 100644 --- a/packages/shared/tsconfig.json +++ b/cli/tsconfig.json @@ -1,7 +1,6 @@ { - "extends": "../../tsconfig.base.json", + "extends": "../tsconfig.base.json", "compilerOptions": { - "composite": true, "rootDir": "src", "outDir": "dist" }, diff --git a/docs/plans/2026-05-15-myst-ui-design.md b/docs/plans/2026-05-15-ui-design.md similarity index 100% rename from docs/plans/2026-05-15-myst-ui-design.md rename to docs/plans/2026-05-15-ui-design.md diff --git a/docs/plans/auth-deployment-design.md b/docs/plans/auth-deployment-design.md index 5b9a0f1..c478c12 100644 --- a/docs/plans/auth-deployment-design.md +++ b/docs/plans/auth-deployment-design.md @@ -338,27 +338,18 @@ The viewer is the only public application surface that emits code content. - Public access must be read-only - Public access must not expose database ports or Forgejo admin surfaces -## Repo Implementation Impact +## Active Surfaces -Active surfaces: +- CLI entrypoint: `cli/src/index.ts` +- Command stubs: `cli/src/commands/*` +- Web app: `web/app/` (FastAPI + Jinja2) +- Web routers: `web/app/routers/*` +- Web models: `web/app/models/*` -- CLI entrypoint: `packages/cli/src/index.ts` -- Command stubs: `packages/cli/src/commands/*` -- Config generators: `packages/cli/src/generators/*` -- Shared constants/types: `packages/shared/src/*` -- Service entrypoint: `packages/service/src/index.ts` -- Viewer routes: `packages/service/src/viewer/*` -- Dashboard routes: `packages/service/src/dashboard/*` +## Next implementation work -Next implementation work: - -1. Narrow `init` to Firebreak-only config generation for an existing Forgejo deployment -2. Add config types for Forgejo connection details, Firebreak base URL, database, and SMTP settings -3. Implement `forgejo bootstrap` and `doctor` -4. Add Postgres-backed service foundation using the data model -5. Wire the service to load generated config and validate required env at startup -6. Implement Forgejo session authentication for the dashboard -7. Build the link creation flow with repo ownership verification -8. Implement the web-based code viewer -9. Build the user dashboard with access logs -10. Implement email sending for private link verification codes +1. Implement Forgejo session authentication for the dashboard +2. Build the link creation flow with repo ownership verification +3. Implement the web-based code viewer +4. Build the user dashboard with access logs +5. Implement email sending for private link verification codes diff --git a/docs/plans/phase-1-design.md b/docs/plans/phase-1-design.md index bb83f7b..3a8d443 100644 --- a/docs/plans/phase-1-design.md +++ b/docs/plans/phase-1-design.md @@ -23,8 +23,8 @@ Phase 1 does not deliver: ## Tech Stack -- **Backend**: Python 3.11+ with FastAPI -- **Frontend**: Jinja2 templates with HTMX for interactivity +- **Backend**: Python 3.13+ with FastAPI +- **Frontend**: Jinja2 templates with HTMX + Tailwind CSS - **Database**: PostgreSQL - **Async**: Uses `async/await` with asyncpg for database access @@ -32,18 +32,9 @@ Phase 1 does not deliver: **FastAPI**: Lightweight async framework, automatic OpenAPI docs, Pydantic for validation. -**Jinja2 + HTMX**: Server-side rendering with minimal JavaScript. HTMX handles dynamic updates (filtering, form submissions) without a build step or heavy SPA framework. +**Jinja2 + HTMX**: Server-side rendering with minimal JavaScript. HTMX handles dynamic updates (filtering, form submissions) without a heavy SPA framework. -**PostgreSQL**: Reliable, well-supported by async libraries (asyncpg, SQLModel). - -## Reviewable Branches - -1. `codex/phase1-bootstrap-monorepo` -2. `codex/phase1-cli-init-skeleton` -3. `codex/phase1-service-foundation` -4. `codex/phase1-forgejo-integration` -5. `codex/phase1-grants-viewer` -6. `codex/phase1-dashboard-logs-settings` +**PostgreSQL**: Reliable, well-supported by async libraries (asyncpg, SQLAlchemy). ## Security Baseline diff --git a/examples/myst.config.example.json b/examples/firebreak.config.example.json similarity index 100% rename from examples/myst.config.example.json rename to examples/firebreak.config.example.json diff --git a/packages/cli/src/utils/crypto.ts b/packages/cli/src/utils/crypto.ts deleted file mode 100644 index 325d399..0000000 --- a/packages/cli/src/utils/crypto.ts +++ /dev/null @@ -1,5 +0,0 @@ -import { randomBytes } from "node:crypto"; - -export function generateSecret(bytes = 32): string { - return randomBytes(bytes).toString("hex"); -} diff --git a/packages/cli/tsconfig.json b/packages/cli/tsconfig.json deleted file mode 100644 index 4a52f6a..0000000 --- a/packages/cli/tsconfig.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "extends": "../../tsconfig.base.json", - "compilerOptions": { - "rootDir": "src", - "outDir": "dist" - }, - "references": [{ "path": "../shared" }], - "include": ["src/**/*.ts"] -} diff --git a/packages/shared/package.json b/packages/shared/package.json deleted file mode 100644 index dae6131..0000000 --- a/packages/shared/package.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "name": "@firebreak/shared", - "version": "0.1.0", - "private": true, - "type": "module", - "exports": { - ".": { - "types": "./src/index.ts", - "default": "./src/index.ts" - } - }, - "main": "./src/index.ts", - "types": "./src/index.ts", - "scripts": { - "build": "tsc -p tsconfig.json", - "check": "tsc -b tsconfig.json", - "clean": "rm -rf dist" - } -} diff --git a/packages/shared/src/constants.ts b/packages/shared/src/constants.ts deleted file mode 100644 index e58e900..0000000 --- a/packages/shared/src/constants.ts +++ /dev/null @@ -1 +0,0 @@ -export const FIREBREAK_DEFAULT_SERVICE_PORT = 4000; diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts deleted file mode 100644 index 002d702..0000000 --- a/packages/shared/src/index.ts +++ /dev/null @@ -1,3 +0,0 @@ -export * from "./constants.js"; -export * from "./types.js"; - diff --git a/packages/shared/src/types.ts b/packages/shared/src/types.ts deleted file mode 100644 index 85e41f4..0000000 --- a/packages/shared/src/types.ts +++ /dev/null @@ -1,10 +0,0 @@ -export interface RepoRef { - owner: string; - name: string; -} - -export interface GrantSnapshot { - repo: RepoRef; - sourceBranch: string; - commitSha: string; -} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 10f2795..3b7a2f5 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -15,7 +15,7 @@ importers: specifier: ^5.8.3 version: 5.9.3 - packages/cli: + cli: dependencies: '@clack/prompts': specifier: ^1.2.0 @@ -24,8 +24,6 @@ importers: specifier: ^2.1.2 version: 2.1.2 - packages/shared: {} - packages: '@clack/core@1.2.0': diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 4d846bc..3577e79 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -1,3 +1,3 @@ packages: - - packages/* + - cli diff --git a/tsconfig.base.json b/tsconfig.base.json index e17218e..6d81bf6 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -5,9 +5,7 @@ "moduleResolution": "NodeNext", "lib": ["ES2022"], "baseUrl": ".", - "paths": { - "@firebreak/shared": ["packages/shared/src/index.ts"] - }, + "paths": {}, "strict": true, "skipLibCheck": true, "declaration": true, diff --git a/tsconfig.json b/tsconfig.json index 8574109..ef59135 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,7 +1,6 @@ { "files": [], "references": [ - { "path": "./packages/shared" }, - { "path": "./packages/cli" } + { "path": "./cli" } ] } \ No newline at end of file diff --git a/web/app/static/img/firebreak-logo-black.svg b/web/app/static/img/firebreak-logo-black.svg deleted file mode 100644 index 809a132..0000000 --- a/web/app/static/img/firebreak-logo-black.svg +++ /dev/null @@ -1,3 +0,0 @@ - - - diff --git a/web/app/static/img/firebreak-logo-cream-red.svg b/web/app/static/img/firebreak-logo-cream-red.svg deleted file mode 100644 index c54dc25..0000000 --- a/web/app/static/img/firebreak-logo-cream-red.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - - - - - - - - - - - diff --git a/web/pyproject.toml b/web/pyproject.toml index d2447c5..b13d121 100644 --- a/web/pyproject.toml +++ b/web/pyproject.toml @@ -8,7 +8,6 @@ version = "0.1.0" description = "Firebreak: FastAPI + HTMX web interface for managing Forgejo repositories" requires-python = ">=3.13" dependencies = [ - "aiofiles>=24.1.0", "asyncpg>=0.31.0", "cryptography>=48.0.1", "fastapi>=0.136.0", diff --git a/web/uv.lock b/web/uv.lock index 1e60614..8b6b67c 100644 --- a/web/uv.lock +++ b/web/uv.lock @@ -6,15 +6,6 @@ resolution-markers = [ "python_full_version < '3.15'", ] -[[package]] -name = "aiofiles" -version = "25.1.0" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/41/c3/534eac40372d8ee36ef40df62ec129bee4fdb5ad9706e58a29be53b2c970/aiofiles-25.1.0.tar.gz", hash = "sha256:a8d728f0a29de45dc521f18f07297428d56992a742f0cd2701ba86e44d23d5b2", size = 46354, upload-time = "2025-10-09T20:51:04.358Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/bc/8a/340a1555ae33d7354dbca4faa54948d76d89a27ceef032c8c3bc661d003e/aiofiles-25.1.0-py3-none-any.whl", hash = "sha256:abe311e527c862958650f9438e859c1fa7568a141b22abcd015e120e86a85695", size = 14668, upload-time = "2025-10-09T20:51:03.174Z" }, -] - [[package]] name = "annotated-doc" version = "0.0.4" @@ -335,7 +326,6 @@ name = "firebreak-web" version = "0.1.0" source = { virtual = "." } dependencies = [ - { name = "aiofiles" }, { name = "asyncpg" }, { name = "cryptography" }, { name = "fastapi" }, @@ -358,7 +348,6 @@ dev = [ [package.metadata] requires-dist = [ - { name = "aiofiles", specifier = ">=24.1.0" }, { name = "asyncpg", specifier = ">=0.31.0" }, { name = "cryptography", specifier = ">=48.0.1" }, { name = "fastapi", specifier = ">=0.136.0" },