@obh/forge 0.2.0

package/dist/capabilities/events.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.events = void 0;
+const helpers_1 = require("./helpers");
+exports.events = {
+    name: "events",
+    describe: "Postgres event outbox + dispatcher — durable facts emitted inside your transactions",
+    apply(ctx, plan) {
+        (0, helpers_1.addPlatformPackage)(plan, ctx, "events", { api: true, worker: true });
+        // defineEvent requires a zod schema; events peer-depends on zod.
+        if (ctx.hasApp("api"))
+            plan.addDependency("apps/api", "zod", "^3.23.8");
+        plan.create("scripts/migrations.d/events.ts", (0, helpers_1.migrationModule)("events"), "events migrations wiring");
+        if (ctx.hasApp("api")) {
+            plan.create("apps/api/src/platform/events.ts", registryFile((0, helpers_1.hasNotesExample)(ctx)), "events registry + client");
+            // Bridge the in-app bus to the durable outbox — same transaction as the write.
+            plan.create("apps/api/src/bus.d/events-outbox.ts", OUTBOX, "forward domain facts to the outbox");
+        }
+        if (ctx.hasWorker()) {
+            plan.create("apps/worker/src/dispatch.d/.gitkeep", "", "event-consumer registration directory");
+            plan.create("apps/worker/src/consumers.d/events.ts", WORKER, "events dispatcher (fans facts to registered consumers)");
+        }
+        plan.patchManifest({ platform: { events: true } });
+        plan.nextStep("Run `pnpm migrate` — domain facts land in platform.events and fan out to consumers.");
+    },
+};
+function registryFile(notes) {
+    const defs = notes
+        ? `const notePayload = z.object({ id: z.string() }).passthrough()
+
+export const noteCreated = defineEvent({ name: "note.created", version: 1, schema: notePayload })
+export const noteUpdated = defineEvent({ name: "note.updated", version: 1, schema: notePayload })
+export const noteDeleted = defineEvent({ name: "note.deleted", version: 1, schema: notePayload })
+
+export const registry = createEventRegistry([noteCreated, noteUpdated, noteDeleted])`
+        : `// Declare your domain facts, e.g.:
+// export const thingCreated = defineEvent({ name: "thing.created", version: 1, schema: z.object({ id: z.string() }) })
+export const registry = createEventRegistry([])`;
+    return `import { z } from "zod"
+import { createEventClient, createEventRegistry, defineEvent, type EventDb } from "@obh/events"
+
+// Every platform row is scoped to a workspace. Single-tenant apps can leave this.
+export const WORKSPACE = process.env.WORKSPACE_ID ?? "default"
+
+${defs}
+
+export const events = createEventClient({ source: "app", registry })
+
+/** Adapt a raw pg transaction to the structural EventDb @obh/events expects. */
+export function asEventDb(tx: { query: (sql: string, params?: unknown[]) => Promise<{ rows: unknown[] }> }): EventDb {
+  return { query: (sql: string, params?: unknown[]) => tx.query(sql, params) as never }
+}
+`;
+}
+const OUTBOX = `import { onEmit } from "../bus"
+import { asEventDb, events, WORKSPACE } from "../platform/events"
+
+// Every domain fact emitted on the bus is written to the durable @obh/events
+// outbox on the SAME transaction, so nothing is lost after a committed write.
+onEmit(async (tx, name, payload) => {
+  await events.emit(asEventDb(tx), name, { workspaceId: WORKSPACE, payload })
+})
+`;
+const WORKER = `// Fans new events into per-consumer deliveries. Each event-consuming capability
+// (analytics, audit, search, …) drops a { name, events } registration into
+// dispatch.d/; this loads them so their deliveries get created.
+import { createEventDispatcher, pgAdapter } from "@obh/events"
+import { readdirSync } from "node:fs"
+import path from "node:path"
+import type { WorkerContext } from "../context"
+
+interface DispatchConsumer {
+  name: string
+  events: string[]
+}
+
+function loadDispatchConsumers(): DispatchConsumer[] {
+  const dir = path.join(__dirname, "..", "dispatch.d")
+  const out: DispatchConsumer[] = []
+  try {
+    for (const file of readdirSync(dir).sort()) {
+      if (!/\\.(ts|js)$/.test(file) || file.endsWith(".d.ts")) continue
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const mod = require(path.join(dir, file))
+      if (mod.consumer) out.push(mod.consumer as DispatchConsumer)
+    }
+  } catch {
+    // no dispatch.d yet
+  }
+  return out
+}
+
+let dispatcher: ReturnType<typeof createEventDispatcher>
+
+export function init(ctx: WorkerContext): void {
+  dispatcher = createEventDispatcher({
+    db: pgAdapter(ctx.pool),
+    instanceId: "worker",
+    consumers: loadDispatchConsumers(),
+  })
+}
+
+export async function tick(): Promise<void> {
+  await dispatcher.tick()
+}
+`;
+//# sourceMappingURL=events.js.map

