@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/observability/logger.js

@@ -0,0 +1,110 @@
+import pino from "pino";
+import { requestContextStore } from "../app/context/RequestContext.js";
+// Re-export the context primitives so the logger module remains a one-stop
+// import for code that wants both `logger` and request-context helpers, while
+// keeping the canonical store in `app/context/RequestContext.ts`.
+export { getRequestContext, runWithRequestContext, setRequestContextField, } from "../app/context/RequestContext.js";
+/**
+ * Structured logger built on pino. Replaces the v3 `Logger` console-wrapper.
+ *
+ * - **ND-JSON** in production; **pino-pretty** in dev / local.
+ * - **Redaction** of standard secret-bearing paths (`Authorization`, cookies,
+ *   `password`, `token`, `secret`, `apiKey`, Firebase / GCP credentials blobs).
+ * - **Request context** propagation via the canonical framework-wide
+ *   `AsyncLocalStorage` (see `app/context/RequestContext.ts`). Any code running
+ *   inside `runWithRequestContext({ requestId, userId, tenantId }, fn)` gets
+ *   those fields auto-attached to every log line via pino's `mixin`, without
+ *   callsite changes. The same context flows into `DrizzleEntityService`
+ *   lifecycle hooks (audit / CDC / multi-tenancy) — single SoT.
+ * - Forward-compatible with `@opentelemetry/instrumentation-pino`, which
+ *   auto-injects `trace_id` / `span_id` / `trace_flags` once the OTel SDK is
+ *   running. No mixin work required there.
+ */
+const DEFAULT_REDACT_PATHS = [
+    // Top-level secret-bearing keys (pino's `*.foo` wildcard matches one level
+    // of nesting, not top-level — list these separately).
+    "password",
+    "token",
+    "secret",
+    "apiKey",
+    // Common one-level-nested locations (e.g., `user.password`, `body.token`).
+    "*.password",
+    "*.token",
+    "*.secret",
+    "*.apiKey",
+    // Auth headers in their usual containers.
+    "req.headers.authorization",
+    "req.headers.cookie",
+    "request.headers.authorization",
+    "request.headers.cookie",
+    "headers.authorization",
+    "headers.cookie",
+    // App / framework keys with non-generic shapes.
+    "firebaseCredentials",
+    "gcpCredentialsJson",
+    "FIREBASE_CREDENTIALS",
+    "GCP_CREDENTIALS_JSON",
+    "SESSION_SECRET",
+];
+function isPrettyEnvByDefault() {
+    const env = process.env.ENVIRONMENT_NAME ?? process.env.NODE_ENV ?? "";
+    return env === "local" || env === "dev" || env === "development" || env === "";
+}
+function buildOptions(opts) {
+    const redactPaths = opts.extraRedactPaths
+        ? [...DEFAULT_REDACT_PATHS, ...opts.extraRedactPaths]
+        : DEFAULT_REDACT_PATHS;
+    return {
+        level: opts.level ?? process.env.LOG_LEVEL ?? "info",
+        redact: {
+            paths: [...redactPaths],
+            censor: "[REDACTED]",
+        },
+        mixin() {
+            const ctx = requestContextStore.getStore();
+            if (!ctx)
+                return {};
+            const out = {};
+            if (ctx.requestId !== undefined)
+                out.requestId = ctx.requestId;
+            if (ctx.userId !== undefined)
+                out.userId = ctx.userId;
+            if (ctx.tenantId !== undefined)
+                out.tenantId = ctx.tenantId;
+            if (ctx.extra)
+                Object.assign(out, ctx.extra);
+            return out;
+        },
+    };
+}
+export function createLogger(opts = {}) {
+    const options = buildOptions(opts);
+    // Explicit destination wins (test hook).
+    if (opts.destination) {
+        return pino(options, opts.destination);
+    }
+    const usePretty = opts.pretty ?? isPrettyEnvByDefault();
+    if (usePretty) {
+        return pino({
+            ...options,
+            transport: {
+                target: "pino-pretty",
+                options: {
+                    colorize: true,
+                    translateTime: "SYS:HH:MM:ss.l",
+                    ignore: "pid,hostname",
+                    singleLine: false,
+                },
+            },
+        });
+    }
+    // Production / staging: ND-JSON to stdout (pino default).
+    return pino(options);
+}
+/**
+ * Default framework-wide logger. Most callsites should import this and either
+ * use it directly or call `logger.child({ module: "<name>" })` for a scoped
+ * sub-logger.
+ */
+export const logger = createLogger();
+//# sourceMappingURL=logger.js.map

