gsdd-cli 0.18.5 → 0.19.1

package/distilled/templates/codebase/concerns.md

@@ -1,95 +1,95 @@
-# Codebase Concerns
-
-**Analysis Date:** [YYYY-MM-DD]
-
-<guidelines>
-- Every concern must include concrete file paths.
-- Be specific with measurements (e.g., "p95 500ms") not adjectives ("slow").
-- Include reproduction steps for bugs, and "safe change" advice for fragile areas.
-- This document is about risk and leverage: what breaks, where, and how to change safely.
-</guidelines>
-
-## Tech Debt
-
-Area/component: [Name]
-- Issue: [What's the shortcut/workaround]
-- Files: `[file paths]`
-- Impact: [What breaks or degrades]
-- Fix approach: [How to address it]
-
-## Known Bugs
-
-Bug: [Description]
-- Symptoms: [What happens]
-- Files: `[file paths]`
-- Trigger: [How to reproduce]
-- Workaround: [If any]
-
-## Security Considerations
-
-Area: [Name]
-- Risk: [What could go wrong]
-- Files: `[file paths]`
-- Current mitigation: [What's in place]
-- Recommendations: [What should be added]
-
-## Performance Bottlenecks
-
-Operation: [Name]
-- Problem: [What is slow]
-- Files: `[file paths]`
-- Measurement: [numbers, if known]
-- Suspected cause: [why]
-- Improvement path: [how]
-
-## Fragile Areas
-
-Component/module: [Name]
-- Files: `[file paths]`
-- Why fragile: [what makes it break easily]
-- Safe modification: [how to change safely]
-- Test coverage: [gaps]
-
-## Dependency Risks
-
-Dependency: [Package/service]
-- Risk: [what is wrong]
-- Impact: [what breaks]
-- Mitigation: [what to do]
-
-## Missing Critical Features (If Any)
-
-Feature gap: [Name]
-- Problem: [what is missing]
-- Blocks: [what can't be done]
-
-## Test Coverage Gaps
-
-Untested area: [Name]
-- What's not tested: [specific functionality]
-- Files: `[file paths]`
-- Risk: [what could break unnoticed]
-- Priority: [High/Medium/Low]
-
-<good_examples>
-Example (good):
-- "Auth refresh tokens are stored unencrypted in `src/auth/tokenStore.ts` and logged in `src/auth/logger.ts` (risk: credential leakage). Fix: remove token logging and encrypt at rest. Repro: enable debug logging and observe tokens in logs."
-- "Checkout endpoint p95 is 1.8s in staging due to N+1 queries in `src/db/orders.ts` (see `getOrdersForUser`). Fix: batch query and add integration test asserting query count."
-</good_examples>
-
-## Downstream Impact Ranking
-
-Rank the top 3 concerns by how much future work they block. Use the Change Routing table in ARCHITECTURE.md as reference: concerns that block multiple change-routing rows rank highest.
-
-| Rank | Concern | Blocks | Severity | Fix effort |
-|------|---------|--------|----------|------------|
-| 1 | [Concern name] | [Which change types from ARCHITECTURE.md this blocks] | critical/moderate/minor | [small/medium/large] |
-| 2 | [Concern name] | [Blocks] | [Severity] | [Effort] |
-| 3 | [Concern name] | [Blocks] | [Severity] | [Effort] |
-
-Ranking heuristic: a concern that blocks 3 change-routing rows ranks above one that blocks 1, even if the latter is more severe in isolation.
-
----
-
-*Concerns audit: [date]*
-
+# Codebase Concerns
+
+**Analysis Date:** [YYYY-MM-DD]
+
+<guidelines>
+- Every concern must include concrete file paths.
+- Be specific with measurements (e.g., "p95 500ms") not adjectives ("slow").
+- Include reproduction steps for bugs, and "safe change" advice for fragile areas.
+- This document is about risk and leverage: what breaks, where, and how to change safely.
+</guidelines>
+
+## Tech Debt
+
+Area/component: [Name]
+- Issue: [What's the shortcut/workaround]
+- Files: `[file paths]`
+- Impact: [What breaks or degrades]
+- Fix approach: [How to address it]
+
+## Known Bugs
+
+Bug: [Description]
+- Symptoms: [What happens]
+- Files: `[file paths]`
+- Trigger: [How to reproduce]
+- Workaround: [If any]
+
+## Security Considerations
+
+Area: [Name]
+- Risk: [What could go wrong]
+- Files: `[file paths]`
+- Current mitigation: [What's in place]
+- Recommendations: [What should be added]
+
+## Performance Bottlenecks
+
+Operation: [Name]
+- Problem: [What is slow]
+- Files: `[file paths]`
+- Measurement: [numbers, if known]
+- Suspected cause: [why]
+- Improvement path: [how]
+
+## Fragile Areas
+
+Component/module: [Name]
+- Files: `[file paths]`
+- Why fragile: [what makes it break easily]
+- Safe modification: [how to change safely]
+- Test coverage: [gaps]
+
+## Dependency Risks
+
+Dependency: [Package/service]
+- Risk: [what is wrong]
+- Impact: [what breaks]
+- Mitigation: [what to do]
+
+## Missing Critical Features (If Any)
+
+Feature gap: [Name]
+- Problem: [what is missing]
+- Blocks: [what can't be done]
+
+## Test Coverage Gaps
+
+Untested area: [Name]
+- What's not tested: [specific functionality]
+- Files: `[file paths]`
+- Risk: [what could break unnoticed]
+- Priority: [High/Medium/Low]
+
+<good_examples>
+Example (good):
+- "Auth refresh tokens are stored unencrypted in `src/auth/tokenStore.ts` and logged in `src/auth/logger.ts` (risk: credential leakage). Fix: remove token logging and encrypt at rest. Repro: enable debug logging and observe tokens in logs."
+- "Checkout endpoint p95 is 1.8s in staging due to N+1 queries in `src/db/orders.ts` (see `getOrdersForUser`). Fix: batch query and add integration test asserting query count."
+</good_examples>
+
+## Downstream Impact Ranking
+
+Rank the top 3 concerns by how much future work they block. Use the Change Routing table in ARCHITECTURE.md as reference: concerns that block multiple change-routing rows rank highest.
+
+| Rank | Concern | Blocks | Severity | Fix effort |
+|------|---------|--------|----------|------------|
+| 1 | [Concern name] | [Which change types from ARCHITECTURE.md this blocks] | critical/moderate/minor | [small/medium/large] |
+| 2 | [Concern name] | [Blocks] | [Severity] | [Effort] |
+| 3 | [Concern name] | [Blocks] | [Severity] | [Effort] |
+
+Ranking heuristic: a concern that blocks 3 change-routing rows ranks above one that blocks 1, even if the latter is more severe in isolation.
+
+---
+
+*Concerns audit: [date]*
+

package/distilled/templates/codebase/conventions.md

@@ -1,193 +1,193 @@
-# Codebase Conventions
-
-**Analysis Date:** [YYYY-MM-DD]
-
-<guidelines>
-- This document is durable intent (rules/patterns), not a directory dump.
-- Be prescriptive. If 80%+ of the codebase follows a pattern, document it as a rule ("Use X"), not as a survey ("Sometimes X").
-- Every non-trivial claim must include at least one concrete file path example.
-- Prefer "how to do it here" over general best practices.
-- Capture testing and mocking boundaries explicitly ("what NOT to mock"). Missing boundaries cause broken tests and slow CI.
-- Capture external integration patterns (webhook verification, auth session management). Missing these causes security vulnerabilities.
-</guidelines>
-
-## Naming Patterns
-
-Files:
-- [Pattern observed]
-
-Functions:
-- [Pattern observed]
-
-Variables:
-- [Pattern observed]
-
-Types:
-- [Pattern observed]
-
-## Code Style
-
-Formatting:
-- Tool: [Tool used]
-- Key settings: [Key settings]
-
-Linting:
-- Tool: [Tool used]
-- Key rules: [Key rules]
-
-## Import Organization
-
-Order:
-1. [First group]
-2. [Second group]
-3. [Third group]
-
-Path aliases:
-- [Aliases used]
-
-## Error Handling
-
-Patterns:
-- [How errors are handled]
-- Examples: `[file paths]`
-
-## Logging
-
-Framework:
-- [Tool or "console"]
-
-Patterns:
-- [When/how to log]
-- Examples: `[file paths]`
-
-## Module / Function Design
-
-Function size:
-- [Guidelines]
-
-Parameters:
-- [Pattern]
-
-Return values:
-- [Pattern]
-
-Exports:
-- [Pattern]
-
-## Convention Adoption Rates
-
-For each major convention documented above, estimate adoption rate using grep-counting (count occurrences in production source files, exclude `node_modules`, `vendor`, generated files). Use the format `~N% (stable|rising|declining)`.
-
-- Pattern requires ≥5 occurrences to estimate; below that, write "prevalence unknown — seen in multiple files."
-- Trend signal: stable = consistent across file age, rising = newer files adopt more, declining = older files adopt more.
-
-Examples:
-- Constructor injection: `~84% (declining)` — 37 of 44 service classes; newer files use factory functions
-- camelCase exports: `~100% (stable)` — enforced by lint rule, zero violations found
-- Inline error handling: `~62% (rising)` — 18 of 29 handlers; recent PRs consistently use this
-
-Replace examples with findings from this codebase.
-
-## Testing And Mocking (High-Leverage)
-
-Test types used:
-- Unit: [yes/no] (runner: [tool]) - examples: `[file paths]`
-- Integration: [yes/no] - examples: `[file paths]`
-- E2E: [yes/no] - examples: `[file paths]`
-
-Where tests live:
-- Unit tests: `[path pattern]`
-- Integration tests: `[path pattern]`
-- E2E tests: `[path pattern]`
-
-Fixtures and factories:
-- Where fixtures live: `[path pattern]`
-- Preferred factory pattern: [pattern]
-
-Mocking boundaries (explicit):
-- Do mock: [what is safe to mock here]
-- Do NOT mock: [what must remain real]
-- Why: [rationale grounded in this codebase]
-- Examples: `[file paths]`
-
-External calls:
-- Network calls in tests: [allowed/blocked]
-- How HTTP is stubbed: [pattern] - examples: `[file paths]`
-- DB usage in tests: [pattern] - examples: `[file paths]`
-
-CI reliability rules:
-- Timeouts: [standard value if any]
-- Flake policy: [rerun policy or "none"]
-- Test parallelism constraints: [if any]
-
-<good_examples>
-Example (good):
-- "All HTTP clients must be injected via `src/lib/http/client.ts` and mocked via `test/utils/mockHttp.ts` (do NOT mock `fetch` directly). See `src/services/billing.ts` and `test/services/billing.test.ts`."
-- "Integration tests use a real Postgres via Docker Compose. Do NOT mock DB queries; instead use `test/fixtures/dbSeed.ts`. See `test/integration/users.test.ts`."
-
-Example (bad):
-- "We use Jest and sometimes integration tests." (no paths, no boundaries, no rules)
-</good_examples>
-
-## External Integration Patterns (Security-Critical)
-
-Capture these only if external integrations exist. Missing these causes subtle security bugs.
-
-### Webhook Verification
-- Webhook endpoints: `[paths]`
-- Signature verification method: [HMAC-SHA256 / provider-specific / none]
-- Where verification happens: `[file path]` (middleware? route handler?)
-- Verified before or after parsing payload: [before — always verify raw body]
-- Do NOT: parse JSON before verifying signature (timing attacks)
-- Examples: `[file paths for webhook handlers]`
-
-### Authentication and Session Management
-- Auth provider: [JWT / session cookie / OAuth / API key / none]
-- Token storage (client): [httpOnly cookie / localStorage / memory]
-- Token storage (server): [Redis / DB / stateless]
-- Refresh logic: [how tokens are refreshed, where that code lives]
-- Where auth is enforced: [middleware path / per-route / both]
-- Protected vs public routes: [pattern or file]
-- Do NOT: store tokens in localStorage for sensitive apps (XSS risk)
-- Examples: `[file paths for auth middleware]`
-
-### Environment Configuration
-- Config loading: `[file path]` (e.g., `src/config/index.ts`)
-- Environment-specific overrides: [dev/staging/prod distinction]
-- Secrets access pattern: [env var / secrets manager / vault]
-- Do NOT: hardcode secrets; do NOT commit `.env` files
-- Examples: `[file paths]`
-
-### Observability Hooks
-- Request logging: [tool + where it's configured]
-- Error tracking: [tool + integration file path]
-- Performance monitoring: [tool + integration point]
-- Health check endpoint: `[path]` (e.g., `/health`)
-- Examples: `[file paths]`
-
-<good_examples>
-Example (good):
-- "Stripe webhooks are verified via `src/webhooks/stripe.ts:verifyStripeSignature()` using the raw request body before JSON parsing. Do NOT route Stripe events through the JSON body parser middleware. See `src/middleware/webhooks.ts`."
-- "Auth tokens are httpOnly cookies (not localStorage). Refresh happens via `src/auth/refresh.ts` called by the global axios interceptor. Token expiry = 15min access, 7-day refresh. See `src/lib/http.ts`."
-- "All secrets come from env vars loaded via `src/config/env.ts`. Never read `process.env` directly outside that file. Dev/staging/prod configs are in `.env.example`, `.env.staging`, `.env.production` (secrets redacted, committed)."
-
-Example (bad):
-- "We use JWT and have some webhooks." (no paths, no security rules, no boundaries)
-</good_examples>
-
-## Golden Files
-
-Identify 3–5 files that best exemplify this codebase's conventions. Selection algorithm: highest density of documented conventions in production feature files (not scaffolding, not generated code, not test files).
-
-Format: `file path — what makes it a good example`
-
-- `[path/to/file.ts]` — [which conventions it demonstrates, e.g., "named exports, constructor injection, custom error class, full test coverage"]
-- `[path/to/file.ts]` — [conventions it demonstrates]
-- `[path/to/file.ts]` — [conventions it demonstrates]
-
-If no single file exemplifies multiple conventions, list the best per-category file instead.
-
----
-
-*Convention analysis: [date]*
-
+# Codebase Conventions
+
+**Analysis Date:** [YYYY-MM-DD]
+
+<guidelines>
+- This document is durable intent (rules/patterns), not a directory dump.
+- Be prescriptive. If 80%+ of the codebase follows a pattern, document it as a rule ("Use X"), not as a survey ("Sometimes X").
+- Every non-trivial claim must include at least one concrete file path example.
+- Prefer "how to do it here" over general best practices.
+- Capture testing and mocking boundaries explicitly ("what NOT to mock"). Missing boundaries cause broken tests and slow CI.
+- Capture external integration patterns (webhook verification, auth session management). Missing these causes security vulnerabilities.
+</guidelines>
+
+## Naming Patterns
+
+Files:
+- [Pattern observed]
+
+Functions:
+- [Pattern observed]
+
+Variables:
+- [Pattern observed]
+
+Types:
+- [Pattern observed]
+
+## Code Style
+
+Formatting:
+- Tool: [Tool used]
+- Key settings: [Key settings]
+
+Linting:
+- Tool: [Tool used]
+- Key rules: [Key rules]
+
+## Import Organization
+
+Order:
+1. [First group]
+2. [Second group]
+3. [Third group]
+
+Path aliases:
+- [Aliases used]
+
+## Error Handling
+
+Patterns:
+- [How errors are handled]
+- Examples: `[file paths]`
+
+## Logging
+
+Framework:
+- [Tool or "console"]
+
+Patterns:
+- [When/how to log]
+- Examples: `[file paths]`
+
+## Module / Function Design
+
+Function size:
+- [Guidelines]
+
+Parameters:
+- [Pattern]
+
+Return values:
+- [Pattern]
+
+Exports:
+- [Pattern]
+
+## Convention Adoption Rates
+
+For each major convention documented above, estimate adoption rate using grep-counting (count occurrences in production source files, exclude `node_modules`, `vendor`, generated files). Use the format `~N% (stable|rising|declining)`.
+
+- Pattern requires ≥5 occurrences to estimate; below that, write "prevalence unknown — seen in multiple files."
+- Trend signal: stable = consistent across file age, rising = newer files adopt more, declining = older files adopt more.
+
+Examples:
+- Constructor injection: `~84% (declining)` — 37 of 44 service classes; newer files use factory functions
+- camelCase exports: `~100% (stable)` — enforced by lint rule, zero violations found
+- Inline error handling: `~62% (rising)` — 18 of 29 handlers; recent PRs consistently use this
+
+Replace examples with findings from this codebase.
+
+## Testing And Mocking (High-Leverage)
+
+Test types used:
+- Unit: [yes/no] (runner: [tool]) - examples: `[file paths]`
+- Integration: [yes/no] - examples: `[file paths]`
+- E2E: [yes/no] - examples: `[file paths]`
+
+Where tests live:
+- Unit tests: `[path pattern]`
+- Integration tests: `[path pattern]`
+- E2E tests: `[path pattern]`
+
+Fixtures and factories:
+- Where fixtures live: `[path pattern]`
+- Preferred factory pattern: [pattern]
+
+Mocking boundaries (explicit):
+- Do mock: [what is safe to mock here]
+- Do NOT mock: [what must remain real]
+- Why: [rationale grounded in this codebase]
+- Examples: `[file paths]`
+
+External calls:
+- Network calls in tests: [allowed/blocked]
+- How HTTP is stubbed: [pattern] - examples: `[file paths]`
+- DB usage in tests: [pattern] - examples: `[file paths]`
+
+CI reliability rules:
+- Timeouts: [standard value if any]
+- Flake policy: [rerun policy or "none"]
+- Test parallelism constraints: [if any]
+
+<good_examples>
+Example (good):
+- "All HTTP clients must be injected via `src/lib/http/client.ts` and mocked via `test/utils/mockHttp.ts` (do NOT mock `fetch` directly). See `src/services/billing.ts` and `test/services/billing.test.ts`."
+- "Integration tests use a real Postgres via Docker Compose. Do NOT mock DB queries; instead use `test/fixtures/dbSeed.ts`. See `test/integration/users.test.ts`."
+
+Example (bad):
+- "We use Jest and sometimes integration tests." (no paths, no boundaries, no rules)
+</good_examples>
+
+## External Integration Patterns (Security-Critical)
+
+Capture these only if external integrations exist. Missing these causes subtle security bugs.
+
+### Webhook Verification
+- Webhook endpoints: `[paths]`
+- Signature verification method: [HMAC-SHA256 / provider-specific / none]
+- Where verification happens: `[file path]` (middleware? route handler?)
+- Verified before or after parsing payload: [before — always verify raw body]
+- Do NOT: parse JSON before verifying signature (timing attacks)
+- Examples: `[file paths for webhook handlers]`
+
+### Authentication and Session Management
+- Auth provider: [JWT / session cookie / OAuth / API key / none]
+- Token storage (client): [httpOnly cookie / localStorage / memory]
+- Token storage (server): [Redis / DB / stateless]
+- Refresh logic: [how tokens are refreshed, where that code lives]
+- Where auth is enforced: [middleware path / per-route / both]
+- Protected vs public routes: [pattern or file]
+- Do NOT: store tokens in localStorage for sensitive apps (XSS risk)
+- Examples: `[file paths for auth middleware]`
+
+### Environment Configuration
+- Config loading: `[file path]` (e.g., `src/config/index.ts`)
+- Environment-specific overrides: [dev/staging/prod distinction]
+- Secrets access pattern: [env var / secrets manager / vault]
+- Do NOT: hardcode secrets; do NOT commit `.env` files
+- Examples: `[file paths]`
+
+### Observability Hooks
+- Request logging: [tool + where it's configured]
+- Error tracking: [tool + integration file path]
+- Performance monitoring: [tool + integration point]
+- Health check endpoint: `[path]` (e.g., `/health`)
+- Examples: `[file paths]`
+
+<good_examples>
+Example (good):
+- "Stripe webhooks are verified via `src/webhooks/stripe.ts:verifyStripeSignature()` using the raw request body before JSON parsing. Do NOT route Stripe events through the JSON body parser middleware. See `src/middleware/webhooks.ts`."
+- "Auth tokens are httpOnly cookies (not localStorage). Refresh happens via `src/auth/refresh.ts` called by the global axios interceptor. Token expiry = 15min access, 7-day refresh. See `src/lib/http.ts`."
+- "All secrets come from env vars loaded via `src/config/env.ts`. Never read `process.env` directly outside that file. Dev/staging/prod configs are in `.env.example`, `.env.staging`, `.env.production` (secrets redacted, committed)."
+
+Example (bad):
+- "We use JWT and have some webhooks." (no paths, no security rules, no boundaries)
+</good_examples>
+
+## Golden Files
+
+Identify 3–5 files that best exemplify this codebase's conventions. Selection algorithm: highest density of documented conventions in production feature files (not scaffolding, not generated code, not test files).
+
+Format: `file path — what makes it a good example`
+
+- `[path/to/file.ts]` — [which conventions it demonstrates, e.g., "named exports, constructor injection, custom error class, full test coverage"]
+- `[path/to/file.ts]` — [conventions it demonstrates]
+- `[path/to/file.ts]` — [conventions it demonstrates]
+
+If no single file exemplifies multiple conventions, list the best per-category file instead.
+
+---
+
+*Convention analysis: [date]*
+