package/dist/capabilities/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/capabilities/events.ts"],"names":[],"mappings":";;;AACA,uCAAgF;AAEnE,QAAA,MAAM,GAAe;IAChC,IAAI,EAAE,QAAQ;IACd,QAAQ,EAAE,qFAAqF;IAC/F,KAAK,CAAC,GAAG,EAAE,IAAI;QACb,IAAA,4BAAkB,EAAC,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;QACpE,iEAAiE;QACjE,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC;YAAE,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,KAAK,EAAE,SAAS,CAAC,CAAA;QACvE,IAAI,CAAC,MAAM,CAAC,gCAAgC,EAAE,IAAA,yBAAe,EAAC,QAAQ,CAAC,EAAE,0BAA0B,CAAC,CAAA;QAEpG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM,CAAC,iCAAiC,EAAE,YAAY,CAAC,IAAA,yBAAe,EAAC,GAAG,CAAC,CAAC,EAAE,0BAA0B,CAAC,CAAA;YAC9G,+EAA+E;YAC/E,IAAI,CAAC,MAAM,CAAC,qCAAqC,EAAE,MAAM,EAAE,oCAAoC,CAAC,CAAA;QAClG,CAAC;QACD,IAAI,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC;YACpB,IAAI,CAAC,MAAM,CAAC,qCAAqC,EAAE,EAAE,EAAE,uCAAuC,CAAC,CAAA;YAC/F,IAAI,CAAC,MAAM,CAAC,uCAAuC,EAAE,MAAM,EAAE,wDAAwD,CAAC,CAAA;QACxH,CAAC;QAED,IAAI,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,CAAA;QAClD,IAAI,CAAC,QAAQ,CAAC,qFAAqF,CAAC,CAAA;IACtG,CAAC;CACF,CAAA;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,MAAM,IAAI,GAAG,KAAK;QAChB,CAAC,CAAC;;;;;;qFAM+E;QACjF,CAAC,CAAC;;gDAE0C,CAAA;IAC9C,OAAO;;;;;;EAMP,IAAI;;;;;;;;CAQL,CAAA;AACD,CAAC;AAED,MAAM,MAAM,GAAG;;;;;;;;CAQd,CAAA;AAED,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0Cd,CAAA"}

package/dist/capabilities/files.d.ts

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

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

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