package/lib/observability/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/observability/logger.ts"],"names":[],"mappings":"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"}

package/lib/observability/metrics.d.ts

@@ -0,0 +1,3 @@
+/** @deprecated Import metrics from `@sixthsummit/ship-observability-otel/metrics`. */
+export * from "@sixthsummit/ship-observability-otel/metrics";
+//# sourceMappingURL=metrics.d.ts.map

package/lib/observability/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/observability/metrics.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,cAAc,8CAA8C,CAAC"}

package/lib/observability/metrics.js

@@ -0,0 +1,3 @@
+/** @deprecated Import metrics from `@sixthsummit/ship-observability-otel/metrics`. */
+export * from "@sixthsummit/ship-observability-otel/metrics";
+//# sourceMappingURL=metrics.js.map

package/lib/observability/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/observability/metrics.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,cAAc,8CAA8C,CAAC"}

package/lib/observability/otel.d.ts

@@ -0,0 +1,3 @@
+/** @deprecated Import SDK lifecycle from `@sixthsummit/ship-observability-otel/sdk`. */
+export * from "@sixthsummit/ship-observability-otel/sdk";
+//# sourceMappingURL=otel.d.ts.map

package/lib/observability/otel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../../src/observability/otel.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,cAAc,0CAA0C,CAAC"}

package/lib/observability/otel.js

@@ -0,0 +1,3 @@
+/** @deprecated Import SDK lifecycle from `@sixthsummit/ship-observability-otel/sdk`. */
+export * from "@sixthsummit/ship-observability-otel/sdk";
+//# sourceMappingURL=otel.js.map

package/lib/observability/otel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.js","sourceRoot":"","sources":["../../src/observability/otel.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,cAAc,0CAA0C,CAAC"}

package/lib/observability/safeErrorFields.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Log-safe identifying fields of an error: its `code`, `name` and `syscall`,
+ * never its message. Database and network error messages can contain the
+ * host, port, user or database name, so only these short identifiers are kept
+ * (for Postgres the SQLSTATE such as `28P01`, or a Node code such as
+ * `ECONNREFUSED` with the failing `syscall`).
+ */
+export interface SafeErrorFields {
+    errorCode?: string | number;
+    errorName?: string;
+    syscall?: string;
+}
+export declare function safeErrorFields(error: unknown): SafeErrorFields;
+//# sourceMappingURL=safeErrorFields.d.ts.map

package/lib/observability/safeErrorFields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeErrorFields.d.ts","sourceRoot":"","sources":["../../src/observability/safeErrorFields.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAQ/D"}

package/lib/observability/safeErrorFields.js

@@ -0,0 +1,14 @@
+export function safeErrorFields(error) {
+    const fields = {};
+    if (error === null || typeof error !== "object")
+        return fields;
+    const { code, name, syscall } = error;
+    if (typeof code === "string" || typeof code === "number")
+        fields.errorCode = code;
+    if (typeof name === "string")
+        fields.errorName = name;
+    if (typeof syscall === "string")
+        fields.syscall = syscall;
+    return fields;
+}
+//# sourceMappingURL=safeErrorFields.js.map

package/lib/observability/safeErrorFields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeErrorFields.js","sourceRoot":"","sources":["../../src/observability/safeErrorFields.ts"],"names":[],"mappings":"AAaA,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC;IAC/D,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,KAA8D,CAAC;IAC/F,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC;IAClF,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC;IACtD,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;IAC1D,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/lib/observability/tracing.d.ts

@@ -0,0 +1,3 @@
+/** @deprecated Import tracing from `@sixthsummit/ship-observability-otel/tracing`. */
+export * from "@sixthsummit/ship-observability-otel/tracing";
+//# sourceMappingURL=tracing.d.ts.map

package/lib/observability/tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/observability/tracing.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,cAAc,8CAA8C,CAAC"}

package/lib/observability/tracing.js

@@ -0,0 +1,3 @@
+/** @deprecated Import tracing from `@sixthsummit/ship-observability-otel/tracing`. */
+export * from "@sixthsummit/ship-observability-otel/tracing";
+//# sourceMappingURL=tracing.js.map

