From e7a2aa8df39957f333161d994508ee208e67168a Mon Sep 17 00:00:00 2001 From: Tyler Gillispie Date: Tue, 25 Aug 2026 20:31:09 -0700 Subject: [PATCH] docs(tasks): establish refined modularization specs ph3.1 and ph4.1 --- ...nolith-decomposition-roadmap-1845.ph3.1.md | 55 +++++++++++++++++++ ...nolith-decomposition-roadmap-1845.ph4.1.md | 51 +++++++++++++++++ 2 files changed, 106 insertions(+) create mode 100644 tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph3.1.md create mode 100644 tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph4.1.md diff --git a/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph3.1.md b/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph3.1.md new file mode 100644 index 0000000..b762fda --- /dev/null +++ b/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph3.1.md @@ -0,0 +1,55 @@ +# TASK METADATA + +- **Target Files:** `server/routes/admin.ts`, `server/routes/auth.ts`, + `server/routes/admin/*.ts`, `server/routes/auth/*.ts`, `server/main.ts` +- **Core Objective:** Phase 3.1 (Domain Route Modularization): Decompose the + monolithic 865-line `server/routes/admin.ts` and 928-line + `server/routes/auth.ts` into clean, domain-isolated sub-routers under + `server/routes/admin/` and `server/routes/auth/`. +- **Dependencies:** + `tasks/complete/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph3.md` +- **Additional Important Notes:** Must preserve 100% route path compatibility, + zero-trust scope guards (`requireAdmin`, `requirePrimarySession`), rate + limiting middlewares, and pass all 59 tests. + +--- + +### 2. Architectural Considerations & Risks + +- **Risks:** + - Route mounting path mismatches (e.g. prefix collisions when mounting + sub-routers in Hono). + - Scope guard bypass if `requireAdmin` or `requirePrimarySession` is not + applied at the top of domain routers. +- **Alternatives:** + - Keeping 900-line monolithic route files; rejected because it mashes + unrelated business domains and violates SRP. + +### 3. Proposed Implementation + +1. **Decompose `server/routes/admin.ts` into `server/routes/admin/`:** + - `server/routes/admin/users.ts`: `/users`, `/users/:id/status`, + `/users/:id/profile`, `/users/:id/grants`, `/users/:id/recovery`. + - `server/routes/admin/apps.ts`: `/apps`, `/apps/:id` CRUD. + - `server/routes/admin/roles.ts`: `/roles`, `/roles/:id` RBAC CRUD. + - `server/routes/admin/invites.ts`: `/invites`, `/invites/create`, + `/invites/:id/redemptions`, `/invites/:id`. + - `server/routes/admin/hardware_keys.ts`: `/aaguid`, `/hwk`. + - `server/routes/admin/audit.ts`: `/audit-logs`, `/check`, `/sessions/:id`. + - `server/routes/admin/index.ts` (or `admin.ts` entry router): Mounts the + sub-routers and enforces `requireAdmin` + `adminRateLimiter`. + +2. **Decompose `server/routes/auth.ts` into `server/routes/auth/`:** + - `server/routes/auth/register.ts`: `/.well-known/webauthn`, + `/api/register/challenge`, `/api/register/verify`. + - `server/routes/auth/login.ts`: `/api/login/challenge`, `/api/login/verify`. + - `server/routes/auth/passkeys.ts`: `/api/passkeys/register/challenge`, + `/api/passkeys/register/verify`, `GET /api/passkeys`, + `DELETE /api/passkeys/:id` guarded by `requirePrimarySession`. + - `server/routes/auth/guest.ts`: `/api/guests/sandbox`, `/api/revoke`. + - `server/routes/auth/index.ts` (or `auth.ts` entry router): Assembles the + auth sub-routers. + +3. **Quality Gates & Validation:** + - Run `deno fmt`, `deno task lint`, `deno task check`. + - Run `deno test --allow-all` (all 59 tests must pass). diff --git a/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph4.1.md b/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph4.1.md new file mode 100644 index 0000000..842f4fb --- /dev/null +++ b/tasks/new/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph4.1.md @@ -0,0 +1,51 @@ +# TASK METADATA + +- **Target Files:** `infra/setup/cli.ts`, `infra/setup/prompts/*.ts`, + `infra/setup/commands/*.ts` +- **Core Objective:** Phase 4.1 (CLI Setup Modularization): Decompose the + 772-line `infra/setup/cli.ts` monolith into isolated prompt flows and Cliffy + command modules under `infra/setup/prompts/` and `infra/setup/commands/`. +- **Dependencies:** + `tasks/complete/2026-0825.01.jul.story.arch.monolith-decomposition-roadmap-1845.ph4.md` +- **Additional Important Notes:** Must reduce `infra/setup/cli.ts` to a clean + ~60-line router, pass `deno check infra/setup.ts`, and preserve all CLI + subcommands (`auth`, `test`, `build`, `compile_proto`, `dump_compose`, + `spire`, `secrets`, `wizard`). + +--- + +### 2. Architectural Considerations & Risks + +- **Risks:** + - Breaking CLI argument parsing or flag inheritance in Cliffy commands if + command action handlers are miswired. +- **Alternatives:** + - Leaving 772 lines in `cli.ts`; rejected because it violates the Single + Responsibility Principle and combines UI prompts, network testers, and + command routing into one file. + +### 3. Proposed Implementation + +1. **Extract Interactive Prompts (`infra/setup/prompts/`):** + - `infra/setup/prompts/auth.ts`: `promptAuthConfig`, `promptSpireConfig`, + `promptConfirmation`. + - `infra/setup/prompts/wizard.ts`: `runSetupWizard`, `handleReviewConfigs`. + +2. **Extract CLI Subcommands (`infra/setup/commands/`):** + - `infra/setup/commands/auth.ts`: `auth` command action & setup file + generator. + - `infra/setup/commands/test.ts`: `test` connection action + (`handleTestConnection`). + - `infra/setup/commands/build.ts`: `build` and `compile_proto` command + actions. + - `infra/setup/commands/compose.ts`: `dump_compose` and `spire` command + actions. + - `infra/setup/commands/secrets.ts`: `secrets` command action. + +3. **Refactor `infra/setup/cli.ts`:** + - Keep `cli.ts` purely as the lightweight Cliffy Command router (~60-80 + lines) registering the command modules and executing `runCli(args)`. + +4. **Quality Gates & Validation:** + - Run `deno check infra/setup.ts`. + - Run `deno fmt infra/` and `deno test --allow-all`.