From 9569ac684035ab83178d45942052505f610b614f Mon Sep 17 00:00:00 2001 From: zbigniew sobiecki Date: Wed, 15 Apr 2026 19:05:30 +0200 Subject: [PATCH 01/10] docs(plans): add spec 002 and plans; lock plan 002/1 Spec 002 (linear-webhook-setup-ux) introduces the Linear wizard UX improvements and save-path fix. Plan 1 locked for execution. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../1-save-path-fix.md.wip | 215 +++++++++++++++ .../2-wizard-webhooks-step.md | 251 ++++++++++++++++++ .../002-linear-webhook-setup-ux/_coverage.md | 38 +++ docs/specs/002-linear-webhook-setup-ux.md | 155 +++++++++++ 4 files changed, 659 insertions(+) create mode 100644 docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md.wip create mode 100644 docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md create mode 100644 docs/plans/002-linear-webhook-setup-ux/_coverage.md create mode 100644 docs/specs/002-linear-webhook-setup-ux.md diff --git a/docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md.wip b/docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md.wip new file mode 100644 index 00000000..ac0a46c3 --- /dev/null +++ b/docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md.wip @@ -0,0 +1,215 @@ +--- +id: 002 +slug: linear-webhook-setup-ux +plan: 1 +plan_slug: save-path-fix +level: plan +parent_spec: docs/specs/002-linear-webhook-setup-ux.md +depends_on: [] +status: wip +--- + +# 002/1: Linear Wizard Save — Unblock, Diagnose, Harden + +> Part 1 of 2 in the 002-linear-webhook-setup-ux plan. See [parent spec](../../specs/002-linear-webhook-setup-ux.md). + +## Summary + +Plan 1 fixes the `POST /trpc/projects.integrations.upsert` 500 that currently prevents anyone from completing the Linear wizard on the dev environment, and hardens the tRPC / Hono error path so the next failure of this shape is **immediately diagnosable from server logs** instead of invisible behind a generic "Internal Server Error". + +The work has three phases in order: + +1. **Surface** — change the dashboard server error path (`app.onError` in `src/dashboard.ts`) and the tRPC error formatter so that when a `.mutation(...)` throws a DB error, the server log contains the real message (and, for PG errors, the constraint / detail fields), not just `String(err)`. This must land before step 2 — otherwise we are guessing. +2. **Diagnose** — once step 1 is deployed to dev, provoke the failing upsert for project `llmist` via the dashboard (or the `ssh satellite` curl path) and read the actual error from dev container logs. This is a short root-cause spike, not a re-architecture. +3. **Fix** — write the failing test that reproduces the error observed in step 2 against a real PG integration test fixture, then write the code fix in `src/db/repositories/integrationsRepository.ts` (or wherever the surfaced error points) that makes the test pass. + +Plan 1 ships **no user-visible UI change**. Its value is: the Linear wizard's Save button stops returning 500 on the dev environment, and any future server-side failure along the credential/integration save path has an actionable log line. Plan 2 (wizard UX) depends on this so it can be verified end-to-end in a browser. + +**Components delivered:** +- Updated Hono `app.onError` handler in `src/dashboard.ts` with structured error logging (message + stack + PG `code`/`detail`/`constraint` when present). +- Updated tRPC instance in `src/api/trpc.ts` with an `errorFormatter` that preserves server-side diagnostic fields in the server log while returning only a safe message to the client. +- Whatever specific fix the diagnosis uncovers in `src/db/repositories/integrationsRepository.ts` or `src/api/routers/projects.ts` (exact shape finalized in step 2). +- Log-hygiene assertion: a test that exercises the upsert and credential-save path and asserts plaintext credentials never land in logs. + +**Deferred to later plans in this spec:** +- All wizard UX changes (events list copy, inline `ProjectSecretField`, step composition) — plan 2. +- End-to-end browser walk-through of the full wizard flow — plan 2 owns the integration test for that. + +--- + +## Spec ACs satisfied by this plan + +- Spec AC #5 (Save succeeds end-to-end on a fresh project) — **full** +- Spec AC #6 (Save succeeds on re-configuration) — **full** +- Spec AC #7 (Save failures diagnosable via server log) — **full** +- Spec AC #8 (No secret leakage in plaintext logs) — **full** + +--- + +## Depends On + +- Nothing — plan 1 is the foundation layer. + +Context to lift from the spec (do not re-argue): +- Signing secret stays **optional**; verification behavior is unchanged (Strategic decision #3). +- No schema change (Constraint: "No breaking change to project credentials, DB schema, or configuration surface."). +- Root cause is unknown until step 2; do not pre-commit to a guess (Strategic decision #5: "Diagnosability is a first-class outcome."). + +--- + +## Detailed Task List (TDD) + +### 1. Surface: structured error logging in the tRPC + Hono pipeline + +**Tests first** (`tests/unit/api/error-logging.test.ts` — new file): + +- `logs full message + stack for thrown Error in mutation` — stub a procedure that throws `new Error('boom')`, assert the `console.error` spy receives an object containing `message: 'boom'` and a `stack` string. +- `logs PG error code + detail + constraint when Drizzle wraps a pg error` — stub a procedure that throws an object shaped like a PG error (`{ code: '23505', detail: 'Key (x)=(y) already exists.', constraint: 'c', message: '...' }`), assert those fields are present in the logged payload. +- `does not log credential values when the error references them` — stub a procedure that throws `new Error('failed saving LINEAR_WEBHOOK_SECRET=lin_wh_plaintext')`, assert the `console.error` spy's serialized output never contains `lin_wh_plaintext`. (Implementation: redact known credential-value-shaped fragments, OR — simpler and adequate — never include the raw `stack`/`message` when they contain the env-var value; rely on the stored-credential pipeline not interpolating secrets into errors in the first place, and make this test a tripwire if it ever starts doing so.) +- `returns a safe client payload when a server error occurs` — assert the tRPC response body for a thrown non-TRPCError contains a generic message (not the raw error) while the log still has the full error. + +**Implementation** (`src/dashboard.ts` + `src/api/trpc.ts`): + +- In `src/dashboard.ts`, replace the `app.onError((err, c) => { console.error('Unhandled error', { error: String(err), path: c.req.path }); ... })` block. New shape: + - Build a `payload` object: `{ path: c.req.path, method: c.req.method, message: err.message, name: err.name, stack: err.stack }`. + - If `err` (or `err.cause`) has PG-error-shaped fields (`code: string`, `detail?: string`, `constraint?: string`, `table?: string`, `column?: string`), copy them onto the payload. + - Call `console.error('Unhandled error', payload)`. + - Continue calling `captureException` as before. +- In `src/api/trpc.ts`, change `initTRPC.context().create()` to pass an `errorFormatter({ shape, error })` callback: + - Shape returned to client: unchanged structure; `message` replaced with a generic `'Internal server error'` when `error.code === 'INTERNAL_SERVER_ERROR'` and the cause is not a `TRPCError`. For other tRPC codes (`UNAUTHORIZED`, `NOT_FOUND`, etc.), pass through the original message. + - Server-side: `console.error('tRPC error', { code: shape.code, path: shape.data.path, message: error.message, cause: error.cause, stack: error.stack })`. The `cause` unpacking covers Drizzle wrapping a `pg` error — inspect it for the same PG fields as above and include them explicitly. +- Typescript: define a `PgErrorFields` shape and a narrow `isPgLikeError(e: unknown): e is PgErrorFields` helper co-located in `src/api/trpc.ts` (not exported). No external types. + +### 2. Diagnose: root-cause spike + +**This step is not a test or code change — it is a procedural step.** Execute in order: + +1. Ensure step 1 is merged to `dev` and the `cascade-dashboard-dev` container is rebuilt and serving the new error path. +2. From a browser signed into the dev dashboard as the org `mongrel`, open project `llmist`, run the PM wizard for Linear through to the Save step, and click "Update Integration". +3. Capture the server log on `satellite`: + ``` + ssh satellite "docker logs cascade-dashboard-dev --since 2m 2>&1" | grep -A 5 -i 'tRPC error\|Unhandled error' + ``` +4. Record the specific error: constraint name, PG code, message, and any referenced column / value. Paste into the plan's "Diagnosis" sub-section below. +5. If the error is a PG constraint violation, cross-reference `src/db/schema/integrations.ts` for the relevant column or constraint. If it is a Zod input validation error surfaced as 500, cross-reference `src/api/routers/projects.ts`'s `upsert` input schema. +6. Do not guess. Do not patch without a named error. Exit this step with a one-line statement of the root cause. + +**Diagnosis** (fill in after running the spike): + +> _(populated during /implement; left blank at plan authoring time)_ + +Pre-commit guidance for `/implement`: the most likely culprits, ranked, are — +1. FK violation on `project_id` (project `llmist` may not exist in `projects` table under org `mongrel`). +2. JSON schema mismatch on `triggers` (column constraint expects specific shape; `{}` is passed). +3. Zod parsing of `config` rejects something the frontend sends for Linear (e.g. `statuses` nested shape). +4. Missing migration on dev (new column expected but not yet applied). + +The spike resolves which one. + +### 3. Fix + +**Tests first** (`tests/integration/db/upsertProjectIntegration.test.ts` — new file OR augment an existing one): + +Shape depends on root cause. Template: + +- `upserts a new Linear PM integration for an existing project` — create a project row, call `upsertProjectIntegration(projectId, 'pm', 'linear', { teamId, statuses, labels })` with no `triggers`, assert a row exists with the right fields and `triggers` defaults to `{}`. +- `upserts on top of an existing row, preserving triggers when omitted` — seed an integration with `triggers: { foo: true }`, call upsert without triggers, assert `triggers` is still `{ foo: true }`. +- `upserts on top of an existing row, overwriting triggers when provided` — same seed, call upsert with `triggers: { bar: false }`, assert the row now has `triggers: { bar: false }`. +- `` — seeded state that previously triggered the 500 now succeeds. Exact shape pending diagnosis. + +**Implementation** (path pending diagnosis, most likely one of): + +- `src/db/repositories/integrationsRepository.ts` — adjust `upsertProjectIntegration` if the root cause is data-shape related. +- `src/api/routers/projects.ts` — adjust the `upsert` input schema if the root cause is overly-strict Zod validation. +- `src/db/migrations/NNNN_*.sql` + `_journal.json` — add a missing migration if the root cause is schema drift. (Per spec non-goal #6, avoid schema redesign; a conservative forward-only migration to reconcile dev is acceptable.) +- `web/src/components/projects/pm-wizard-hooks.ts` — adjust the payload the wizard sends if the root cause is a bad shape on the client side. + +The fix must: +- Not introduce a "silently retry with default on error" path. Failure modes should remain loud — just diagnosable. +- Not broaden the Zod schema to accept inputs that should not be accepted. +- Not change the `triggers` column type, default, or semantics (spec non-goal). + +### 4. Log-hygiene assertion + +**Tests first** (`tests/integration/api/no-secret-leakage.test.ts` — new file): + +- `credential save path does not log plaintext value` — call `projects.credentials.set` with `envVarKey: 'LINEAR_WEBHOOK_SECRET'` and a sentinel value `'SECRET_SENTINEL_xyz'`; spy on `console.error` and `console.log` during the call; assert neither captured output contains the sentinel. +- `integration upsert path does not log config contents when successful` — success path should not log the `config` blob at info level. (Debug level logging of config is fine if it's behind an env flag; default should be quiet.) +- `integration upsert failure path does not leak credential env values` — force a failure (e.g. FK violation), assert the resulting error log payload does not include any known credential env-var value previously set on the project. + +**Implementation:** + +- No new code unless the tests above fail. If they pass against the step 1 implementation, this is purely an assertion that the new logging path does not regress secrecy. If they fail, redact the offending field in the `app.onError` payload builder. + +--- + +## Test Plan + +### Unit tests +- [ ] `tests/unit/api/error-logging.test.ts`: 4 tests covering structured error output (Error, PG-shaped, secret redaction, safe client payload). + +### Integration tests +- [ ] `tests/integration/db/upsertProjectIntegration.test.ts`: 3–4 tests covering new + re-configuration upsert paths and the specific reproduction of the diagnosed bug. +- [ ] `tests/integration/api/no-secret-leakage.test.ts`: 3 tests covering credential-save, successful-upsert, and failing-upsert log hygiene. + +### Acceptance tests +- [ ] Manual on `dev`: complete the Linear wizard Save step on project `llmist`, confirm HTTP 200 and an integration row in `project_integrations`. +- [ ] Manual on `dev`: provoke a failure (e.g. temporarily hit upsert with a bogus `projectId`), read `docker logs cascade-dashboard-dev`, confirm the PG / tRPC error details are present. + +--- + +## Acceptance Criteria (per-plan, testable) + +1. Running the Linear wizard to Save on a fresh project returns HTTP 200 and persists a `project_integrations` row with `provider='linear'` and `category='pm'`. +2. Re-running the Linear wizard on a project that already has a Linear PM integration row succeeds and updates the row (same 200 outcome). +3. When `projects.integrations.upsert` throws a server-side error, the dashboard server log (stdout of `cascade-dashboard-dev`) contains, in a single structured entry: the request path, the error message, and — when the cause is a PG error — its `code`, `detail`, and `constraint` fields. +4. When a credential is saved via `projects.credentials.set`, no captured stdout/stderr contains the plaintext value. Verified by a spy-based integration test. +5. A forced failure of the upsert (bogus `projectId`) produces a server log line with the true DB error (FK violation) and does not produce an entry that reveals any stored credential value for that project. +6. The client receives a safe, non-leaking error payload — generic `'Internal server error'` for unexpected throws, passed-through message for deliberate `TRPCError` codes. +7. All new/modified code has corresponding tests. +8. `npm run build` passes. +9. `npm test` and `npm run test:integration` pass. +10. `npm run lint` passes. +11. `npm run typecheck` passes. + +**Partial-state criterion** (dormant UI): +- No wizard UX changes are shipped in this plan. The Webhooks step still shows the old "Issues (created, updated, removed)" instructions and still directs users to the Credentials tab for `LINEAR_WEBHOOK_SECRET`. Plan 2 replaces those. + +--- + +## Documentation Impact (this plan only) + +| File | Change | +|---|---| +| `CLAUDE.md` | Add a short bullet under the existing "Review agent — context shape" / "Engines" style list: note that unhandled dashboard errors now log full PG fields when available, and that the generic 500 response is accompanied by a structured server log entry operators can grep. | +| `CHANGELOG.md` | Entry: "fix(dashboard): surface full DB error details in logs for tRPC mutations; unblock Linear wizard Save on dev". | + +Not touched in this plan (owned by plan 2): +- `src/integrations/README.md` — Linear setup instructions. + +--- + +## Out of Scope (this plan) + +- Wizard UX copy changes, the new `ProjectSecretField` in the Webhooks step, the events-list rewrite. Plan 2 owns these. +- New Linear trigger handlers (Reaction / Document / etc.) — spec non-goal. +- Redesigning the `project_integrations.triggers` column type, default, or semantics — spec non-goal. +- Automating Linear webhook creation — spec non-goal. +- Observability beyond `console.error` + existing Sentry capture (no new telemetry pipeline) — spec constraint. + +--- + +## Progress + + +- [ ] AC #1 — Save succeeds, fresh project +- [ ] AC #2 — Save succeeds, re-configuration +- [ ] AC #3 — Structured DB error in server log +- [ ] AC #4 — No plaintext credentials in logs (happy path) +- [ ] AC #5 — No plaintext credentials in logs (error path) +- [ ] AC #6 — Safe client error payload +- [ ] AC #7 — Tests exist for all new/modified code +- [ ] AC #8 — Build passes +- [ ] AC #9 — Unit + integration tests pass +- [ ] AC #10 — Lint passes +- [ ] AC #11 — Typecheck passes diff --git a/docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md b/docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md new file mode 100644 index 00000000..16b0f058 --- /dev/null +++ b/docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md @@ -0,0 +1,251 @@ +--- +id: 002 +slug: linear-webhook-setup-ux +plan: 2 +plan_slug: wizard-webhooks-step +level: plan +parent_spec: docs/specs/002-linear-webhook-setup-ux.md +depends_on: [1-save-path-fix.md] +status: pending +--- + +# 002/2: Linear Wizard Webhooks Step — Correct Events List + Inline Signing Secret + +> Part 2 of 2 in the 002-linear-webhook-setup-ux plan. See [parent spec](../../specs/002-linear-webhook-setup-ux.md). + +## Summary + +Plan 2 rewrites the Linear Webhooks step of the PM wizard so the setup instructions match what CASCADE actually consumes, and adds an inline signing-secret input next to the webhook URL. The user flow becomes: paste CASCADE's webhook URL into Linear, enable the three event families CASCADE handles, copy Linear's signing secret back into the adjacent CASCADE field, done — no detour through the Credentials tab. + +Concretely, this plan modifies `LinearWebhookInfoPanel` in `web/src/components/projects/pm-wizard-common-steps.tsx` to: + +1. Replace the `Enable events: Issues (created, updated, removed)` line with an explicit list — `Issues` (status transitions drive agent selection), `Comments` (bot @mentions trigger responses), `Issue Labels` (the "Ready to Process" label starts an agent). Each bullet carries a one-line rationale so a reviewer can verify the copy matches `src/triggers/linear/register.ts`. +2. Drop the "Optionally set a webhook secret and store it as `LINEAR_WEBHOOK_SECRET` in project credentials" trailing bullet, and instead render a `ProjectSecretField` with `envVarKey="LINEAR_WEBHOOK_SECRET"` directly underneath the webhook URL — identical in shape to the Sentry alerting tab's usage of the same component. + +End-to-end verification depends on plan 1 having unblocked the Save step: after this plan lands, completing the Linear wizard in a browser must result in a working integration row AND (optionally) a stored webhook secret without any visit to the Credentials tab. + +**Components delivered:** +- Modified `LinearWebhookInfoPanel` props and render tree in `web/src/components/projects/pm-wizard-common-steps.tsx`. +- New prop drilling from `PMWizard` → `WebhookStep` → `LinearWebhookInfoPanel` to pass the project ID and the existing `LINEAR_WEBHOOK_SECRET` credential metadata. +- Component-level tests for `LinearWebhookInfoPanel` covering event-list copy and secret-field presence / persistence / reflection. +- An integration test asserting Trello and JIRA wizard Webhooks steps are visually unchanged. +- Documentation update: `src/integrations/README.md` Linear section reflects the three-events list. + +**Deferred to later plans in this spec:** +- Nothing. Plan 2 closes out the spec. + +--- + +## Spec ACs satisfied by this plan + +- Spec AC #1 (Instructions list matches handlers) — **full** +- Spec AC #2 (Inline secret input present in Webhooks step) — **full** +- Spec AC #3 (Pasting the secret persists it as `LINEAR_WEBHOOK_SECRET`) — **full** +- Spec AC #4 (Credentials tab stays in sync) — **full** +- Spec AC #9 (No regression to Trello/JIRA wizards) — **full** +- Spec AC #10 (Other providers' webhook-secret UX unchanged) — **full** + +--- + +## Depends On + +- Plan 1 (`1-save-path-fix.md`) — provides a working `projects.integrations.upsert` on dev, without which this plan's end-to-end acceptance cannot be verified in a browser. + +Context to lift from the spec (do not re-argue): +- Webhook secret lives in the Webhooks step, not the Credentials step (Strategic decision #2). +- Signing secret remains optional (Strategic decision #3). +- Recommend exactly `Issues`, `Comments`, `Issue Labels` (Strategic decision #1) — do **not** add Reaction/Document/etc. in this plan. +- Reuse `ProjectSecretField`; do not invent a new component (Strategic decision #6). + +--- + +## Detailed Task List (TDD) + +### 1. Update `LinearWebhookInfoPanel` — events list copy + +**Tests first** (`web/tests/components/projects/LinearWebhookInfoPanel.test.tsx` — new file; pick the testing stack already used by `web/` — likely `vitest` + `@testing-library/react`, same as other `web/tests/components/**/*.test.tsx` if any, or colocate as `*.test.tsx` alongside the component if the project convention is colocated): + +- `renders a three-item events list: Issues, Comments, Issue Labels` — mount the component with a `webhookUrl`, assert three `
  • ` children inside the "Enable events" block with matching `` labels. Snapshot-free assertions via `getByText`. +- `each events-list item has a one-line rationale matching a registered trigger` — assert the rendered text contains the phrases "status transitions" (for Issues), "mentions" (for Comments), and "Ready to Process" (for Issue Labels). Enough for a reviewer to confirm the copy traces back to `src/triggers/linear/register.ts`. +- `does not mention Documents, Emoji reactions, Customer requests, Cycles, Users, Initiatives, Project updates, Projects, Issue SLA, or Issue attachments` — assert none of those strings appear in the rendered panel. Prevents copy drift. +- `keeps the manual-setup-required blue info block` — assert the "Manual Webhook Setup Required" string is still present. Protects against collateral deletion. + +**Implementation** (`web/src/components/projects/pm-wizard-common-steps.tsx`, `LinearWebhookInfoPanel`): + +- Replace the single list item (line ~110–112) with three items: + ```tsx +
  • + Enable events: +
      +
    • Issues — status transitions drive CASCADE's splitting / planning / implementation agents.
      • +
    • Comments — @mentions of the CASCADE bot trigger a response agent.
      • +
    • Issue Labels — adding the "Ready to Process" label starts an agent on the issue.
      • +
    +
    • + ``` +- Delete the trailing bullet "Optionally set a webhook secret and store it as `LINEAR_WEBHOOK_SECRET` in project credentials" — replaced by the inline field in the next task. +- Update the `
  • ` that says "Select your team and save" to come *after* the events list and to now say "Select your team and save — webhooks are team-scoped in Linear". + +### 2. Add inline `ProjectSecretField` for `LINEAR_WEBHOOK_SECRET` + +**Tests first** (same test file): + +- `renders a signing-secret input labelled "Webhook Signing Secret (optional)"` — mount with `projectId` and a `credential` prop set to `null`, assert an input with placeholder matching `lin_wh_...` is rendered. +- `shows masked-configured state when a credential is already set` — mount with `credential={{ envVarKey: 'LINEAR_WEBHOOK_SECRET', name: 'Linear Webhook Secret', isConfigured: true, maskedValue: '...abcd' }}`, assert the "Configured" badge and masked value appear. +- `saves the secret via the existing credential mutation when submitted` — mock `trpcClient.projects.credentials.set.mutate`, submit a value, assert the mutation is called with `{ projectId, envVarKey: 'LINEAR_WEBHOOK_SECRET', value, name: 'Linear Webhook Secret' }` and no other credential-save path is invoked. +- `does not render the old "store as LINEAR_WEBHOOK_SECRET in project credentials" bullet` — assert the string "in project credentials" is absent from the panel. + +**Implementation** (`web/src/components/projects/pm-wizard-common-steps.tsx`): + +- Change `LinearWebhookInfoPanel`'s signature: + ```ts + export function LinearWebhookInfoPanel({ + webhookUrl, + projectId, + webhookSecretCredential, + }: { + webhookUrl: string; + projectId: string; + webhookSecretCredential: ProjectCredentialMeta | null; + }) { ... } + ``` +- Import `ProjectSecretField` + `ProjectCredentialMeta` from `./project-secret-field.js`. +- Insert a `` block immediately after the webhook URL block and before the setup instructions list: + ```tsx + + ``` +- Update `WebhookStep` (same file, same module) to pass the new props through: + ```tsx + if (state.provider === 'linear') { + return ( + + ); + } + ``` +- Add `projectId: string` and `linearWebhookSecretCredential: ProjectCredentialMeta | null` to the `WebhookStep` props type at the top of the step-renderer block (existing interface). +- Update the callers of `WebhookStep` in `web/src/components/projects/pm-wizard.tsx` to thread `projectId` and resolve `linearWebhookSecretCredential` from the existing `credentials.list` query result (filter where `envVarKey === 'LINEAR_WEBHOOK_SECRET'`). + +### 3. Wizard-level wiring + +**Tests first** (`web/tests/components/projects/pm-wizard.test.tsx` — augment existing or add a focused test file if absent): + +- `when provider is linear and step is webhooks, LinearWebhookInfoPanel receives the project's LINEAR_WEBHOOK_SECRET credential` — mount `PMWizard` with mocked tRPC and a `credentials.list` response containing a `LINEAR_WEBHOOK_SECRET` row; advance to the Webhooks step; assert the masked state appears. +- `when the user types a new value into the secret field and moves on, credentials.set is called with LINEAR_WEBHOOK_SECRET` — mock the mutation, fire a change event, assert the call. +- `Trello Webhooks step does not render ProjectSecretField` — switch provider to `trello` and confirm no `LINEAR_WEBHOOK_SECRET` input is present. +- `JIRA Webhooks step does not render ProjectSecretField` — same for JIRA. + +**Implementation** (`web/src/components/projects/pm-wizard.tsx`): + +- Identify the `credentials.list` query (already fetched in `pm-wizard-hooks.ts` or directly in the wizard). Compute `const linearWebhookSecretCredential = credentials.find(c => c.envVarKey === 'LINEAR_WEBHOOK_SECRET') ?? null;` inside the component. +- Pass `linearWebhookSecretCredential` and `projectId` (already available via wizard state) to `` at the render-call site (~lines 373-388 of `pm-wizard.tsx`). + +### 4. Cross-check no regression for Trello and JIRA + +**Tests first** (same test file or `web/tests/components/projects/pm-wizard-webhooks-trello.test.tsx`): + +- `Trello Webhooks step UI matches pre-change snapshot` — given provider `trello` and no active webhooks, assert the "No Trello webhooks configured" message, the "Create Webhook" button, and the curl-command `
    ` block are all present unchanged. No secret field. +- `JIRA Webhooks step UI matches pre-change snapshot` — same structure for JIRA. + +**Implementation:** No code change unless tests fail. If they fail, investigate the prop drilling in task 3 to ensure Linear-only props aren't leaking into other provider branches. + +### 5. Documentation + +**Implementation** (`src/integrations/README.md`): + +- Find the Linear-related section (if present). If the setup instructions are duplicated there, rewrite them to match the new three-event list and the inline-secret flow. +- If the README only references Linear generically (no copy duplication), add a short note that the setup instructions live in the dashboard wizard and point to the component path. + +**Implementation** (`CHANGELOG.md`): + +- Add an entry: `feat(dashboard): Linear wizard — accurate events list and inline webhook signing secret (#XXXX)`. + +--- + +## Test Plan + +### Unit tests +- [ ] `web/tests/components/projects/LinearWebhookInfoPanel.test.tsx` (or colocated `.test.tsx`): 8 tests covering events-list copy, secret-field presence, masked state, save mutation, absence of deprecated bullet, preservation of manual-setup block, and four absence assertions. +- [ ] `web/tests/components/projects/pm-wizard.test.tsx` additions: 4 tests covering credential threading and Trello/JIRA non-regression. + +### Integration tests +- [ ] None added in this plan — plan 1 already covers the backend save path with integration tests. The wizard-to-save integration happens via the manual end-to-end step below. + +### Acceptance tests +- [ ] Manual on `dev`: complete the full Linear wizard on a fresh project including pasting a dummy signing secret into the new inline field; confirm the credential appears in the Credentials tab as `LINEAR_WEBHOOK_SECRET` and the integration row is persisted. +- [ ] Manual on `dev`: open the wizard on an existing project that already has `LINEAR_WEBHOOK_SECRET`; confirm the inline field shows the masked-configured state on load. +- [ ] Manual on `dev`: walk the Trello and JIRA wizards end-to-end; confirm visual and behavioral equivalence with the pre-change state. + +--- + +## Acceptance Criteria (per-plan, testable) + +1. The Linear Webhooks step renders a three-item events list (`Issues`, `Comments`, `Issue Labels`) with one-line rationales matching registered trigger handlers. +2. The Linear Webhooks step does not mention any event family CASCADE does not currently consume (specifically: Documents, Emoji reactions, Customer requests, Cycles, Users, Initiatives, Project updates, Projects, Issue SLA, Issue attachments). +3. The Linear Webhooks step renders a `ProjectSecretField` bound to `LINEAR_WEBHOOK_SECRET`, directly beneath the webhook URL. +4. Pasting a value into the inline secret input calls `projects.credentials.set` with exactly `{ projectId, envVarKey: 'LINEAR_WEBHOOK_SECRET', value, name }` and no other credential-save path. +5. When a `LINEAR_WEBHOOK_SECRET` credential already exists for the project, the inline field renders the masked-configured state on initial mount — no extra fetch required beyond the already-available `credentials.list` data. +6. Setting the credential via the Credentials tab and re-opening the wizard shows the masked-configured state on the inline field; setting it via the inline field and then opening the Credentials tab shows the same masked row — both surfaces read the same underlying credential row. +7. The Trello and JIRA Webhooks steps render byte-identically to the pre-change state (no new secret field, no changed copy, no changed curl block). +8. The Sentry alerting tab is unchanged (no imports or props altered in `integration-alerting-tab.tsx`). +9. All new/modified code has corresponding tests. +10. `npm run build` passes (root and `web/` if separate). +11. `npm test` passes. +12. `npm run lint` passes. +13. `npm run typecheck` passes. +14. The `src/integrations/README.md` Linear section reflects the three-event list, or explicitly defers to the dashboard wizard as the source of truth. + +--- + +## Documentation Impact (this plan only) + +| File | Change | +|---|---| +| `src/integrations/README.md` | Update the Linear setup reference to list the three consumed event families and to note that the signing secret is entered inline in the dashboard wizard. If the file doesn't currently duplicate the setup copy, add a one-line pointer to the wizard component. | +| `CHANGELOG.md` | Entry: "feat(dashboard): Linear wizard — accurate events list and inline webhook signing secret". | + +Not touched in this plan (already owned by plan 1): +- `CLAUDE.md` — plan 1 adds the error-logging bullet. + +--- + +## Out of Scope (this plan) + +- Backend save-path changes and error-logging hardening — plan 1 owns these. +- Adding new Linear trigger handlers (Reaction, Document, Issue.create, Issue.remove, IssueLabel.remove) — spec non-goal. +- Automating Linear webhook creation — spec non-goal. +- Changes to Trello or JIRA wizard steps (beyond confirming they remain unchanged) — spec non-goal. +- Changes to the Sentry alerting tab — spec non-goal. +- Making the webhook secret mandatory — spec strategic decision #3. +- Any modification to `ProjectSecretField` itself — the existing component must be used as-is. +- A "send test event" button or similar post-setup validation UI — spec non-goal / out of scope. + +--- + +## Progress + + +- [ ] AC #1 — three-item events list +- [ ] AC #2 — no unused event families mentioned +- [ ] AC #3 — ProjectSecretField renders for Linear +- [ ] AC #4 — save mutation called with correct args +- [ ] AC #5 — masked state on initial mount +- [ ] AC #6 — inline and Credentials-tab surfaces stay in sync +- [ ] AC #7 — Trello/JIRA unchanged +- [ ] AC #8 — Sentry alerting tab unchanged +- [ ] AC #9 — tests for all new code +- [ ] AC #10 — build passes +- [ ] AC #11 — tests pass +- [ ] AC #12 — lint passes +- [ ] AC #13 — typecheck passes +- [ ] AC #14 — integrations/README.md reflects the change diff --git a/docs/plans/002-linear-webhook-setup-ux/_coverage.md b/docs/plans/002-linear-webhook-setup-ux/_coverage.md new file mode 100644 index 00000000..92855edf --- /dev/null +++ b/docs/plans/002-linear-webhook-setup-ux/_coverage.md @@ -0,0 +1,38 @@ +# Coverage map for spec 002-linear-webhook-setup-ux + +Auto-generated by /plan. Tracks which plans satisfy which spec ACs. + +## Spec ACs + +| # | Spec AC (short) | Satisfied by | Status | +|---|---|---|---| +| 1 | Instructions list matches registered Linear trigger handlers | plan 2 (wizard-webhooks-step) | full | +| 2 | Inline webhook signing secret input present in the Webhooks step | plan 2 (wizard-webhooks-step) | full | +| 3 | Pasting the secret persists it as `LINEAR_WEBHOOK_SECRET` | plan 2 (wizard-webhooks-step) | full | +| 4 | Credentials tab and wizard inline field stay in sync | plan 2 (wizard-webhooks-step) | full | +| 5 | Save succeeds end-to-end on a fresh project | plan 1 (save-path-fix) | full | +| 6 | Save succeeds on re-configuration | plan 1 (save-path-fix) | full | +| 7 | Save failures diagnosable in server log | plan 1 (save-path-fix) | full | +| 8 | No secret leakage in plaintext logs | plan 1 (save-path-fix) | full | +| 9 | No regression to Trello / JIRA wizards | plan 2 (wizard-webhooks-step) | full | +| 10 | Other providers' webhook-secret UX (Sentry alerting) unchanged | plan 2 (wizard-webhooks-step) | full | + +## Coverage summary + +- **10 spec ACs** mapped to **2 plans** +- **10 / 10** full-coverage ACs (each ACs is fully delivered by a single plan — no partial chains) +- **0 partial-coverage ACs** — the plans are cleanly orthogonal: plan 1 is pure backend save-path + logging, plan 2 is pure wizard UI. Secret leakage (AC #8) is verified in plan 1 because the logging invariant is established there and exercised by the backend tests; plan 2 does not touch logging. + +## Plan dependency graph + +``` +1-save-path-fix ──→ 2-wizard-webhooks-step +``` + +Linear: plan 2 depends on plan 1 for end-to-end browser verification (the Save step must return 200 before the wizard can be walked through successfully on `dev`). + +## Notes + +- Plan 1 ships no user-visible UI change on its own; its value is "Linear wizard Save stops failing on `dev`" plus a permanent diagnostic improvement to the dashboard error path. +- Plan 2 ships the visible UX polish and closes the spec. +- Build/test/lint/typecheck are per-plan hygiene criteria, not counted against spec ACs above. diff --git a/docs/specs/002-linear-webhook-setup-ux.md b/docs/specs/002-linear-webhook-setup-ux.md new file mode 100644 index 00000000..d16219ac --- /dev/null +++ b/docs/specs/002-linear-webhook-setup-ux.md @@ -0,0 +1,155 @@ +--- +id: 002 +slug: linear-webhook-setup-ux +level: spec +title: Linear Webhook Setup UX — Complete Events, Inline Secret, Unblock Save +created: 2026-04-15 +status: draft +--- + +# 002: Linear Webhook Setup UX — Complete Events, Inline Secret, Unblock Save + +## Problem & Motivation + +CASCADE shipped Linear as a PM provider in the dashboard wizard (#1107, #1108, #1112). The end-to-end setup flow is now working in principle, but three real problems are surfacing the first time an operator actually walks through it on a live project (dev environment, project `llmist`): + +1. **The "Enable events" instruction is incomplete.** The Webhooks step currently tells the user to enable only `Issues (created, updated, removed)`. CASCADE's Linear trigger handlers actually consume three event families: `Issue.update` (status transitions), `Comment.create` (bot @mentions), and `IssueLabel.create` (the "Ready to Process" label). If the operator follows the instructions literally, the comment-mention and ready-to-process-label triggers never fire, and there is no feedback loop — the integration appears configured, events arrive from Linear, and nothing happens. + +2. **The webhook signing secret has no dashboard home.** The setup panel says *"Optionally set a webhook secret and store it as `LINEAR_WEBHOOK_SECRET` in project credentials"* — meaning the user must leave the wizard, navigate to the Credentials tab, and paste the secret into a generic env-var form. Meanwhile the user is already staring at Linear's "Signing secret" field in a different browser tab. The obvious flow — copy secret → paste adjacent to the instructions → done — is not supported. (Compare: the Sentry alerting tab already uses `ProjectSecretField` to inline the webhook secret next to the webhook URL. This is the established pattern.) + +3. **The final "Update Integration" save returns HTTP 500.** On `dev`, finishing the Linear wizard for project `llmist` fails the `POST /trpc/projects.integrations.upsert` call with a Drizzle "Failed query" error against `project_integrations`. The underlying cause is not visible in dashboard logs (only the 500 status is logged, not the error text). The net effect: the operator cannot complete Linear setup at all on dev today. This is a regression from the wizard work in #1107 and must be fixed as part of the same UX polish pass — shipping the cosmetic fixes while the primary flow is broken would be pointless. + +Together, these three defects mean the first-time Linear setup experience is demonstrably broken, even though every individual piece (wizard steps, trigger handlers, credential storage, signature verification) is present and wired. + +--- + +## Goals + +1. An operator following the on-screen setup instructions configures a Linear webhook that actually delivers every event CASCADE can act on — no silent under-subscription. +2. An operator who wants to protect the webhook endpoint with a signing secret can do so without leaving the wizard — one place to look, one place to paste. +3. The Linear wizard's final Save step completes successfully end-to-end on the dev environment, and any future failure at that step produces a server-side error message the operator (or an engineer reading logs) can act on. +4. The wizard's guidance is trustworthy: every event the instructions tell the user to enable in Linear is one CASCADE actually consumes, and no event CASCADE consumes is missing from the instructions. + +--- + +## Non-goals + +- Adding new Linear trigger handlers (e.g., `Reaction`, `Document`, `Issue.create`, `IssueLabel.remove`). These are separate product decisions, not in scope here. +- Automating webhook creation via Linear's API. Linear webhooks remain manually created by the user; the panel's "Manual Webhook Setup Required" notice stays. +- Changing the credential storage model (encrypted `project_credentials` table, env-var-key semantics). The inline input is a new surface on top of the existing store. +- Making the webhook secret mandatory. It stays optional, matching current signature-verification behavior (skip if absent). +- Redesigning the broader PM wizard, step ordering, or other providers' setup flows. Changes to Trello/JIRA setup are out of scope. +- Changing how `project_integrations.triggers` is structured, defaulted, or interpreted. The save-error fix targets the actual error, not a schema redesign. +- Post-setup validation that Linear is actually sending webhooks to CASCADE (e.g., a "send test event" button). + +--- + +## Constraints + +- **TDD-first.** Every behavior change (new input field, new instruction text, save-error fix) must be preceded by a failing test that demonstrates the bug or requirement. +- **No hacks, no half-measures.** The save-error fix must address the true root cause observable in server logs, not silence a symptom. If the upsert is genuinely failing on an invalid value, fix the invalid value; if it's a schema drift, reconcile the schema. +- **Observability for the save path.** After this spec lands, any future failure at `projects.integrations.upsert` must produce a server-side log line containing the actual error message — not just an HTTP 500. +- **Follow existing conventions.** Use the existing `ProjectSecretField` component for the inline secret input (same pattern as the Sentry alerting tab). Use the existing `setCredential` tRPC path to persist it. Use the existing `LINEAR_WEBHOOK_SECRET` env-var key. +- **No regression to JIRA or Trello setup.** The Linear-specific changes must not alter other providers' wizard steps or behavior. +- **No regression to the Credentials tab.** Users who already stored `LINEAR_WEBHOOK_SECRET` via the Credentials tab must see their value reflected in the new inline field, and editing it in either place must be equivalent. +- **No credential leakage in logs.** The signing secret must never appear in plaintext in server logs, tRPC traces, or error responses. + +--- + +## User stories / Requirements + +### As an operator setting up Linear for the first time + +1. **Correct events list.** When I reach the Webhooks step, the instructions list exactly the events CASCADE consumes — `Issues`, `Comments`, and `Issue Labels` — and explain in one line each why they're needed (status transitions, @mention responses, "Ready to Process" labeling). I do not see events CASCADE ignores. +2. **Inline secret input.** On the same Webhooks step, immediately under the webhook URL, I see an input labelled "Webhook Signing Secret (optional)" with the same copy-paste affordance as other credential fields. When I paste my Linear signing secret and move on, it is persisted as the `LINEAR_WEBHOOK_SECRET` project credential without any further action on my part. +3. **Saved state is reflected.** If a `LINEAR_WEBHOOK_SECRET` credential already exists for the project, the field shows a masked indicator (same affordance `ProjectSecretField` uses elsewhere). I can update or clear it from here. +4. **Save completes.** When I reach the final Save step and confirm, the "Update Integration" action succeeds on the first try, the wizard closes, and the Linear integration appears as configured on the project page. + +### As an engineer responding to a save failure + +5. **Actionable server log.** If the upsert fails, the dashboard server log contains the error message (constraint name, type mismatch, whatever the DB said) alongside the already-logged SQL + parameters. I can diagnose without attaching a debugger. + +### As a reviewer of the change + +6. **Instructions match code.** A reviewer can verify correctness by comparing the setup instructions to the registered Linear trigger handlers. The two lists agree. + +--- + +## Research Notes + +- Linear webhooks are **manually configured** in the team settings UI; there is no first-class public API for creating them programmatically. The manual-setup framing is correct and must stay. Reference: [Linear — Webhooks](https://developers.linear.app/docs/graphql/webhooks). +- Linear's `Data change events` checkboxes on the "Create webhook" screen are independent subscriptions. The currently recommended set (`Issues`) is a strict subset of what the CASCADE router actually parses — parsed event types include `Issue.create`, `Issue.update`, `Comment.create`, `IssueLabel.create`, and a declared-but-unhandled `Reaction`. Only the handlers that exist drive behavior. +- Linear signs webhooks with HMAC-SHA256 hex-encoded in the `Linear-Signature` header. CASCADE already verifies this via `verifyLinearSignature` → `verifyLinearWebhookSignature`, pulling the secret from the `webhook_secret` credential role. If the credential is absent, verification is skipped. This behavior is intentional and documented in the provider role registration and is **not** changing. +- The dashboard already has precedent for inlining a webhook secret next to a webhook URL: the Sentry alerting tab composes `ProjectSecretField` with an immediate `envVarKey="SENTRY_WEBHOOK_SECRET"`. The same component is reusable for Linear with zero new primitives. +- The `project_integrations` repository already has a preserve-existing-triggers fallback for the case where the wizard omits the `triggers` input — `upsertProjectIntegration` reads the existing row and reuses its triggers if undefined is passed. The save path on dev is failing *after* this fallback, so the defect is elsewhere; the root cause needs to be confirmed by surfacing the actual DB error rather than guessed at. + +--- + +## Open Source Decisions + +| Tool | Solves | Decision | Reason | +|------|--------|----------|--------| +| `ProjectSecretField` (internal dashboard component) | Inline credential input with masked existing-value display, save-on-blur semantics | **Use** | Already the standard. Used by Sentry webhook secret; Linear should match. | +| Linear webhook HMAC verification (`verifyLinearSignature`, internal) | Signature check using stored `LINEAR_WEBHOOK_SECRET` | **Use** (no change) | Already implemented and wired; this spec only changes *how the secret gets stored*, not how it's verified. | +| No new external OSS dependencies | — | **Skip** | The work is a composition of existing internal primitives. No tool adoption is warranted. | + +--- + +## Strategic decisions + +1. **Events list reflects reality, not ambition.** Recommend exactly the three event families CASCADE consumes today (`Issues`, `Comments`, `Issue Labels`). When new trigger handlers land (e.g., reactions), the instruction list updates with them — not before. Reason: guidance drifts into noise if it promises events that do nothing. +2. **Webhook secret lives in the Webhooks step, not the Credentials step.** The user's mental context when they look at CASCADE's Webhooks step is "I am staring at Linear's webhook creation screen; it just gave me a signing secret; where does it go?" The answer should be inches away, not two tabs over. Reason: minimize the distance between the Linear-side and CASCADE-side of the same action. +3. **Secret remains optional.** No change to the current verification behavior. Reason: mandatory would block users who can't (yet) create a secret on the Linear side, and the verification code already handles absence cleanly. +4. **Save-error fix is in scope.** The bug blocks the very flow this spec improves — polishing a broken path would be theatre. Reason: ship the complete first-time experience, not a subset. +5. **Diagnosability is a first-class outcome.** Rather than just fixing today's specific save failure, ensure the next one is *visible* (server logs the DB error text). Reason: the current 500-without-detail mode has already cost debugging time once; it will again. +6. **Reuse, don't invent.** Compose `ProjectSecretField` + existing credential save mutation + existing env-var key. No new component, no new tRPC route. Reason: the primitives are correct; the composition is the fix. + +--- + +## Acceptance Criteria (outcome-level) + +1. **Instructions list matches handlers.** On the Webhooks step of the Linear PM wizard, the enabled-events instruction lists `Issues`, `Comments`, and `Issue Labels`, with a one-line rationale per item, and nothing else. Each bullet corresponds to at least one registered Linear trigger handler. +2. **Inline secret input is present.** The Webhooks step renders an input labelled "Webhook Signing Secret (optional)" placed adjacent to the webhook URL. The input uses the same masked / copy / clear affordance used by other secret fields in the dashboard. +3. **Pasting the secret persists it.** Entering a value into the inline input stores it as the `LINEAR_WEBHOOK_SECRET` credential for the current project, using the existing credential-save path. After a page reload, the field shows the masked existing-value state, not an empty input. +4. **Credentials tab stays in sync.** A value written via the wizard input is readable from the Credentials tab under `LINEAR_WEBHOOK_SECRET`, and vice versa — the two surfaces point at the same underlying row. +5. **Save succeeds end-to-end.** Completing the Linear wizard on a project with no prior PM integration results in a successful `projects.integrations.upsert` call (HTTP 200), a persisted `project_integrations` row, and a visible "configured" state on the project page. +6. **Save succeeds on re-configuration.** Re-running the wizard on a project that already has a Linear PM integration updates the existing row (same upsert) without 500s, preserving any previously configured triggers on the row. +7. **Save failures are diagnosable.** When the upsert does fail for any reason, the dashboard server log contains the underlying error message (not just the HTTP status). This can be verified by provoking a failure — e.g., writing an invalid `config` payload — and reading the server log. +8. **No secret leakage.** The signing secret value does not appear in plaintext in any server log emitted during the save path (wizard save, credential save, upsert). A search of the log for the secret's literal value returns zero hits. +9. **No regression to other providers.** Running through the Trello and JIRA wizards end-to-end (including their Save step) continues to succeed and produces the same result it did before this change. +10. **Other providers' webhook-secret UX unchanged.** The Sentry alerting tab's inline secret field and the JIRA / Trello wizard steps are byte-for-byte unchanged. + +--- + +## Documentation Impact (high-level) + +- `src/integrations/README.md` — if the setup-instruction text is referenced or duplicated, update it to match the new events list. If not, no change needed. +- `CLAUDE.md` (root) — no change expected; Linear setup specifics live in `src/integrations/README.md`. +- `CHANGELOG.md` — add an entry noting the Linear wizard improvements (events, inline secret) and the save-path fix. +- `web/` component-level docs, if any exist for the PM wizard — reflect the new step contents. + +--- + +## Out of Scope + +- Adding handlers for Linear `Reaction`, `Document`, `Issue.create`, `Issue.remove`, or `IssueLabel.remove` events. +- Automating Linear webhook creation or rotation. +- Migrating existing `LINEAR_WEBHOOK_SECRET` credentials to a different storage model or key name. +- Redesigning the wizard's step ordering, visual layout, or multi-provider flow. +- Adding a "send test event" button or other post-setup verification UI. +- Making the signing secret mandatory for any provider. +- Changes to trigger-discovery or the `agent_trigger_configs` table. +- Changes to JIRA, Trello, or Sentry setup flows. + +--- + +## Verification + +- Spin up the dashboard on dev, walk the Linear wizard end-to-end on a fresh project (no prior PM integration), complete the Save step, and confirm the project page shows Linear as configured. +- Repeat on a project that already has a Linear integration (re-configuration path). +- Paste a secret into the inline field, reload, and confirm the masked state. +- Paste a secret via the Credentials tab, open the wizard, and confirm the inline field shows the masked state. +- Compare the registered Linear trigger handlers against the on-screen events list — they must agree. +- Force an upsert failure (e.g., via a bad config payload in devtools) and confirm the underlying error is present in the dashboard server log. +- Grep the dashboard server log for the literal secret value after a save — must return zero hits. +- Run unit + integration tests: the new failing tests written first for each behavior above must now pass; all previously passing tests must still pass. From 0d1cb76274c8261755643c2723dad3424cf87b69 Mon Sep 17 00:00:00 2001 From: zbigniew sobiecki Date: Wed, 15 Apr 2026 19:07:59 +0200 Subject: [PATCH 02/10] feat(dashboard): structured error logging for tRPC + Hono Adds src/api/errorLogging.ts with formatters that surface pg driver fields (code, detail, constraint, table) onto server-side logs for both Hono app.onError and the tRPC errorFormatter. Client responses for INTERNAL_SERVER_ERROR now carry a generic message; real details remain in cascade-dashboard-* stdout for operators to grep. plan 002/1 task 1. Co-Authored-By: Claude Opus 4.6 (1M context) --- src/api/errorLogging.ts | 180 +++++++++++++++++++++++++++ src/api/trpc.ts | 13 +- src/dashboard.ts | 7 +- tests/unit/api/error-logging.test.ts | 172 +++++++++++++++++++++++++ 4 files changed, 370 insertions(+), 2 deletions(-) create mode 100644 src/api/errorLogging.ts create mode 100644 tests/unit/api/error-logging.test.ts diff --git a/src/api/errorLogging.ts b/src/api/errorLogging.ts new file mode 100644 index 00000000..c893dd9e --- /dev/null +++ b/src/api/errorLogging.ts @@ -0,0 +1,180 @@ +import { TRPCError } from '@trpc/server'; + +/** + * Shape of a `pg` driver error (or anything wrapping one, e.g. Drizzle). + * Exposed so the Hono error handler and the tRPC error formatter both surface + * the same diagnostic fields in server logs. + */ +export interface PgLikeError { + code: string; + message?: string; + detail?: string; + constraint?: string; + table?: string; + column?: string; + schema?: string; +} + +function asPgLike(value: unknown): PgLikeError | null { + if (value === null || typeof value !== 'object') return null; + if (value instanceof TRPCError) return null; + const rec = value as Record; + if (typeof rec.code !== 'string') return null; + return { + code: rec.code, + message: typeof rec.message === 'string' ? rec.message : undefined, + detail: typeof rec.detail === 'string' ? rec.detail : undefined, + constraint: typeof rec.constraint === 'string' ? rec.constraint : undefined, + table: typeof rec.table === 'string' ? rec.table : undefined, + column: typeof rec.column === 'string' ? rec.column : undefined, + schema: typeof rec.schema === 'string' ? rec.schema : undefined, + }; +} + +/** + * Returns true if `err` (or a direct `.cause`) looks like a pg-driver error + * with a string `code` field. + */ +export function isPgLikeError(err: unknown): boolean { + if (asPgLike(err)) return true; + if (err && typeof err === 'object' && 'cause' in err) { + const cause = (err as { cause: unknown }).cause; + if (asPgLike(cause)) return true; + } + return false; +} + +function extractPgFields(err: unknown): PgLikeError | null { + const direct = asPgLike(err); + if (direct) return direct; + if (err && typeof err === 'object' && 'cause' in err) { + return asPgLike((err as { cause: unknown }).cause); + } + return null; +} + +export interface DashboardErrorLogPayload { + path: string; + method: string; + name: string; + message: string; + stack?: string; + code?: string; + detail?: string; + constraint?: string; + table?: string; + column?: string; +} + +/** + * Build a structured log payload for `app.onError` in the Hono dashboard. + * Includes PG-error diagnostic fields when present (on the error or its cause). + */ +export function formatDashboardErrorLog( + err: unknown, + ctx: { path: string; method: string }, +): DashboardErrorLogPayload { + let name = 'NonError'; + let message = ''; + let stack: string | undefined; + if (err instanceof Error) { + name = err.name || 'Error'; + message = err.message; + stack = err.stack; + } else if (typeof err === 'string') { + message = err; + } else { + try { + message = JSON.stringify(err); + } catch { + message = String(err); + } + } + + const payload: DashboardErrorLogPayload = { + path: ctx.path, + method: ctx.method, + name, + message, + stack, + }; + + const pg = extractPgFields(err); + if (pg) { + payload.code = pg.code; + if (pg.detail !== undefined) payload.detail = pg.detail; + if (pg.constraint !== undefined) payload.constraint = pg.constraint; + if (pg.table !== undefined) payload.table = pg.table; + if (pg.column !== undefined) payload.column = pg.column; + } + + return payload; +} + +export interface TRPCErrorLogPayload { + code: string; + path: string; + type?: string; + message: string; + stack?: string; + cause?: string; + pgCode?: string; + pgDetail?: string; + pgConstraint?: string; + pgTable?: string; + pgColumn?: string; +} + +/** + * Build a structured log payload for tRPC errors. Invoked by the tRPC + * `errorFormatter` server-side so operators can grep `cascade-dashboard-dev` + * logs and see real DB error messages instead of just an HTTP 500. + */ +export function formatTRPCErrorLog(opts: { + error: TRPCError; + path?: string | null; + type?: string; +}): TRPCErrorLogPayload { + const { error } = opts; + const payload: TRPCErrorLogPayload = { + code: error.code, + path: opts.path ?? '', + type: opts.type, + message: error.message, + stack: error.stack, + }; + + const cause = (error as unknown as { cause?: unknown }).cause; + if (cause instanceof Error) { + payload.cause = `${cause.name}: ${cause.message}`; + } else if (cause !== undefined) { + try { + payload.cause = JSON.stringify(cause); + } catch { + payload.cause = String(cause); + } + } + + const pg = extractPgFields(error) ?? extractPgFields(cause); + if (pg) { + payload.pgCode = pg.code; + if (pg.detail !== undefined) payload.pgDetail = pg.detail; + if (pg.constraint !== undefined) payload.pgConstraint = pg.constraint; + if (pg.table !== undefined) payload.pgTable = pg.table; + if (pg.column !== undefined) payload.pgColumn = pg.column; + } + + return payload; +} + +/** + * Shape the tRPC error response sent to the client. Swaps the message for + * an unexpected INTERNAL_SERVER_ERROR with a generic placeholder so raw DB + * error text never reaches the browser. + */ +export function formatTRPCErrorResponse(error: TRPCError): { code: string; message: string } { + if (error.code === 'INTERNAL_SERVER_ERROR') { + return { code: error.code, message: 'Internal server error' }; + } + return { code: error.code, message: error.message }; +} diff --git a/src/api/trpc.ts b/src/api/trpc.ts index 47cd077a..66d4dbdd 100644 --- a/src/api/trpc.ts +++ b/src/api/trpc.ts @@ -1,4 +1,5 @@ import { initTRPC, TRPCError } from '@trpc/server'; +import { formatTRPCErrorLog, formatTRPCErrorResponse } from './errorLogging.js'; export interface TRPCUser { id: string; @@ -13,7 +14,17 @@ export interface TRPCContext { effectiveOrgId: string | null; } -const t = initTRPC.context().create(); +const t = initTRPC.context().create({ + errorFormatter({ shape, error, path, type }) { + // Log the full diagnostic payload server-side (picks up PG error fields + // from error.cause when Drizzle wraps a pg driver error). + console.error('tRPC error', formatTRPCErrorLog({ error, path, type })); + + // Sanitise the client response: never send raw internal-error text back. + const safe = formatTRPCErrorResponse(error); + return { ...shape, message: safe.message }; + }, +}); export const router = t.router; export const publicProcedure = t.procedure; diff --git a/src/dashboard.ts b/src/dashboard.ts index be01ec14..07dc4293 100644 --- a/src/dashboard.ts +++ b/src/dashboard.ts @@ -26,6 +26,7 @@ import { loginHandler } from './api/auth/login.js'; import { logoutHandler } from './api/auth/logout.js'; import { resolveUserFromSession } from './api/auth/session.js'; import { computeEffectiveOrgId } from './api/context.js'; +import { formatDashboardErrorLog } from './api/errorLogging.js'; import { appRouter } from './api/router.js'; import { registerBuiltInEngines } from './backends/bootstrap.js'; import { validateCredentialMasterKey } from './db/crypto.js'; @@ -95,7 +96,11 @@ app.notFound((c) => c.json({ error: 'Not Found' }, 404)); // Error handler app.onError((err, c) => { - console.error('Unhandled error', { error: String(err), path: c.req.path }); + const payload = formatDashboardErrorLog(err, { + path: c.req.path, + method: c.req.method, + }); + console.error('Unhandled error', payload); captureException(err, { tags: { source: 'hono_error' }, extra: { path: c.req.path, method: c.req.method }, diff --git a/tests/unit/api/error-logging.test.ts b/tests/unit/api/error-logging.test.ts new file mode 100644 index 00000000..8aa6b030 --- /dev/null +++ b/tests/unit/api/error-logging.test.ts @@ -0,0 +1,172 @@ +import { TRPCError } from '@trpc/server'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { + formatDashboardErrorLog, + formatTRPCErrorLog, + formatTRPCErrorResponse, + isPgLikeError, +} from '../../../src/api/errorLogging.js'; + +describe('isPgLikeError', () => { + it('returns true for an object with a string code field', () => { + expect(isPgLikeError({ code: '23505', message: 'dup' })).toBe(true); + }); + + it('returns false for a plain Error', () => { + expect(isPgLikeError(new Error('boom'))).toBe(false); + }); + + it('returns false for null / undefined / primitives', () => { + expect(isPgLikeError(null)).toBe(false); + expect(isPgLikeError(undefined)).toBe(false); + expect(isPgLikeError('string')).toBe(false); + expect(isPgLikeError(42)).toBe(false); + }); + + it('returns true when code is present on a nested cause', () => { + const err = new Error('wrapped'); + (err as unknown as { cause: unknown }).cause = { code: '23503', detail: 'FK' }; + expect(isPgLikeError(err)).toBe(true); + }); +}); + +describe('formatDashboardErrorLog', () => { + it('captures message, name, stack for a plain Error', () => { + const err = new Error('boom'); + const payload = formatDashboardErrorLog(err, { path: '/trpc/foo', method: 'POST' }); + expect(payload.path).toBe('/trpc/foo'); + expect(payload.method).toBe('POST'); + expect(payload.message).toBe('boom'); + expect(payload.name).toBe('Error'); + expect(payload.stack).toContain('boom'); + }); + + it('copies PG-shaped fields (code, detail, constraint, table, column) onto the payload', () => { + const pgErr = { + message: 'duplicate key value violates unique constraint', + code: '23505', + detail: 'Key (project_id, category)=(llmist, pm) already exists.', + constraint: 'project_integrations_project_id_category_key', + table: 'project_integrations', + column: undefined, + }; + const payload = formatDashboardErrorLog(pgErr, { path: '/trpc/x', method: 'POST' }); + expect(payload.code).toBe('23505'); + expect(payload.detail).toBe(pgErr.detail); + expect(payload.constraint).toBe(pgErr.constraint); + expect(payload.table).toBe('project_integrations'); + }); + + it('unwraps PG fields from a nested cause', () => { + const wrapped = new Error('failed query'); + (wrapped as unknown as { cause: unknown }).cause = { + code: '23503', + detail: 'Key (project_id)=(llmist) is not present in table "projects".', + constraint: 'project_integrations_project_id_fkey', + }; + const payload = formatDashboardErrorLog(wrapped, { path: '/trpc/x', method: 'POST' }); + expect(payload.code).toBe('23503'); + expect(payload.constraint).toBe('project_integrations_project_id_fkey'); + }); + + it('stringifies non-Error throwables safely', () => { + const payload = formatDashboardErrorLog('oops', { path: '/x', method: 'GET' }); + expect(payload.message).toBe('oops'); + expect(payload.name).toBe('NonError'); + }); +}); + +describe('formatTRPCErrorLog', () => { + it('includes code, path, message, cause, stack for an unexpected throw', () => { + const err = new TRPCError({ + code: 'INTERNAL_SERVER_ERROR', + message: 'boom', + cause: new Error('underlying'), + }); + const logged = formatTRPCErrorLog({ + error: err, + path: 'projects.integrations.upsert', + type: 'mutation', + }); + expect(logged.code).toBe('INTERNAL_SERVER_ERROR'); + expect(logged.path).toBe('projects.integrations.upsert'); + expect(logged.message).toBe('boom'); + expect(logged.stack).toBeDefined(); + }); + + it('merges PG fields from error.cause into the log payload', () => { + const pgLike = { + message: 'duplicate', + code: '23505', + detail: 'dup', + constraint: 'uniq', + }; + const err = new TRPCError({ code: 'INTERNAL_SERVER_ERROR', message: 'wrapped', cause: pgLike }); + const logged = formatTRPCErrorLog({ + error: err, + path: 'projects.integrations.upsert', + type: 'mutation', + }); + expect(logged.code).toBe('INTERNAL_SERVER_ERROR'); + expect(logged.pgCode).toBe('23505'); + expect(logged.pgDetail).toBe('dup'); + expect(logged.pgConstraint).toBe('uniq'); + }); +}); + +describe('formatTRPCErrorResponse', () => { + it('returns generic message for INTERNAL_SERVER_ERROR with non-TRPCError cause', () => { + const err = new TRPCError({ + code: 'INTERNAL_SERVER_ERROR', + message: 'dup key value violates unique constraint "project_integrations_pkey"', + cause: new Error('underlying'), + }); + const resp = formatTRPCErrorResponse(err); + expect(resp.code).toBe('INTERNAL_SERVER_ERROR'); + expect(resp.message).toBe('Internal server error'); + }); + + it('preserves original message for UNAUTHORIZED', () => { + const err = new TRPCError({ code: 'UNAUTHORIZED', message: 'please sign in' }); + const resp = formatTRPCErrorResponse(err); + expect(resp.code).toBe('UNAUTHORIZED'); + expect(resp.message).toBe('please sign in'); + }); + + it('preserves original message for NOT_FOUND, FORBIDDEN, BAD_REQUEST', () => { + for (const code of ['NOT_FOUND', 'FORBIDDEN', 'BAD_REQUEST'] as const) { + const err = new TRPCError({ code, message: `msg-${code}` }); + const resp = formatTRPCErrorResponse(err); + expect(resp.code).toBe(code); + expect(resp.message).toBe(`msg-${code}`); + } + }); +}); + +describe('secret redaction in error logs', () => { + let consoleErrorSpy: ReturnType; + beforeEach(() => { + consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {}); + }); + afterEach(() => { + consoleErrorSpy.mockRestore(); + }); + + it('dashboard error log does not include arbitrary interpolated credential values in message', () => { + // Sanity tripwire: the system should not interpolate secrets into error messages. + // If this ever starts failing, the bug is upstream — redact at the source, don't patch here. + const err = new Error('save failed'); + const payload = formatDashboardErrorLog(err, { path: '/trpc/foo', method: 'POST' }); + expect(JSON.stringify(payload)).not.toContain('SECRET_SENTINEL_xyz'); + }); + + it('tRPC error log does not include arbitrary interpolated credential values', () => { + const err = new TRPCError({ code: 'INTERNAL_SERVER_ERROR', message: 'save failed' }); + const logged = formatTRPCErrorLog({ + error: err, + path: 'projects.credentials.set', + type: 'mutation', + }); + expect(JSON.stringify(logged)).not.toContain('SECRET_SENTINEL_xyz'); + }); +}); From a774d878563a6348028da0cf37faa126a691a121 Mon Sep 17 00:00:00 2001 From: zbigniew sobiecki Date: Wed, 15 Apr 2026 19:10:47 +0200 Subject: [PATCH 03/10] fix(db): allow provider=linear under category=pm in integration check constraint The chk_integration_category_provider check constraint (from 0047_add_alerting_integration.sql) only permitted trello/jira for pm-category integrations. Linear support was introduced without a matching constraint update, so every projects.integrations.upsert for category=pm + provider=linear failed with SQLSTATE 23514 and surfaced as HTTP 500 from the dashboard Linear wizard. Migration 0049 drops and re-creates the constraint with linear added to the pm branch. Forward-only, no data migration required. Reproduced with two new integration tests against the test DB. plan 002/1 tasks 2-3 (diagnose + fix). Co-Authored-By: Claude Opus 4.6 (1M context) --- .../1-save-path-fix.md.wip | 12 +++++-- .../0049_allow_linear_pm_provider.sql | 18 ++++++++++ src/db/migrations/meta/_journal.json | 7 ++++ .../db/integrationsRepository.test.ts | 33 +++++++++++++++++++ 4 files changed, 67 insertions(+), 3 deletions(-) create mode 100644 src/db/migrations/0049_allow_linear_pm_provider.sql diff --git a/docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md.wip b/docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md.wip index ac0a46c3..1559b17b 100644 --- a/docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md.wip +++ b/docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md.wip @@ -94,9 +94,15 @@ Context to lift from the spec (do not re-argue): 5. If the error is a PG constraint violation, cross-reference `src/db/schema/integrations.ts` for the relevant column or constraint. If it is a Zod input validation error surfaced as 500, cross-reference `src/api/routers/projects.ts`'s `upsert` input schema. 6. Do not guess. Do not patch without a named error. Exit this step with a one-line statement of the root cause. -**Diagnosis** (fill in after running the spike): - -> _(populated during /implement; left blank at plan authoring time)_ +**Diagnosis** (populated 2026-04-15 during /implement): + +> **Root cause:** CHECK constraint violation (`23514`) on `chk_integration_category_provider`. +> +> The constraint, defined originally in `0047_add_alerting_integration.sql`, allows `pm` × `{trello, jira}` only — **`linear` is not in the allowed set**. When Linear support landed (PRs #1107/#1108/#1112), the corresponding migration was never shipped. Any `INSERT` with `category='pm', provider='linear'` fails on this constraint, surfacing as HTTP 500 from `projects.integrations.upsert`. +> +> Verified on dev by querying Supabase from inside `cascade-dashboard-dev` (org `mongrel`, project `llmist` exists; `project_integrations` already has rows with `provider='trello'` and `provider='github'` — the constraint is genuinely blocking `linear`). +> +> **Fix:** ship migration `0049_allow_linear_pm_provider.sql` that drops and re-creates the check constraint with `linear` added to the `pm` branch. Forward-only; no data migration needed. Pre-commit guidance for `/implement`: the most likely culprits, ranked, are — 1. FK violation on `project_id` (project `llmist` may not exist in `projects` table under org `mongrel`). diff --git a/src/db/migrations/0049_allow_linear_pm_provider.sql b/src/db/migrations/0049_allow_linear_pm_provider.sql new file mode 100644 index 00000000..d34959c0 --- /dev/null +++ b/src/db/migrations/0049_allow_linear_pm_provider.sql @@ -0,0 +1,18 @@ +-- 0049_allow_linear_pm_provider.sql +-- Add linear to the allowed pm providers in the integration category/provider CHECK constraint. + +BEGIN; + +ALTER TABLE project_integrations + DROP CONSTRAINT IF EXISTS chk_integration_category_provider; + +ALTER TABLE project_integrations + ADD CONSTRAINT chk_integration_category_provider CHECK ( + (category = 'pm' AND provider IN ('trello', 'jira', 'linear')) + OR (category = 'scm' AND provider IN ('github')) + OR (category = 'email' AND provider IN ('imap', 'gmail')) + OR (category = 'sms' AND provider IN ('twilio')) + OR (category = 'alerting' AND provider IN ('sentry')) + ); + +COMMIT; diff --git a/src/db/migrations/meta/_journal.json b/src/db/migrations/meta/_journal.json index b09ac4ec..8c4136fc 100644 --- a/src/db/migrations/meta/_journal.json +++ b/src/db/migrations/meta/_journal.json @@ -344,6 +344,13 @@ "when": 1783000000000, "tag": "0048_remove_squint_db_url", "breakpoints": false + }, + { + "idx": 49, + "version": "7", + "when": 1784000000000, + "tag": "0049_allow_linear_pm_provider", + "breakpoints": false } ] } diff --git a/tests/integration/db/integrationsRepository.test.ts b/tests/integration/db/integrationsRepository.test.ts index 82297daa..898de5e0 100644 --- a/tests/integration/db/integrationsRepository.test.ts +++ b/tests/integration/db/integrationsRepository.test.ts @@ -187,6 +187,39 @@ describe('integrationsRepository (integration)', () => { expect(row?.category).toBe('scm'); expect(row?.provider).toBe('github'); }); + + it('accepts provider=linear under category=pm (Linear is a first-class PM provider)', async () => { + const row = await upsertProjectIntegration('test-project', 'pm', 'linear', { + teamId: '310c41fe-eee4-4b3f-a56d-f992b85d9568', + statuses: { backlog: 'Backlog', inProgress: 'In Progress' }, + labels: { processing: 'cascade-processing' }, + }); + + expect(row).not.toBeNull(); + expect(row?.provider).toBe('linear'); + expect(row?.category).toBe('pm'); + expect((row?.config as Record)?.teamId).toBe( + '310c41fe-eee4-4b3f-a56d-f992b85d9568', + ); + }); + + it('updates an existing pm integration from trello to linear without conflict', async () => { + await upsertProjectIntegration('test-project', 'pm', 'trello', { + boardId: 'board-1', + lists: {}, + labels: {}, + }); + + await upsertProjectIntegration('test-project', 'pm', 'linear', { + teamId: 'team-xyz', + statuses: {}, + labels: {}, + }); + + const result = await getIntegrationByProjectAndCategory('test-project', 'pm'); + expect(result?.provider).toBe('linear'); + expect((result?.config as Record)?.teamId).toBe('team-xyz'); + }); }); // ========================================================================= From 36ea4cdc064bfcc068532a62a1afd21ff3d6e684 Mon Sep 17 00:00:00 2001 From: zbigniew sobiecki Date: Wed, 15 Apr 2026 19:11:40 +0200 Subject: [PATCH 04/10] test(api): assert plaintext credentials never leak into server logs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Integration tests that spy on console.{log,error,warn} around writeProjectCredential, upsertProjectIntegration (happy + FK-violation paths), and the formatTRPCErrorLog formatter. Asserts the sentinel credential value never appears in captured output, while confirming the real PG error (SQLSTATE + constraint name) IS present on the failure path — proving diagnosability without leakage. plan 002/1 task 4. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../integration/api/no-secret-leakage.test.ts | 120 ++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 tests/integration/api/no-secret-leakage.test.ts diff --git a/tests/integration/api/no-secret-leakage.test.ts b/tests/integration/api/no-secret-leakage.test.ts new file mode 100644 index 00000000..8faccfa3 --- /dev/null +++ b/tests/integration/api/no-secret-leakage.test.ts @@ -0,0 +1,120 @@ +/** + * Log-hygiene integration tests. + * + * Plain-text credential values must never appear in server stdout/stderr — not + * on the happy-path credential save, not on a successful integration upsert, + * not even on the error path when an upsert fails. Captures `console.log` + * and `console.error` around each operation and asserts the sentinel value + * never leaks into the captured output. + */ + +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { formatDashboardErrorLog, formatTRPCErrorLog } from '../../../src/api/errorLogging.js'; +import { writeProjectCredential } from '../../../src/db/repositories/credentialsRepository.js'; +import { upsertProjectIntegration } from '../../../src/db/repositories/integrationsRepository.js'; +import { truncateAll } from '../helpers/db.js'; +import { seedOrg, seedProject } from '../helpers/seed.js'; + +const SECRET_SENTINEL = 'lin_wh_SECRET_SENTINEL_do_not_log'; + +describe('log hygiene — plaintext credentials never appear in server logs', () => { + let logs: string[]; + let logSpy: ReturnType; + let errSpy: ReturnType; + let warnSpy: ReturnType; + + beforeEach(async () => { + await truncateAll(); + await seedOrg(); + await seedProject(); + + logs = []; + const capture = (...args: unknown[]) => { + try { + logs.push(args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ')); + } catch { + logs.push(args.map(String).join(' ')); + } + }; + logSpy = vi.spyOn(console, 'log').mockImplementation(capture); + errSpy = vi.spyOn(console, 'error').mockImplementation(capture); + warnSpy = vi.spyOn(console, 'warn').mockImplementation(capture); + }); + + afterEach(() => { + logSpy.mockRestore(); + errSpy.mockRestore(); + warnSpy.mockRestore(); + }); + + it('credential save path does not log the plaintext value', async () => { + await writeProjectCredential('test-project', 'LINEAR_WEBHOOK_SECRET', SECRET_SENTINEL); + + const joined = logs.join('\n'); + expect(joined).not.toContain(SECRET_SENTINEL); + }); + + it('successful integration upsert does not log the config payload verbatim', async () => { + // Even benign config shouldn't flood logs — assert the upsert runs quietly. + await upsertProjectIntegration('test-project', 'pm', 'linear', { + teamId: 'team-123', + statuses: { backlog: 'Backlog' }, + labels: {}, + }); + + const errLogs = logs.filter((l) => /config/i.test(l) && /team-123/.test(l)); + expect(errLogs).toEqual([]); + }); + + it('failing upsert (bad projectId FK) does not leak any stored credential value into the error log', async () => { + await writeProjectCredential('test-project', 'LINEAR_WEBHOOK_SECRET', SECRET_SENTINEL); + + // FK violation — project 'nonexistent-project' does not exist. + let caught: unknown; + try { + await upsertProjectIntegration('nonexistent-project', 'pm', 'linear', { + teamId: 'team-xyz', + }); + } catch (e) { + caught = e; + } + expect(caught).toBeDefined(); + + // Simulate what app.onError / the tRPC errorFormatter would log. + const dashboardPayload = formatDashboardErrorLog(caught, { + path: '/trpc/projects.integrations.upsert', + method: 'POST', + }); + console.error('Unhandled error', dashboardPayload); + + const joined = logs.join('\n'); + expect(joined).not.toContain(SECRET_SENTINEL); + // But the log DID capture the real PG error (diagnosability). + expect(joined).toMatch(/23503|foreign key|project_integrations_project_id_fkey/); + }); + + it('tRPC error log formatter output does not contain credential values', async () => { + await writeProjectCredential('test-project', 'LINEAR_WEBHOOK_SECRET', SECRET_SENTINEL); + + let caught: unknown; + try { + await upsertProjectIntegration('nonexistent-project', 'pm', 'linear', {}); + } catch (e) { + caught = e; + } + + const payload = formatTRPCErrorLog({ + error: { + code: 'INTERNAL_SERVER_ERROR', + message: (caught as Error).message, + cause: caught, + name: 'TRPCError', + stack: (caught as Error).stack, + } as unknown as import('@trpc/server').TRPCError, + path: 'projects.integrations.upsert', + type: 'mutation', + }); + const serialized = JSON.stringify(payload); + expect(serialized).not.toContain(SECRET_SENTINEL); + }); +}); From 92870c95953c2767aac6e72d106fe1948e814c63 Mon Sep 17 00:00:00 2001 From: zbigniew sobiecki Date: Wed, 15 Apr 2026 19:13:30 +0200 Subject: [PATCH 05/10] =?UTF-8?q?docs(plans):=20plan=20002/1=20(save-path-?= =?UTF-8?q?fix)=20done=20=E2=80=94=20unblock=20Linear=20wizard=20Save?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All 11 per-plan ACs pass. Spec ACs #5-8 delivered: - Linear upsert succeeds on fresh projects and re-configuration - DB error diagnostics (SQLSTATE, constraint, detail) surface in server logs - tRPC clients receive generic 'Internal server error' for unexpected throws - Plaintext credentials never leak into captured stdout/stderr Caveat: CLAUDE.md addition deferred to avoid conflicting with the user's in-progress rewrite of that file. Doc impact met via CHANGELOG. Co-Authored-By: Claude Opus 4.6 (1M context) --- CHANGELOG.md | 3 +++ .../{1-save-path-fix.md.wip => 1-save-path-fix.md.done} | 0 2 files changed, 3 insertions(+) rename docs/plans/002-linear-webhook-setup-ux/{1-save-path-fix.md.wip => 1-save-path-fix.md.done} (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index a69641f5..fab69269 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,4 +10,7 @@ All notable user-visible changes to CASCADE are documented here. The format is l ### Fixed +- **Linear wizard Save — HTTP 500 on `projects.integrations.upsert`.** A check constraint (`chk_integration_category_provider`) restricted the `pm` category to `trello` or `jira`; Linear support shipped without a matching constraint update, so every attempt to save a Linear PM integration failed with SQLSTATE 23514. Migration 0049 adds `linear` to the allowed `pm` providers. (Spec [002](docs/specs/002-linear-webhook-setup-ux.md), plan [1/2](docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md).) +- **Dashboard error logs now surface DB diagnostic fields.** Unhandled errors in the Hono app error handler and tRPC error formatter now include PG error code, detail, constraint, table, and column (unwrapped from `.cause` when Drizzle wraps a pg driver error). Clients still receive a generic "Internal server error" for unexpected `INTERNAL_SERVER_ERROR` throws — real diagnostics go to stdout for operators to grep. (Spec [002](docs/specs/002-linear-webhook-setup-ux.md), plan [1/2](docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md).) + - **Review agent on external-fork and large PRs.** PR checkouts now use the canonical `refs/pull/N/head` ref, which works for same-repo branches and external-fork branches alike. Previously, a silent `git checkout ` failure on fork PRs caused the worker to review the base branch (`dev`) while believing it was on the PR branch, producing confidently wrong reviews. Any git or HEAD-SHA mismatch now fails the run loudly rather than silently continuing. Additionally, every paginated GitHub REST endpoint used in the review setup pipeline now paginates to completion, so PRs with more than 100 changed files are no longer truncated at the first page. (Spec [001](docs/specs/001-pr-review-correctness.md), plan [1/2](docs/plans/001-pr-review-correctness/1-checkout-and-pagination.md.done).) diff --git a/docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md.wip b/docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md.done similarity index 100% rename from docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md.wip rename to docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md.done From d79c923ca557bf8d1b6f698427002912417f3db5 Mon Sep 17 00:00:00 2001 From: zbigniew sobiecki Date: Wed, 15 Apr 2026 19:13:50 +0200 Subject: [PATCH 06/10] docs(plans): update plan 002/1 progress checkboxes to done Co-Authored-By: Claude Opus 4.6 (1M context) --- .../1-save-path-fix.md.done | 27 ++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md.done b/docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md.done index 1559b17b..97be5c94 100644 --- a/docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md.done +++ b/docs/plans/002-linear-webhook-setup-ux/1-save-path-fix.md.done @@ -6,7 +6,7 @@ plan_slug: save-path-fix level: plan parent_spec: docs/specs/002-linear-webhook-setup-ux.md depends_on: [] -status: wip +status: done --- # 002/1: Linear Wizard Save — Unblock, Diagnose, Harden @@ -208,14 +208,17 @@ Not touched in this plan (owned by plan 2): ## Progress -- [ ] AC #1 — Save succeeds, fresh project -- [ ] AC #2 — Save succeeds, re-configuration -- [ ] AC #3 — Structured DB error in server log -- [ ] AC #4 — No plaintext credentials in logs (happy path) -- [ ] AC #5 — No plaintext credentials in logs (error path) -- [ ] AC #6 — Safe client error payload -- [ ] AC #7 — Tests exist for all new/modified code -- [ ] AC #8 — Build passes -- [ ] AC #9 — Unit + integration tests pass -- [ ] AC #10 — Lint passes -- [ ] AC #11 — Typecheck passes +- [x] AC #1 — Save succeeds, fresh project +- [x] AC #2 — Save succeeds, re-configuration +- [x] AC #3 — Structured DB error in server log +- [x] AC #4 — No plaintext credentials in logs (happy path) +- [x] AC #5 — No plaintext credentials in logs (error path) +- [x] AC #6 — Safe client error payload +- [x] AC #7 — Tests exist for all new/modified code +- [x] AC #8 — Build passes (typecheck + lint clean) +- [x] AC #9 — Unit + integration tests pass (7568 + 522 green) +- [x] AC #10 — Lint passes +- [x] AC #11 — Typecheck passes + +**Caveats:** +- CLAUDE.md doc update deferred — user has an in-progress CLAUDE.md rewrite (pre-existing uncommitted diff at session start). Adding a bullet now would conflict. Plan 1's doc impact is met by the CHANGELOG entry (two "Fixed" bullets covering the save-path fix and the structured error logging). From c642823c28550dbcdf04fea9f8912635e3cf423e Mon Sep 17 00:00:00 2001 From: zbigniew sobiecki Date: Wed, 15 Apr 2026 19:19:15 +0200 Subject: [PATCH 07/10] docs(plans): lock plan 002/2 + record testing-approach divergence Plan 2 originally assumed @testing-library/react in web/; project has no such infrastructure and the web/ package has no test script. Plan edited in place to: - use react-dom/server.renderToStaticMarkup (available; no new deps) - test under the existing root unit-core project - drop interactive-mutation tests (would need jsdom); ProjectSecretField internals are out-of-scope per spec non-goal Co-Authored-By: Claude Opus 4.6 (1M context) --- ...-step.md => 2-wizard-webhooks-step.md.wip} | 48 ++++++++++++------- 1 file changed, 30 insertions(+), 18 deletions(-) rename docs/plans/002-linear-webhook-setup-ux/{2-wizard-webhooks-step.md => 2-wizard-webhooks-step.md.wip} (73%) diff --git a/docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md b/docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md.wip similarity index 73% rename from docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md rename to docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md.wip index 16b0f058..887f2202 100644 --- a/docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md +++ b/docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md.wip @@ -61,13 +61,25 @@ Context to lift from the spec (do not re-argue): ## Detailed Task List (TDD) +### Testing approach (note on plan divergence 2026-04-15) + +`web/` has **no React component-testing infrastructure** — no `@testing-library/react`, no jsdom, no `.test.tsx` files anywhere. Existing web-ui tests (e.g. `tests/unit/web/pm-wizard-state.test.ts`) are Node-side `.test.ts` files that exercise pure reducer/utility code under the root's `unit-core` vitest project. + +Rather than add new test infrastructure (out of scope for a UX-polish plan), these plan-2 tests use **`react-dom/server`'s `renderToStaticMarkup`** to render components to an HTML string in plain Node, then assert against the string. This is adequate for the copy / presence / absence assertions the ACs demand; it cannot cover interactive behavior (typing, clicking, mutation firing), which is dropped from the plan here. + +**Test locations:** +- `tests/unit/web/linear-webhook-info-panel.test.ts` — renders `LinearWebhookInfoPanel` with `renderToStaticMarkup`; asserts copy, events list, absence of deprecated bullets, presence of `ProjectSecretField` shape. +- `tests/unit/web/pm-wizard-webhooks-step.test.ts` — renders `WebhookStep` for each provider (`linear`, `trello`, `jira`); asserts Linear shows the secret field, Trello/JIRA do not. + +Interactive behavior (clicking Save, mutation invocation, query invalidation) is **out of scope for automated tests in this plan** — the `ProjectSecretField` component itself is untested today under the same constraint, and re-verifying `ProjectSecretField`'s internals is spec non-goal ("Any modification to `ProjectSecretField` itself — the existing component must be used as-is"). Interactive verification lives in the manual acceptance-tests section below. + ### 1. Update `LinearWebhookInfoPanel` — events list copy -**Tests first** (`web/tests/components/projects/LinearWebhookInfoPanel.test.tsx` — new file; pick the testing stack already used by `web/` — likely `vitest` + `@testing-library/react`, same as other `web/tests/components/**/*.test.tsx` if any, or colocate as `*.test.tsx` alongside the component if the project convention is colocated): +**Tests first** (`tests/unit/web/linear-webhook-info-panel.test.ts` — new file, Node SSR style): -- `renders a three-item events list: Issues, Comments, Issue Labels` — mount the component with a `webhookUrl`, assert three `
  • ` children inside the "Enable events" block with matching `` labels. Snapshot-free assertions via `getByText`. -- `each events-list item has a one-line rationale matching a registered trigger` — assert the rendered text contains the phrases "status transitions" (for Issues), "mentions" (for Comments), and "Ready to Process" (for Issue Labels). Enough for a reviewer to confirm the copy traces back to `src/triggers/linear/register.ts`. -- `does not mention Documents, Emoji reactions, Customer requests, Cycles, Users, Initiatives, Project updates, Projects, Issue SLA, or Issue attachments` — assert none of those strings appear in the rendered panel. Prevents copy drift. +- `renders a three-item events list: Issues, Comments, Issue Labels` — SSR-render with a `webhookUrl`, assert the HTML contains `Issues`, `Comments`, `Issue Labels` exactly once each. +- `each events-list item has a one-line rationale matching a registered trigger` — assert the rendered HTML contains the phrases "status transitions" (for Issues), "mention" (for Comments, case-insensitive), and "Ready to Process" (for Issue Labels). Traces back to `src/triggers/linear/register.ts`. +- `does not mention Documents, Emoji reactions, Customer requests, Cycles, Users, Initiatives, Project updates, Projects, Issue SLA, or Issue attachments` — assert none of those strings appear in the rendered HTML. Prevents copy drift. - `keeps the manual-setup-required blue info block` — assert the "Manual Webhook Setup Required" string is still present. Protects against collateral deletion. **Implementation** (`web/src/components/projects/pm-wizard-common-steps.tsx`, `LinearWebhookInfoPanel`): @@ -90,10 +102,10 @@ Context to lift from the spec (do not re-argue): **Tests first** (same test file): -- `renders a signing-secret input labelled "Webhook Signing Secret (optional)"` — mount with `projectId` and a `credential` prop set to `null`, assert an input with placeholder matching `lin_wh_...` is rendered. -- `shows masked-configured state when a credential is already set` — mount with `credential={{ envVarKey: 'LINEAR_WEBHOOK_SECRET', name: 'Linear Webhook Secret', isConfigured: true, maskedValue: '...abcd' }}`, assert the "Configured" badge and masked value appear. -- `saves the secret via the existing credential mutation when submitted` — mock `trpcClient.projects.credentials.set.mutate`, submit a value, assert the mutation is called with `{ projectId, envVarKey: 'LINEAR_WEBHOOK_SECRET', value, name: 'Linear Webhook Secret' }` and no other credential-save path is invoked. -- `does not render the old "store as LINEAR_WEBHOOK_SECRET in project credentials" bullet` — assert the string "in project credentials" is absent from the panel. +- `renders a signing-secret input labelled "Webhook Signing Secret (optional)"` — SSR-render with `projectId` and no credential; assert the rendered HTML contains the label "Webhook Signing Secret (optional)" and a placeholder matching `lin_wh_`. +- `shows masked-configured state when a credential is already set` — SSR-render with `credential={{ envVarKey: 'LINEAR_WEBHOOK_SECRET', name: 'Linear Webhook Secret', isConfigured: true, maskedValue: '...abcd' }}`; assert the masked value `...abcd` is present in the HTML. +- ~~`saves the secret via the existing credential mutation when submitted`~~ — **dropped as plan divergence**: interactive mutation firing requires jsdom + testing-library which the project does not ship. `ProjectSecretField` already calls `trpcClient.projects.credentials.set.mutate({projectId, envVarKey, value, name: label})` — verified by code inspection. Spec AC #4 is met because the inline field composes `ProjectSecretField` with `envVarKey="LINEAR_WEBHOOK_SECRET"` and `label="Webhook Signing Secret (optional)"`, which the component uses as the `name` argument. Manual acceptance test below covers end-to-end firing. +- `does not render the old "store as LINEAR_WEBHOOK_SECRET in project credentials" bullet` — assert the string "in project credentials" is absent from the rendered HTML. **Implementation** (`web/src/components/projects/pm-wizard-common-steps.tsx`): @@ -138,12 +150,12 @@ Context to lift from the spec (do not re-argue): ### 3. Wizard-level wiring -**Tests first** (`web/tests/components/projects/pm-wizard.test.tsx` — augment existing or add a focused test file if absent): +**Tests first** (`tests/unit/web/pm-wizard-webhooks-step.test.ts` — new file, Node SSR style): -- `when provider is linear and step is webhooks, LinearWebhookInfoPanel receives the project's LINEAR_WEBHOOK_SECRET credential` — mount `PMWizard` with mocked tRPC and a `credentials.list` response containing a `LINEAR_WEBHOOK_SECRET` row; advance to the Webhooks step; assert the masked state appears. -- `when the user types a new value into the secret field and moves on, credentials.set is called with LINEAR_WEBHOOK_SECRET` — mock the mutation, fire a change event, assert the call. -- `Trello Webhooks step does not render ProjectSecretField` — switch provider to `trello` and confirm no `LINEAR_WEBHOOK_SECRET` input is present. -- `JIRA Webhooks step does not render ProjectSecretField` — same for JIRA. +- `Linear Webhooks step receives and threads a LINEAR_WEBHOOK_SECRET credential into the panel` — SSR-render `WebhookStep` with `state.provider='linear'`, `state.projectId='p1'`, and `linearWebhookSecretCredential={...configured with maskedValue ...abcd}`; assert `...abcd` appears in the rendered HTML. +- `Trello Webhooks step does not render a LINEAR_WEBHOOK_SECRET input` — SSR-render with `state.provider='trello'`; assert `LINEAR_WEBHOOK_SECRET` string and `Webhook Signing Secret` label do not appear. +- `JIRA Webhooks step does not render a LINEAR_WEBHOOK_SECRET input` — same for `jira`. +- ~~`user types and credentials.set is called`~~ — interactive, dropped (see divergence note). **Implementation** (`web/src/components/projects/pm-wizard.tsx`): @@ -152,10 +164,10 @@ Context to lift from the spec (do not re-argue): ### 4. Cross-check no regression for Trello and JIRA -**Tests first** (same test file or `web/tests/components/projects/pm-wizard-webhooks-trello.test.tsx`): +**Tests first** (same test file, `tests/unit/web/pm-wizard-webhooks-step.test.ts`): -- `Trello Webhooks step UI matches pre-change snapshot` — given provider `trello` and no active webhooks, assert the "No Trello webhooks configured" message, the "Create Webhook" button, and the curl-command `
    ` block are all present unchanged. No secret field. -- `JIRA Webhooks step UI matches pre-change snapshot` — same structure for JIRA. +- `Trello Webhooks step still renders curl command block` — SSR-render with `state.provider='trello'`; assert the rendered HTML contains `curl -X POST` and `api.trello.com`. +- `JIRA Webhooks step still renders curl command block` — SSR-render with `state.provider='jira'`; assert HTML contains `curl -X POST` and `/rest/webhooks/1.0/webhook`. **Implementation:** No code change unless tests fail. If they fail, investigate the prop drilling in task 3 to ensure Linear-only props aren't leaking into other provider branches. @@ -175,8 +187,8 @@ Context to lift from the spec (do not re-argue): ## Test Plan ### Unit tests -- [ ] `web/tests/components/projects/LinearWebhookInfoPanel.test.tsx` (or colocated `.test.tsx`): 8 tests covering events-list copy, secret-field presence, masked state, save mutation, absence of deprecated bullet, preservation of manual-setup block, and four absence assertions. -- [ ] `web/tests/components/projects/pm-wizard.test.tsx` additions: 4 tests covering credential threading and Trello/JIRA non-regression. +- [ ] `tests/unit/web/linear-webhook-info-panel.test.ts` (Node SSR): ~7 tests covering events-list copy, secret-field presence, masked state, absence of deprecated bullet, preservation of manual-setup block, absence assertions. +- [ ] `tests/unit/web/pm-wizard-webhooks-step.test.ts` (Node SSR): ~5 tests covering Linear credential threading, Trello/JIRA non-regression. ### Integration tests - [ ] None added in this plan — plan 1 already covers the backend save path with integration tests. The wizard-to-save integration happens via the manual end-to-end step below. From 6105d1069fff06ded93953cbd1728609ea886827 Mon Sep 17 00:00:00 2001 From: zbigniew sobiecki Date: Wed, 15 Apr 2026 19:19:27 +0200 Subject: [PATCH 08/10] docs(plans): plan 002/2 frontmatter status -> wip Co-Authored-By: Claude Opus 4.6 (1M context) --- .../002-linear-webhook-setup-ux/2-wizard-webhooks-step.md.wip | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md.wip b/docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md.wip index 887f2202..ece5d4ff 100644 --- a/docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md.wip +++ b/docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md.wip @@ -6,7 +6,7 @@ plan_slug: wizard-webhooks-step level: plan parent_spec: docs/specs/002-linear-webhook-setup-ux.md depends_on: [1-save-path-fix.md] -status: pending +status: wip --- # 002/2: Linear Wizard Webhooks Step — Correct Events List + Inline Signing Secret From 546abcc861b7a38c1ede1b821a9bd586467c2ca7 Mon Sep 17 00:00:00 2001 From: zbigniew sobiecki Date: Wed, 15 Apr 2026 19:26:22 +0200 Subject: [PATCH 09/10] =?UTF-8?q?feat(dashboard):=20linear=20wizard=20UX?= =?UTF-8?q?=20=E2=80=94=20accurate=20events=20list=20and=20inline=20signin?= =?UTF-8?q?g=20secret?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Plan 002/2 (wizard-webhooks-step). Linear PM wizard Webhooks step now: - lists the three event families CASCADE consumes (Issues, Comments, Issue Labels), each with a one-line rationale tracing to src/triggers/linear/ - renders a ProjectSecretField bound to LINEAR_WEBHOOK_SECRET directly beneath the webhook URL, matching the Sentry alerting tab pattern - drops the 'store as LINEAR_WEBHOOK_SECRET in project credentials' trailing bullet (replaced by the inline input) PMWizard threads projectId + the masked LINEAR_WEBHOOK_SECRET credential meta from projects.credentials.list through WebhookStep, so the field reflects its own stored value on mount and stays in sync with the Credentials tab. Tests: 17 new SSR tests using react-dom/server — no React testing library required. Interactive mutation firing is out of scope (would need jsdom); ProjectSecretField itself is untested today under the same constraint and is spec non-goal to modify. vitest.config.ts gains @/components, @/lib, @/hooks aliases pointing at web/src/ for test-time resolution. src/integrations/README.md Linear section defers to the dashboard wizard as the authoritative setup source. Plan 2 closes out spec 002. Co-Authored-By: Claude Opus 4.6 (1M context) --- CHANGELOG.md | 4 + ....md.wip => 2-wizard-webhooks-step.md.done} | 30 +-- src/integrations/README.md | 4 + .../web/linear-webhook-info-panel.test.ts | 130 +++++++++++++ .../unit/web/pm-wizard-webhooks-step.test.ts | 181 ++++++++++++++++++ vitest.config.ts | 17 +- .../projects/pm-wizard-common-steps.tsx | 46 ++++- web/src/components/projects/pm-wizard.tsx | 6 + 8 files changed, 393 insertions(+), 25 deletions(-) rename docs/plans/002-linear-webhook-setup-ux/{2-wizard-webhooks-step.md.wip => 2-wizard-webhooks-step.md.done} (95%) create mode 100644 tests/unit/web/linear-webhook-info-panel.test.ts create mode 100644 tests/unit/web/pm-wizard-webhooks-step.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index fab69269..e71ebdf5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ All notable user-visible changes to CASCADE are documented here. The format is l ## Unreleased +### Added + +- **Linear wizard — inline webhook signing-secret field and accurate events list.** The Webhooks step of the Linear PM wizard now renders a `ProjectSecretField` bound to `LINEAR_WEBHOOK_SECRET` directly beneath the webhook URL, so operators can paste Linear's signing secret in place instead of navigating to the Credentials tab. The "Enable events" instructions now list the three event families CASCADE actually consumes — `Issues` (status transitions), `Comments` (bot @mentions), and `Issue Labels` ("Ready to Process") — each with a one-line rationale tracing back to the registered trigger handlers. (Spec [002](docs/specs/002-linear-webhook-setup-ux.md), plan [2/2](docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md).) + ### Changed - **Review-agent context shape: compact diffs instead of full files.** The review agent's pre-fetched PR context now consists of compact per-file diffs (using GitHub's `file.patch`) rather than full file contents. Files that can't fit the budget — deleted, binary, oversized patch, or cumulative budget exhausted — are surfaced in a structured `SKIPPED FILES` injection that names each file with a reason and tells the agent how to fetch it on demand (`gh pr diff`, `Read`, `Grep`). This scales with PR size rather than repo size, mitigates LLM context rot, and ensures the agent is aware of (rather than blind to) the omissions. The context budget is `REVIEW_DIFF_CONTEXT_TOKEN_LIMIT` (200k tokens), replacing the prior 25k full-file cap. The `SKIPPED FILES` injection is also delivered to the four other agents that share the PR context pipeline (`respond-to-ci`, `respond-to-pr-comment`, `respond-to-review`, `resolve-conflicts`); explicit prompt guidance is added in `review.yaml` only. (Spec [001](docs/specs/001-pr-review-correctness.md), plan [2/2](docs/plans/001-pr-review-correctness/2-context-rework.md.done).) diff --git a/docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md.wip b/docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md.done similarity index 95% rename from docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md.wip rename to docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md.done index ece5d4ff..750ca2d7 100644 --- a/docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md.wip +++ b/docs/plans/002-linear-webhook-setup-ux/2-wizard-webhooks-step.md.done @@ -6,7 +6,7 @@ plan_slug: wizard-webhooks-step level: plan parent_spec: docs/specs/002-linear-webhook-setup-ux.md depends_on: [1-save-path-fix.md] -status: wip +status: done --- # 002/2: Linear Wizard Webhooks Step — Correct Events List + Inline Signing Secret @@ -247,17 +247,17 @@ Not touched in this plan (already owned by plan 1): ## Progress -- [ ] AC #1 — three-item events list -- [ ] AC #2 — no unused event families mentioned -- [ ] AC #3 — ProjectSecretField renders for Linear -- [ ] AC #4 — save mutation called with correct args -- [ ] AC #5 — masked state on initial mount -- [ ] AC #6 — inline and Credentials-tab surfaces stay in sync -- [ ] AC #7 — Trello/JIRA unchanged -- [ ] AC #8 — Sentry alerting tab unchanged -- [ ] AC #9 — tests for all new code -- [ ] AC #10 — build passes -- [ ] AC #11 — tests pass -- [ ] AC #12 — lint passes -- [ ] AC #13 — typecheck passes -- [ ] AC #14 — integrations/README.md reflects the change +- [x] AC #1 — three-item events list +- [x] AC #2 — no unused event families mentioned +- [x] AC #3 — ProjectSecretField renders for Linear +- [x] AC #4 — save mutation called with correct args (*verified by code inspection; interactive test requires jsdom — see divergence note*) +- [x] AC #5 — masked state on initial mount +- [x] AC #6 — inline and Credentials-tab surfaces stay in sync (by construction — both read `project_credentials`) +- [x] AC #7 — Trello/JIRA unchanged +- [x] AC #8 — Sentry alerting tab unchanged (file unmodified) +- [x] AC #9 — tests for all new code (17 new SSR tests) +- [x] AC #10 — build passes (root + web typecheck clean) +- [x] AC #11 — tests pass (7585 unit + 522 integration) +- [x] AC #12 — lint passes +- [x] AC #13 — typecheck passes +- [x] AC #14 — integrations/README.md adds "Linear — operator setup" pointer to the wizard diff --git a/src/integrations/README.md b/src/integrations/README.md index 9a1b6d0c..f5006eeb 100644 --- a/src/integrations/README.md +++ b/src/integrations/README.md @@ -459,5 +459,9 @@ Before submitting a new integration: | `trello` | pm | `src/pm/trello/integration.ts` | `src/router/adapters/trello.ts` | `src/triggers/trello/` | | `jira` | pm | `src/pm/jira/integration.ts` | `src/router/adapters/jira.ts` | `src/triggers/jira/` | | `linear` | pm | `src/pm/linear/integration.ts` | `src/router/adapters/linear.ts` | `src/triggers/linear/` | + +### Linear — operator setup + +Linear webhooks are configured **manually in Linear** (CASCADE cannot create them programmatically). The authoritative setup instructions — including the three event families CASCADE consumes (**Issues**, **Comments**, **Issue Labels**) and the inline signing-secret input — live in the dashboard PM wizard at `web/src/components/projects/pm-wizard-common-steps.tsx` (`LinearWebhookInfoPanel`). Any changes to the trigger handlers in `src/triggers/linear/` should be reflected there. | `github` | scm | `src/github/scm-integration.ts` | `src/router/adapters/github.ts` | `src/triggers/github/` | | `sentry` | alerting | `src/sentry/alerting-integration.ts` | `src/router/adapters/sentry.ts` | `src/triggers/sentry/` | diff --git a/tests/unit/web/linear-webhook-info-panel.test.ts b/tests/unit/web/linear-webhook-info-panel.test.ts new file mode 100644 index 00000000..ab0dac34 --- /dev/null +++ b/tests/unit/web/linear-webhook-info-panel.test.ts @@ -0,0 +1,130 @@ +/** + * Unit tests for LinearWebhookInfoPanel — Node SSR via react-dom/server. + * + * `web/` ships no jsdom + testing-library. These tests render the component + * to a static HTML string and assert copy/structure against that string. + * Interactive behavior (submit, mutation invocation) is out of scope — see + * the plan-divergence note in docs/plans/002-linear-webhook-setup-ux/2-*.md. + */ + +import { createElement } from 'react'; +import { renderToStaticMarkup } from 'react-dom/server'; +import { describe, expect, it, vi } from 'vitest'; + +// ProjectSecretField pulls in React Query + tRPC client. For copy/structure +// assertions we only need to know it was rendered with the expected props. +vi.mock('../../../web/src/components/projects/project-secret-field.js', () => ({ + ProjectSecretField: ({ + projectId, + envVarKey, + label, + placeholder, + credential, + }: { + projectId: string; + envVarKey: string; + label: string; + placeholder?: string; + credential?: { isConfigured: boolean; maskedValue: string }; + }) => + createElement( + 'div', + { + 'data-testid': 'project-secret-field', + 'data-envvarkey': envVarKey, + 'data-projectid': projectId, + }, + createElement('label', null, label), + createElement('input', { placeholder, type: 'password' }), + credential?.isConfigured + ? createElement('span', null, credential.maskedValue) + : createElement('span', null, 'not configured'), + ), +})); + +import { LinearWebhookInfoPanel } from '../../../web/src/components/projects/pm-wizard-common-steps.js'; + +function render(props: Parameters[0]): string { + return renderToStaticMarkup(createElement(LinearWebhookInfoPanel, props)); +} + +const baseProps = { + webhookUrl: 'https://dev.api.ca.sca.de.com/linear/webhook', + projectId: 'test-project', + webhookSecretCredential: undefined, +} as const; + +describe('LinearWebhookInfoPanel — events list', () => { + it('renders a three-item events list: Issues, Comments, Issue Labels', () => { + const html = render(baseProps); + expect(html).toMatch(/Issues<\/strong>/); + expect(html).toMatch(/Comments<\/strong>/); + expect(html).toMatch(/Issue Labels<\/strong>/); + }); + + it('each events-list item has a rationale tracing back to a registered trigger', () => { + const html = render(baseProps); + expect(html.toLowerCase()).toContain('status transitions'); + expect(html.toLowerCase()).toMatch(/mention/); + expect(html).toContain('Ready to Process'); + }); + + it('does not mention event families CASCADE does not consume', () => { + const html = render(baseProps); + for (const forbidden of [ + 'Documents', + 'Emoji reactions', + 'Customer requests', + 'Cycles', + 'Users', + 'Initiatives', + 'Project updates', + 'Projects', + 'Issue SLA', + 'Issue attachments', + ]) { + expect(html).not.toContain(forbidden); + } + }); + + it('preserves the manual-setup-required blue info block', () => { + const html = render(baseProps); + expect(html).toContain('Manual Webhook Setup Required'); + }); + + it('drops the deprecated "store as LINEAR_WEBHOOK_SECRET in project credentials" bullet', () => { + const html = render(baseProps); + expect(html).not.toContain('in project credentials'); + }); + + it('still shows the webhook URL and copy affordance', () => { + const html = render(baseProps); + expect(html).toContain('https://dev.api.ca.sca.de.com/linear/webhook'); + }); +}); + +describe('LinearWebhookInfoPanel — inline signing-secret field', () => { + it('renders a signing-secret input labelled "Webhook Signing Secret (optional)" with a lin_wh placeholder', () => { + const html = render(baseProps); + expect(html).toContain('Webhook Signing Secret (optional)'); + expect(html).toMatch(/placeholder="lin_wh_/); + }); + + it('shows masked-configured state when the LINEAR_WEBHOOK_SECRET credential is already set', () => { + const html = render({ + ...baseProps, + webhookSecretCredential: { + envVarKey: 'LINEAR_WEBHOOK_SECRET', + name: 'Webhook Signing Secret (optional)', + isConfigured: true, + maskedValue: '...abcd', + }, + }); + expect(html).toContain('...abcd'); + }); + + it('shows "not configured" indicator when no credential is present', () => { + const html = render(baseProps); + expect(html).toContain('not configured'); + }); +}); diff --git a/tests/unit/web/pm-wizard-webhooks-step.test.ts b/tests/unit/web/pm-wizard-webhooks-step.test.ts new file mode 100644 index 00000000..121dd12d --- /dev/null +++ b/tests/unit/web/pm-wizard-webhooks-step.test.ts @@ -0,0 +1,181 @@ +/** + * Unit tests for WebhookStep — Node SSR. + * + * Covers Linear credential threading and Trello / JIRA non-regression. See the + * plan-divergence note in the parent plan for why this is SSR-only (interactive + * tests need jsdom + testing-library, which web/ does not ship). + */ + +import { createElement } from 'react'; +import { renderToStaticMarkup } from 'react-dom/server'; +import { describe, expect, it, vi } from 'vitest'; + +// Stub ProjectSecretField to keep React Query + tRPC out of module load. +vi.mock('../../../web/src/components/projects/project-secret-field.js', () => ({ + ProjectSecretField: ({ + envVarKey, + label, + credential, + }: { + projectId: string; + envVarKey: string; + label: string; + credential?: { isConfigured: boolean; maskedValue: string }; + }) => + createElement( + 'div', + { + 'data-testid': 'project-secret-field', + 'data-envvarkey': envVarKey, + }, + createElement('label', null, label), + credential?.isConfigured ? createElement('span', null, credential.maskedValue) : null, + ), +})); + +import { WebhookStep } from '../../../web/src/components/projects/pm-wizard-common-steps.js'; +import type { WizardState } from '../../../web/src/components/projects/pm-wizard-state.js'; + +function makeState(overrides: Partial): WizardState { + return { + provider: 'trello', + trelloApiKey: '', + trelloToken: '', + trelloApiSecret: '', + trelloBoardId: '', + trelloOrgId: '', + trelloLists: {}, + trelloLabels: {}, + trelloCostField: null, + jiraEmail: '', + jiraApiToken: '', + jiraBaseUrl: '', + jiraProjectId: '', + jiraProjectKey: '', + jiraStatuses: {}, + jiraLabels: {}, + jiraCostField: null, + linearApiKey: '', + linearTeamId: '', + linearStatuses: {}, + linearLabels: {}, + isEditing: false, + verifyStatus: 'idle', + verifyMessage: null, + verifiedLogin: null, + availableBoards: [], + availableOrgs: [], + availableProjects: [], + availableTeams: [], + availableLists: [], + availableStatuses: [], + availableLabels: [], + availableTrelloCustomFields: [], + availableJiraCustomFields: [], + trelloLabelColors: {}, + ...overrides, + } as unknown as WizardState; +} + +const baseMutations = { + createWebhookMutation: { + mutate: () => {}, + isPending: false, + isError: false, + isSuccess: false, + error: null, + }, + deleteWebhookMutation: { + mutate: () => {}, + isPending: false, + isError: false, + }, +} as unknown as { + createWebhookMutation: Parameters[0]['createWebhookMutation']; + deleteWebhookMutation: Parameters[0]['deleteWebhookMutation']; +}; + +const baseProps = { + webhooksQuery: { isLoading: false, data: undefined, refetch: () => {} }, + activeWebhooks: [], + callbackBaseUrl: 'https://dev.api.ca.sca.de.com', + linearWebhookUrl: 'https://dev.api.ca.sca.de.com/linear/webhook', + projectId: 'test-project', + ...baseMutations, +} as const; + +function render(extra: Partial[0]>) { + return renderToStaticMarkup( + createElement(WebhookStep, { + ...baseProps, + ...extra, + } as Parameters[0]), + ); +} + +describe('WebhookStep — Linear credential threading', () => { + it('renders the LINEAR_WEBHOOK_SECRET field when state.provider is linear', () => { + const html = render({ + state: makeState({ provider: 'linear' }), + }); + expect(html).toContain('data-envvarkey="LINEAR_WEBHOOK_SECRET"'); + expect(html).toContain('Webhook Signing Secret (optional)'); + }); + + it('surfaces the masked credential value when one is threaded through', () => { + const html = render({ + state: makeState({ provider: 'linear' }), + linearWebhookSecretCredential: { + envVarKey: 'LINEAR_WEBHOOK_SECRET', + name: 'Webhook Signing Secret (optional)', + isConfigured: true, + maskedValue: '...abcd', + }, + }); + expect(html).toContain('...abcd'); + }); + + it('renders the three-item events list on the Linear step', () => { + const html = render({ state: makeState({ provider: 'linear' }) }); + expect(html).toMatch(/Issues<\/strong>/); + expect(html).toMatch(/Comments<\/strong>/); + expect(html).toMatch(/Issue Labels<\/strong>/); + }); +}); + +describe('WebhookStep — Trello non-regression', () => { + it('does not render the Linear secret field for Trello', () => { + const html = render({ state: makeState({ provider: 'trello' }) }); + expect(html).not.toContain('LINEAR_WEBHOOK_SECRET'); + expect(html).not.toContain('Webhook Signing Secret'); + }); + + it('still renders the Trello curl command block', () => { + const html = render({ + state: makeState({ provider: 'trello', trelloBoardId: 'b1' }), + }); + expect(html).toContain('curl -X POST'); + expect(html).toContain('api.trello.com'); + }); + + it('still renders the Create Webhook button', () => { + const html = render({ state: makeState({ provider: 'trello' }) }); + expect(html).toContain('Create Webhook'); + }); +}); + +describe('WebhookStep — JIRA non-regression', () => { + it('does not render the Linear secret field for JIRA', () => { + const html = render({ state: makeState({ provider: 'jira' }) }); + expect(html).not.toContain('LINEAR_WEBHOOK_SECRET'); + expect(html).not.toContain('Webhook Signing Secret'); + }); + + it('still renders the JIRA curl command block', () => { + const html = render({ + state: makeState({ provider: 'jira', jiraBaseUrl: 'https://example.atlassian.net' }), + }); + expect(html).toContain('curl -X POST'); + expect(html).toContain('/rest/webhooks/1.0/webhook'); + }); +}); diff --git a/vitest.config.ts b/vitest.config.ts index 2e17c567..a8b7c17b 100644 --- a/vitest.config.ts +++ b/vitest.config.ts @@ -5,11 +5,18 @@ import { defineConfig } from 'vitest/config'; const isCI = process.env.CI === 'true' || process.env.CI === '1'; const resolve = { - alias: { - '@': path.resolve(__dirname, './src'), - react: path.resolve(__dirname, 'node_modules/react'), - 'react-dom': path.resolve(__dirname, 'node_modules/react-dom'), - }, + // Order matters: web-side prefixes must come before the catch-all `@`. + alias: [ + { + find: /^@\/components\/(.*)/, + replacement: path.resolve(__dirname, './web/src/components/$1'), + }, + { find: /^@\/lib\/(.*)/, replacement: path.resolve(__dirname, './web/src/lib/$1') }, + { find: /^@\/hooks\/(.*)/, replacement: path.resolve(__dirname, './web/src/hooks/$1') }, + { find: '@', replacement: path.resolve(__dirname, './src') }, + { find: 'react', replacement: path.resolve(__dirname, 'node_modules/react') }, + { find: 'react-dom', replacement: path.resolve(__dirname, 'node_modules/react-dom') }, + ], }; // Shared settings inherited by every unit project diff --git a/web/src/components/projects/pm-wizard-common-steps.tsx b/web/src/components/projects/pm-wizard-common-steps.tsx index e87f918f..f0227bca 100644 --- a/web/src/components/projects/pm-wizard-common-steps.tsx +++ b/web/src/components/projects/pm-wizard-common-steps.tsx @@ -18,6 +18,7 @@ import { import { useState } from 'react'; import { Label } from '@/components/ui/label.js'; import type { WizardState } from './pm-wizard-state.js'; +import { type ProjectCredentialMeta, ProjectSecretField } from './project-secret-field.js'; // ============================================================================ // WebhookStep @@ -65,7 +66,15 @@ function CopyButton({ text }: { text: string }) { // LinearWebhookInfoPanel // ============================================================================ -export function LinearWebhookInfoPanel({ webhookUrl }: { webhookUrl: string }) { +export function LinearWebhookInfoPanel({ + webhookUrl, + projectId, + webhookSecretCredential, +}: { + webhookUrl: string; + projectId: string; + webhookSecretCredential?: ProjectCredentialMeta; +}) { return (
    @@ -91,6 +100,15 @@ export function LinearWebhookInfoPanel({ webhookUrl }: { webhookUrl: string }) {
    + +

    Setup instructions:

      @@ -108,13 +126,25 @@ export function LinearWebhookInfoPanel({ webhookUrl }: { webhookUrl: string }) {
    1. Click "New webhook" and enter the URL above
    2. - Enable events: Issues (created, updated, removed) + Enable these events (each maps to a CASCADE trigger handler): +
        +
      • + Issues — status transitions drive CASCADE's splitting, + planning, and implementation agents +
        • +
      • + Comments — @mentions of the CASCADE bot trigger a response agent +
        • +
      • + Issue Labels — adding the "Ready to Process" label starts + an agent on the issue +
        • +
    3. Select your team and save — webhooks are team-scoped in Linear
    4. - Optionally set a webhook secret and store it as{' '} - LINEAR_WEBHOOK_SECRET in - project credentials + If you set a signing secret in Linear, paste it into the field above so CASCADE can + verify webhook authenticity
    @@ -134,6 +164,8 @@ export function WebhookStep({ createWebhookMutation, deleteWebhookMutation, linearWebhookUrl, + projectId, + linearWebhookSecretCredential, }: { state: WizardState; webhooksQuery: WebhooksQueryProps; @@ -142,12 +174,16 @@ export function WebhookStep({ createWebhookMutation: UseMutationResult; deleteWebhookMutation: UseMutationResult; linearWebhookUrl?: string; + projectId: string; + linearWebhookSecretCredential?: ProjectCredentialMeta; }) { // Linear uses a display-only panel — no create/delete buttons if (state.provider === 'linear') { return ( ); } diff --git a/web/src/components/projects/pm-wizard.tsx b/web/src/components/projects/pm-wizard.tsx index 339407ec..12cd4c26 100644 --- a/web/src/components/projects/pm-wizard.tsx +++ b/web/src/components/projects/pm-wizard.tsx @@ -161,6 +161,10 @@ export function PMWizard({ const { webhookUrl: linearWebhookUrl } = useLinearWebhookInfo(); const { saveMutation } = useSaveMutation(projectId, state); + const linearWebhookSecretCredential = credentialsQuery.data?.find( + (c) => c.envVarKey === 'LINEAR_WEBHOOK_SECRET', + ); + // ---- Label creation handlers ---- const handleCreateLabel = (slot: string) => { @@ -383,6 +387,8 @@ export function PMWizard({ webhooksQuery={webhooksQuery} activeWebhooks={activeWebhooks} linearWebhookUrl={linearWebhookUrl} + projectId={projectId} + linearWebhookSecretCredential={linearWebhookSecretCredential} {...webhookManagement} /> From 3ce60533922ca563bc7c633741a483e443a19527 Mon Sep 17 00:00:00 2001 From: zbigniew sobiecki Date: Wed, 15 Apr 2026 19:27:13 +0200 Subject: [PATCH 10/10] docs(claude): streamline CLAUDE.md to essentials Compacts the project's CLAUDE.md from ~820 to ~163 lines by dropping dated setup minutiae, duplicated process docs, and legacy sections. Keeps the load-bearing context: architecture, PR checkout gotcha, testing commands, Zod policy, migrations, GitHub dual-persona rules, trigger system, engines, environment, and git hooks. No code changes. Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 829 ++++++------------------------------------------------ 1 file changed, 85 insertions(+), 744 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 517e0073..029ef90c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,821 +1,162 @@ -# CASCADE - PM-to-Code Automation Platform +# CASCADE — PM-to-Code Automation Platform -## Quick Start +## Quick start ```bash npm install cd web && npm install && cd .. -# Start Redis (required for router/BullMQ): -# macOS: brew install redis && brew services start redis -# Linux: apt-get install redis-server && service redis-server start -# The .cascade/setup.sh script handles this automatically. -npm run dev # Router (webhook receiver, requires Redis) -npm run dev:web # Dashboard frontend (separate terminal) +# Redis required (router/BullMQ). `.cascade/setup.sh` installs + starts it. +npm run dev # Router (webhook receiver, :3000) +npm run dev:web # Dashboard frontend (:5173, separate terminal) +node dist/dashboard.js # Dashboard API (:3001, third terminal, after `npm run build`) ``` -## Architecture - -CASCADE runs as three services (no monolithic server mode): - -1. **Router** (`src/router/index.ts`) — receives webhooks, enqueues jobs to Redis via BullMQ -2. **Worker** (`src/worker-entry.ts`) — processes one job per container, exits when done -3. **Dashboard** (`src/dashboard.ts`) — API + tRPC for web UI and CLI - -### Trigger System +> `npm start` runs the **router** (`dist/router/index.js`), **not** the dashboard. -The extensible trigger system routes events to agents: - -``` -Trello/JIRA/Linear/Sentry/GitHub Webhook → Router → Redis/BullMQ → Worker → TriggerRegistry → Agent → Code Changes → PR -``` +## Architecture -- `src/router/` - Webhook receiver (enqueues jobs to Redis) -- `src/webhook/` - Shared webhook handler factory, parsers, and logging -- `src/triggers/` - Event handlers (Trello/JIRA/Linear issue moves, labels, GitHub PRs, Sentry alerts) -- `src/agents/` - AI agents (splitting, planning, implementation, review, debug, alerting, backlog-manager, resolve-conflicts) -- `src/gadgets/` - Tools agents can use (PM/SCM/alerting operations, Tmux, Todo, file system) +Three separate services, **no monolithic server mode**: -### Multi-Project Support +1. **Router** (`src/router/index.ts`) — receives webhooks, enqueues to Redis/BullMQ. +2. **Worker** (`src/worker-entry.ts`) — processes one job per container, exits. +3. **Dashboard** (`src/dashboard.ts`) — tRPC API + static frontend for web UI and CLI. -Projects are configured in the PostgreSQL database (`projects` table). Each project has its own PM board, GitHub repo, and optional per-project credentials. +Flow: `PM/SCM/alerting webhook → Router → Redis → Worker → TriggerRegistry → Agent → Code → PR`. -## Development +Integration abstraction lives in `src/integrations/`. For **adding a new integration, trigger, or agent**, see @src/integrations/README.md — don't improvise, it covers all extension points. -### PR Checkout (worker) +## PR checkout (worker) — gotcha -The worker checks out PRs via the canonical `refs/pull/N/head` ref — works for both same-repo branches and external-fork branches. When `prNumber` is set on `AgentInput`, `setupRepository`: +Worker checks out PRs via `refs/pull/N/head` (works for same-repo **and** external-fork branches). When `prNumber` is set on `AgentInput`, `setupRepository`: 1. Fetches `+refs/pull//head:refs/remotes/pr/` from `origin`. 2. Detached-checks out `pr/`. -3. If `headSha` is also set on `AgentInput`, verifies `git rev-parse HEAD` matches. - -Any non-zero git exit code throws — there is no warn-and-continue in setup. Failed runs are marked failed in the dashboard rather than proceeding on a stale or wrong working tree. - -The legacy `prBranch` field is retained for human-readable logging but is **not** used to drive checkout (fork branches don't exist on `origin` and the by-name path silently 404s). +3. If `headSha` is also set, verifies `git rev-parse HEAD` matches. -### Testing +Any non-zero git exit code **throws** — no warn-and-continue. The legacy `prBranch` field is retained for log readability but **not** used to drive checkout (fork branches don't exist on `origin` and the by-name path silently 404s). -> **For a full catalog of test helpers, factory functions, and mock objects**, see [`tests/README.md`](tests/README.md). +## Testing ```bash -npm test # Run unit tests (all 4 unit projects) -npm run test:unit # Alias for npm test -npm run test:integration # Run integration tests (requires DB — see below) -npm run test:all # Run unit + integration tests together -npm run test:coverage # Coverage report (unit tests) -npm run test:watch # Watch mode (unit tests) +npm test # Unit tests (all 4 unit projects) +npm run test:integration # Integration tests (requires Postgres — see below) +npm run test:all # Unit + integration ``` -> **Do not use `npm test -- --project integration`** — it _adds_ the integration project on top of the hardcoded unit project flags, running all 5 projects instead of filtering. Use `npm run test:integration` instead. - -> **Agent tip — integration test runs are slow (~4 min for full suite).** When a specific -> test file is failing, always target it directly: -> ```bash -> # Run one file (seconds) instead of the full suite (4+ min): -> TEST_DATABASE_URL=... npx vitest run --project integration tests/integration/.test.ts -> ``` -> Run the full suite only to confirm all tests pass before pushing. - -Integration tests require a PostgreSQL database. The setup: -1. **Auto-creates** the database when `TEST_DATABASE_URL` is set and postgres is reachable - but the database doesn't exist yet (connects to `postgres` admin DB and creates it) -2. **Auto-finds** an existing DB via (in order): `TEST_DATABASE_URL` env var → - `TEST_DATABASE_URL` in `.cascade/env` → Docker Compose at `127.0.0.1:5433` → - container IP of `cascade-postgres-test` -3. **Silently skips** all integration tests if no database is reachable at all - -On developer machines (Docker): -```bash -npm run test:db:up # start ephemeral postgres on :5433 (one-time per session) -npm run test:integration # tests auto-find it, run migrations, clean up -``` +**⚠️ Do not use `npm test -- --project integration`** — it _adds_ the integration project on top of the hardcoded unit flags, running all 5 projects. Use `npm run test:integration`. -In worker/agent environments (local postgres already running): -```bash -TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/cascade_test \ - npm run test:integration # setup auto-creates cascade_test DB if missing -``` - -### Linting +**⚠️ Full integration suite takes ~4 min.** When iterating on one file, target it directly: ```bash -npm run lint # Check -npm run lint:fix # Fix -npm run typecheck # Type check +TEST_DATABASE_URL=... npx vitest run --project integration tests/integration/.test.ts ``` -### Zod Version Policy - -Both the root workspace and the `web/` workspace **must use the same Zod major version**. Currently both are aligned on `zod@^3.25.0` (the bridge version that ships v3 and v4 dual exports). - -- **Root (`package.json`)**: `"zod": "^3.25.0"` — backend uses the v3 API surface -- **Web (`web/package.json`)**: `"zod": "^3.25.0"` — frontend also uses v3 API surface - -**Why this matters**: `web/tsconfig.json` includes `../src/api/**/*` and `../src/db/**/*` (backend files that import from `zod`). If the two workspaces resolve different Zod major versions, `z.infer<>` can silently compute different types for the same schema in backend vs. frontend compilation contexts. - -**When upgrading Zod**: Both workspaces must be bumped to the same new version together. A full migration to the v4 API would also require auditing `z.ZodType` usage (renamed class hierarchy in v4), `z.ZodIssueCode` (slightly different enum), and `.default()` behavior (eagerly evaluated in v4). - -### Git Hooks - -Lefthook runs pre-commit (lint, typecheck) and pre-push (unit tests, integration tests) hooks automatically. The pre-push hook auto-starts an ephemeral PostgreSQL via Docker (`npm run test:db:up`) for integration tests — Docker must be running. - -## Key Directories - -- `src/router/` - Router entry point (webhook receiver, enqueues to Redis) -- `src/webhook/` - Shared webhook handler factory, parsers, and logging helpers -- `src/config/` - Configuration provider, caching, Zod schemas -- `src/db/` - Database client, Drizzle schema, repositories -- `src/integrations/` - **Unified integration interfaces and registry** (see below) -- `src/triggers/` - Extensible trigger system (Trello, JIRA, GitHub, Sentry) -- `src/agents/` - AI agent implementations -- `src/gadgets/` - Custom gadgets (PM, SCM, alerting, Tmux, Todo, file system) -- `src/cli/dashboard/` - Dashboard CLI commands (`cascade` binary) -- `src/cli/alerting/` - Alerting gadget commands (`cascade-tools` binary) -- `src/api/` - Dashboard API (tRPC routers, auth handlers) -- `src/github/` - GitHub client, dual-persona model (personas.ts) -- `src/trello/` - Trello API client -- `src/jira/` - JIRA API client -- `src/linear/` - Linear API client -- `src/sentry/` - Sentry API client and integration -- `src/utils/` - Utilities (logging, repo cloning, lifecycle) -- `web/` - Dashboard frontend (React 19, Vite, Tailwind v4, TanStack Router) -- `tools/` - Developer scripts (session debugging, DB seeding, secrets management) - -## Integration Architecture - -CASCADE uses a unified integration abstraction layer in `src/integrations/`. Every PM, SCM, -and alerting provider is a class implementing `IntegrationModule` (and optionally a -category-specific sub-interface). Modules register into `IntegrationRegistry` at bootstrap time. -Infrastructure (router, worker, webhook handler) looks up integrations by `type` string with no -provider-specific branching. +Integration test DB is auto-discovered in order: `TEST_DATABASE_URL` env → `TEST_DATABASE_URL` in `.cascade/env` → Docker Compose at `127.0.0.1:5433` → `cascade-postgres-test` container IP. If none reachable, integration tests **silently skip**. DB is auto-created if missing. -### Categories +Developer machines: `npm run test:db:up` once, then `npm run test:integration`. -| Category | Interface | Example providers | -|----------|-----------|-------------------| -| `pm` | `PMIntegration` (extends `IntegrationModule`) | Trello, JIRA, Linear | -| `scm` | `SCMIntegration` (extends `IntegrationModule`) | GitHub | -| `alerting` | `AlertingIntegration` (extends `IntegrationModule`) | Sentry | +Full test helper/factory/mock catalog: @tests/README.md. -### IntegrationModule (base contract) - -All integrations implement four required members: - -- `type` — unique provider string (e.g. `'trello'`, `'github'`, `'sentry'`) -- `category` — which capability group (`'pm'`, `'scm'`, or `'alerting'`) -- `withCredentials(projectId, fn)` — set env vars for the project, call `fn`, restore on exit -- `hasIntegration(projectId)` — returns `true` if all required credentials are present - -Optional webhook methods (`parseWebhookPayload`, `isSelfAuthored`, `lookupProject`, -`extractWorkItemId`) are implemented by providers that receive webhooks. - -### IntegrationRegistry - -`integrationRegistry` (singleton in `src/integrations/registry.ts`) is populated once at -bootstrap (`src/integrations/bootstrap.ts`). Callers use: - -```typescript -integrationRegistry.get('github') // throws if missing -integrationRegistry.getOrNull('sentry') // null if missing -integrationRegistry.getByCategory('pm') // all PM integrations -``` - -PM integrations are registered in `pmRegistry` via `src/integrations/bootstrap.ts` (the single canonical registration point). - -### Credential roles - -Each provider declares its credential roles in `src/config/integrationRoles.ts` via -`registerCredentialRoles(provider, category, roles)`. Roles map a logical `role` name to an -env-var key (e.g. `api_key` → `TRELLO_API_KEY`). Roles without `optional: true` are required -for `hasIntegration()` to return `true`. - -### Bootstrap - -`src/integrations/bootstrap.ts` is the single registration point for all five built-in -integrations. It is safe to import from both the router and worker — it does not pull in the -agent execution pipeline or template files. - -### Adding a new integration - -See [`src/integrations/README.md`](src/integrations/README.md) for the complete step-by-step -guide covering all extension points: interface implementation, credential roles, bootstrap -registration, webhook routes, router adapters, trigger handlers, and gadgets. - -## Environment Variables - -Required: -- `DATABASE_URL` - PostgreSQL connection string (e.g., `postgresql://user:pass@host:5432/cascade`) -- `REDIS_URL` - Redis connection string for BullMQ job queue (router + worker). Defaults to `redis://localhost:6379`. Run `.cascade/setup.sh` to install and start Redis locally. - -Optional (infrastructure): -- `PORT` - Server port (default: 3000) -- `LOG_LEVEL` - Logging level (default: info) -- `DATABASE_SSL` - Set to `false` to disable SSL for local PostgreSQL (default: enabled with certificate validation) -- `DATABASE_CA_CERT` - Path to a PEM-encoded CA certificate file for managed databases that use a private CA (e.g., AWS RDS, Azure Database, GCP Cloud SQL). When set, the certificate is read and passed as the `ca` option to `pg.Pool`, enabling TLS certificate validation against the specified CA. Example: `DATABASE_CA_CERT=/etc/ssl/certs/rds-ca.pem` -- `CLAUDE_CODE_OAUTH_TOKEN` - For Claude Code engine (subscription auth) -- `CREDENTIAL_MASTER_KEY` - 64-char hex string (32-byte AES-256 key) for encrypting credentials at rest. Generate with `npm run credentials:generate-key`. When set, all new/updated credentials are encrypted automatically; existing plaintext credentials continue to work. -- `WEBHOOK_CALLBACK_BASE_URL` - Base URL for webhook callbacks (e.g., `https://cascade.example.com`). Used by `tools/setup-webhooks.ts` and the `cascade webhooks create` CLI command to construct the full webhook URL. -- `GITHUB_WEBHOOK_SECRET` - Optional HMAC secret for GitHub webhook signature verification. When set as an integration credential (`webhook_secret` role on the GitHub SCM integration), all newly created GitHub webhooks will include the secret so GitHub signs each delivery. The router then verifies the `X-Hub-Signature-256` header on incoming payloads. -- `SENTRY_DSN` - Sentry DSN for error monitoring (router + worker) -- `SENTRY_ENVIRONMENT` - Sentry environment tag (default: NODE_ENV or 'production') -- `SENTRY_RELEASE` - Release identifier for source maps (e.g., git SHA) -- `SENTRY_TRACES_SAMPLE_RATE` - Trace sampling rate 0.0-1.0 (default: 0.1) - -**Project credentials** (`GITHUB_TOKEN_IMPLEMENTER`, `GITHUB_TOKEN_REVIEWER`, `TRELLO_API_KEY`, `TRELLO_TOKEN`, `LINEAR_API_KEY`, `LINEAR_WEBHOOK_SECRET`, LLM API keys) are stored in the `project_credentials` table — project-scoped, encrypted at rest when `CREDENTIAL_MASTER_KEY` is set. All credentials (integration tokens and LLM keys) use the same `project_credentials` table keyed by `(projectId, envVarKey)`. There is no env var fallback — the database is the sole source of truth for project-scoped secrets. - -## Database Configuration - -CASCADE stores all project configuration in PostgreSQL. The `config/projects.json` file is only used by `npm run db:seed` (initial seeding) — it is not read at runtime. - -### Schema - -- `organizations` - Organization definitions (multi-tenant support) -- `projects` - Per-project config (repo, base branch, budget, engine, and per-project overrides for model, iterations, timeouts, progress model/interval, `run_links_enabled`, `max_in_flight_items`) -- `project_integrations` - Integration configs per project with `category` (pm/scm), `provider` (trello/jira/linear/github), `config` JSONB, and `triggers` JSONB. One PM + one SCM per project (enforced by unique constraint) -- `project_credentials` - Project-scoped credentials keyed by `(projectId, envVarKey)`. Stores all credential types (GitHub tokens, Trello keys, JIRA tokens, Linear API keys, LLM API keys). Encrypted at rest when `CREDENTIAL_MASTER_KEY` is set -- `agent_configs` - Per-agent-type overrides (model, iterations, engine, `agent_engine_settings`, max_concurrency, `system_prompt`, `task_prompt`), project-scoped only (`project_id NOT NULL`) -- `agent_definitions` - Agent YAML definitions (built-in and custom). Each row stores the full definition JSONB, keyed by `agent_type` -- `agent_trigger_configs` - Configured trigger events per project/agent pair (replaces legacy `project_integrations.triggers`) -- `prompt_partials` - Org-scoped partial prompt templates for customizing agent prompts (`.eta` partials) -- `pr_work_items` - Maps PRs to work items (PR number + repo → work item ID/URL) for run-link display -- `webhook_logs` - Raw webhook payloads for debugging (source, headers, body, status, decision reason) -- `users` - Dashboard users (email, bcrypt password hash, org-scoped) -- `sessions` - Session tokens for cookie-based auth (30-day expiry) - -### Database Scripts +## Lint + typecheck ```bash -npm run db:generate # Generate migration SQL from schema changes -npm run db:migrate # Apply pending migrations -npm run db:push # Push schema directly (dev only) -npm run db:studio # Open Drizzle Studio -npm run db:seed -- --org # Seed DB from config/projects.json into an org -npm run db:bootstrap-journal # Bootstrap migration journal (one-time setup for existing DBs) +npm run lint # Check +npm run lint:fix # Fix +npm run typecheck ``` -### Migration Workflow - -Migrations are hand-written SQL files in `src/db/migrations/` tracked by drizzle-kit's journal (`meta/_journal.json`). When adding a new migration: +## Zod version policy -1. Create `src/db/migrations/NNNN_description.sql` -2. Add a corresponding entry to `src/db/migrations/meta/_journal.json` with a unique `when` timestamp (ms since epoch) and `tag` matching the filename without `.sql` -3. Run `npm run db:migrate` to apply +**Root and `web/` must use the same Zod major version.** Currently both on `zod@^3.25.0`. `web/tsconfig.json` includes `../src/api/**/*` and `../src/db/**/*` — if majors diverge, `z.infer<>` silently computes different types in backend vs frontend compilation. Bump both workspaces together. -For databases initially set up with `drizzle-kit push` (no migration journal), run `npm run db:bootstrap-journal` once to register existing migrations in the `drizzle.__drizzle_migrations` tracking table. +## Database -### Credential Encryption at Rest +Projects config lives in **PostgreSQL**, not in `config/projects.json`. The JSON file is only used by `npm run db:seed` for initial seeding; it is **not** read at runtime. -All credentials are project-scoped and stored in the `project_credentials` table keyed by `(projectId, envVarKey)`. Credentials are encrypted using AES-256-GCM when `CREDENTIAL_MASTER_KEY` is set. Encryption is transparent — all callers (config provider, tRPC, CLI, tools) are unaffected. +Migrations are **hand-written SQL** in `src/db/migrations/` tracked by drizzle-kit's journal. To add one: -- **Algorithm**: AES-256-GCM with 12-byte random IV, 16-byte auth tag, `projectId` as AAD -- **Storage format**: `enc:v1:::` in the existing `value` TEXT column -- **Automatic encryption**: `writeProjectCredential()` encrypts before DB write -- **Automatic decryption**: All resolve/list functions decrypt on read -- **Opt-in**: Without the env var, system works identically to plaintext (zero behavior change) +1. Create `src/db/migrations/NNNN_description.sql`. +2. Add a matching entry to `src/db/migrations/meta/_journal.json` (unique `when` ms, `tag` matches filename without `.sql`). +3. Run `npm run db:migrate`. -```bash -npm run credentials:generate-key # Generate a new 32-byte hex key -npm run credentials:encrypt -- --dry-run # Preview migration (plaintext → encrypted) -npm run credentials:encrypt # Encrypt all existing plaintext credentials -npm run credentials:decrypt # Rollback: decrypt all back to plaintext -npm run credentials:rotate-key # Re-encrypt with CREDENTIAL_MASTER_KEY_NEW -``` - -**Key rotation** requires both `CREDENTIAL_MASTER_KEY` (current) and `CREDENTIAL_MASTER_KEY_NEW` (new). After rotation, update the env var to the new key and restart. +For an existing DB set up via `drizzle-kit push` (no journal), run `npm run db:bootstrap-journal` once. -### GitHub Dual-Persona Model +## GitHub dual-persona model -CASCADE uses two dedicated GitHub bot accounts per project to prevent feedback loops: +Every project needs **two** bot tokens (prevents feedback loops): -- **Implementer** (`GITHUB_TOKEN_IMPLEMENTER`) — writes code, creates PRs, responds to review comments - - Agents: `implementation`, `respond-to-review`, `respond-to-ci`, `respond-to-pr-comment`, `splitting`, `planning`, `respond-to-planning-comment`, `debug`, `alerting`, `backlog-manager`, `resolve-conflicts` -- **Reviewer** (`GITHUB_TOKEN_REVIEWER`) — reviews PRs, can approve or request changes - - Agents: `review` +- `GITHUB_TOKEN_IMPLEMENTER` — writes code, opens PRs, responds to reviews. +- `GITHUB_TOKEN_REVIEWER` — reviews PRs (used only by the `review` agent). -Both tokens are **required** for each project. Store them via the dashboard (Project Settings > Credentials tab) or CLI: +Both are **required**. Set via dashboard Credentials tab or: ```bash -cascade projects credentials-set --key GITHUB_TOKEN_IMPLEMENTER --value ghp_aaa... -cascade projects credentials-set --key GITHUB_TOKEN_REVIEWER --value ghp_bbb... +cascade projects credentials-set --key GITHUB_TOKEN_IMPLEMENTER --value ghp_... +cascade projects credentials-set --key GITHUB_TOKEN_REVIEWER --value ghp_... ``` -**Bot detection**: Both persona usernames are resolved at first use and cached. Trigger handlers use `isCascadeBot(login)` to check if an event came from either persona, preventing self-triggered loops. - -**Loop prevention rules**: -- `respond-to-review` ONLY fires when the **reviewer** persona submits a `changes_requested` review -- `respond-to-pr-comment` skips @mentions from **any** known persona -- `check-suite-success` checks reviews from the **reviewer** persona specifically - -### Webhook Signature Verification - -CASCADE supports opt-in HMAC-SHA256 signature verification for GitHub webhook payloads. +**Loop-prevention rules (behavioral invariants):** -1. Store a `GITHUB_WEBHOOK_SECRET` credential as a project credential: - ```bash - cascade projects credentials-set --key GITHUB_WEBHOOK_SECRET --value - ``` -2. Create (or recreate) the GitHub webhook — CASCADE will include the secret automatically: - ```bash - cascade webhooks create [--callback-url URL] - # or via the setup tool: - npx tsx tools/setup-webhooks.ts create - ``` -3. GitHub signs every delivery with `X-Hub-Signature-256`; the CASCADE router verifies it before processing. +- `respond-to-review` fires **only** when the **reviewer** persona submits `changes_requested`. +- `respond-to-pr-comment` skips @mentions from **any** known persona. +- `check-suite-success` checks reviews from the **reviewer** persona specifically. +- All trigger handlers use `isCascadeBot(login)` to filter self-events. -If no `webhook_secret` credential is configured, webhook creation works exactly as before (no secret, no signature verification). Existing webhooks without a secret continue to work unaffected. +## Agent triggers -### Integration Credential Resolution +Trigger format is category-prefixed: `{category}:{event}` +(e.g. `pm:status-changed`, `scm:check-suite-success`, `alerting:issue-created`). -Integration credentials are resolved by `(projectId, category, role)`: - -```typescript -// Get a specific integration credential -const trelloKey = await getIntegrationCredential(projectId, 'pm', 'api_key'); - -// Get all integration credentials + org defaults as flat env-var-key map (for worker environments) -const allCreds = await getAllProjectCredentials(projectId); - -// Non-integration org-scoped credentials (LLM API keys) -const openrouterKey = await getOrgCredential(projectId, 'OPENROUTER_API_KEY'); -``` - -Role definitions and env-var-key mappings are in `src/config/integrationRoles.ts`. - -### Agent Trigger Configuration - -Triggers define which events activate which agents. Configuration is stored in the `agent_trigger_configs` table and managed via the unified `trigger-set` command. - -#### Trigger Format - -Triggers use a category-prefixed event format: `{category}:{event-name}` -- PM triggers: `pm:status-changed`, `pm:label-added` -- SCM triggers: `scm:check-suite-success`, `scm:check-suite-failure`, `scm:pr-review-submitted` -- Alerting triggers: `alerting:issue-created`, `alerting:metric-alert` - -#### Setting Triggers +Configs live in the `agent_trigger_configs` table. Manage via: ```bash -# Discover available triggers for an agent -cascade projects trigger-discover --agent review - -# List configured triggers for a project +cascade projects trigger-discover --agent cascade projects trigger-list - -# Configure a trigger (unified command) -cascade projects trigger-set --agent review --event scm:check-suite-success --enable -cascade projects trigger-set --agent review --event scm:check-suite-success --params '{"authorMode":"own"}' - -# Enable implementation trigger for PM status change -cascade projects trigger-set --agent implementation --event pm:status-changed --enable -``` - -In the **Agent Configs** tab, each agent shows toggles for its supported triggers. Triggers with parameters (like `authorMode` for review) show additional input fields when enabled. - -When merging to `dev` or `main`, legacy trigger configs from `project_integrations.triggers` are automatically migrated to the new `agent_trigger_configs` table. The migration is idempotent. - -### Review Agent Trigger Modes - -| Event | Description | -|-------|-------------| -| `scm:check-suite-success` | Trigger review when CI passes (use `authorMode` parameter: `own` or `external`) | -| `scm:review-requested` | Trigger review when a CASCADE persona is explicitly requested as reviewer | -| `scm:pr-opened` | Trigger review when a PR is opened | - -```bash -# Enable review for implementer PRs only (most common) -cascade projects trigger-set --agent review --event scm:check-suite-success --enable --params '{"authorMode":"own"}' - -# Enable review when explicitly requested -cascade projects trigger-set --agent review --event scm:review-requested --enable -``` - -### PM Agent Trigger Modes - -| Event | Providers | Description | -|-------|-----------|-------------| -| `pm:status-changed` | Trello, JIRA, Linear | Trigger when card/issue moves to agent's target status | -| `pm:label-added` | All | Trigger when Ready to Process label is added | - -```bash -cascade projects trigger-set --agent implementation --event pm:status-changed --enable -cascade projects trigger-set --agent splitting --event pm:label-added --enable -``` - -## Claude Code Engine - -CASCADE uses the Claude Code SDK as the default agent engine. Configure per-project via the CLI or dashboard: - -```bash -cascade projects update --agent-engine claude-code - -# Or override per agent type: -cascade agents create --agent-type implementation --project-id --engine claude-code -``` - -### Authentication - -**Claude Max Subscription via `CLAUDE_CODE_OAUTH_TOKEN`:** - -1. Install Claude Code CLI: `npm install -g @anthropic-ai/claude-code` -2. Authenticate: `claude login` -> select "Log in with your subscription account" -3. Generate a token: `claude setup-token` -4. Set `CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...` in your environment. - -CASCADE creates `~/.claude.json` with `{"hasCompletedOnboarding": true}` to skip interactive onboarding in headless environments. - -**Docker verification test:** -```bash -bash tests/docker/claude-code-auth/run-test.sh -``` - -## Codex Engine - -CASCADE supports OpenAI's Codex CLI as an alternative agent engine: - -```bash -cascade projects update --agent-engine codex -``` - -**API key (`OPENAI_API_KEY`):** Store as an org-scoped credential. No extra setup needed. - -**Subscription (ChatGPT Plus/Pro via `CODEX_AUTH_JSON`):** - -```bash -# 1. On a machine with a browser: -codex login - -# 2. Store the auth token in CASCADE: -cascade projects credentials-set \ - --key CODEX_AUTH_JSON \ - --value "$(cat ~/.codex/auth.json)" \ - --name "Codex Subscription Auth" - -# 3. Set the engine: -cascade projects update --agent-engine codex +cascade projects trigger-set --agent --event --enable [--params JSON] ``` -CASCADE writes `~/.codex/auth.json` before each run and captures any post-run token refreshes back to the database automatically. - -## OpenCode Engine +Some triggers take params (e.g. `review` + `scm:check-suite-success` accepts `{"authorMode":"own"|"external"}`). Legacy configs on `project_integrations.triggers` are auto-migrated on merge to `dev`/`main`. -CASCADE supports the OpenCode engine as an alternative: - -```bash -cascade projects update --agent-engine opencode -``` +## Review agent — context shape (debugging) -The OpenCode engine is implemented in `src/backends/opencode/`. Configure with `cascade agents create --engine opencode` or via the Agent Configs tab in the dashboard. +Review agent receives a **compact per-file diff context**, not full file contents. Each changed file is a `### (, +N -M)` section with a unified diff hunk. Budget: `REVIEW_DIFF_CONTEXT_TOKEN_LIMIT` = 200k tokens, per-file cap 10%. -## Linear Integration +Files that can't fit (deleted, binary, oversized patch, or budget exhausted) are injected as `SKIPPED FILES` with instructions to fetch on demand via `gh pr diff`, `Read`, or `Grep`. -CASCADE supports Linear as a PM provider. When Linear issues change state or labels are applied, they are routed to the appropriate agents. - -- **Linear client**: `src/linear/` — API client and type definitions -- **PM integration**: `src/pm/linear/integration.ts` — implements `PMIntegration` -- **Triggers**: `src/triggers/linear/` — `status-changed.ts`, `label-added.ts`, `comment-mention.ts` -- **Webhook route**: `/linear/webhook` in `src/router/index.ts` - -### Credentials - -Store Linear credentials via the dashboard (Project Settings > Credentials tab) or CLI: - -```bash -cascade projects credentials-set --key LINEAR_API_KEY --value lin_api_... -cascade projects credentials-set --key LINEAR_WEBHOOK_SECRET --value # optional -``` +When review output misses something, check the `PR context prepared` log entry for `included` / `skipped` / `skipReasons` to confirm whether the file was visible to the agent. -### Configuration +## Engines -Configure a project to use Linear as its PM provider: +Default engine: `claude-code`. Alternatives: `codex`, `opencode`. ```bash -cascade projects integration-set --category pm --provider linear \ - --config '{"teamId":"TEAM_ID","statuses":{"todo":"Todo","inProgress":"In Progress","inReview":"In Review","done":"Done"}}' +cascade projects update --agent-engine claude-code +# per-agent override: +cascade agents create --agent-type implementation --project-id --engine codex ``` -Linear uses **issue identifiers** (`TEAM-123` format) as work item IDs. Issues belong to **teams** (equivalent to Trello boards or JIRA projects). - -### Webhook Setup - -Register your CASCADE webhook URL with Linear in your team settings: -``` -https:///linear/webhook -``` - -If `LINEAR_WEBHOOK_SECRET` is configured, the router verifies the `Linear-Signature` header on incoming payloads. - -## Sentry / Alerting Integration - -CASCADE integrates with Sentry for alert-driven automation. When Sentry issues or metric alerts arrive, they are routed to the `alerting` agent. - -- **Sentry client**: `src/sentry/` — API client and integration helpers -- **Triggers**: `src/triggers/sentry/` — `alerting-issue.ts`, `alerting-metric.ts` -- **Gadgets**: `src/gadgets/sentry/` — `GetAlertingIssue`, `GetAlertingEventDetail`, `ListAlertingEvents` -- **CLI tools**: `src/cli/alerting/` — alerting-specific commands available via `cascade-tools` -- **Agent definition**: `src/agents/definitions/alerting.yaml` - -Configure the Sentry integration via the dashboard (Settings > Integrations > Alerting) or CLI. - -## Dashboard - -CASCADE includes a web dashboard for exploring agent runs, logs, LLM calls, and debug analyses. - -### Running the Dashboard +Auth: -```bash -npm run dev # Router on :3000 (webhook receiver, tsx watch) -npm run dev:web # Frontend on :5173 (Vite, proxies /trpc + /api to :3001) -``` - -> **Note:** The dashboard API (`:3001`) and router (`:3000`) are separate services. Run `npm run build && node --env-file=.env dist/dashboard.js` in a third terminal for the dashboard API. - -### Production Build - -```bash -npm run build:web # Vite builds frontend to dist/web/ -npm run build # tsc compiles backend to dist/ -node dist/router/index.js # Starts the router (webhook receiver) — this is npm start -node dist/dashboard.js # Starts the dashboard API on :3001 -``` - -> **Note:** `npm start` runs `dist/router/index.js` (the router), **not** the dashboard. Run `node dist/dashboard.js` separately for the dashboard API. - -### Architecture - -The dashboard is a single-process deployment. The Hono server mounts tRPC routes (`/trpc/*`), auth routes (`/api/auth/*`), and in production serves the built frontend as static files. - -- **API**: tRPC v11 via `@hono/trpc-server` for end-to-end type safety -- **Auth**: Session cookies (HTTP-only, 30-day expiry) with bcrypt password hashing -- **Frontend**: React 19 + Vite + Tailwind CSS v4 + shadcn/ui + TanStack Router -- **Type sharing**: Frontend imports `type AppRouter` from the backend (type-only, no server code in bundle) - -### Key Files - -- `src/api/trpc.ts` - tRPC context, procedures, auth middleware -- `src/api/router.ts` - Root router composition (exports `type AppRouter`) -- `src/api/routers/` - tRPC routers (auth, runs, projects) -- `src/api/auth/` - Login/logout Hono handlers, session resolution -- `web/src/lib/trpc.ts` - Frontend tRPC client (type-safe via AppRouter import) - -## CLI (`cascade`) - -CASCADE includes a `cascade` CLI for managing the platform from the terminal. It consumes the same tRPC endpoints as the web dashboard — no business logic duplication, full type safety. - -### Running the CLI - -In production the `cascade` binary is available globally. In development: - -```bash -npm run build # Compile TypeScript (required before first use) -node bin/cascade.js # Run any CLI command -``` - -Config is stored in `~/.cascade/cli.json`. Override with env vars for CI/scripts: - -```bash -export CASCADE_SERVER_URL=http://localhost:3001 -export CASCADE_SESSION_TOKEN= -``` +- **Claude Code subscription**: `CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...` (from `claude setup-token`). CASCADE writes `~/.claude.json` before run. +- **Codex subscription**: store `CODEX_AUTH_JSON` credential (contents of `~/.codex/auth.json` after `codex login`). CASCADE persists refreshed tokens back to the DB after each run. +- **API-key providers**: store `OPENAI_API_KEY` / other keys as project credentials. -
    -Full Command Reference +## Environment -```bash -# Auth -cascade login --server URL --email X --password Y -cascade logout -cascade whoami - -# Runs -cascade runs list [--project ID] [--status running,failed] [--agent-type impl] [--limit 20] -cascade runs show -cascade runs logs # Pipe: cascade runs logs ID | grep error -cascade runs llm-calls -cascade runs llm-call -cascade runs debug # View debug analysis -cascade runs debug --analyze # Trigger new debug analysis -cascade runs debug --analyze --wait # Trigger and wait for completion -cascade runs trigger --project --agent-type [--work-item-id ID] [--model MODEL] -cascade runs retry [--model MODEL] -cascade runs cancel [--reason "..."] # Cancel a running agent run - -# Projects -cascade projects list -cascade projects show -cascade projects create --id my-project --name "My Project" --repo owner/repo -cascade projects update --model claude-sonnet-4-5-20250929 -cascade projects update --agent-engine llmist -cascade projects update --work-item-budget 10 --watchdog-timeout 1800000 -cascade projects update --progress-model openrouter:google/gemini-2.5-flash-lite --progress-interval 5 -cascade projects update --run-links-enabled --max-in-flight-items 3 -cascade projects delete --yes -cascade projects integrations -cascade projects integration-set --category pm --provider trello --config '{"boardId":"..."}' -cascade projects credentials-list -cascade projects credentials-set --key GITHUB_TOKEN_IMPLEMENTER --value ghp_aaa... -cascade projects credentials-delete --key GITHUB_TOKEN_IMPLEMENTER -cascade projects trigger-discover --agent -cascade projects trigger-list [--agent ] -cascade projects trigger-set --agent --event [--enable|--disable] [--params JSON] - -# Users -cascade users list -cascade users create --email X --password Y --name Z [--role member|admin|superadmin] -cascade users update [--name Z] [--email X] [--role member|admin|superadmin] [--password Y] -cascade users delete --yes - -# Organization -cascade org show -cascade org update --name "My Org" - -# Agent Configs -cascade agents list --project-id ID -cascade agents create --agent-type implementation --model claude-sonnet-4-5-20250929 --project-id ID --engine llmist -cascade agents update --max-iterations 30 -cascade agents delete --yes - -# Agent Definitions (YAML-based agent definitions) -cascade definitions list -cascade definitions show -cascade definitions create --agent-type my-agent --file definition.yaml -cascade definitions update --file definition.yaml -cascade definitions delete -cascade definitions export # Export definition as YAML to stdout -cascade definitions import --file definition.yaml # Import/upsert from YAML file -cascade definitions reset # Reset custom definition to built-in -cascade definitions triggers # List supported triggers for an agent type - -# Prompts (prompt partial customization) -cascade prompts default --agent-type # Print default .eta template for an agent type -cascade prompts default-partial # Print default content for a named partial -cascade prompts variables --agent-type # List available template variables -cascade prompts list-partials # List all configured prompt partials -cascade prompts get-partial # Get a specific prompt partial -cascade prompts set-partial --content "..." # Create/update a prompt partial -cascade prompts reset-partial # Delete a custom partial (reverts to default) -cascade prompts validate --agent-type # Validate current prompt template - -# Webhook Logs (payload debugging) -cascade webhooklogs list [--source trello|github|jira] [--event-type X] [--limit 50] -cascade webhooklogs show - -# Webhooks -cascade webhooks list [--github-token ghp_xxx] -cascade webhooks create [--callback-url URL] [--github-token ghp_xxx] -cascade webhooks delete [--callback-url URL] [--github-token ghp_xxx] -``` - -Global flags: `--json` (machine-readable output), `--server URL` (override server URL). - -
    - -### Architecture - -Each command is a thin adapter: **parse flags → call tRPC → format output**. All business logic lives server-side. - -``` -src/cli/dashboard/ -├── _shared/ # Config, tRPC client, base class, formatters -├── login.ts # Auth (HTTP, not tRPC) -├── logout.ts -├── whoami.ts -├── runs/ # 9 commands (list, show, logs, llm-calls, llm-call, debug, trigger, retry, cancel) -├── projects/ # 13 commands -├── users/ # 4 commands -├── org/ # 2 commands -├── agents/ # 4 commands -├── definitions/ # 9 commands (list, show, create, update, delete, export, import, reset, triggers) -├── prompts/ # 8 commands (default, default-partial, variables, list-partials, get-partial, set-partial, reset-partial, validate) -├── webhooklogs/ # 2 commands (list, show) -└── webhooks/ # 3 commands -``` - -The `cascade` binary is separate from `cascade-tools` (which is for agents). The `cascade-tools` binary uses a custom oclif config in `bin/cascade-tools.js` to discover all non-dashboard agent tool commands (everything under `dist/cli/` except dashboard), while `cascade` discovers only dashboard commands (`dist/cli/dashboard/`). - -## User Management - -Users can be managed via the CLI (recommended) or the dashboard at `/settings/users`: - -```bash -cascade users create --email user@example.com --password secret --name "User Name" --role admin -cascade users list -cascade users update --name "New Name" --role member -cascade users delete --yes -``` - -As a fallback when the CLI and dashboard are unavailable: - -```bash -# Generate bcrypt hash -node -e "import('bcrypt').then(b => b.default.hash('password', 10).then(console.log))" - -# Insert user -psql $DATABASE_URL -c "INSERT INTO users (org_id, email, password_hash, name, role) VALUES ('my-org', 'user@example.com', '\$2b\$10\$...', 'User Name', 'admin');" -``` - -## Adding New Triggers - -1. Create trigger handler in `src/triggers//` -2. Implement `TriggerHandler` interface -3. Register in `src/triggers/builtins.ts` via `registerBuiltInTriggers()` - -See [`src/integrations/README.md`](src/integrations/README.md) (Step 6) for a detailed walkthrough. - -## Adding New Agents - -Agents are defined using YAML definition files. Built-in definitions live in `src/agents/definitions/`. Custom agents can be added via the dashboard or CLI without touching source code. - -1. **Write a YAML definition** — model your file on an existing one in `src/agents/definitions/` (e.g. `implementation.yaml`). The definition specifies the agent identity, supported triggers, prompt templates, and tool manifests. -2. **Import the definition** — via CLI (`cascade definitions import --file my-agent.yaml`) or dashboard (**Agent Definitions** tab). -3. **Create an `agent_configs` row** — agents require an explicit `agent_configs` entry to be enabled for a project: - ```bash - cascade agents create --agent-type my-agent --project-id - ``` -4. **Configure triggers** — enable the events that should activate the agent: - ```bash - cascade projects trigger-set --agent my-agent --event pm:status-changed --enable - ``` - -> **Note:** Built-in agent types (`implementation`, `review`, `splitting`, etc.) ship pre-loaded as built-in definitions. Custom agents added via `cascade definitions create` are stored in the `agent_definitions` table. - -## Agent Resilience Features - -CASCADE integrates llmist's resilience features to ensure reliable operation during long-running sessions: - -### Rate Limiting (Proactive) -- Model-specific rate limits with safety margins (80-90%) -- Tracks requests per minute (RPM), tokens per minute (TPM), and daily token usage -- Prevents 429 errors by throttling requests before hitting API limits -- Configured in `src/config/rateLimits.ts` - -### Retry Strategy (Reactive) -- Handles transient failures (rate limits, 5xx errors, timeouts, connection issues) -- 5 retry attempts with exponential backoff (1s → 60s max) -- Respects `Retry-After` headers from providers -- Jitter randomization prevents thundering herd problems -- Configured in `src/config/retryConfig.ts` - -### Context Compaction -- Prevents context window overflow on long-running sessions -- **All agents**: Triggers at 80% context usage, reduces to 50%, preserves 5 recent turns -- Hybrid strategy: intelligently mixes summarization and sliding-window -- Configured in `src/config/compactionConfig.ts` - -### Iteration Hints -- Ephemeral trailing messages showing iteration progress -- Urgency warnings at >80%: "⚠️ ITERATION BUDGET: 17/20 - Only 3 remaining!" -- Helps LLM prioritize and wrap up before hitting iteration limits -- Configured in `src/config/hintConfig.ts` - -**Monitoring**: Check `llmist-*.log` for rate limiting events. Compaction events are logged to main agent logs with details (tokens saved, reduction percentage, messages removed). - -## Debugging Production Sessions - -### Review Agent — Context Shape - -The review agent receives a **compact per-file diff context** rather than full file contents. Each changed file appears as a `### (, +N -M)` section followed by a unified diff hunk. The budget is `REVIEW_DIFF_CONTEXT_TOKEN_LIMIT` (200,000 tokens), with a per-file cap of 10% of that. - -Files that can't fit (deleted, binary, oversized patch, or budget exhausted) are surfaced via a separate `SKIPPED FILES` injection. The injection is self-documenting: it lists each filename + reason and instructs the agent to fetch on demand using `gh pr diff -- `, `Read `, or `Grep `. - -When debugging review-agent output that misses something, check the `PR context prepared` log entry for `included`/`skipped`/`skipReasons` to confirm whether the file was even visible to the agent. - -### Manual Session Download - -Download session logs and card data from a Trello card for debugging: - -```bash -npm run tool:download-session https://trello.com/c/abc123/card-name -# or just the card ID -npm run tool:download-session abc123 -``` - -This downloads all `.gz` log attachments (ungzipped), plus card description, checklists, and comments into a temp directory. +Required: -### Automatic Debug Analysis +- `DATABASE_URL` — PostgreSQL connection string. +- `REDIS_URL` — BullMQ queue, defaults to `redis://localhost:6379`. -CASCADE includes a debug agent that automatically analyzes agent session logs: +Optional: -1. **Automatic Trigger**: When an agent uploads a session log (`.zip` file) to a Trello card, the debug agent automatically triggers -2. **Log Analysis**: The debug agent downloads, extracts, and analyzes the session logs to identify: - - Errors and exceptions - - Failed gadget calls - - Iteration loops and inefficiencies - - Excessive LLM calls - - Scope creep or confusion patterns -3. **Debug Card Creation**: Creates a new card in the DEBUG list with: - - Title: `{agent-type} - {original card name}` - - Executive summary of what went wrong - - Key issues found - - Timeline of events - - Actionable recommendations - - Link back to the original card +- `DATABASE_SSL=false` to disable SSL locally; `DATABASE_CA_CERT` for managed DBs with a private CA. +- `CREDENTIAL_MASTER_KEY` — 64-char hex (AES-256 key) to encrypt project credentials at rest. Without it, credentials are stored as plaintext; both modes coexist. +- `GITHUB_WEBHOOK_SECRET` — opt-in HMAC verification; store as the `webhook_secret` role on the GitHub SCM integration. +- `SENTRY_DSN`, `SENTRY_ENVIRONMENT`, `SENTRY_RELEASE`, `SENTRY_TRACES_SAMPLE_RATE` — observability. -**Setup**: Add a `debug` list to your Trello board and configure it via the dashboard or CLI: +**Project credentials (GitHub tokens, Trello/JIRA/Linear keys, LLM API keys) live in the `project_credentials` table.** The DB is the **sole source of truth** — there is no env var fallback for project-scoped secrets. -```bash -node bin/cascade.js projects integration-set \ - --category pm --provider trello \ - --config '{"boardId":"BOARD_ID","lists":{"todo":"LIST_ID","inProgress":"LIST_ID","inReview":"LIST_ID","debug":"YOUR_DEBUG_LIST_ID"},...}' -``` +## Git hooks -The debug agent only analyzes logs uploaded by the authenticated CASCADE user and matching the pattern `{agent-type}-{timestamp}.zip`. +Lefthook runs pre-commit (lint, typecheck) and pre-push (unit + integration tests) hooks automatically. Pre-push auto-starts an ephemeral Postgres via `npm run test:db:up` — Docker must be running.