@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/templates/default/AGENTS.md

@@ -0,0 +1,166 @@
+# Agents Guide — your ShipAPI v4 app
+
+This is the entry-point doc for any AI coding agent (Claude Code, Cursor, Codex, etc.) working in this app. Read it before doing anything.
+
+## What this is
+
+A TypeScript backend on **Hono + Drizzle + pluggable AuthProvider + BullMQ + OpenTelemetry**, scaffolded from `@sixthsummit/ship-api` v4. The framework is your dependency at `node_modules/@sixthsummit/ship-api/`; you write modules, schemas, routes, jobs, and tests against its primitives.
+
+The framework's full agent guide lives at `https://github.com/SixthSummit/Ship/blob/main/AGENTS.md`. This doc is the consumer-side projection — patterns and gotchas that apply *inside this app*, not the framework's monorepo.
+
+## Where things live
+
+- `src/index.ts` — bootstrap only: load instrumentation, then dynamically import the server.
+- `src/instrumentation.ts` — the early OpenTelemetry boundary; no application imports.
+- `src/server.ts` — `createApp()` root; mount each module sub-app via `root.route("/", buildXxxApp(deps))`; `serve()`.
+- `src/environment.ts` — `defineEnv(zodSchema)`. **The only application-config boundary for `process.env`; `instrumentation.ts` is the intentional early exception.**
+- `src/db/schema.ts` — composed Drizzle schema (module schema fragments + your tables; the framework ships no default tables).
+- `src/db/migrations/` — `drizzle-kit`-generated SQL. **Never hand-edit.**
+- `src/config/modules.ts` — placeholder for planned module auto-wiring; today, wire modules in `src/server.ts`.
+- `src/modules/<name>/` — your feature modules. Canonical 7-file shape: `schema.ts`, `permissions.ts`, `validation/schemas.ts`, `services/<NameSingular>Service.ts`, `routes.ts`, `index.ts`, `module.json`.
+- `tests/` — integration tests.
+- `drizzle.config.ts` — `drizzle-kit` config consumed by the `db:*` scripts.
+- `docker-compose.yml` — Postgres + Redis + OTel collector for `ship-api dev`.
+- `ship-api.config.ts` — Claude Code plugin activation marker (don't delete).
+
+## Run, test, build
+
+- `npm install` — install deps.
+- `ship-api dev` — recommended dev workflow. Brings up Docker Compose deps, runs `tsx watch src/index.ts`, polls `/livez` until ready, prints the URL.
+- `npm run build` — build to `lib/`.
+- `npm start` — run built output.
+- `npm test` — Vitest. The scaffold ships with `src/index.test.ts` as a sample (exercises `createApp` via `app.request("/...")` without booting a server) — use it as the pattern for your own tests; service tests next to the service, route tests at `src/modules/<name>/routes.test.ts`.
+- `npm run lint` — ESLint.
+- `npm run format` — Prettier write.
+- `npm run type-check` — `tsc --noEmit`.
+- `npm run db:generate -- --name <description>` — generate a migration from schema diffs.
+- `npm run db:migrate` — apply pending migrations.
+- `npm run db:studio` — Drizzle Studio web UI.
+
+## Adding a feature
+
+```sh
+# Full canonical 7-file module shape (schema / permissions / validation /
+# service / routes / index + module.json)
+ship-api g module billing
+
+# Or — when you already know the columns — a CRUD resource in one go:
+ship-api g resource posts --fields "title:string,body:text,published:boolean,publishedAt:timestamp?"
+```
+
+> Scaffolding stamps a `scaffold.tool` breadcrumb into `module.json` for the by-tool delivery metric. Claude Code auto-detects; **Cursor users should export `SHIP_API_SCAFFOLD_TOOL=cursor`** first (Cursor has no reliable env marker), so the metric attributes correctly.
+
+Then customize the generated files:
+
+1. **Schema** — `src/modules/<name>/schema.ts` defines the Drizzle `pgTable` + relations + types. Use `...baseFields` for audit columns (`createdAt`, `updatedAt`, `deletedAt`, `createdBy`, `updatedBy`).
+2. **Permissions** — `src/modules/<name>/permissions.ts` exports `module:resource:action` slug constants.
+3. **Validation** — `src/modules/<name>/validation/schemas.ts` defines the Zod schemas. Use `.strict()` on object schemas.
+4. **Service** — `src/modules/<name>/services/<NameSingular>Service.ts` extends `DrizzleEntityService<typeof table>`. Override `getDefaultSearchFields()` / `getDefaultRelations()` per module. Add domain-specific methods.
+5. **Routes** — `src/modules/<name>/routes.ts` exports `buildXxxApp(deps)`, which returns the module's **own** sub-app via `defineXxxRoutes(createModuleApp("xxx"), deps)`. Each route chains: `requireAuth({ provider })` → `requirePermission(slug)` → `validate("json"|"query"|"param", schema)` → handler. `defineXxxRoutes(app, deps)` is kept as an advanced escape hatch (return the chained app, stay schema-generic) but threading one shared app through several modules detonates `tsc` — see the foot-gun note below.
+6. **Compose** — mount each module sub-app onto the root in `src/server.ts`: `const app = root.route("/", buildXxxApp(deps))` (chaining the mounts), then `export type ShipApiClient = typeof app`. Modules keep their absolute paths, so the client shape is unchanged; cross-cutting concerns (`registerErrorHandlers`, `httpLogger`, CORS) live on the root only.
+7. **Tests** — `<NameSingular>Service.test.ts` (fake-DB unit) + `routes.test.ts` (full-chain integration).
+8. **Migration** — `npm run db:generate -- --name add_<name>_<change>` then commit the generated SQL.
+
+## Conventions you must follow
+
+The full rules are in `.cursor/rules/`. Read them when relevant. Indexed:
+
+- @.cursor/rules/api.mdc — RESTful design, response shapes, error handling, **never write migrations manually**
+- @.cursor/rules/typescript.mdc — coding standards, type / null safety
+- @.cursor/rules/testing.mdc — Vitest patterns, mocking, route + service test shapes
+- @.cursor/rules/security.mdc — Firebase auth, RBAC, permission system
+- @.cursor/rules/commits.mdc — Conventional Commits
+
+## Things agents commonly get wrong
+
+- **Don't read `process.env` directly** outside `src/environment.ts` / `defineEnv()` and the early `src/instrumentation.ts` boundary. Module + handler code routes through the validated `env` object.
+- **Don't hand-write SQL migrations.** Use `drizzle-kit generate` from schema source. The framework's plugin `PreToolUse` hook (`block-migration-edit.sh`) blocks edits to `src/db/migrations/*.sql` to enforce this.
+- **Don't `console.log`.** Use `logger` from `@sixthsummit/ship-api/observability/logger`. `console.*` writes lose request-id + trace context.
+- **Don't import from `node_modules/@sixthsummit/ship-api/lib/`.** Those are build artifacts. Import from package-export paths (`@sixthsummit/ship-api`, `@sixthsummit/ship-api/client`, etc.).
+- **Don't use `c.req.json()` / `c.req.query()` / `c.req.param()`** directly. Register a Zod schema with `validate("json"|"query"|"param", schema)` and read via `c.req.valid(...)`. The route registry, typed client, and (eventual) OpenAPI all read off the registered schema. ESLint's `no-restricted-syntax` rule fires on raw use.
+- **Don't import raw Drizzle operators (`eq`/`and`/`sql`/…) into a service.** Express queries via `DrizzleEntityService` + the `QueryOptions` DSL (raw Drizzle belongs in `src/db` / schema files). ESLint's `@typescript-eslint/no-restricted-imports` rule fires on a raw `drizzle-orm` value import outside the data-access layer; for specialized access (row locking, raw SQL) add a justified `eslint-disable`. Type-only imports are fine.
+- **Don't skip `requireAuth({ provider })` / `requirePermission(slug)` middleware** on protected routes — authorization runs at the route, not on the controller.
+- **Don't shape error responses inside handlers** — throw from the AppError taxonomy (`NotFoundError`, `BadRequestError`, etc.). `registerErrorHandlers(app)` shapes the JSON response uniformly.
+- **Don't enqueue BullMQ jobs inside a transaction** — risks "queued before commit". Use the **outbox pattern** via `OutboxEventEmitter.emit({...}, { tx })`.
+- **Don't thread one shared `app` through several `defineXxxRoutes` calls.** That accumulates one giant route-type and detonates `tsc` (TS2589). Build each module as its own sub-app with `buildXxxApp(deps)` (on `createModuleApp("xxx")`) and mount it via `root.route("/", buildXxxApp(deps))`. If you reach for the raw `defineXxxRoutes(app, ...)` escape hatch, keep it schema-generic and **return** the chained `app` (never `(app) => void`) so RPC types survive on `hc<ShipApiClient>()` consumers.
+- **Don't commit secrets.** Env vars only.
+
+## Consuming this app from clients
+
+The cross-framework contract is `hc()` typed-client over your app's chained-app type. **No codegen.** Schema changes flow:
+
+```
+Drizzle table → drizzle-zod → zValidator → c.req.valid() → hc<ShipApiClient>()
+```
+
+through TypeScript types end-to-end.
+
+**Server side** — mount each module sub-app on the root, then pin the typed-app alias:
+
+```ts
+// src/server.ts
+import { createApp, registerErrorHandlers, httpLogger } from "@sixthsummit/ship-api";
+import { buildAccountsApp } from "./modules/accounts";
+
+const root = createApp({ cors });
+registerErrorHandlers(root);          // root owns cross-cutting concerns
+root.use("*", httpLogger());
+
+const app = root
+  .route("/", buildAccountsApp({ service: new AccountService(db), provider }));
+export type ShipApiClient = typeof app;   // api.accounts.$get — flat shape
+export { app };
+```
+
+**Client side** (web / mobile / another service) — import the type only:
+
+```ts
+import { hc } from "@sixthsummit/ship-api/client";
+import type { ShipApiClient } from "@my-org/api/app";
+
+export const api = hc<ShipApiClient>(BASE_URL, { init: { credentials: "include" } });
+const me = await api.me.$get();
+if (me.ok) { const account = await me.json(); /* typed end-to-end */ }
+```
+
+## How to verify your work
+
+1. `npm run type-check` — passes.
+2. `npm run lint` — passes (the `no-restricted-syntax` rule catches raw `c.req.json/query/param`).
+3. `npm test` — passes.
+4. `npx vitest run src/modules/<name>/` — module-specific tests pass.
+5. If you touched routes — hit them via curl against `ship-api dev` and confirm status code, response shape, auth behavior.
+6. If you touched the schema — `npm run db:generate -- --name <description>` produces a sane SQL diff.
+
+## Claude Code specifics
+
+The `@sixthsummit/ship-api-claude-plugin` auto-activates in this workspace (it detects the `ship-api.config.ts` marker file). You get:
+
+- **Slash commands**: `/ship:lint-conventions [--diff|--all]`, `/ship:new-module <description>`, `/ship:add-job <name> -m <module>`, `/ship:add-cron <name> -m <module>`, `/ship:add-migration <name>`, `/ship:trace-request <request-id>`, `/ship:sherpa-brief [--base <ref>]`
+- **Agents**: `ship-architect` (designs new modules), `ship-codegen` (executes a plan), `ship-reviewer` (audits a diff for v4 conventions — auto-fires on `Edit`/`Write` to `modules/**/*.ts` via the PostToolUse hook), `qa-brief` (generates a Sherpa-ready QA brief from the branch diff — invoked by the `sherpa-brief.yml` workflow on PR-to-`dev` and push-to-`dev`)
+- **Skills**: ship-api-conventions, ship-module-pattern, ship-drizzle-migrations, ship-bullmq-jobs, ship-otel-debugging
+- **MCP server tools**: `list_routes`, `describe_route`, `find_route_collisions`, `execute_route` (the load-bearing one — runs requests through the live middleware chain with pre-flight schema validation)
+
+Tooling tips:
+
+- Use `Edit` over `Write` for existing files.
+- Use the `Explore` subagent for broad code searches; use direct `Grep`/`Read` for known paths.
+- Don't spin long-running processes (`npm run dev`, `tsx watch`, etc.) — they stall the agent loop. Use `ship-api dev` only when the user explicitly asks; otherwise leave it to them.
+- For UI / integration verification, ask the user to verify in their browser; don't claim "tested" without evidence.
+- The plugin's MCP `execute_route` tool is the right way to drive routes during agent iteration; pre-flight schema validation surfaces schema errors *as* schema errors, not as opaque 500s.
+
+## QA handoff (Sherpa briefs)
+
+A `.github/workflows/sherpa-brief.yml` ships with this template. It auto-generates a plain-English QA brief from each branch's diff and hands it to the QA team via [Sherpa](https://github.com/sixthsummit/sherpa), with **zero engineer admin work**:
+
+- **On PR-to-`dev`** — posts (or updates) a sticky preview comment on the PR. Informational; engineers can ignore it.
+- **On push to `dev`** — posts the final brief to the QA Slack channel (`SLACK_QA_WEBHOOK_URL`) and uploads `brief.md` as a workflow artifact.
+
+The brief is generated by the framework's `qa-brief` agent and contains plain-English flows the QA pastes into Sherpa's `/explore` — no Playwright code, no curl snippets. Editor-agnostic: Cursor and Claude Code engineers both get the same output via the CI path.
+
+Add these repo secrets (Settings → Secrets and variables → Actions):
+
+- `ANTHROPIC_API_KEY` — required for the headless agent run.
+- `SLACK_QA_WEBHOOK_URL` — Incoming Webhook for the QA channel. Optional — the push-to-dev step skips Slack with a warning if unset.
+
+If your deploy branch isn't `dev`, search-and-replace `dev` in the workflow's `on:` block. Local preview (Claude Code only): `/ship:sherpa-brief`. Full reference: [ShipAPI docs → Tooling → Sherpa QA briefs](https://docs.shipapi.dev/tooling/sherpa-qa-briefs).

package/templates/default/CLAUDE.md

@@ -0,0 +1,17 @@
+# {{PROJECT_NAME}}
+
+A ShipAPI v4 application — TypeScript backend on Hono + Drizzle + pluggable AuthProvider + BullMQ + OpenTelemetry. The framework is your dependency at `node_modules/@sixthsummit/ship-api/`; you write modules, schemas, routes, jobs, and tests against its primitives.
+
+## Agent onboarding
+
+Read `AGENTS.md` first — it covers what this app is, where things live, how to run/test/build, the canonical "add a feature" flow, common agent mistakes, and how to verify your work. The rules in `.cursor/rules/` (also `@`-imported below) are the canonical conventions; AGENTS.md is the entry-point that points at them.
+
+@AGENTS.md
+
+## Project rules
+
+@.cursor/rules/api.mdc
+@.cursor/rules/typescript.mdc
+@.cursor/rules/testing.mdc
+@.cursor/rules/security.mdc
+@.cursor/rules/commits.mdc

package/templates/default/README.md

@@ -0,0 +1,97 @@
+# {{PROJECT_NAME}}
+
+A ShipAPI v4 application. Generated by `npx ship-api create my-app`.
+
+## Stack
+
+- **HTTP**: Hono (`@hono/node-server`)
+- **Validation**: Zod 4 + `@hono/zod-validator`
+- **ORM**: Drizzle (Postgres)
+- **Auth**: Pluggable `AuthProvider` (Firebase by default)
+- **Jobs**: BullMQ
+- **Observability**: pino + OpenTelemetry (auto-instrumented)
+- **Typed client**: `hc<ShipApiClient>()` — schema → types → client, no codegen
+
+## Quick start
+
+```sh
+# 1. Install deps
+npm install
+
+# 2. Copy + populate env
+cp .env.example .env
+# Generate a 32-byte OAUTH_STATE_SECRET (any of these works):
+#   openssl rand -hex 32
+#   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+
+# 3. Bring up dependencies + start dev server in one shot
+ship-api dev
+# (Brings up Docker Compose for Postgres / Redis / OTel collector,
+# then `tsx watch src/index.ts`, then waits for /livez to go green
+# before printing the URL.)
+
+# 4. Run migrations against the dev db
+npm run db:generate -- --name initial
+npm run db:migrate
+```
+
+## Common workflows
+
+```sh
+ship-api g module billing               # scaffold a CRUD module
+ship-api g resource posts \
+  --fields "title:string,body:text,published:boolean,publishedAt:timestamp?"
+                                        # CRUD module from a field spec
+ship-api g middleware rate-limit-by-key # add a Hono middleware
+ship-api g job send-invoice-email -m billing  # add a BullMQ job stub
+
+ship-api g doctor                       # project health check
+ship-api migrate-orm <path>             # codemod TypeORM entities → Drizzle
+```
+
+## Project layout
+
+```
+.
+├── ship-api.config.ts           — Claude Code plugin activation marker
+├── drizzle.config.ts            — drizzle-kit configuration (db:* scripts)
+├── docker-compose.yml           — Postgres + Redis + OTel collector
+├── src/
+│   ├── index.ts                 — instrument first, then dynamically load server
+│   ├── instrumentation.ts       — early OpenTelemetry bootstrap boundary
+│   ├── server.ts                — createApp + module composition + serve
+│   ├── environment.ts           — defineEnv(zodSchema) — boundary for process.env
+│   ├── config/
+│   │   └── modules.ts           — placeholder for planned auto-wiring (wire in index.ts)
+│   ├── db/
+│   │   ├── schema.ts            — composed schema (module fragments + your tables)
+│   │   └── migrations/          — drizzle-kit-generated SQL
+│   └── modules/                 — your feature modules (one subdir per feature)
+│       └── (created via `ship-api add <module>` / `g module <name>`)
+└── tests/                       — integration tests
+```
+
+## Conventions
+
+The framework's load-bearing conventions are documented in:
+
+- **AGENTS.md** at the repo root — the entry-point doc for AI coding agents.
+- The Claude Code plugin's skills (auto-loaded when this file is in the workspace).
+- The framework's `.cursor/rules/*.mdc` (synced into the plugin's SKILL.md files).
+
+The shortest version:
+
+- Routes: each module exposes `buildXxxApp(deps)` returning its own sub-app (on `createModuleApp("xxx")`); mount via `root.route("/", buildXxxApp(deps))` (preserves RPC types end-to-end via `hc<ShipApiClient>()`, and keeps `tsc` bounded as modules grow). `defineXxxRoutes(app, deps)` is a kept escape hatch — threading one shared app through several modules detonates `tsc`.
+- Auth: `requireAuth({ provider })` runs the AuthProvider chain; `requirePermission(slug)` enforces against the resolved user.
+- Validation: `validate("json" | "query" | "param", schema)` wraps `zValidator`; handlers read parsed input via `c.req.valid("json" | …)`. Never `c.req.json()` directly.
+- Errors: throw from the AppError taxonomy (`NotFoundError`, `BadRequestError`, etc.); `registerErrorHandlers(app)` shapes the JSON response.
+- Services: extend `DrizzleEntityService<typeof table>` for inherited CRUD + soft-delete + audit auto-stamping.
+- Migrations: `drizzle-kit generate` from schema source. Never hand-edit `src/db/migrations/*.sql`.
+- Logging: `import { logger } from "@sixthsummit/ship-api/observability/logger"`. Never `console.log`.
+- Env: route application config through the validated `env` object. Only the
+  early `instrumentation.ts` boundary reads standard OTel variables directly.
+- Permissions: per-action slug naming (`module:resource:action`), exported as constants.
+
+## Migrating from v3
+
+See [docs/MIGRATION_V3_TO_V4.md](https://github.com/SixthSummit/Ship/blob/main/docs/MIGRATION_V3_TO_V4.md) at the framework repo for the codemod-assisted parallel-path migration walkthrough.

package/templates/default/_gitignore

@@ -0,0 +1,27 @@
+node_modules/
+dist/
+.env
+.env.local
+.env.*.local
+
+# Drizzle
+src/db/migrations/meta/
+.drizzle/
+
+# Build / cache
+*.tsbuildinfo
+.turbo/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+.idea/
+
+# Coverage
+coverage/
+
+# Wrangler (only relevant if you opt into edge runtime)
+.wrangler/

package/templates/default/docker-compose.yml

@@ -0,0 +1,83 @@
+# Local-stack dependency services for `ship-api dev`.
+#
+# `ship-api dev` runs `docker compose up -d` against the services below
+# (Postgres + Redis + Jaeger), then runs the app via `tsx watch` on the
+# host so source edits hot-reload without rebuilding a container.
+#
+# Bring everything up manually with:
+#   docker compose up -d
+#
+# Reset volumes (drops Postgres data) with:
+#   docker compose down -v
+#
+# Run the app inside Docker too (CI / smoke / parity checks): see Dockerfile;
+# `ship-api dev` does not start an api service from this compose file —
+# `tsx watch` on the host is the dev-loop default.
+
+services:
+  postgres:
+    container_name: ship-api-postgres
+    image: postgres:16
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: ship-api
+      POSTGRES_USER: ship-api
+      POSTGRES_PASSWORD: ship-api
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data_ship-api:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ship-api -d ship-api"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  redis:
+    container_name: ship-api-redis
+    image: redis:7-alpine
+    restart: unless-stopped
+    # `appendonly yes` keeps in-flight queue/job state across restarts; safe
+    # for dev. Production Redis tuning belongs in your prod compose / k8s.
+    command: ["redis-server", "--appendonly", "yes"]
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data_ship-api:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  # Jaeger all-in-one — the dev observability viewer for the framework's
+  # OpenTelemetry SDK. Exposes:
+  #   4317  — OTLP/gRPC (the default the SDK auto-detects)
+  #   4318  — OTLP/HTTP (alternate; useful for browser SDKs sharing the env)
+  #   16686 — Jaeger UI (open in a browser to inspect traces)
+  #
+  # Why Jaeger here instead of an OTel Collector: in dev, the high-value
+  # surface is the trace UI — "I just ran my code, show me the spans." The
+  # framework also commits to OTel-only for job history (BullMQ jobs flow
+  # through OTel spans rather than a `job_runs` audit table), so a viewer
+  # is load-bearing for debugging. Jaeger has a native OTLP receiver, so
+  # the app's exporter config doesn't need a separate collector hop.
+  #
+  # Production path is different: point `OTEL_EXPORTER_OTLP_ENDPOINT` at
+  # your real APM (Honeycomb / Tempo / Datadog / Cloud Trace / etc.), or
+  # run a dedicated OTel Collector with `otel/opentelemetry-collector-contrib`
+  # if you need batching / sampling / multi-backend fan-out.
+  jaeger:
+    container_name: ship-api-jaeger
+    image: jaegertracing/all-in-one:latest
+    restart: unless-stopped
+    environment:
+      COLLECTOR_OTLP_ENABLED: "true"
+    ports:
+      - "4317:4317"   # OTLP/gRPC
+      - "4318:4318"   # OTLP/HTTP
+      - "16686:16686" # Jaeger UI
+
+volumes:
+  postgres_data_ship-api:
+  redis_data_ship-api:

package/templates/default/drizzle.config.ts

@@ -0,0 +1,34 @@
+import { defineConfig } from "drizzle-kit";
+import { env } from "./src/environment.js";
+
+/**
+ * Drizzle Kit config — drives the migration tooling
+ * (`db:push`, `db:generate`, `db:migrate`, `db:studio`,
+ * `db:baseline`).
+ *
+ * The schema source aggregates the module-owned tables the consumer
+ * composes (identity/RBAC lives in the `accounts` module — add it with
+ * `ship-api add accounts`) — the same import graph the runtime sees via
+ * `createDb({ config, schema })` in `src/index.ts`. Single source of truth,
+ * never drift between "what the app uses at runtime" and "what
+ * migrations target".
+ *
+ * NEVER hand-edit the emitted SQL files in `src/db/migrations/`.
+ * The next `db:generate` will overwrite or break history. Edit
+ * the schema source and re-generate.
+ */
+
+export default defineConfig({
+  schema: "./src/db/schema.ts",
+  out: "./src/db/migrations",
+  dialect: "postgresql",
+  dbCredentials: {
+    url: env.DATABASE_URL,
+  },
+  // Verbose output makes `db:generate --name <description>` more
+  // informative when reviewing diffs in PR.
+  verbose: true,
+  // Prompt before applying destructive operations (column drops,
+  // type changes that need cast). Skip with --yes for CI.
+  strict: true,
+});

package/templates/default/eslint.config.mjs

@@ -0,0 +1,106 @@
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default [
+  {
+    ignores: ["dist/**", "node_modules/**"],
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    languageOptions: {
+      parserOptions: { ecmaVersion: 2022, sourceType: "module" },
+      globals: {
+        console: "readonly",
+        process: "readonly",
+        Buffer: "readonly",
+        setInterval: "readonly",
+        clearInterval: "readonly",
+        setTimeout: "readonly",
+        clearTimeout: "readonly",
+        global: "readonly",
+        __dirname: "readonly",
+        __filename: "readonly",
+        fetch: "readonly",
+        URL: "readonly",
+      },
+    },
+    rules: {
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { args: "none", varsIgnorePattern: "^_" },
+      ],
+      "no-restricted-globals": [
+        "error",
+        {
+          name: "process",
+          message:
+            "Read env via the validated `env` object from src/environment.ts (defineEnv). Direct process.env access bypasses the schema.",
+        },
+      ],
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "CallExpression[callee.type='MemberExpression'][callee.object.type='MemberExpression'][callee.object.property.name='req'][callee.property.name=/^(json|query|param)$/]",
+          message:
+            "Avoid raw `c.req.json()` / `c.req.query()` / `c.req.param()`. Register a Zod schema with validate() and read via c.req.valid(...).",
+        },
+      ],
+      // Keep raw Drizzle query operators in the data-access layer. Express
+      // service queries via QueryOptions / DrizzleEntityService so a future
+      // ORM swap touches only the db layer. Schema (src/db, src/modules/**/
+      // schema.ts) is exempt below; type-only imports are allowed.
+      "@typescript-eslint/no-restricted-imports": [
+        "error",
+        {
+          paths: [
+            {
+              name: "drizzle-orm",
+              message:
+                "Raw Drizzle operators (eq/and/or/sql/…) bypass the QueryOptions abstraction. Express service queries via QueryOptions / DrizzleEntityService so an ORM swap touches only the db layer. For specialized access (row locking, raw SQL), add `// eslint-disable-next-line @typescript-eslint/no-restricted-imports -- <reason>`.",
+              allowTypeImports: true,
+            },
+          ],
+          // Operators also re-export from drizzle-orm/sql* and **/expressions
+          // subpaths; block those too so `import { eq } from "drizzle-orm/sql"`
+          // can't dodge the rule. `drizzle-orm/pg-core` (columns) stays free.
+          patterns: [
+            {
+              group: [
+                "drizzle-orm/sql",
+                "drizzle-orm/sql/**",
+                "drizzle-orm/**/expressions",
+                "drizzle-orm/**/expressions/**",
+              ],
+              message:
+                "Raw Drizzle operators re-export from these subpaths too — keep them in the data-access layer (src/db / schema) and express service queries via QueryOptions / DrizzleEntityService.",
+              allowTypeImports: true,
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    // Schema + the db layer are where raw Drizzle belongs.
+    files: ["src/db/**", "src/modules/**/schema.ts"],
+    rules: { "@typescript-eslint/no-restricted-imports": "off" },
+  },
+  {
+    files: ["src/environment.ts"],
+    rules: {
+      // environment.ts is the boundary that reads process.env via
+      // defineEnv. The rest of the app routes through `env`.
+      "no-restricted-globals": "off",
+    },
+  },
+  {
+    files: ["**/*.test.ts"],
+    rules: {
+      "no-restricted-syntax": "off",
+      "@typescript-eslint/no-restricted-imports": "off",
+    },
+  },
+];

package/templates/default/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "ship-api-app",
+  "version": "0.0.1",
+  "description": "ShipAPI v4 application",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "ship-api dev",
+    "build": "tsc",
+    "start": "node dist/src/index.js",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "db:push": "drizzle-kit push",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:studio": "drizzle-kit studio",
+    "db:baseline": "drizzle-kit introspect && drizzle-kit migrate"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.19.14",
+    "@hono/zod-validator": "^0.7.6",
+    "@sixthsummit/ship-observability-otel": "^1.0.0",
+    "drizzle-orm": "^0.45.2",
+    "drizzle-zod": "^0.8.3",
+    "firebase-admin": "^13.10.0",
+    "hono": "^4.12.15",
+    "ioredis": "^5.10.1",
+    "jose": "^6.2.3",
+    "pg": "^8.16.3",
+    "pino": "^9.14.0",
+    "pino-pretty": "^13.1.3",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.0",
+    "@types/node": "^24.1.0",
+    "@types/pg": "^8.11.0",
+    "drizzle-kit": "^0.31.10",
+    "eslint": "^10.0.0",
+    "tsx": "^4.20.3",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "overrides": {
+    "uuid": "^11.1.1",
+    "@esbuild-kit/core-utils": {
+      "esbuild": "^0.25.0"
+    }
+  }
+}

package/templates/default/ship-api.config.ts

@@ -0,0 +1,21 @@
+/**
+ * `ship-api.config.ts` — marker file the Claude Code plugin's
+ * activation glob keys off (`**\/ship-api.config.ts`). When this
+ * file is present at the workspace root, the plugin's agents,
+ * slash commands, skills, and hooks become available; when it's
+ * absent, the plugin stays dormant.
+ *
+ * Plugin-side configuration the framework does not own (custom
+ * skill-trigger lists, project-specific agent prompts, hook
+ * overrides) lives here. The framework's runtime config lives in
+ * `src/environment.ts` (validated) and `src/index.ts`
+ * (composition).
+ */
+export const config = {
+  /** Plugin-readable hint for agent-driven workflows. */
+  framework: "ship-api",
+  /** Plugin-readable version pin so agents pick the right SKILL.md. */
+  frameworkVersion: "4",
+} as const;
+
+export default config;

package/templates/default/src/client.ts

@@ -0,0 +1,34 @@
+/**
+ * Materialized typed client — the "compile before using the client" lever.
+ *
+ * `hc<typeof app>()` re-instantiates your entire route chain every time a
+ * consumer (web / mobile / another service) touches the client — fine for a
+ * handful of routes, but as your app grows the per-keystroke type work in the
+ * consumer's editor adds up. Hono's recommended fix is to let `tsc` do that
+ * instantiation **once** at this package's build, emit it to `.d.ts`
+ * (`declaration: true` is set in `tsconfig.json`), and have consumers import
+ * the materialized type from your built package instead of re-deriving it from
+ * source.
+ *
+ * Consumers import `hcWithType` / `Client` from here rather than calling
+ * `hc<ShipApiClient>()` themselves:
+ *
+ * ```ts
+ * // web / mobile / microservice
+ * import { hcWithType } from "@my-org/api/client";
+ * export const api = hcWithType(BASE_URL, { init: { credentials: "include" } });
+ * const me = await api.accounts[":id"].$get({ param: { id } });
+ * ```
+ *
+ * `import type { ShipApiClient }` is erased at runtime, so importing this file
+ * does NOT boot the server in `index.ts` — only the tiny `hono/client` runtime
+ * is pulled in.
+ */
+import { hc } from "@sixthsummit/ship-api/client";
+import type { ShipApiClient } from "./index.js";
+
+/** The fully-resolved `hc()` client type for this app. */
+export type Client = ReturnType<typeof hc<ShipApiClient>>;
+
+/** `hc()` pre-bound to this app's type — use instead of `hc<ShipApiClient>()`. */
+export const hcWithType = (...args: Parameters<typeof hc>): Client => hc<ShipApiClient>(...args);