package/dist/capabilities/files.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.files = void 0;
+const helpers_1 = require("./helpers");
+exports.files = {
+    name: "files",
+    describe: "File metadata + signed URLs over S3-compatible storage (product handles file_id only)",
+    apply(ctx, plan) {
+        (0, helpers_1.addPlatformPackage)(plan, ctx, "files", { api: true });
+        plan.create("scripts/migrations.d/files.ts", (0, helpers_1.migrationModule)("files"), "files migrations wiring");
+        if (ctx.hasApp("api")) {
+            plan.create("apps/api/src/platform/files.ts", CLIENT, "files client + S3 storage provider");
+            plan.create("apps/api/src/routes/files.ts", (0, helpers_1.apiFramework)(ctx) === "hono" ? ROUTE_HONO : ROUTE_EXPRESS, "signed upload/download routes");
+        }
+        plan.addEnvVar({ name: "S3_ENDPOINT", example: "http://localhost:9000", comment: "S3-compatible endpoint (MinIO in dev); omit for real AWS S3" });
+        plan.addEnvVar({ name: "S3_REGION", example: "us-east-1" });
+        plan.addEnvVar({ name: "S3_BUCKET", example: `${ctx.manifest?.name ?? "app"}-files` });
+        plan.addEnvVar({ name: "S3_ACCESS_KEY_ID", example: "minioadmin", comment: "secret in prod — set via lwd secret set", secret: true });
+        plan.addEnvVar({ name: "S3_SECRET_ACCESS_KEY", example: "minioadmin", comment: "secret in prod — set via lwd secret set", secret: true });
+        plan.patchManifest({ platform: { files: true } });
+        plan.nextStep("Run `pnpm migrate`. For local dev run MinIO and create the S3_BUCKET.");
+    },
+};
+const CLIENT = `import { createFilesClient, createS3StorageProvider, pgAdapter } from "@obh/files"
+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"
+
+// S3-compatible provider: AWS S3, MinIO, Cloudflare R2, Backblaze B2, etc.
+// forcePathStyle defaults to true whenever an endpoint is set (MinIO needs it).
+const storage = createS3StorageProvider({
+  endpoint: process.env.S3_ENDPOINT,
+  region: process.env.S3_REGION ?? "us-east-1",
+  accessKeyId: process.env.S3_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
+})
+
+// The bucket lives on the client; the storage provider is bucket-agnostic.
+export const files = createFilesClient({ storage, bucket: process.env.S3_BUCKET! })
+
+// Client methods take a db/tx handle as their first argument so metadata writes
+// can join a transaction. Here we hand them a pool-backed adapter.
+export const filesDb = pgAdapter(pool)
+`;
+const ROUTE_HONO = `import type { Hono } from "hono"
+import { files, filesDb, WORKSPACE } from "../platform/files"
+
+export function register(app: Hono): void {
+  // 1. Ask for a signed upload URL, then PUT the bytes straight to storage.
+  app.post("/files/upload-url", async (c) => {
+    const body = await c.req.json<{ originalName?: string; contentType?: string; sizeBytes?: number }>()
+    if (!body.originalName) return c.json({ error: "originalName is required" }, 400)
+    return c.json(
+      await files.createUpload(filesDb, {
+        workspaceId: WORKSPACE,
+        originalName: body.originalName,
+        contentType: body.contentType ?? null,
+        sizeBytes: body.sizeBytes ?? null,
+      }),
+    )
+  })
+
+  // 2. Confirm the upload completed (the server verifies via a HEAD request).
+  app.post("/files/:id/complete", async (c) => {
+    return c.json(await files.completeUpload(filesDb, { workspaceId: WORKSPACE, fileId: c.req.param("id") }))
+  })
+
+  // 3. Hand back a short-lived signed download URL.
+  app.get("/files/:id/download-url", async (c) => {
+    return c.json(await files.createDownloadUrl(filesDb, { workspaceId: WORKSPACE, fileId: c.req.param("id") }))
+  })
+}
+`;
+const ROUTE_EXPRESS = `import type { Express, Request, Response } from "express"
+import { files, filesDb, WORKSPACE } from "../platform/files"
+
+export function register(app: Express): void {
+  app.post("/files/upload-url", async (req: Request, res: Response) => {
+    if (!req.body.originalName) return res.status(400).json({ error: "originalName is required" })
+    res.json(
+      await files.createUpload(filesDb, {
+        workspaceId: WORKSPACE,
+        originalName: req.body.originalName,
+        contentType: req.body.contentType ?? null,
+        sizeBytes: req.body.sizeBytes ?? null,
+      }),
+    )
+  })
+
+  app.post("/files/:id/complete", async (req: Request, res: Response) => {
+    res.json(await files.completeUpload(filesDb, { workspaceId: WORKSPACE, fileId: req.params.id }))
+  })
+
+  app.get("/files/:id/download-url", async (req: Request, res: Response) => {
+    res.json(await files.createDownloadUrl(filesDb, { workspaceId: WORKSPACE, fileId: req.params.id }))
+  })
+}
+`;
+//# sourceMappingURL=files.js.map