package/lib/observability/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../../src/observability/tracing.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,cAAc,8CAA8C,CAAC"}

package/lib/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "module",
+  "sideEffects": false
+}

package/lib/testing.d.ts

@@ -0,0 +1,3 @@
+/** @deprecated Install and import `@sixthsummit/ship-testing` as a dev dependency. */
+export * from "@sixthsummit/ship-testing";
+//# sourceMappingURL=testing.d.ts.map

package/lib/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,cAAc,2BAA2B,CAAC"}

package/lib/testing.js

@@ -0,0 +1,3 @@
+/** @deprecated Install and import `@sixthsummit/ship-testing` as a dev dependency. */
+export * from "@sixthsummit/ship-testing";
+//# sourceMappingURL=testing.js.map

package/lib/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,cAAc,2BAA2B,CAAC"}

package/package.json

@@ -1,6 +1,196 @@
 {
   "name": "@sixthsummit/ship-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "4.1.1",
+  "description": "ShipAPI Framework — TypeScript backend on Hono + Drizzle + pluggable AuthProvider + BullMQ + OpenTelemetry. Designed to be edited by AI coding agents.",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "bin": {
+    "ship-api": "./cli/ship-api.js"
+  },
+  "keywords": [
+    "typescript",
+    "hono",
+    "drizzle",
+    "firebase",
+    "api",
+    "framework",
+    "rest",
+    "rpc",
+    "authentication",
+    "authorization",
+    "middleware",
+    "bullmq",
+    "opentelemetry",
+    "ai-agents",
+    "claude-code",
+    "boilerplate",
+    "cli"
+  ],
+  "author": "Scott Gibson",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/client.d.ts",
+      "import": "./lib/client.js",
+      "default": "./lib/client.js"
+    },
+    "./contract": {
+      "types": "./lib/contract/index.d.ts",
+      "import": "./lib/contract/index.js",
+      "default": "./lib/contract/index.js"
+    },
+    "./contract/application": {
+      "types": "./lib/contract/application.d.ts",
+      "import": "./lib/contract/application.js",
+      "default": "./lib/contract/application.js"
+    },
+    "./contract/openapi": {
+      "types": "./lib/contract/openapi.d.ts",
+      "import": "./lib/contract/openapi.js",
+      "default": "./lib/contract/openapi.js"
+    },
+    "./contract/project": {
+      "types": "./lib/contract/project.d.ts",
+      "import": "./lib/contract/project.js",
+      "default": "./lib/contract/project.js"
+    },
+    "./contract/schema": {
+      "types": "./lib/contract/schema.d.ts",
+      "import": "./lib/contract/schema.js",
+      "default": "./lib/contract/schema.js"
+    },
+    "./hono": {
+      "types": "./lib/hono/index.d.ts",
+      "import": "./lib/hono/index.js",
+      "default": "./lib/hono/index.js"
+    },
+    "./drizzle": {
+      "types": "./lib/drizzle/index.d.ts",
+      "import": "./lib/drizzle/index.js",
+      "default": "./lib/drizzle/index.js"
+    },
+    "./kernel": {
+      "types": "./lib/kernel/index.d.ts",
+      "import": "./lib/kernel/index.js",
+      "default": "./lib/kernel/index.js"
+    },
+    "./rate-limit": {
+      "types": "./lib/app/services/rateLimit/index.d.ts",
+      "import": "./lib/app/services/rateLimit/index.js",
+      "default": "./lib/app/services/rateLimit/index.js"
+    },
+    "./*": {
+      "types": "./lib/*.d.ts",
+      "import": "./lib/*.js",
+      "default": "./lib/*.js"
+    }
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.19.14",
+    "@hono/node-ws": "^1.3.0",
+    "@hono/zod-validator": "^0.7.6",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/auto-instrumentations-node": "^0.80.0",
+    "@opentelemetry/exporter-prometheus": "^0.222.0",
+    "@opentelemetry/resources": "^2.11.0",
+    "@opentelemetry/sdk-metrics": "^2.11.0",
+    "@opentelemetry/sdk-node": "^0.222.0",
+    "@opentelemetry/semantic-conventions": "^1.43.0",
+    "@sixthsummit/ship-cli": "^1.2.0",
+    "@sixthsummit/ship-contract": "^1.3.0",
+    "@sixthsummit/ship-core": "^1.1.1",
+    "@sixthsummit/ship-drizzle": "^1.2.0",
+    "@sixthsummit/ship-hono": "^1.2.0",
+    "@sixthsummit/ship-observability-otel": "^1.2.0",
+    "async": "^3.2.4",
+    "bullmq": "^5.76.3",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "drizzle-orm": "^0.45.2",
+    "drizzle-zod": "^0.8.3",
+    "file-type": "^21.3.4",
+    "firebase-admin": "^13.10.0",
+    "hono": "^4.13.7",
+    "ioredis": "^5.10.1",
+    "jose": "^6.2.3",
+    "lru-cache": "^11.3.5",
+    "msgpackr": "^1.11.10",
+    "pg": "^8.16.3",
+    "pino": "^9.14.0",
+    "pino-pretty": "^13.1.3",
+    "tsx": "^4.20.3",
+    "zod": "^4.3.6",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "peerDependencies": {
+    "@sixthsummit/ship-testing": "^1.2.0",
+    "typescript": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "@sixthsummit/ship-testing": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "lib/",
+    "cli/ship-api.js",
+    "cli/commands/add.js",
+    "cli/commands/contract.js",
+    "cli/commands/create.js",
+    "cli/commands/dev.js",
+    "cli/commands/doctor.js",
+    "cli/commands/generate.js",
+    "cli/commands/graph.js",
+    "cli/commands/migrate-orm.js",
+    "cli/commands/update.js",
+    "templates/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SixthSummit/Ship.git",
+    "directory": "packages/core"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.1038.0",
+    "@aws-sdk/s3-request-presigner": "^3.1038.0",
+    "@bull-board/api": "^7.0.0",
+    "@bull-board/hono": "^7.0.0",
+    "@google-cloud/storage": "^7.19.0",
+    "@opentelemetry/sdk-trace-base": "^2.11.0",
+    "@sixthsummit/ship-testing": "^1.2.0",
+    "@testcontainers/localstack": "^12.0.1",
+    "@testcontainers/postgresql": "^12.0.1",
+    "@types/pg": "^8.15.6",
+    "drizzle-kit": "^0.31.10",
+    "testcontainers": "^12.0.1"
+  },
+  "scripts": {
+    "build": "node ../../scripts/clean-package.mjs && tsc && node ../../scripts/build-core.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "lint": "eslint src/",
+    "type-check": "tsc --noEmit -p tsconfig.check.json"
+  }
 }

