@obh/forge 0.2.0

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":";;;AAAA,wEAAwE;AAC3D,QAAA,aAAa,GAAG,OAAO,CAAA"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@obh/forge",
+  "version": "0.2.0",
+  "private": false,
+  "description": "OBH Forge — deterministic scaffolding and delivery tooling for OBH software projects.",
+  "license": "MIT",
+  "packageManager": "pnpm@9.7.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "commonjs",
+  "bin": {
+    "forge": "dist/cli.js",
+    "obh-forge": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "start": "node dist/cli.js"
+  },
+  "dependencies": {
+    "@iarna/toml": "^2.2.5",
+    "commander": "^12.1.0",
+    "picocolors": "^1.0.1",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/prompts": "^2.4.9",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}

package/skills/obh-add-events/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: obh-add-events
+description: Use when adding an event catalogue to a project's domain — turning writes into emitted facts. Inspects routes/services, proposes dot.notation event names with payloads and exact in-transaction emit sites, then guides `forge add events` and wiring emits into the app event bus.
+---
+
+Purpose: give a project a coherent set of domain **events** (facts) so other primitives can react, without inventing events that don't map to real state changes. Events are facts in `dot.notation` (e.g. `note.created`); they are emitted inside the write transaction that produced them.
+
+## Workflow
+
+1. **Find the writes.** Inspect `apps/api/src/routes/*.ts` and `apps/api/src/domain/*` for handlers that INSERT/UPDATE/DELETE or change state. Every meaningful state transition is a candidate fact. Ignore pure reads.
+
+2. **Name events as facts.** Use `resource.pastTenseVerb` in dot.notation: `note.created`, `note.updated`, `note.deleted`, `invoice.paid`, `user.invited`. State changes get their own event (`order.shipped`), not a generic `order.updated`, when a consumer would care about the specific transition.
+
+3. **Design payloads.** Each payload carries the IDs and the minimal facts a consumer needs — resource id, actor id, workspace/tenant id, and the fields that changed (or before/after for updates). Keep payloads flat and serialisable; reference large blobs by id, don't inline them. Avoid leaking secrets or full PII into payloads that audit/analytics will persist.
+
+4. **Pin the transaction boundary.** For each event, identify the exact write transaction and place the emit **inside** it (same tx/connection as the DB write) so the fact and the state commit atomically via the outbox. Note the precise call-site (file + function + line region). If a handler does multiple writes, decide whether it emits one event or several.
+
+5. **Map future consumers.** For each event, list which primitives should react: **notifications** (user-facing email/rules), **audit** (immutable trail), **analytics** (KPIs), **search** (index updates), **webhooks** (outbound), **jobs** (follow-up commands). This drives later `forge add` choices — don't wire them yet, just record intent.
+
+6. **Install the primitive.** Run `forge add events` (use `--dry-run` first). This scaffolds the outbox/dispatcher migration in `scripts/migrations.d/*`, the `@obh/events` client, and the in-app bus at `apps/api/src/bus.ts`. Run `pnpm migrate` to apply the platform schema.
+
+7. **Wire the emits.** In each write handler, call `bus.emit('note.created', payload)` inside the tx. Auto-loaded subscribers live in `apps/api/src/bus.d/*` — add a subscriber file per reacting concern (they run in-process; heavy work should enqueue a job rather than block the request). Use `defineX`/`createXClient` grammar from `@obh/events` for the typed event definitions.
+
+## Output
+
+An **event catalogue**: a table of `event.name` → payload shape → emitting file/tx site → intended consumers; the `forge add events` command (with `--dry-run` note) and `pnpm migrate` step; and a per-handler wiring plan showing where `bus.emit(...)` goes inside each transaction and which `bus.d/*` subscribers to create. Flag any write that currently emits nothing but should.

package/skills/obh-generate-audit-rules/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: obh-generate-audit-rules
+description: Use when a project has domain events and needs an immutable audit trail. Generates @obh/audit rule mappings (event -> action/target/actor) covering create/update/delete/state-change events, with redaction and immutability notes.
+---
+
+Purpose: turn existing domain **events** (facts) into an **audit** trail. The audit primitive derives an immutable log from events — each rule maps one event to an audit record's action, target, and actor. Audit does not observe the DB directly; it reacts to events, so this skill depends on an event catalogue already existing (see obh-add-events).
+
+## Workflow
+
+1. **Collect the events.** Read the project's event definitions (from `@obh/events` `defineX` files / the catalogue). List every event name, its payload, and what state change it represents. If no events exist yet, stop and run obh-add-events first — there is nothing for audit to observe.
+
+2. **Classify each event.** Bucket into create / update / delete / state-change. Every one of these is auditable. Pure read or ephemeral events (e.g. `session.pinged`) usually are not — note them as excluded with a reason.
+
+3. **Derive action/target/actor per rule.**
+   - **action** — a stable verb phrase from the event: `note.created` → `note.create`, `invoice.paid` → `invoice.mark_paid`. Keep actions consistent across resources.
+   - **target** — the entity acted on: type + id pulled from the payload (`{ type: 'note', id: payload.noteId }`).
+   - **actor** — who did it: user/api-key/system id from the payload. If the payload lacks an actor, flag it — the event may need to carry `actorId`.
+   - For **update** events, capture a diff (changed fields, or before/after) as audit metadata so the trail is meaningful.
+
+4. **Plan redaction.** Mark payload fields that must not land in the immutable log: secrets, tokens, full PII, large blobs. Specify per-rule redaction (drop or hash) before the audit record is written — remember records are immutable, so a leak can't be edited out later.
+
+5. **Install and wire.** Run `forge add audit` (`--dry-run` first). This adds the audit migration to `scripts/migrations.d/*` and the `@obh/audit` client. Run `pnpm migrate`. Register the rules against the event bus/subscribers (`apps/api/src/bus.d/*` or the audit worker consumer) so each event produces its audit record. Audit writes are append-only — never expose update/delete on them.
+
+## Output
+
+An **audit rule map**: a table of `event.name` → `action` → target (type+id source) → actor (source) → captured metadata/diff → redacted fields, plus an **excluded events** list with reasons; the `forge add audit` + `pnpm migrate` steps; where rules are registered; and an explicit immutability/redaction note (records are append-only; redact before write).

package/skills/obh-inspect-project/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: obh-inspect-project
+description: Use when you need to understand an unfamiliar or pre-Forge codebase before changing it. Reads the repo and reports project shape, DB and deploy patterns, which OBH platform primitives are present vs. candidates, risks, and a recommended `forge add` sequence.
+---
+
+Purpose: build an accurate map of a repository so subsequent Forge/retrofit work is grounded in what actually exists, not assumptions. This skill only reads and reports — it makes no changes.
+
+## Workflow
+
+1. **Detect project shape.** Look for `forge.json` first — if present, read the recorded apps, packages, installed primitives, and topology; the repo is already Forge-managed. Otherwise infer: check for `pnpm-workspace.yaml` + `apps/*` + `packages/*` (Forge-style monorepo) vs. a single-package app. List every app and package with its role (api, admin, worker, mobile, sdk, ui, config).
+
+2. **Identify the package manager.** `pnpm-lock.yaml` → pnpm (Forge default), `package-lock.json` → npm, `yarn.lock` → yarn. Note if mixed lockfiles exist (a risk).
+
+3. **Determine the DB access pattern.** Grep for: raw `pg` / `Pool` / `client.query` (raw SQL — Forge-native); `typeorm`, `@mikro-orm`, `prisma`, `sequelize`, `drizzle` (ORM). Record whether schema is managed by migrations (`migrations/*.sql`, `scripts/migrate.ts`) or by ORM `synchronize`/auto-sync. Note the schemas in use — product tables belong in `public`, OBH primitives own `platform`.
+
+4. **Map deployment.** Look for `deploy/*.lwd.toml` (Forge/lwd), `Dockerfile`, `docker-compose.yml`, `vercel.json`, `fly.toml`, k8s manifests, CI workflows. Note where secrets live (committed `.env`, CI secrets, lwd secret names).
+
+5. **Census platform primitives.** For each OBH primitive (events, jobs, files, audit, settings, api-keys, webhooks, import-export, entitlements, search, analytics, notifications), decide **present** (an `@obh/*` dep or a `scripts/migrations.d/*` entry) vs. **candidate** (hand-rolled equivalent exists — e.g. a homegrown outbox table, a cron route, multer uploads, a `settings`/`options` table). Cite the file that triggered each candidate.
+
+6. **Flag risks.** Watch for: ORM auto-sync/`synchronize: true` (schema drift, no reviewable migrations); missing migrations directory; no `/health` or readiness endpoint; duplicated types between backend and frontend(s); committed secrets; missing event seam (writes with no facts emitted); a worker surface mixed into the API process.
+
+7. **Recommend a `forge add` sequence.** Order by dependency: `events` first (most primitives react to events), then the primitives that consume them (`audit`, `analytics`, `notifications`, `search`), then independent ones (`files`, `jobs`, `settings`, `api-keys`, `webhooks`, `import-export`, `entitlements`). Only recommend primitives justified by a real candidate. Suggest `forge inspect` and `forge doctor` to validate before mutating, and note every mutating command supports `--dry-run`.
+
+## Output
+
+A concise report with sections: **Shape** (apps/packages + package manager), **Data** (DB access + migration strategy + schemas), **Deploy** (surfaces + secrets), **Primitives** (present vs. candidate table, each candidate citing a file), **Risks** (ranked), and **Recommended sequence** (an ordered list of `forge add <primitive>` commands with a one-line reason each, prefixed with a `forge doctor` / `--dry-run` note). No code changes.

package/skills/obh-lwd-manifest/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: obh-lwd-manifest
+description: Use when generating or updating lwd deploy manifests for a Forge project. Encodes real lwd constraints — worker as a separate surface, no co-located Postgres on a replicated API, per-app network isolation, secret NAMES only — and prefers `forge generate lwd` over hand-editing.
+---
+
+Purpose: produce correct `deploy/*.lwd.toml` manifests that match the app topology. Prefer generating them with Forge; hand-edit only for constraints the generator can't infer. lwd manifests reference secret **NAMES** only — values are set out-of-band with `lwd secret set`.
+
+## Workflow
+
+1. **Read the topology.** From `forge.json` and `apps/*`, list the deployable surfaces: api, admin/web, worker. Note replica intent (is the API meant to scale, `replicas > 1`?) and whether a database is expected to be managed by lwd or external.
+
+2. **One surface per manifest, correctly typed.** Each app gets its own `deploy/<app>.lwd.toml`. A **worker is a separate surface** from the API — it needs its own domain/entrypoint and its **own health check** (a liveness signal from the tick loop, not the API's HTTP `/health`). Don't fold the worker into the API manifest.
+
+3. **Apply the Postgres co-location rule.** A `[[services]]` Postgres may be co-located only with a single-instance surface. If the API is scalable (`replicas > 1`), it **cannot** co-locate a `[[services]]` Postgres — point it at an external/managed database instead. A small dev/single-replica API may co-locate Postgres.
+
+4. **Isolate networks per app.** Give each app its own network scope; don't share a network across surfaces beyond what they must reach. The worker and API connect to the same database but are otherwise isolated.
+
+5. **Reference secret NAMES only.** List required secrets by NAME (DB URL, S3/files keys, API-key signing secret, webhook signing secret, SMTP for notifications). Never put values in the toml. Add a note that each is provisioned with `lwd secret set <NAME>` per environment.
+
+6. **Choose small vs. split topology.** **Small**: api + worker + co-located Postgres, single replicas — fine for dev/low volume. **Split**: replicated API (external DB) + independent worker + managed Postgres — for production scale. Pick based on the replica intent from step 1.
+
+7. **Generate, then review.** Run `forge generate lwd` (`--dry-run` first) to emit/update the manifests from `forge.json`. Hand-edit only for things the generator can't know: replica counts, external-DB endpoints, worker health specifics, network scoping. Re-run `forge doctor` to validate.
+
+## Output
+
+The `deploy/*.lwd.toml` manifests (one per surface) with correct types, health checks, network isolation, and secret NAMES; the `forge generate lwd` command used (with `--dry-run`); a short topology recommendation (small vs. split) tied to replica intent; a list of secrets to `lwd secret set`; and an explicit note of any hand-edits made and why the generator couldn't produce them.

package/skills/obh-retrofit-files/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: obh-retrofit-files
+description: Use when replacing ad-hoc upload/storage code (multer, Vercel Blob, local disk, raw S3 SDK) with @obh/files. Maps the existing storage choke-point to createFilesClient behind the same function signature, so the product handles only file_id and uploads go signed direct-to-storage.
+---
+
+Purpose: consolidate all file storage behind the **files** primitive so the product never touches bytes or bucket credentials — it stores a `file_id` and asks `@obh/files` for signed URLs. Uploads go direct from client to storage; downloads are signed, time-boxed URLs.
+
+## Workflow
+
+1. **Locate storage code.** Grep for: `multer`, `formidable`, `@vercel/blob`, `fs.writeFile`/`createWriteStream` to an uploads dir, `@aws-sdk/client-s3` / `S3Client` / `getSignedUrl`, `putObject`, `Bucket`. Identify every choke-point where bytes enter or leave the app and how the resulting location is persisted (a URL column, a path, a bucket key).
+
+2. **Map the current model to file_id.** Wherever the product stores a URL/path/key, it should store a `file_id` (FK to the platform files table). List the columns and code paths that need to change from "store a URL" to "store an id, resolve to a signed URL on read".
+
+3. **Install the primitive.** Run `forge add files` (`--dry-run` first). This adds the files migration to `scripts/migrations.d/*` and the `@obh/files` client (`createFilesClient`/`pgAdapter`). Run `pnpm migrate`. Record required secret NAMES (bucket/endpoint/keys) for deploy — values go in via `lwd secret set`, never committed.
+
+4. **Swap behind the same signature.** Keep the existing function (e.g. `saveAvatar(userId, upload)`), but replace its body with `createFilesClient` calls: request a signed upload target, hand it to the client, and record the returned `file_id`. Callers don't change. Do the same for reads: a `getAvatarUrl(fileId)` that returns a signed URL.
+
+5. **Move to direct-to-storage uploads.** For large/user uploads, have the API mint a signed upload URL and return it; the client PUTs bytes straight to storage; the client then confirms the `file_id`. This removes multipart bodies and the app-as-proxy pattern. For server-generated files (reports, exports), upload from the worker and store the `file_id`.
+
+6. **Retire old storage.** Remove multer/blob/disk/S3 wiring and any static file-serving route. Plan a backfill: for existing rows, register current objects with `@obh/files` to obtain `file_id`s, then drop the old URL/path columns once nothing reads them.
+
+## Output
+
+A **files retrofit plan**: a table of storage choke-point → replacement `@obh/files` call → the function signature kept stable → the column moving from URL/path to `file_id`; the `forge add files` + `pnpm migrate` steps; required secret NAMES; the direct-to-storage upload flow (mint URL → client PUT → confirm id); and a backfill/cutover note for existing rows.

package/skills/obh-retrofit-jobs/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: obh-retrofit-jobs
+description: Use when moving slow, scheduled, or background work off the request path onto the OBH jobs queue. Finds cron routes, slow synchronous handlers, report/import/cleanup tasks and proposes converting each to an idempotent OBH Job enqueued inside a transaction, with a worker handler.
+---
+
+Purpose: get long-running or deferred work out of API request handlers and into durable, retryable **jobs** (commands). Jobs are commands in `snake_case` (e.g. `send_invoice_email`, `rebuild_search_index`); they are enqueued transactionally and run in the worker.
+
+## Workflow
+
+1. **Find candidates.** Grep the API for: cron/scheduled routes (`/cron/*`, `node-cron`, `setInterval`, Vercel cron); handlers doing heavy synchronous work (loops over rows, external HTTP calls, PDF/report generation, bulk email); import/export processing; cleanup/retention tasks; anything that makes the request slow or can fail partway.
+
+2. **Name each as a command.** `snake_case` imperative: `generate_monthly_report`, `import_contacts_csv`, `purge_expired_sessions`, `send_welcome_email`. One job = one unit of retryable work.
+
+3. **Design an idempotent handler.** Each job must be safe to run more than once (at-least-once delivery). Use a natural idempotency key (resource id + operation, or a dedup column), upserts instead of blind inserts, and guard against double side-effects (e.g. mark-then-send). Define the payload as the minimal input the handler needs — pass ids, re-fetch current state inside the handler.
+
+4. **Place the enqueue inside a tx.** Enqueue the job in the **same transaction** as the state change that should trigger it, so a committed write always has its follow-up queued and a rolled-back write never leaks a job. Where a job should follow a fact, prefer emitting an event (see obh-add-events) and enqueueing the job from a subscriber — events are facts, jobs are the commands they trigger.
+
+5. **Install and scaffold.** Run `forge add jobs` (`--dry-run` first). This adds the queue migration in `scripts/migrations.d/*`, the `@obh/jobs` client (`createJobsClient`/`pgAdapter`/`runMigrations`), and a worker surface. Run `pnpm migrate`.
+
+6. **Write the worker handler.** Add a consumer under `apps/worker/src/consumers.d/*.ts` exporting `init(ctx)` / `tick(ctx)` (auto-loaded). Bind each `snake_case` job to its handler; keep handlers small, log start/finish, and let the queue handle retry/backoff rather than catching-and-swallowing.
+
+7. **Retire the old path.** Replace the synchronous body of the original route with an enqueue that returns quickly (202/accepted). Remove cron routes once the worker owns the schedule. Keep the old code behind the same function signature during transition if callers depend on it.
+
+## Output
+
+A **jobs retrofit plan**: a table of source (route/task) → `job_name` (snake_case) → payload → idempotency key → enqueue tx site → worker consumer file; the `forge add jobs` + `pnpm migrate` steps; and per-route notes on what the handler returns after enqueue and which cron/synchronous code is removed.

package/skills/obh-sdk-extraction/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: obh-sdk-extraction
+description: Use when types and API-client code are duplicated between the backend and one or more frontends. Proposes extracting a single packages/sdk (shared types + one typed client), then migrating callers one resource at a time behind a compatibility re-export.
+---
+
+Purpose: eliminate drift between backend and frontend(s) by making `packages/sdk` the single source of shared types and the one typed API client. The migration is incremental and non-breaking: callers move one resource at a time behind a compatibility re-export so nothing breaks mid-flight.
+
+## Workflow
+
+1. **Find the duplication.** Grep across `apps/api`, `apps/admin`, `apps/mobile`, and any frontend for: parallel type declarations (a `User`/`Invoice` interface defined in both backend and frontend), and hand-rolled/defensive fetch clients (bespoke `fetch` wrappers, per-call `try/catch` + manual JSON casting, ad-hoc base-URL handling). List each duplicated type and each client function, and which surfaces define/consume it.
+
+2. **Pick the source of truth.** For shared types, the backend's domain types are usually canonical. For the client, design one typed client whose methods mirror the API routes (`apps/api/src/routes/*`). Note where request/response shapes disagree between front and back — those mismatches are latent bugs to resolve during extraction.
+
+3. **Scaffold the package.** Run `forge add sdk` (`--dry-run` first) to create `packages/sdk` in the workspace and register it in `forge.json`. It holds shared types and a single `createClient`-style typed client — no framework-specific code, so every app (api, admin, mobile) can depend on it.
+
+4. **Move types first.** Relocate the canonical types into `packages/sdk`. In each place that previously declared them, replace the declaration with a **compatibility re-export** from the sdk (`export type { User } from '@obh/sdk'`) so existing imports keep resolving unchanged.
+
+5. **Migrate callers one resource at a time.** For each resource (users, invoices, …): point the frontend at the sdk client method, delete the hand-rolled client code for that resource, and remove its local types (now re-exported). Ship per-resource — the compatibility re-exports mean unmigrated resources keep working alongside migrated ones.
+
+6. **Retire the shims.** Once every caller imports from `@obh/sdk` directly, remove the compatibility re-exports and the last defensive client wrappers. Verify each frontend still type-checks against the sdk.
+
+## Output
+
+An **sdk extraction plan**: a table of duplicated type / client-function → surfaces that define & consume it → canonical source → any front/back shape mismatch to fix; the `forge add sdk` step; a phased sequence (move types + re-export shims → migrate callers resource-by-resource → remove shims); and a per-resource checklist so the migration ships in safe, independent increments.

package/skills/obh-settings-migration/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: obh-settings-migration
+description: Use when consolidating scattered configuration — hardcoded constants, .env sprawl, or an untyped options/settings table — into typed @obh/settings definitions. Proposes scope/schema/default/sensitivity per key plus a read-through-write-both migration path.
+---
+
+Purpose: replace ad-hoc config with the typed, scoped **settings** primitive. Each setting has a scope (global / workspace / user), a typed schema, a default, and a sensitivity flag. The migration is gradual: read through settings while writing both old and new stores until the old source is retired.
+
+## Workflow
+
+1. **Inventory current config.** Grep for three patterns: hardcoded constants in source (magic numbers, feature flags, limits, URLs); `.env` / `process.env.*` usage (env sprawl, especially non-secret tuning values); and untyped key/value config tables (`settings`, `options`, `preferences`, `config` with a `value text` column). Record each key, its current type, where it's read, and who it varies by.
+
+2. **Assign a scope.** Decide the narrowest scope that fits: **global** (one value for the whole deployment), **workspace/tenant** (per-organisation), or **user** (per-account). A single hardcoded constant that never varies is global; anything read per-request off the tenant/user is scoped.
+
+3. **Define a typed schema + default.** For each key give a concrete type (boolean, number with range, enum, string, structured object) and a sensible default so a missing value never breaks. Group related keys under one definition where they move together.
+
+4. **Mark sensitivity.** Flag secrets/credentials as sensitive — those stay out of logs and audit payloads and are supplied via deploy secret NAMES, not stored as plain settings values. Non-secret tuning values are normal settings and can move out of `.env` entirely.
+
+5. **Install the primitive.** Run `forge add settings` (`--dry-run` first). This adds the settings migration to `scripts/migrations.d/*` and the `@obh/settings` client (`defineX`/`createSettingsClient`/`pgAdapter`). Run `pnpm migrate`. Write the `defineSettings` schemas from step 3.
+
+6. **Migrate read-through, write-both.** Introduce a resolver that reads from `@obh/settings` and falls back to the old source (constant/env/options table) when unset — this is safe to ship immediately. For writable config, write to both stores during transition. Backfill existing option-table rows into settings. Once reads are served entirely from settings and backfill is verified, remove the fallback and the old constants/env keys/table.
+
+## Output
+
+A **settings migration plan**: a table of key → scope → typed schema → default → sensitivity → current source (constant/env/table) and read sites; the `forge add settings` + `pnpm migrate` steps with the `defineSettings` definitions to write; and a phased cutover (read-through-with-fallback → write-both + backfill → remove old source), calling out which keys are sensitive and stay as deploy secrets.