@obh/forge 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OBH Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# OBH Forge
+
+Deterministic scaffolding and delivery tooling for OBH software projects.
+
+Forge starts projects correctly, then gets out of the way. It is **not** a
+runtime, framework, or reconciler — just a set of composable CLI commands that
+generate boring, readable, removable code.
+
+```bash
+forge new app qhaul --recipe full-saas       # api + admin + worker + sdk + core primitives
+forge add search                             # add a primitive (prerequisites auto-added)
+forge add notifications
+forge generate lwd                           # (re)generate deploy manifests
+forge inspect                                # what's in this project?
+forge doctor                                 # does it match OBH conventions?
+forge skill install obh-add-events           # drop a Claude skill into .claude/skills/
+```
+
+## Install
+
+```bash
+pnpm add -g @obh/forge     # once published
+# or from source:
+pnpm install && pnpm build && node dist/cli.js --help
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `forge new app <name>` | Scaffold a new project. Recipes: `full-saas`, `api-web-worker`, `api-only`, `worker`. Flags: `--api-framework hono\|express`, `--no-example`, `--no-sdk`, `--mobile [name]`, `--topology small\|split`, `--repo owner/repo`, `--scope`. |
+| `forge new package <name>` | Scaffold an OBH platform-primitive repo (the qtool template: `@obh/<name>`, kernel helpers, record-store client, migrations, CI). `--daemon` adds an admin/worker app. |
+| `forge add <target>` | Add an app (`api`/`web`/`worker`/`sdk`/`mobile`) or a primitive — `events`, `jobs`, `files`, `audit`, `settings`, `api-keys`, `webhooks`, `import-export`, `entitlements`, `search`, `analytics`, `notifications`. Prerequisites resolve automatically. |
+| `forge inspect` | Report project shape and detected conventions. |
+| `forge doctor` | Check the project against OBH conventions (reports only). |
+| `forge generate <artifact>` | Regenerate `lwd`, `ci`, or `env`. |
+| `forge skill <list\|install>` | List or install the bundled OBH Claude skills. |
+| `forge stack <init\|deploy\|status\|rm>` | Deliver the repo to lwd: assemble the apps into one stack, generate + wire secret values, and apply in order. `forge deploy` is an alias for `forge stack deploy`. |
+
+Every mutating command supports `--dry-run`, `--yes`, and `--force`.
+
+## Deploying a stack (`forge stack`)
+
+`forge new` generates per-app `deploy/*.lwd.toml` with **secret names only**.
+`forge stack` closes the gap to a running deployment — as a pure client of the
+`lwd` CLI (zero lwd changes):
+
+```bash
+forge stack init          # inspect deploy/*.lwd.toml → write a reviewable deploy/stack.json
+#                           (groups the apps, proposes generated + derived secrets)
+# review deploy/stack.json
+forge stack deploy         # (alias: forge deploy) generate secret VALUES, wire connections,
+#                           lwd secret set + lwd apply each app in dependency order
+forge stack status         # rolled-up lwd status across the stack
+forge stack rm             # tear down in reverse order (named data volumes preserved)
+```
+
+`deploy` **generates** the random secrets (`POSTGRES_PASSWORD`, `JWT_SECRET`,
+`API_KEYS_PEPPER`), **derives** connection strings (`DATABASE_URL` from the
+Postgres backing service), **orders** the multi-app apply, and is **idempotent**
+(lwd is the sole secret store — already-set secrets are skipped, never rotated
+silently; `--dry-run` masks all values). It **honestly flags** lwd's per-app
+network isolation: a worker that can't reach a Postgres co-located in the API is
+reported (fix by moving to split topology), never wired with a broken value.
+`--rotate <KEY>` regenerates a secret and re-derives everything built from it.
+
+## What you get from `forge new`
+
+A real, working vertical slice — not stubs:
+
+- **`apps/api`** — Hono or Express, a Postgres pool with a `withTx` helper, a
+  transaction-aware **event bus**, and (unless `--no-example`) a real `notes`
+  domain: CRUD over Postgres that emits `note.created/updated/deleted` facts
+  inside its write transaction. Routes auto-mount from `src/routes/*`.
+- **`apps/admin`** — Vite + React, a real Notes management UI driving the API
+  through the shared SDK.
+- **`apps/worker`** — a tick loop with a health port that auto-loads consumers
+  from `src/consumers.d/*`.
+- **`packages/sdk`** — the one typed contract (types + client) shared by the API
+  and every frontend.
+- **`apps/mobile`** (with `--mobile`) — an Expo React Native app driving the same
+  SDK; the notes screen works end-to-end. Ships via EAS, so it gets no lwd
+  manifest.
+- **`deploy/*.lwd.toml`**, per-app **Dockerfiles**, **CI** (with Postgres),
+  a **migration runner**, `.env.example`, `forge.json`.
+
+## How capabilities stay safe
+
+Adding a primitive never patches your code. Generated apps auto-load from
+convention directories, so `forge add <x>` just drops files:
+
+- API routes → `apps/api/src/routes/*` (each `register(app)`)
+- domain-fact subscribers → `apps/api/src/bus.d/*` (`onEmit(...)`)
+- worker consumers → `apps/worker/src/consumers.d/*` (`init`/`tick`)
+- platform migrations → `scripts/migrations.d/*` (`migrate(pool)`)
+
+Every change flows through a `Plan` that classifies each op as create / append /
+overwrite and refuses to clobber a differing file without `--force`.
+
+Primitives wire into the example domain for real: `events` bridges the bus to the
+durable outbox, `jobs` enqueues on note writes, `audit` records `note.*`,
+`search`/`analytics` index and roll up note events, `notifications` emails on
+`note.created`, `import-export` moves notes as CSV, `entitlements` gates note
+creation, `api-keys` protects a machine route.
+
+## Design guarantees
+
+- **Boring, real output.** Generated projects are normal TypeScript you can read,
+  edit, or delete. No TODOs, no empty handlers, no placeholder URLs (deploy repos
+  are auto-detected from `git remote`, else prompted).
+- **Composable & opt-in.** Nothing is installed unless a recipe or `forge add`
+  asks for it.
+- **Configurable, not rigid.** Framework choice, example on/off, SDK on/off,
+  topology, custom app names — all recorded in `forge.json`.
+- **lwd-aware.** Manifests encode lwd's real constraints (workers are separate
+  surfaces; a scalable API can't co-locate a backing DB; per-app network
+  isolation). Secret names only — never values.
+
+## forge.json
+
+Each project carries a `forge.json` recording shape, chosen conventions, and
+installed primitives. It's a receipt and an aid for `forge doctor` and the Claude
+skills — not a desired-state contract.
+
+## Claude skills
+
+Bundled under `skills/` and installable per-project with `forge skill install`:
+`obh-inspect-project`, `obh-add-events`, `obh-retrofit-jobs`, `obh-retrofit-files`,
+`obh-generate-audit-rules`, `obh-settings-migration`, `obh-lwd-manifest`,
+`obh-sdk-extraction`. Forge does the mechanical file work; the skills do the
+interpretive work (reading a repo, proposing event names, mapping legacy code).
+
+## Deferred
+
+AST-level patching and an upgrade/reconcile mode.
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm typecheck
+pnpm test
+```
+
+Requires Node ≥ 20 and pnpm 9.

package/dist/capabilities/analytics.d.ts

@@ -0,0 +1,3 @@
+import type { Capability } from "./types";
+export declare const analytics: Capability;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/capabilities/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../src/capabilities/analytics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAGzC,eAAO,MAAM,SAAS,EAAE,UA8BvB,CAAA"}

package/dist/capabilities/analytics.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analytics = void 0;
+const helpers_1 = require("./helpers");
+exports.analytics = {
+    name: "analytics",
+    requires: ["events"],
+    describe: "Event-derived KPIs — facts rolled into queryable timeseries",
+    apply(ctx, plan) {
+        (0, helpers_1.addPlatformPackage)(plan, ctx, "analytics", { api: true, worker: true });
+        plan.create("scripts/migrations.d/analytics.ts", (0, helpers_1.migrationModule)("analytics"), "analytics migrations wiring");
+        const notes = (0, helpers_1.hasNotesExample)(ctx);
+        if (ctx.hasApp("api")) {
+            plan.create("apps/api/src/platform/analytics.ts", apiClient(notes), "analytics client + metrics");
+            plan.create("apps/api/src/routes/analytics.ts", (0, helpers_1.apiFramework)(ctx) === "hono" ? ROUTE_HONO : ROUTE_EXPRESS, "metric timeseries route");
+        }
+        if (ctx.hasWorker()) {
+            plan.create("apps/worker/src/analytics-metrics.ts", workerMetrics(notes), "worker-side metric definitions");
+            plan.create("apps/worker/src/dispatch.d/analytics.ts", `export const consumer = { name: "analytics", events: ["*"] }\n`, "register analytics as an event consumer");
+            plan.create("apps/worker/src/consumers.d/analytics.ts", WORKER, "analytics rollup tick");
+        }
+        plan.patchManifest({ platform: { analytics: true } });
+        plan.nextStep("Run `pnpm migrate`. Query metrics at GET /api/analytics/:metric.");
+    },
+};
+function metricDefs(notes) {
+    return notes
+        ? `  defineMetric({ key: "notes_created", events: "note.created", aggregation: "count" }),`
+        : `  // defineMetric({ key: "things_created", events: "thing.created", aggregation: "count" }),`;
+}
+function apiClient(notes) {
+    return `import { createAnalyticsClient, defineMetric, pgAdapter, type MetricDefinition } from "@obh/analytics"
+import { pool } from "../db"
+
+export const metrics: MetricDefinition[] = [
+${metricDefs(notes)}
+]
+
+export const analytics = createAnalyticsClient({ db: pgAdapter(pool), metrics })
+`;
+}
+function workerMetrics(notes) {
+    return `import { defineMetric, type MetricDefinition } from "@obh/analytics"
+
+// Worker-side copy of the metric definitions (kept here so the worker never
+// imports across app boundaries). Mirror of apps/api/src/platform/analytics.ts.
+export const metrics: MetricDefinition[] = [
+${metricDefs(notes)}
+]
+`;
+}
+const ROUTE_HONO = `import type { Hono } from "hono"
+import type { Bucket } from "@obh/analytics"
+import { analytics } from "../platform/analytics"
+import { WORKSPACE } from "../platform/events"
+
+export function register(app: Hono): void {
+  app.get("/api/analytics/:metric", async (c) => {
+    const bucket = (c.req.query("bucket") as Bucket) ?? "day"
+    return c.json(await analytics.timeseries({ workspaceId: WORKSPACE, metric: c.req.param("metric"), bucket }))
+  })
+}
+`;
+const ROUTE_EXPRESS = `import type { Express, Request, Response } from "express"
+import type { Bucket } from "@obh/analytics"
+import { analytics } from "../platform/analytics"
+import { WORKSPACE } from "../platform/events"
+
+export function register(app: Express): void {
+  app.get("/api/analytics/:metric", async (req: Request, res: Response) => {
+    const bucket = (req.query.bucket as Bucket) ?? "day"
+    res.json(await analytics.timeseries({ workspaceId: WORKSPACE, metric: req.params.metric, bucket }))
+  })
+}
+`;
+const WORKER = `// Claims the "analytics" deliveries and rolls facts into metric buckets.
+import { createAnalyticsWorker, pgAdapter } from "@obh/analytics"
+import { metrics } from "../analytics-metrics"
+import type { WorkerContext } from "../context"
+
+let worker: ReturnType<typeof createAnalyticsWorker>
+
+export function init(ctx: WorkerContext): void {
+  worker = createAnalyticsWorker({ db: pgAdapter(ctx.pool), metrics, instanceId: "worker" })
+}
+
+export async function tick(): Promise<void> {
+  await worker.tick()
+}
+`;
+//# sourceMappingURL=analytics.js.map

package/dist/capabilities/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../../src/capabilities/analytics.ts"],"names":[],"mappings":";;;AACA,uCAA8F;AAEjF,QAAA,SAAS,GAAe;IACnC,IAAI,EAAE,WAAW;IACjB,QAAQ,EAAE,CAAC,QAAQ,CAAC;IACpB,QAAQ,EAAE,6DAA6D;IACvE,KAAK,CAAC,GAAG,EAAE,IAAI;QACb,IAAA,4BAAkB,EAAC,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;QACvE,IAAI,CAAC,MAAM,CAAC,mCAAmC,EAAE,IAAA,yBAAe,EAAC,WAAW,CAAC,EAAE,6BAA6B,CAAC,CAAA;QAE7G,MAAM,KAAK,GAAG,IAAA,yBAAe,EAAC,GAAG,CAAC,CAAA;QAClC,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM,CAAC,oCAAoC,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,4BAA4B,CAAC,CAAA;YACjG,IAAI,CAAC,MAAM,CACT,kCAAkC,EAClC,IAAA,sBAAY,EAAC,GAAG,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,aAAa,EACzD,yBAAyB,CAC1B,CAAA;QACH,CAAC;QACD,IAAI,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC;YACpB,IAAI,CAAC,MAAM,CAAC,sCAAsC,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,gCAAgC,CAAC,CAAA;YAC3G,IAAI,CAAC,MAAM,CACT,yCAAyC,EACzC,gEAAgE,EAChE,yCAAyC,CAC1C,CAAA;YACD,IAAI,CAAC,MAAM,CAAC,0CAA0C,EAAE,MAAM,EAAE,uBAAuB,CAAC,CAAA;QAC1F,CAAC;QAED,IAAI,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC,CAAA;QACrD,IAAI,CAAC,QAAQ,CAAC,kEAAkE,CAAC,CAAA;IACnF,CAAC;CACF,CAAA;AAED,SAAS,UAAU,CAAC,KAAc;IAChC,OAAO,KAAK;QACV,CAAC,CAAC,yFAAyF;QAC3F,CAAC,CAAC,8FAA8F,CAAA;AACpG,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,OAAO;;;;EAIP,UAAU,CAAC,KAAK,CAAC;;;;CAIlB,CAAA;AACD,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO;;;;;EAKP,UAAU,CAAC,KAAK,CAAC;;CAElB,CAAA;AACD,CAAC;AAED,MAAM,UAAU,GAAG;;;;;;;;;;;CAWlB,CAAA;AAED,MAAM,aAAa,GAAG;;;;;;;;;;;CAWrB,CAAA;AAED,MAAM,MAAM,GAAG;;;;;;;;;;;;;;CAcd,CAAA"}

package/dist/capabilities/api-keys.d.ts

@@ -0,0 +1,3 @@
+import type { Capability } from "./types";
+export declare const apiKeys: Capability;
+//# sourceMappingURL=api-keys.d.ts.map

package/dist/capabilities/api-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-keys.d.ts","sourceRoot":"","sources":["../../src/capabilities/api-keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAGzC,eAAO,MAAM,OAAO,EAAE,UAwBrB,CAAA"}

package/dist/capabilities/api-keys.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiKeys = void 0;
+const helpers_1 = require("./helpers");
+exports.apiKeys = {
+    name: "api-keys",
+    describe: "Scoped machine-to-machine API keys (non-human credentials)",
+    apply(ctx, plan) {
+        (0, helpers_1.addPlatformPackage)(plan, ctx, "api-keys", { api: true });
+        plan.create("scripts/migrations.d/api-keys.ts", (0, helpers_1.migrationModule)("api-keys"), "api-keys migrations wiring");
+        if (ctx.hasApp("api")) {
+            plan.create("apps/api/src/platform/api-keys.ts", CLIENT, "api-keys client");
+            const hono = (0, helpers_1.apiFramework)(ctx) === "hono";
+            const notes = (0, helpers_1.hasNotesExample)(ctx);
+            plan.create("apps/api/src/routes/machine.ts", hono ? routeHono(notes) : routeExpress(notes), "scope-protected machine route");
+        }
+        plan.addEnvVar({
+            name: "API_KEYS_PEPPER",
+            example: "change-me-to-a-long-random-secret",
+            comment: "REQUIRED — api-keys won't work without it; keep out of the DB",
+            secret: true,
+        });
+        plan.patchManifest({ platform: { "api-keys": true } });
+        plan.nextStep("Run `pnpm migrate` and set API_KEYS_PEPPER. Issue keys via apiKeys.create({ workspaceId, name, scopes }).");
+    },
+};
+const CLIENT = `import { createApiKeysClient, pgAdapter } from "@obh/api-keys"
+import { pool } from "../db"
+
+export const apiKeys = createApiKeysClient({
+  db: pgAdapter(pool),
+  pepper: process.env.API_KEYS_PEPPER!,
+})
+`;
+function routeHono(notes) {
+    const body = notes
+        ? `    const body = await c.req.json<{ title?: string; body?: string }>()
+    if (!body.title) return c.json({ error: "title is required" }, 400)
+    return c.json(await notes.createNote({ title: body.title, body: body.body }), 201)`
+        : `    return c.json({ ok: true, principal: ctx.principalId })`;
+    return `import type { Hono } from "hono"
+import { ApiKeyAuthError } from "@obh/api-keys"
+import { apiKeys } from "../platform/api-keys"
+${notes ? 'import * as notes from "../domain/notes"\n' : ""}
+export function register(app: Hono): void {
+  app.post("/machine/${notes ? "notes" : "ping"}", async (c) => {
+    const bearer = (c.req.header("authorization") ?? "").replace(/^Bearer /, "")
+    let ctx
+    try {
+      ctx = await apiKeys.authenticate(bearer)
+    } catch (err) {
+      if (err instanceof ApiKeyAuthError) return c.json({ error: "invalid api key" }, 401)
+      throw err
+    }
+    if (!apiKeys.hasScope(ctx, "${notes ? "notes:write" : "machine:use"}")) {
+      return c.json({ error: "missing scope" }, 403)
+    }
+${body}
+  })
+}
+`;
+}
+function routeExpress(notes) {
+    const body = notes
+        ? `    if (!req.body.title) return res.status(400).json({ error: "title is required" })
+    res.status(201).json(await notes.createNote({ title: req.body.title, body: req.body.body }))`
+        : `    res.json({ ok: true, principal: ctx.principalId })`;
+    return `import type { Express, Request, Response } from "express"
+import { ApiKeyAuthError } from "@obh/api-keys"
+import { apiKeys } from "../platform/api-keys"
+${notes ? 'import * as notes from "../domain/notes"\n' : ""}
+export function register(app: Express): void {
+  app.post("/machine/${notes ? "notes" : "ping"}", async (req: Request, res: Response) => {
+    const bearer = (req.headers.authorization ?? "").replace(/^Bearer /, "")
+    let ctx
+    try {
+      ctx = await apiKeys.authenticate(bearer)
+    } catch (err) {
+      if (err instanceof ApiKeyAuthError) return res.status(401).json({ error: "invalid api key" })
+      throw err
+    }
+    if (!apiKeys.hasScope(ctx, "${notes ? "notes:write" : "machine:use"}")) {
+      return res.status(403).json({ error: "missing scope" })
+    }
+${body}
+  })
+}
+`;
+}
+//# sourceMappingURL=api-keys.js.map

package/dist/capabilities/api-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-keys.js","sourceRoot":"","sources":["../../src/capabilities/api-keys.ts"],"names":[],"mappings":";;;AACA,uCAA8F;AAEjF,QAAA,OAAO,GAAe;IACjC,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE,4DAA4D;IACtE,KAAK,CAAC,GAAG,EAAE,IAAI;QACb,IAAA,4BAAkB,EAAC,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAA;QACxD,IAAI,CAAC,MAAM,CAAC,kCAAkC,EAAE,IAAA,yBAAe,EAAC,UAAU,CAAC,EAAE,4BAA4B,CAAC,CAAA;QAE1G,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM,CAAC,mCAAmC,EAAE,MAAM,EAAE,iBAAiB,CAAC,CAAA;YAC3E,MAAM,IAAI,GAAG,IAAA,sBAAY,EAAC,GAAG,CAAC,KAAK,MAAM,CAAA;YACzC,MAAM,KAAK,GAAG,IAAA,yBAAe,EAAC,GAAG,CAAC,CAAA;YAClC,IAAI,CAAC,MAAM,CAAC,gCAAgC,EAAE,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,+BAA+B,CAAC,CAAA;QAC/H,CAAC;QAED,IAAI,CAAC,SAAS,CAAC;YACb,IAAI,EAAE,iBAAiB;YACvB,OAAO,EAAE,mCAAmC;YAC5C,OAAO,EAAE,+DAA+D;YACxE,MAAM,EAAE,IAAI;SACb,CAAC,CAAA;QAEF,IAAI,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,CAAC,CAAA;QACtD,IAAI,CAAC,QAAQ,CAAC,2GAA2G,CAAC,CAAA;IAC5H,CAAC;CACF,CAAA;AAED,MAAM,MAAM,GAAG;;;;;;;CAOd,CAAA;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,MAAM,IAAI,GAAG,KAAK;QAChB,CAAC,CAAC;;uFAEiF;QACnF,CAAC,CAAC,6DAA6D,CAAA;IACjE,OAAO;;;EAGP,KAAK,CAAC,CAAC,CAAC,4CAA4C,CAAC,CAAC,CAAC,EAAE;;uBAEpC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;;;;;;;;;kCASb,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,aAAa;;;EAGrE,IAAI;;;CAGL,CAAA;AACD,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,MAAM,IAAI,GAAG,KAAK;QAChB,CAAC,CAAC;iGAC2F;QAC7F,CAAC,CAAC,wDAAwD,CAAA;IAC5D,OAAO;;;EAGP,KAAK,CAAC,CAAC,CAAC,4CAA4C,CAAC,CAAC,CAAC,EAAE;;uBAEpC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;;;;;;;;;kCASb,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,aAAa;;;EAGrE,IAAI;;;CAGL,CAAA;AACD,CAAC"}

package/dist/capabilities/audit.d.ts

@@ -0,0 +1,3 @@
+import type { Capability } from "./types";
+export declare const audit: Capability;
+//# sourceMappingURL=audit.d.ts.map

package/dist/capabilities/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/capabilities/audit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAGzC,eAAO,MAAM,KAAK,EAAE,UAwBnB,CAAA"}

package/dist/capabilities/audit.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.audit = void 0;
+const helpers_1 = require("./helpers");
+exports.audit = {
+    name: "audit",
+    requires: ["events"],
+    describe: "Immutable who-did-what-to-what trail, derived from events",
+    apply(ctx, plan) {
+        (0, helpers_1.addPlatformPackage)(plan, ctx, "audit", { worker: true });
+        plan.create("scripts/migrations.d/audit.ts", (0, helpers_1.migrationModule)("audit"), "audit migrations wiring");
+        const notes = (0, helpers_1.hasNotesExample)(ctx);
+        if (ctx.hasWorker()) {
+            plan.create("apps/worker/src/audit-rules.ts", rulesFile(notes), "audit rule definitions");
+            plan.create("apps/worker/src/dispatch.d/audit.ts", `export const consumer = { name: "audit", events: ["*"] }\n`, "register audit as an event consumer");
+            plan.create("apps/worker/src/consumers.d/audit.ts", WORKER, "audit event consumer tick");
+        }
+        else {
+            plan.create("apps/api/src/platform/audit-rules.ts", rulesFile(notes), "audit rules (add a worker to consume them)");
+        }
+        plan.patchManifest({ platform: { audit: true } });
+        plan.nextStep("Run `pnpm migrate`. Edit audit rules in apps/worker/src/audit-rules.ts.");
+    },
+};
+function rulesFile(notes) {
+    const rules = notes
+        ? `  defineAuditRule({
+    event: "note.created",
+    action: "note.created",
+    target: (e) => ({ type: "note", id: idOf(e) }),
+    summary: () => "created a note",
+  }),
+  defineAuditRule({
+    event: "note.updated",
+    action: "note.updated",
+    target: (e) => ({ type: "note", id: idOf(e) }),
+    summary: () => "updated a note",
+  }),
+  defineAuditRule({
+    event: "note.deleted",
+    action: "note.deleted",
+    target: (e) => ({ type: "note", id: idOf(e) }),
+    summary: () => "deleted a note",
+  }),`
+        : `  // defineAuditRule({
+  //   event: "thing.created", action: "thing.created",
+  //   target: (e) => ({ type: "thing", id: idOf(e) }), summary: () => "created a thing",
+  // }),`;
+    return `import { createRuleSet, defineAuditRule, type AuditEvent } from "@obh/audit"
+
+const idOf = (e: AuditEvent): string => String((e.payload as { id?: string }).id ?? "?")
+
+// Map domain events to immutable audit entries.
+export const auditRules = createRuleSet([
+${rules}
+])
+`;
+}
+const WORKER = `// Claims the "audit" deliveries and records immutable audit entries.
+import { createAuditWorker, pgAdapter } from "@obh/audit"
+import { auditRules } from "../audit-rules"
+import type { WorkerContext } from "../context"
+
+let worker: ReturnType<typeof createAuditWorker>
+
+export function init(ctx: WorkerContext): void {
+  worker = createAuditWorker({ db: pgAdapter(ctx.pool), rules: auditRules, instanceId: "worker" })
+}
+
+export async function tick(): Promise<void> {
+  await worker.tick()
+}
+`;
+//# sourceMappingURL=audit.js.map

package/dist/capabilities/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/capabilities/audit.ts"],"names":[],"mappings":";;;AACA,uCAAgF;AAEnE,QAAA,KAAK,GAAe;IAC/B,IAAI,EAAE,OAAO;IACb,QAAQ,EAAE,CAAC,QAAQ,CAAC;IACpB,QAAQ,EAAE,2DAA2D;IACrE,KAAK,CAAC,GAAG,EAAE,IAAI;QACb,IAAA,4BAAkB,EAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;QACxD,IAAI,CAAC,MAAM,CAAC,+BAA+B,EAAE,IAAA,yBAAe,EAAC,OAAO,CAAC,EAAE,yBAAyB,CAAC,CAAA;QAEjG,MAAM,KAAK,GAAG,IAAA,yBAAe,EAAC,GAAG,CAAC,CAAA;QAClC,IAAI,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC;YACpB,IAAI,CAAC,MAAM,CAAC,gCAAgC,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,wBAAwB,CAAC,CAAA;YACzF,IAAI,CAAC,MAAM,CACT,qCAAqC,EACrC,4DAA4D,EAC5D,qCAAqC,CACtC,CAAA;YACD,IAAI,CAAC,MAAM,CAAC,sCAAsC,EAAE,MAAM,EAAE,2BAA2B,CAAC,CAAA;QAC1F,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,CAAC,sCAAsC,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,4CAA4C,CAAC,CAAA;QACrH,CAAC;QAED,IAAI,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAA;QACjD,IAAI,CAAC,QAAQ,CAAC,yEAAyE,CAAC,CAAA;IAC1F,CAAC;CACF,CAAA;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,MAAM,KAAK,GAAG,KAAK;QACjB,CAAC,CAAC;;;;;;;;;;;;;;;;;MAiBA;QACF,CAAC,CAAC;;;SAGG,CAAA;IACP,OAAO;;;;;;EAMP,KAAK;;CAEN,CAAA;AACD,CAAC;AAED,MAAM,MAAM,GAAG;;;;;;;;;;;;;;CAcd,CAAA"}

package/dist/capabilities/entitlements.d.ts

@@ -0,0 +1,3 @@
+import type { Capability } from "./types";
+export declare const entitlements: Capability;
+//# sourceMappingURL=entitlements.d.ts.map

package/dist/capabilities/entitlements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlements.d.ts","sourceRoot":"","sources":["../../src/capabilities/entitlements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAGzC,eAAO,MAAM,YAAY,EAAE,UAe1B,CAAA"}

package/dist/capabilities/entitlements.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.entitlements = void 0;
+const helpers_1 = require("./helpers");
+exports.entitlements = {
+    name: "entitlements",
+    describe: "Entitlements — feature access + numeric limits, enforced before the write",
+    apply(ctx, plan) {
+        (0, helpers_1.addPlatformPackage)(plan, ctx, "entitlements", { api: true });
+        plan.create("scripts/migrations.d/entitlements.ts", (0, helpers_1.migrationModule)("entitlements"), "entitlements migrations wiring");
+        if (ctx.hasApp("api")) {
+            plan.create("apps/api/src/platform/entitlements.ts", registryFile((0, helpers_1.hasNotesExample)(ctx)), "entitlements registry + client + guard");
+            plan.create("apps/api/src/routes/entitlements.ts", (0, helpers_1.apiFramework)(ctx) === "hono" ? ROUTE_HONO : ROUTE_EXPRESS, "read a workspace's entitlements");
+        }
+        plan.patchManifest({ platform: { entitlements: true } });
+        plan.nextStep("Run `pnpm migrate`. Grant plans/overrides, then guard writes with entitlements.require(db, workspaceId, key).");
+    },
+};
+function registryFile(notes) {
+    const def = notes
+        ? `// A numeric limit with a code default; grant a higher value per plan or workspace.
+export const notesMax = defineEntitlement({
+  key: "notes.max",
+  type: "number",
+  defaultValue: 100,
+})`
+        : `// A boolean feature flag with a code default; grant true per plan or workspace.
+export const exampleFeature = defineEntitlement({
+  key: "app.example_feature",
+  type: "boolean",
+  defaultValue: false,
+})`;
+    const exportName = notes ? "notesMax" : "exampleFeature";
+    const guard = notes
+        ? `
+/** Throws unless the workspace is under its notes.max entitlement. */
+export async function requireCanCreateNote(): Promise<void> {
+  const max = await entitlements.limit(entitlementsDb, WORKSPACE, notesMax.key)
+  const { rows } = await pool.query<{ count: string }>("select count(*)::int as count from notes")
+  if (Number(rows[0].count) >= max) {
+    throw new Error(\`workspace \${WORKSPACE} has reached its notes limit (\${max})\`)
+  }
+}
+`
+        : `
+/** Throws EntitlementRequiredError unless the workspace has the feature. */
+export async function requireExampleFeature(): Promise<void> {
+  await entitlements.require(entitlementsDb, WORKSPACE, exampleFeature.key)
+}
+`;
+    return `import { createEntitlementRegistry, createEntitlementsClient, defineEntitlement, pgAdapter } from "@obh/entitlements"
+import { pool } from "../db"
+
+// Every platform row is scoped to a workspace. Single-tenant apps can leave this.
+export const WORKSPACE = process.env.WORKSPACE_ID ?? "default"
+
+${def}
+
+export const registry = createEntitlementRegistry([${exportName}])
+
+// The client is stateless; each call takes a db/tx handle and a workspace id.
+export const entitlements = createEntitlementsClient({ registry })
+export const entitlementsDb = pgAdapter(pool)
+${guard}`;
+}
+const ROUTE_HONO = `import type { Hono } from "hono"
+import { entitlements, entitlementsDb, WORKSPACE } from "../platform/entitlements"
+
+export function register(app: Hono): void {
+  // All effective entitlements for the workspace (value + where it resolved from).
+  app.get("/entitlements", async (c) => {
+    return c.json(await entitlements.listEffective(entitlementsDb, WORKSPACE))
+  })
+
+  // Explain a single entitlement: effective value plus the full fallback chain.
+  app.get("/entitlements/:key", async (c) => {
+    return c.json(await entitlements.explain(entitlementsDb, WORKSPACE, c.req.param("key")))
+  })
+}
+`;
+const ROUTE_EXPRESS = `import type { Express, Request, Response } from "express"
+import { entitlements, entitlementsDb, WORKSPACE } from "../platform/entitlements"
+
+export function register(app: Express): void {
+  app.get("/entitlements", async (_req: Request, res: Response) => {
+    res.json(await entitlements.listEffective(entitlementsDb, WORKSPACE))
+  })
+
+  app.get("/entitlements/:key", async (req: Request, res: Response) => {
+    res.json(await entitlements.explain(entitlementsDb, WORKSPACE, req.params.key))
+  })
+}
+`;
+//# sourceMappingURL=entitlements.js.map

package/dist/capabilities/entitlements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlements.js","sourceRoot":"","sources":["../../src/capabilities/entitlements.ts"],"names":[],"mappings":";;;AACA,uCAA8F;AAEjF,QAAA,YAAY,GAAe;IACtC,IAAI,EAAE,cAAc;IACpB,QAAQ,EAAE,2EAA2E;IACrF,KAAK,CAAC,GAAG,EAAE,IAAI;QACb,IAAA,4BAAkB,EAAC,IAAI,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAA;QAC5D,IAAI,CAAC,MAAM,CAAC,sCAAsC,EAAE,IAAA,yBAAe,EAAC,cAAc,CAAC,EAAE,gCAAgC,CAAC,CAAA;QAEtH,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM,CAAC,uCAAuC,EAAE,YAAY,CAAC,IAAA,yBAAe,EAAC,GAAG,CAAC,CAAC,EAAE,wCAAwC,CAAC,CAAA;YAClI,IAAI,CAAC,MAAM,CAAC,qCAAqC,EAAE,IAAA,sBAAY,EAAC,GAAG,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,aAAa,EAAE,iCAAiC,CAAC,CAAA;QAClJ,CAAC;QAED,IAAI,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,EAAE,CAAC,CAAA;QACxD,IAAI,CAAC,QAAQ,CAAC,+GAA+G,CAAC,CAAA;IAChI,CAAC;CACF,CAAA;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,MAAM,GAAG,GAAG,KAAK;QACf,CAAC,CAAC;;;;;GAKH;QACC,CAAC,CAAC;;;;;GAKH,CAAA;IACD,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,gBAAgB,CAAA;IACxD,MAAM,KAAK,GAAG,KAAK;QACjB,CAAC,CAAC;;;;;;;;;CASL;QACG,CAAC,CAAC;;;;;CAKL,CAAA;IACC,OAAO;;;;;;EAMP,GAAG;;qDAEgD,UAAU;;;;;EAK7D,KAAK,EAAE,CAAA;AACT,CAAC;AAED,MAAM,UAAU,GAAG;;;;;;;;;;;;;;CAclB,CAAA;AAED,MAAM,aAAa,GAAG;;;;;;;;;;;;CAYrB,CAAA"}

package/dist/capabilities/events.d.ts

@@ -0,0 +1,3 @@
+import type { Capability } from "./types";
+export declare const events: Capability;
+//# sourceMappingURL=events.d.ts.map

package/dist/capabilities/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/capabilities/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAGzC,eAAO,MAAM,MAAM,EAAE,UAsBpB,CAAA"}