package/templates/default/.claude/agents/qa-brief.md

@@ -0,0 +1,106 @@
+---
+name: qa-brief
+description: Generate a Sherpa-ready QA brief from a backend diff. Use when the user asks for "QA brief", "Sherpa brief", "test cases for QA", or when the `/ship:sherpa-brief` slash command fires. Walks the diff in a ShipAPI consumer app, enumerates new/changed routes, auth + permission requirements, validation surfaces, and AppError-driven sad paths, and writes a plain-English brief that the QA can paste into Sherpa's `/explore` and `/generate-test` commands. Read-only — emits markdown, never edits source.
+tools: Read, Grep, Glob, Bash
+---
+
+You are **qa-brief**, the QA-handoff agent for ShipAPI v4. Your output is what an engineer would have hand-written for QA today — but generated from the diff, with no engineer admin work.
+
+You produce a markdown brief. You never edit source. You never propose code changes.
+
+## Your audience
+
+The QA at Sixth Summit who uses **Sherpa** (`../sherpa` — a separate Claude-Code-driven toolkit). They paste flows into Sherpa's `/explore` and `/generate-test` commands, and Sherpa walks the live web app via Playwright MCP to generate specs. They do **not** read TypeScript, route signatures, or middleware chains — your flows must be plain English.
+
+## When you fire
+
+- The user asks "write a QA brief" / "Sherpa brief" / "what should QA test for this branch?"
+- The `/ship:sherpa-brief` slash command invokes you
+- The `sherpa-brief.yml` GitHub Action invokes you headless (in that case, env vars `BASE_REF`, `HEAD_REF`, `PR_TITLE`, `PR_BODY`, `PR_NUMBER`, `REPO`, `BRANCH` may be set)
+
+## Inputs you read
+
+1. **Diff** — compute via `git diff $BASE_REF..$HEAD_REF` (or default `git diff main..HEAD`). Scope to files that affect observable backend behavior: `modules/**/*.ts`, `packages/core/src/http/**/*.ts`, `packages/core/src/app/schema/**/*.ts`. Ignore `*.test.ts`, `lib/`, `dist/`, `node_modules/`.
+2. **PR context** — `PR_TITLE` + `PR_BODY` when set; otherwise the last few commit messages on the branch.
+3. **Route registry** — if a ShipAPI dev server is running and the MCP `list_routes` / `describe_route` tools are available, use them to enumerate routes precisely. In CI / headless mode the MCP server is **not** available — fall back to static parse: grep for `app.get(` / `app.post(` / `app.put(` / `app.patch(` / `app.delete(` in the changed files.
+4. **Auth / permission chain** — look for `requireAuth({ provider })` and `requirePermission("...")` middleware on each touched route. Routes lacking `requireAuth` are public.
+5. **Validation surface** — look for `validate("json"|"query"|"param", <schema>)` middleware. The schema name (e.g. `createWidgetSchema`) hints at the input shape; read the schema definition if it's in the diff or in `modules/<name>/validation/schemas.ts`.
+6. **AppError taxonomy** — `throw new NotFoundError(...)` / `BadRequestError` / `ConflictError` / `ForbiddenError` etc. inside touched handlers. Each one is a sad path worth exercising.
+7. **BullMQ + outbox** — `defineJob(...)`, `OutboxEventEmitter.emit(...)`, `defineCron(...)` in the diff indicate async side effects that QA can't observe in a single request. Note them explicitly under "What this brief did NOT cover."
+
+## Output shape (exact)
+
+Emit markdown with these sections, in this order. Plain English in the "Flows to test" section — no code, no curl snippets, no route paths.
+
+```markdown
+# QA brief — <feature title>
+
+> **Stack:** ShipAPI (backend)  |  **Repo:** `<owner/repo>`  |  **Branch:** `<branch>`  |  **PR:** #<n>
+
+## What changed (engineer's summary)
+<1–3 lines pulled from PR_BODY / commit messages — not a diff dump>
+
+## Surface area
+- **New:**
+  - POST /api/widgets — create a widget (requires `widgets:create`)
+  - GET /api/widgets/:id — read a widget (requires `widgets:read`)
+- **Changed:**
+  - PATCH /api/accounts/:id — now requires `accounts:write` (was public)
+- **Removed:**
+  - DELETE /api/legacy/foo
+
+## Flows to test (paste these into Sherpa's `/explore` one at a time)
+1. A signed-in user with the **widgets:create** permission opens the widgets page, creates a widget named "Test", and sees it in the list.
+2. A signed-in user **without** widgets:create tries to create a widget and gets a clear permission-denied message — no widget is created.
+3. An unauthenticated visitor going to the widgets page is redirected to sign-in.
+4. Creating a widget with an empty name shows an inline validation error and the widget is not saved.
+5. <…one numbered flow per observable behavior change…>
+
+## Auth / permission paths touched
+- `widgets:create` (new) — needs a fixture user with this permission for happy-path tests
+- `widgets:read` (new) — same
+- `accounts:write` (existing) — re-verify after the PATCH change
+
+## Likely sad paths worth exercising
+- <pull from AppError throws> — e.g. "Submitting a widget with a name longer than 200 chars returns a validation error."
+- <middleware-driven> — e.g. "Replaying a request with a repeated Idempotency-Key returns the cached response, not a duplicate."
+- <middleware-driven> — e.g. "Sending requests above the rate limit returns 429."
+
+## What this brief did NOT cover
+- UI affordances on the consuming frontend — see the **companion ShipAngular brief** (if any) for that half.
+- Async job side effects — this diff enqueues `<job-name>` via the outbox; QA cannot observe it inside a single browser flow. Verify via logs / dashboards.
+- Anything outside the diff range (`<base>..<head>`).
+```
+
+## Style rules
+
+- **No code in flows.** "POST /api/widgets" appears only in **Surface area**, never in **Flows to test**. Flows are descriptions of user behavior.
+- **One flow = one numbered item.** No nested bullets, no "and also…". QA copy-pastes single items into `/explore` and Sherpa generates one spec per flow.
+- **Each flow includes a happy-path or sad-path frame.** "A user with X does Y and sees Z" or "A user without X tries Y and sees Z." Never "the system validates Y" — that's not testable in a browser.
+- **Permissions named in plain words.** `widgets:create` is fine in the auth section; in flows say "a user with the widgets:create permission".
+- **No reference to `requireAuth` / `validate()` / Hono / middleware.** That's framework vocabulary, not QA vocabulary.
+
+## Mode selection
+
+**Live (with dev server + MCP):** prefer `list_routes` for surface area enumeration; it's authoritative.
+
+**Headless (in GitHub Action):** use `git diff` + grep. Detect this mode by checking for the env var `GITHUB_ACTIONS=true` or by the absence of the MCP tools.
+
+## When the diff is empty or non-substantive
+
+If the diff touches only `*.test.ts`, generated migrations, or non-handler files, emit:
+
+```markdown
+# QA brief — <title>
+
+No observable backend behavior changes detected in this diff (tests / migrations / generated only). No QA flows to enumerate. The ShipAngular brief (if any) covers the user-facing half.
+```
+
+Do not invent flows to fill space. A short honest brief beats a long fabricated one.
+
+## What you DO NOT do
+
+- Do not run tests, lint, type-check, or build.
+- Do not propose code changes or convention fixes — that's `ship-reviewer`'s job.
+- Do not generate Playwright code — that's Sherpa's job after the QA pastes your flows.
+- Do not ask the user clarifying questions when run from a hook or the GitHub Action — emit the brief and exit.