package/dist/capabilities/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/capabilities/files.ts"],"names":[],"mappings":";;;AACA,uCAA6E;AAEhE,QAAA,KAAK,GAAe;IAC/B,IAAI,EAAE,OAAO;IACb,QAAQ,EAAE,uFAAuF;IACjG,KAAK,CAAC,GAAG,EAAE,IAAI;QACb,IAAA,4BAAkB,EAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAA;QACrD,IAAI,CAAC,MAAM,CAAC,+BAA+B,EAAE,IAAA,yBAAe,EAAC,OAAO,CAAC,EAAE,yBAAyB,CAAC,CAAA;QAEjG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM,CAAC,gCAAgC,EAAE,MAAM,EAAE,oCAAoC,CAAC,CAAA;YAC3F,IAAI,CAAC,MAAM,CAAC,8BAA8B,EAAE,IAAA,sBAAY,EAAC,GAAG,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,aAAa,EAAE,+BAA+B,CAAC,CAAA;QACzI,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,uBAAuB,EAAE,OAAO,EAAE,6DAA6D,EAAE,CAAC,CAAA;QACjJ,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAA;QAC3D,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,QAAQ,EAAE,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC,CAAA;QACtF,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,yCAAyC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;QACrI,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,yCAAyC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;QAEzI,IAAI,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAA;QACjD,IAAI,CAAC,QAAQ,CAAC,uEAAuE,CAAC,CAAA;IACxF,CAAC;CACF,CAAA;AAED,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;CAqBd,CAAA;AAED,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BlB,CAAA;AAED,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;CAwBrB,CAAA"}

package/dist/capabilities/helpers.d.ts

@@ -0,0 +1,27 @@
+import type { ApiFramework } from "../types";
+import type { ProjectContext } from "../project/context";
+import type { Plan } from "../project/plan";
+/** The API framework the project chose (defaults to hono). */
+export declare function apiFramework(ctx: ProjectContext): ApiFramework;
+/** Whether the project was scaffolded with the notes example domain. */
+export declare function hasNotesExample(ctx: ProjectContext): boolean;
+/** Map a capability's short name to its published @obh package name. */
+export declare const OBH_PACKAGE: Record<string, string>;
+export interface PackageTargets {
+    /** Add to apps/api (client/emit side). */
+    api?: boolean;
+    /** Add to apps/worker (consumer side). */
+    worker?: boolean;
+}
+/**
+ * Add an @obh platform package to the right package.json files. It is always
+ * added to the root (so scripts/migrate.ts can resolve it) plus any requested
+ * app that actually exists.
+ */
+export declare function addPlatformPackage(plan: Plan, ctx: ProjectContext, cap: string, targets: PackageTargets): void;
+/**
+ * Standard migrations.d module. Every @obh package exports `pgAdapter` and
+ * `runMigrations`, so the wiring is uniform.
+ */
+export declare function migrationModule(cap: string): string;
+//# sourceMappingURL=helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/capabilities/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAI3C,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,YAAY,CAE9D;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAE5D;AAED,wEAAwE;AACxE,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAa9C,CAAA;AAED,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,0CAA0C;IAC1C,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,cAAc,GACtB,IAAI,CAMN;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWnD"}

package/dist/capabilities/helpers.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OBH_PACKAGE = void 0;
+exports.apiFramework = apiFramework;
+exports.hasNotesExample = hasNotesExample;
+exports.addPlatformPackage = addPlatformPackage;
+exports.migrationModule = migrationModule;
+const OBH_VERSION = "^0.1.0";
+/** The API framework the project chose (defaults to hono). */
+function apiFramework(ctx) {
+    return ctx.manifest?.config?.apiFramework ?? "hono";
+}
+/** Whether the project was scaffolded with the notes example domain. */
+function hasNotesExample(ctx) {
+    return ctx.manifest?.config?.example === "notes";
+}
+/** Map a capability's short name to its published @obh package name. */
+exports.OBH_PACKAGE = {
+    events: "@obh/events",
+    jobs: "@obh/jobs",
+    files: "@obh/files",
+    audit: "@obh/audit",
+    settings: "@obh/settings",
+    "api-keys": "@obh/api-keys",
+    webhooks: "@obh/webhooks",
+    "import-export": "@obh/import-export",
+    entitlements: "@obh/entitlements",
+    search: "@obh/search",
+    analytics: "@obh/analytics",
+    notifications: "@obh/notifications",
+};
+/**
+ * Add an @obh platform package to the right package.json files. It is always
+ * added to the root (so scripts/migrate.ts can resolve it) plus any requested
+ * app that actually exists.
+ */
+function addPlatformPackage(plan, ctx, cap, targets) {
+    const pkg = exports.OBH_PACKAGE[cap];
+    if (!pkg)
+        return;
+    plan.addDependency(".", pkg, OBH_VERSION);
+    if (targets.api && ctx.hasApp("api"))
+        plan.addDependency("apps/api", pkg, OBH_VERSION);
+    if (targets.worker && ctx.hasWorker())
+        plan.addDependency("apps/worker", pkg, OBH_VERSION);
+}
+/**
+ * Standard migrations.d module. Every @obh package exports `pgAdapter` and
+ * `runMigrations`, so the wiring is uniform.
+ */
+function migrationModule(cap) {
+    const pkg = exports.OBH_PACKAGE[cap];
+    return `import { pgAdapter, runMigrations } from "${pkg}"
+import type { Pool } from "pg"
+
+// Registered automatically by scripts/migrate.ts. Creates this primitive's
+// tables under the "platform" schema.
+export async function migrate(pool: Pool): Promise<void> {
+  await runMigrations(pgAdapter(pool))
+}
+`;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/capabilities/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/capabilities/helpers.ts"],"names":[],"mappings":";;;AAOA,oCAEC;AAGD,0CAEC;AA8BD,gDAWC;AAMD,0CAWC;AApED,MAAM,WAAW,GAAG,QAAQ,CAAA;AAE5B,8DAA8D;AAC9D,SAAgB,YAAY,CAAC,GAAmB;IAC9C,OAAO,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,IAAI,MAAM,CAAA;AACrD,CAAC;AAED,wEAAwE;AACxE,SAAgB,eAAe,CAAC,GAAmB;IACjD,OAAO,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,KAAK,OAAO,CAAA;AAClD,CAAC;AAED,wEAAwE;AAC3D,QAAA,WAAW,GAA2B;IACjD,MAAM,EAAE,aAAa;IACrB,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,YAAY;IACnB,KAAK,EAAE,YAAY;IACnB,QAAQ,EAAE,eAAe;IACzB,UAAU,EAAE,eAAe;IAC3B,QAAQ,EAAE,eAAe;IACzB,eAAe,EAAE,oBAAoB;IACrC,YAAY,EAAE,mBAAmB;IACjC,MAAM,EAAE,aAAa;IACrB,SAAS,EAAE,gBAAgB;IAC3B,aAAa,EAAE,oBAAoB;CACpC,CAAA;AASD;;;;GAIG;AACH,SAAgB,kBAAkB,CAChC,IAAU,EACV,GAAmB,EACnB,GAAW,EACX,OAAuB;IAEvB,MAAM,GAAG,GAAG,mBAAW,CAAC,GAAG,CAAC,CAAA;IAC5B,IAAI,CAAC,GAAG;QAAE,OAAM;IAChB,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,WAAW,CAAC,CAAA;IACzC,IAAI,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC;QAAE,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,GAAG,EAAE,WAAW,CAAC,CAAA;IACtF,IAAI,OAAO,CAAC,MAAM,IAAI,GAAG,CAAC,SAAS,EAAE;QAAE,IAAI,CAAC,aAAa,CAAC,aAAa,EAAE,GAAG,EAAE,WAAW,CAAC,CAAA;AAC5F,CAAC;AAED;;;GAGG;AACH,SAAgB,eAAe,CAAC,GAAW;IACzC,MAAM,GAAG,GAAG,mBAAW,CAAC,GAAG,CAAC,CAAA;IAC5B,OAAO,6CAA6C,GAAG;;;;;;;;CAQxD,CAAA;AACD,CAAC"}

package/dist/capabilities/import-export.d.ts

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

package/dist/capabilities/import-export.d.ts.map

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

package/dist/capabilities/import-export.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importExport = void 0;
+const helpers_1 = require("./helpers");
+exports.importExport = {
+    name: "import-export",
+    requires: ["files", "jobs"],
+    describe: "CSV import/export engine — files in/out, run as background jobs",
+    apply(ctx, plan) {
+        (0, helpers_1.addPlatformPackage)(plan, ctx, "import-export", { api: true, worker: true });
+        plan.create("scripts/migrations.d/import-export.ts", (0, helpers_1.migrationModule)("import-export"), "import-export migrations wiring");
+        // defineImport fields carry Zod schemas; the FileStore port wires to @obh/files.
+        if (ctx.hasApp("api")) {
+            plan.addDependency("apps/api", "zod", "^3.23.8");
+            plan.addDependency("apps/api", "@obh/files", "^0.1.0");
+        }
+        if (ctx.hasWorker()) {
+            plan.addDependency("apps/worker", "zod", "^3.23.8");
+            plan.addDependency("apps/worker", "@obh/files", "^0.1.0");
+        }
+        const notes = (0, helpers_1.hasNotesExample)(ctx);
+        if (ctx.hasApp("api")) {
+            plan.create("apps/api/src/platform/import-export.ts", apiPlatform(notes), "import/export registry + client");
+            plan.create("apps/api/src/routes/import-export.ts", (0, helpers_1.apiFramework)(ctx) === "hono" ? ROUTE_HONO : ROUTE_EXPRESS, "start CSV import/export routes");
+        }
+        if (ctx.hasWorker()) {
+            plan.create("apps/worker/src/consumers.d/import-export.ts", worker(notes), "import/export job worker tick");
+        }
+        plan.patchManifest({ platform: { "import-export": true } });
+        plan.nextStep("Run `pnpm migrate`. Start imports/exports via the API; the worker runs them as jobs, reading/writing CSV through the files service.");
+    },
+};
+// A FileStore port over @obh/files plus the import/export registry, shared by the
+// API client and the worker (each builds its own — the worker never imports from
+// apps/api). `pool` is passed in so this works at module scope or inside init().
+function portBuilder(notes) {
+    const imports = notes
+        ? `      defineImport({
+        type: "note",
+        fields: [
+          { key: "title", label: "Title", required: true, schema: z.string().min(1) },
+          { key: "body", label: "Body", schema: z.string().optional() },
+        ],
+        commitRow: async (_ctx, row) => {
+          // Replace with your own domain write. Must be idempotent.
+          const id = randomUUID()
+          await pool.query("insert into notes (id, title, body) values ($1, $2, $3)", [
+            id,
+            String(row.mapped.title ?? ""),
+            String(row.mapped.body ?? ""),
+          ])
+          return { entityType: "note", entityId: id }
+        },
+      }),`
+        : `      // defineImport({ type: "thing", fields: [{ key: "name", label: "Name", required: true, schema: z.string().min(1) }], commitRow: async (ctx, row) => ({ entityType: "thing", entityId: "…" }) }),`;
+    const exports = notes
+        ? `      defineExport({
+        type: "note",
+        columns: [
+          { key: "title", label: "Title" },
+          { key: "body", label: "Body" },
+        ],
+        loadRows: async () => {
+          const res = await pool.query("select title, body from notes order by created_at desc")
+          return res.rows as Array<Record<string, unknown>>
+        },
+      }),`
+        : `      // defineExport({ type: "thing", columns: [{ key: "name", label: "Name" }], loadRows: async (ctx, filters) => [] }),`;
+    return `function buildClient(pool: Pool): ImportExportClient {
+  const filesDb = filesPgAdapter(pool)
+  const filesClient = createFilesClient({
+    bucket: process.env.S3_BUCKET!,
+    storage: createS3StorageProvider({
+      endpoint: process.env.S3_ENDPOINT,
+      region: process.env.S3_REGION ?? "us-east-1",
+      accessKeyId: process.env.S3_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
+    }),
+  })
+
+  // read via a signed download URL; write by creating a file and PUTting the
+  // bytes to its signed upload URL, then confirming the upload.
+  const files: FileStore = {
+    async read({ workspaceId, fileId }) {
+      const { url } = await filesClient.createDownloadUrl(filesDb, { workspaceId, fileId })
+      const res = await fetch(url)
+      if (!res.ok) throw new Error(\`file download failed (\${res.status})\`)
+      return Buffer.from(await res.arrayBuffer())
+    },
+    async create({ workspaceId, filename, contentType, content, createdBy }) {
+      const upload = await filesClient.createUpload(filesDb, {
+        workspaceId,
+        originalName: filename,
+        contentType,
+        createdBy: createdBy ?? null,
+      })
+      const put = await fetch(upload.uploadUrl, {
+        method: "PUT",
+        headers: upload.headers,
+        body: typeof content === "string" ? content : content.toString("utf8"),
+      })
+      if (!put.ok) throw new Error(\`file upload failed (\${put.status})\`)
+      await filesClient.completeUpload(filesDb, { workspaceId, fileId: upload.fileId })
+      return { fileId: upload.fileId }
+    },
+  }
+
+  const registry = createRegistry({
+    imports: [
+${imports}
+    ],
+    exports: [
+${exports}
+    ],
+  })
+
+  return createImportExportClient({ db: pgAdapter(pool), files, registry })
+}`;
+}
+function apiPlatform(notes) {
+    return `import { createFilesClient, createS3StorageProvider, pgAdapter as filesPgAdapter } from "@obh/files"
+import {
+  createImportExportClient,
+  createRegistry,
+  defineExport,
+  defineImport,
+  pgAdapter,
+  type FileStore,
+  type ImportExportClient,
+} from "@obh/import-export"
+import { randomUUID } from "node:crypto"
+import type { Pool } from "pg"
+import { z } from "zod"
+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"
+
+${portBuilder(notes)}
+
+export const importExport = buildClient(pool)
+`;
+}
+const ROUTE_HONO = `import type { Hono } from "hono"
+import { createJobClient, pgAdapter as jobsPgAdapter } from "@obh/jobs"
+import { importExport, WORKSPACE } from "../platform/import-export"
+import { pool } from "../db"
+
+// Processing runs in the background via @obh/jobs; the worker registers the
+// handlers under these snake_case command names.
+const jobs = createJobClient({ source: "api" })
+const jobsDb = jobsPgAdapter(pool)
+
+export function register(app: Hono): void {
+  // Start an import over an already-uploaded CSV (sourceFileId from the files service).
+  app.post("/api/imports", async (c) => {
+    const body = await c.req.json<{ sourceFileId: string }>()
+    const batch = await importExport.imports.createBatch({
+      workspaceId: WORKSPACE,
+      importType: "note",
+      sourceFileId: body.sourceFileId,
+    })
+    await jobs.enqueue(jobsDb, "import_parse_csv", {
+      workspaceId: WORKSPACE,
+      payload: { workspaceId: WORKSPACE, batchId: batch.id },
+    })
+    return c.json(batch, 202)
+  })
+
+  // Start an export; the worker generates the CSV and stores it via files.
+  app.post("/api/exports", async (c) => {
+    const exp = await importExport.exports.createExport({
+      workspaceId: WORKSPACE,
+      exportType: "note",
+    })
+    await jobs.enqueue(jobsDb, "export_generate_csv", {
+      workspaceId: WORKSPACE,
+      payload: { workspaceId: WORKSPACE, exportId: exp.id },
+    })
+    return c.json(exp, 202)
+  })
+}
+`;
+const ROUTE_EXPRESS = `import type { Express, Request, Response } from "express"
+import { createJobClient, pgAdapter as jobsPgAdapter } from "@obh/jobs"
+import { importExport, WORKSPACE } from "../platform/import-export"
+import { pool } from "../db"
+
+const jobs = createJobClient({ source: "api" })
+const jobsDb = jobsPgAdapter(pool)
+
+export function register(app: Express): void {
+  app.post("/api/imports", async (req: Request, res: Response) => {
+    const batch = await importExport.imports.createBatch({
+      workspaceId: WORKSPACE,
+      importType: "note",
+      sourceFileId: req.body.sourceFileId,
+    })
+    await jobs.enqueue(jobsDb, "import_parse_csv", {
+      workspaceId: WORKSPACE,
+      payload: { workspaceId: WORKSPACE, batchId: batch.id },
+    })
+    res.status(202).json(batch)
+  })
+
+  app.post("/api/exports", async (_req: Request, res: Response) => {
+    const exp = await importExport.exports.createExport({
+      workspaceId: WORKSPACE,
+      exportType: "note",
+    })
+    await jobs.enqueue(jobsDb, "export_generate_csv", {
+      workspaceId: WORKSPACE,
+      payload: { workspaceId: WORKSPACE, exportId: exp.id },
+    })
+    res.status(202).json(exp)
+  })
+}
+`;
+function worker(notes) {
+    return `// Job-driven CSV pipeline. createImportWorker/createExportWorker expose handlers
+// keyed by the recommended (dotted) job names; we register them with @obh/jobs
+// under snake_case commands the API enqueues, then drain the queue each tick.
+import { createFilesClient, createS3StorageProvider, pgAdapter as filesPgAdapter } from "@obh/files"
+import {
+  createExportWorker,
+  createImportExportClient,
+  createImportWorker,
+  createRegistry,
+  defineExport,
+  defineImport,
+  pgAdapter,
+  type FileStore,
+  type ImportExportClient,
+} from "@obh/import-export"
+import { createJobRegistry, createWorker, defineJob, pgAdapter as jobsPgAdapter } from "@obh/jobs"
+import { randomUUID } from "node:crypto"
+import type { Pool } from "pg"
+import { z } from "zod"
+import type { WorkerContext } from "../context"
+
+let worker: ReturnType<typeof createWorker>
+
+${portBuilder(notes)}
+
+export function init(ctx: WorkerContext): void {
+  const client = buildClient(ctx.pool)
+  const imp = createImportWorker(client)
+  const exp = createExportWorker(client)
+
+  // Each qport handler validates its own payload (workspaceId + batch/export id),
+  // so the job schema stays permissive.
+  const registry = createJobRegistry([
+    defineJob({ name: "import_parse_csv", version: 1, schema: z.any(), handler: (_c, p) => imp.handlers["import.parse_csv"](p) }),
+    defineJob({ name: "import_validate_batch", version: 1, schema: z.any(), handler: (_c, p) => imp.handlers["import.validate_batch"](p) }),
+    defineJob({ name: "import_commit_batch", version: 1, schema: z.any(), handler: (_c, p) => imp.handlers["import.commit_batch"](p) }),
+    defineJob({ name: "export_generate_csv", version: 1, schema: z.any(), handler: (_c, p) => exp.handlers["export.generate_csv"](p) }),
+  ])
+
+  worker = createWorker({ db: jobsPgAdapter(ctx.pool), registry, instanceId: "worker" })
+}
+
+export async function tick(): Promise<void> {
+  await worker.tick()
+}
+`;
+}
+//# sourceMappingURL=import-export.js.map

package/dist/capabilities/import-export.js.map

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

package/dist/capabilities/index.d.ts

@@ -0,0 +1,16 @@
+import type { CapabilityName } from "../types";
+import type { Capability } from "./types";
+export type { Capability } from "./types";
+/** Every OBH platform primitive Forge can install. */
+export declare const CAPABILITIES: Partial<Record<CapabilityName, Capability>>;
+export declare function getCapability(name: CapabilityName): Capability | undefined;
+export declare function isImplemented(name: CapabilityName): boolean;
+/**
+ * Expand a requested set of capabilities to include their prerequisites, then
+ * return them in dependency order (requires-before-dependents). Unknown names
+ * are dropped by the caller after reporting.
+ */
+export declare function resolveOrder(requested: CapabilityName[]): CapabilityName[];
+/** Prerequisites of a capability that are not already installed/requested. */
+export declare function missingPrerequisites(name: CapabilityName, installed: (n: CapabilityName) => boolean): CapabilityName[];
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/capabilities/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAczC,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzC,sDAAsD;AACtD,eAAO,MAAM,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,UAAU,CAAC,CAapE,CAAA;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,UAAU,GAAG,SAAS,CAE1E;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE,CAe1E;AAED,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,cAAc,EACpB,SAAS,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,OAAO,GACxC,cAAc,EAAE,CAIlB"}