package/templates/default/.claude/commands/sherpa-brief.md

@@ -0,0 +1,23 @@
+---
+description: Generate a Sherpa-ready QA brief from the current branch's backend diff. Plain-English flows the QA pastes into Sherpa's /explore. Engineer admin work goes to zero.
+argument-hint: "[--base <ref>]"
+allowed-tools: Bash, Agent
+---
+
+Run **qa-brief** against the current branch's diff.
+
+**Base ref resolution** (in order):
+1. `$1` if present and parseable as `--base <ref>`
+2. `BASE_REF` env var if set (the GitHub Action sets this)
+3. Default: the merge-base with `main` (`git merge-base main HEAD`)
+
+**Head ref:** `HEAD_REF` env var if set, otherwise `HEAD`.
+
+**PR context** (optional, set by the workflow when available):
+- `PR_TITLE`, `PR_BODY`, `PR_NUMBER`, `REPO`, `BRANCH` env vars feed the brief's header
+
+Scope the diff to files that affect observable backend behavior. The agent will compute the diff itself; just pass the resolved base + head refs in the prompt.
+
+Invoke the **qa-brief** subagent. Surface its markdown output as the response — do not summarize, do not editorialize.
+
+If `--base` was passed but doesn't resolve to a valid ref, fall back to the default and note the fallback in a one-line prefix above the brief.

package/templates/default/.cursor/rules/api.mdc

@@ -0,0 +1,80 @@
+---
+alwaysApply: true
+description: "API development guidelines for ShipAPI v4 (Hono + Drizzle)"
+tags: ["api", "hono", "drizzle", "zod"]
+globs: ["modules/**/*.ts", "src/index.ts"]
+---
+
+# API Development Guidelines
+
+## Module structure
+
+Each feature module under `modules/<name>/` follows the canonical 7-file shape:
+
+```
+modules/<name>/
+├── schema.ts                       # Drizzle pgTable + relations + types
+├── permissions.ts                  # module:resource:action slug constants
+├── validation/schemas.ts           # Zod schemas (.strict() on objects)
+├── services/<NameSingular>Service.ts   # extends DrizzleEntityService<typeof table>
+├── routes.ts                       # buildXxxApp(deps) → mounts at root; defineXxxRoutes escape hatch
+├── index.ts                        # barrel
+└── module.json                     # metadata
+```
+
+Scaffold with `ship-api g module <name>` (full shape) or `ship-api g resource <name> --fields "..."` (CRUD shortcut).
+
+## Routes
+
+- Each route chains: `requireAuth({ provider })` → `requirePermission(slug)` → `validate("json"|"query"|"param", schema)` → handler.
+- **Each module exposes `buildXxxApp(deps)`** returning its **own** sub-app (built on `createModuleApp("xxx")`); the consumer mounts it with `root.route("/", buildXxxApp(deps))`. Modules keep absolute paths (`/posts`, `/posts/:id`), so the client shape (`api.posts.$get`) and route registry are unchanged. Mounting bounded sub-apps — rather than threading one shared `app` through every module's `defineXxxRoutes` — keeps `tsc`'s route-type instantiation bounded so the typed client scales to many modules.
+- **`defineXxxRoutes(app, deps)` is kept as an advanced / back-compat escape hatch**, but threading one shared `app` through several modules detonates `tsc` (TS2589 / "instantiation excessively deep"), collapsing the `hc()` client to `never`. Prefer `buildXxxApp`. When you do use it, return the chained app (a `(app) => void` shape loses the type chain) and stay generic over Hono's schema param `S`.
+- **Cross-cutting middleware (`registerErrorHandlers`, `httpLogger`, CORS) lives on the root only** — a module sub-app must not set its own `onError` or `use("*")`.
+- Use proper HTTP methods (GET, POST, PUT, PATCH, DELETE). Plural nouns for collections (`/posts`, `/posts/:id`).
+- Status codes: 200 (success), 201 (created), 204 (no body), 400 (validation), 401 (auth), 403 (permission), 404 (not found), 409 (conflict), 422 (semantic validation), 429 (rate limit), 500 (unhandled).
+
+## Validation
+
+- Register Zod schemas via `validate("json"|"query"|"param", schema)`. Read parsed input with `c.req.valid("json"|...)`.
+- **Never use `c.req.json()` / `c.req.query()` / `c.req.param()` directly** — the route registry, typed client, and (eventual) OpenAPI all read off the registered schema. The framework's `no-restricted-syntax` ESLint rule fires on raw use.
+- Use `.strict()` on object schemas to reject unknown fields.
+- Co-locate request + response Zod schemas in `validation/schemas.ts`. Export inferred types via `z.infer`.
+- Derive create / update schemas from Drizzle tables using `drizzle-zod` where possible.
+
+## Services
+
+- Extend `DrizzleEntityService<typeof table>` for inherited CRUD (`get`, `getAll`, `list`, `count`, `create`, `update`, `delete` + `*WithContext` variants).
+- Override `getDefaultSearchFields()` / `getDefaultRelations()` per module.
+- Add domain methods on the service; keep route handlers thin (delegate to the service).
+- Use `withTransaction(db, tx => ...)` for multi-step operations.
+- For queue-after-commit correctness, **never enqueue BullMQ jobs inside a transaction** — use the outbox pattern via `OutboxEventEmitter.emit({...}, { tx })`.
+
+## Errors
+
+- Throw from the AppError taxonomy: `NotFoundError`, `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `ConflictError`, `ValidationError`, `RateLimitError`, etc.
+- Never shape error responses inside handlers. `registerErrorHandlers(app)` (called once at boot) handles the JSON shape uniformly.
+- Don't expose internal stack traces or DB error details. The error handler strips them in production.
+
+## Migrations
+
+- **Never hand-write SQL migrations.** Generate them from schema source: `npm run db:generate -- --name <description>`.
+- The framework's plugin `PreToolUse` hook (`block-migration-edit.sh`) blocks edits to `src/db/migrations/*.sql` to enforce this.
+- Apply with `npm run db:migrate`. Inspect with `npm run db:studio`.
+- Schema lives in `modules/<name>/schema.ts` (per module) and is composed in `src/db/schema.ts`. Use `...baseFields` for audit columns.
+
+## Logging
+
+- Import: `import { logger } from "@sixthsummit/ship-api/observability/logger"`.
+- **Never `console.log` / `console.error` / `console.warn`.** They lose request-id and trace context that pino + OpenTelemetry inject automatically.
+- Log structured: `logger.info({ accountId, action }, "user did thing")`, not `logger.info("user " + accountId + " did thing")`.
+
+## Environment
+
+- All `process.env` access goes through `src/environment.ts` via `defineEnv(zodSchema)`. The function fail-fasts at boot with structured errors for missing/invalid vars.
+- **Never `process.env.X` outside `src/environment.ts`.** The framework's `no-restricted-globals` ESLint rule catches violations.
+
+## Idempotency, rate limit, CSRF
+
+- Mutating routes that may be retried (payment, email send, account creation): apply `idempotency({ ttlSec, scope })` middleware. Clients send `Idempotency-Key` header.
+- Rate-limit sensitive routes: `rateLimit({ windowMs, max, keyGenerator, scope })`. Default behavior on Redis unavailable is fail-closed.
+- CSRF default is Origin / Sec-Fetch-Site checking on mutating requests. For double-submit-cookie protection, opt in with `csrf({ doubleSubmit: true })`.