@suluk/provision 0.1.0

package/src/types.ts

@@ -0,0 +1,145 @@
+/**
+ * The Open Service Broker API, recast as a TypeScript seam (C047). Each service a Suluk app needs (a Cloudflare D1
+ * database, a KV namespace, an R2 bucket, Worker secrets, a Stripe account's products/webhooks, a custom domain, a
+ * scoped token) is a {@link Broker} — it advertises a {@link Catalog}, then `provision` / `bind` / `deprovision` a
+ * Service Instance, exactly the OSB lifecycle. The platform (this package) is the OSB *client*: it reads a declared
+ * desired-state, diffs it against live state, and walks the brokers. Brokers are PURE of the orchestration — they hold
+ * only their own provider call (e.g. @suluk/cloudflare's `provisionD1`), so the lifecycle logic can never drift per
+ * service. See `spec.md` (the OSB v2 master) for the contract these types mirror.
+ */
+
+/** OSB last-operation state for an ASYNC provision/deprovision (a database that takes seconds, a cert that takes minutes). */
+export type OperationState = "in progress" | "succeeded" | "failed";
+
+/** A plan tier within an offering (OSB Service Plan). Most infra has a single "standard" plan; `free` marks $0 tiers. */
+export interface ServicePlan {
+  id: string;
+  name: string;
+  description?: string;
+  free?: boolean;
+}
+
+/** What a broker can provision (OSB Service Offering). `bindable` = provisioning yields credentials/config to bind. */
+export interface ServiceOffering {
+  /** the stable broker id used in a config's `service`, e.g. "cloudflare-d1". */
+  id: string;
+  name: string;
+  description: string;
+  bindable: boolean;
+  plans: ServicePlan[];
+}
+
+/** The set of offerings a broker advertises (OSB Catalog). */
+export interface Catalog {
+  services: ServiceOffering[];
+}
+
+/** A declared instance the platform WANTS (the desired state — one entry in provision.config). */
+export interface InstanceSpec {
+  /** a unique handle within the config, referenced by other instances' params (e.g. "db", "kv-sessions"). */
+  ref: string;
+  /** the broker id that provisions it (must match a catalog offering's id), e.g. "cloudflare-d1". */
+  service: string;
+  /** the plan id; defaults to the offering's first plan. */
+  plan?: string;
+  /** the provider-facing name, e.g. "toolfactory-db". */
+  name: string;
+  /** provision params (broker-specific). A string value of the form `@<ref>.<key>` is a BINDING REFERENCE, resolved at
+   *  apply time from that producer instance's outputs — this is what wires the provisioning DAG. */
+  params?: Record<string, unknown>;
+  /** binding outputs → env var names: where this instance's credentials/ids LAND (the binding-chain sink). e.g.
+   *  `{ database_id: "CLOUDFLARE_D1_ID" }`. */
+  bind?: Record<string, string>;
+  /** guard a stateful resource (a database, a bucket) from destruction: `prune` + `teardown` SKIP it unless forced.
+   *  The terraform `prevent_destroy` analog — the safety rail for the resources whose loss is unrecoverable. */
+  protected?: boolean;
+}
+
+/** The live record of a provisioned instance (the journal `plan` diffs against — like drizzle's migration meta). */
+export interface InstanceState {
+  ref: string;
+  service: string;
+  plan?: string;
+  name: string;
+  /** the provider's instance id (e.g. the D1 uuid, the KV namespace id). */
+  instanceId: string;
+  /** the binding outputs captured at provision/bind time (so downstream refs resolve without re-calling the provider). */
+  outputs: Record<string, string>;
+  /** a stable fingerprint of (name + plan + params), to detect drift → an `update` step. */
+  fingerprint: string;
+  /** carried from the spec so `teardown`/`prune` (which work off the journal) honour the destroy guard. */
+  protected?: boolean;
+  provisionedAt: number;
+}
+
+/** The resolved request handed to a broker's `provision` (param refs already substituted). */
+export interface ProvisionRequest {
+  ref: string;
+  name: string;
+  plan?: string;
+  params: Record<string, unknown>;
+}
+
+/** A broker's provision outcome — sync (ready now) or async (poll `lastOperation` with `operation`). An async ack MAY
+ *  already carry `outputs` (e.g. a D1 create returns the database_id immediately even though the DB takes a moment to be
+ *  queryable); they're threaded once the op settles, alongside any from `bind`. */
+export type ProvisionResult =
+  | { state: "succeeded"; instanceId: string; outputs?: Record<string, string> }
+  | { state: "in progress"; operation: string; instanceId?: string; outputs?: Record<string, string> };
+
+/** The resolved request handed to a broker's `bind`. */
+export interface BindRequest {
+  ref: string;
+  name: string;
+  instanceId: string;
+  params: Record<string, unknown>;
+}
+
+/** A broker's bind outcome — the credentials/config the platform + downstream instances consume. */
+export interface BindResult {
+  outputs: Record<string, string>;
+}
+
+/** The request handed to `lastOperation` / `deprovision`. */
+export interface OperationRequest {
+  ref: string;
+  name: string;
+  instanceId?: string;
+  operation: string;
+}
+
+/**
+ * The OSB-shaped broker every service implements. Provision MUST be idempotent (re-running reconciles, never duplicates —
+ * OSB's "200 vs 201" rule). `lastOperation`/`bind`/`deprovision` are optional: a synchronous, non-bindable, or
+ * never-torn-down service simply omits them.
+ */
+export interface Broker {
+  /** OSB Catalog — what this broker can provision. */
+  catalog(): Catalog | Promise<Catalog>;
+  /** Provision (idempotent): create the Service Instance, or reconcile an existing one. Sync or async. */
+  provision(req: ProvisionRequest): Promise<ProvisionResult>;
+  /** Poll an async provision (OSB last-operation). Required only for brokers that return `state: "in progress"`. */
+  lastOperation?(req: OperationRequest): Promise<{ state: OperationState; description?: string }>;
+  /** Bind (OSB): generate the credentials / config the platform + downstream instances consume. Optional (non-bindable). */
+  bind?(req: BindRequest): Promise<BindResult>;
+  /** Deprovision (OSB): tear down the Service Instance. Optional — orphan mitigation, `apply --prune`, + `teardown` call it. */
+  deprovision?(req: OperationRequest): Promise<{ state: OperationState; operation?: string }>;
+  /** Fetch a Service Instance (OSB): the live state of a KNOWN instance — used by `pull` to detect EXTERNAL drift (a
+   *  resource deleted/changed in the provider's dashboard, behind the config's back). Optional; absent → "unknown". */
+  fetch?(req: OperationRequest): Promise<{ exists: boolean; outputs?: Record<string, string> }>;
+  /** Discover existing instances of this service — used by `pull --discover` to ADOPT untracked resources into the
+   *  journal. Optional; absent → discovery skipped for this service. */
+  list?(): Promise<Array<{ name: string; instanceId: string; outputs?: Record<string, string> }>>;
+}
+
+/** Where bound credentials LAND. The default sink writes the @suluk/env manifest (typed + post-quantum-encrypted +
+ *  commit-safe); a test passes an in-memory sink. `mapping` is the instance's `bind` (output key → env var name). */
+export interface BindingSink {
+  write(outputs: Record<string, string>, mapping: Record<string, string>): Promise<void> | void;
+}
+
+/** The persisted provision journal (desired-vs-live diffing). The default store is a JSON file; a test passes memory. */
+export interface StateStore {
+  load(): Promise<InstanceState[]> | InstanceState[];
+  save(state: InstanceState[]): Promise<void> | void;
+}

package/test/brokers-async.test.ts

@@ -0,0 +1,83 @@
+import { test, expect, describe } from "bun:test";
+import { cloudflareToken, cloudflarePagesDomain, apply, memoryStore, memorySink, type ProvisionConfig } from "../src/index";
+import type { CloudflareClient } from "@suluk/cloudflare";
+
+/** C047 build #4 — the scoped-token broker + the ASYNC Pages-domain broker (the OSB last-operation showcase). */
+type Call = { method: string; path: string; opts?: { json?: unknown } };
+
+/** A mock CF whose GET .../domains returns "not attached" on the FIRST call (provision's check) then the domain with a
+ *  status that flips pending → active across polls — so an `apply` actually polls the cert to "active". */
+function mockCfDomains(host: string): CloudflareClient & { calls: Call[] } {
+  const calls: Call[] = [];
+  let getDomains = 0;
+  const cf = {
+    resolveAccountId: async () => "acct1",
+    request: async (method: string, path: string, opts?: { json?: unknown }) => {
+      calls.push({ method, path, opts });
+      if (method === "GET" && path.endsWith("/domains")) {
+        getDomains++;
+        if (getDomains === 1) return []; // provision attach-check: not yet attached
+        return [{ name: host, status: getDomains >= 3 ? "active" : "pending" }]; // poll #1 pending, poll #2 active
+      }
+      return {};
+    },
+    calls,
+  };
+  return cf as unknown as CloudflareClient & { calls: Call[] };
+}
+
+function mockCfToken(): CloudflareClient & { calls: Call[] } {
+  const calls: Call[] = [];
+  const cf = {
+    resolveAccountId: async () => "acct1",
+    request: async (method: string, path: string, opts?: { json?: unknown }) => {
+      calls.push({ method, path, opts });
+      if (method === "POST" && path.endsWith("/tokens")) return { id: "tok-id", value: "tok-secret" };
+      return {};
+    },
+    calls,
+  };
+  return cf as unknown as CloudflareClient & { calls: Call[] };
+}
+
+describe("cloudflare-token (least-privilege binding)", () => {
+  test("mints a scoped token; the value rides out as the binding; deprovision revokes by id", async () => {
+    const cf = mockCfToken();
+    const broker = cloudflareToken(cf);
+    const res = await broker.provision({ ref: "d1tok", name: "app-d1-token", params: { permissionGroups: ["pg-d1-write"] } });
+    expect(res).toEqual({ state: "succeeded", instanceId: "tok-id", outputs: { token: "tok-secret", token_id: "tok-id" } });
+    const post = cf.calls.find((c) => c.method === "POST" && c.path.endsWith("/tokens"))!;
+    expect(post.opts?.json).toMatchObject({ name: "app-d1-token", policies: [{ effect: "allow", permission_groups: [{ id: "pg-d1-write" }] }] });
+    await broker.deprovision!({ ref: "d1tok", name: "app-d1-token", instanceId: "tok-id", operation: "deprovision" });
+    expect(cf.calls.at(-1)).toMatchObject({ method: "DELETE", path: "/accounts/acct1/tokens/tok-id" });
+  });
+});
+
+describe("cloudflare-pages-domain (async last-operation)", () => {
+  test("provision attaches + returns in-progress; lastOperation settles pending → active", async () => {
+    const cf = mockCfDomains("app.example.com");
+    const broker = cloudflarePagesDomain(cf);
+    const res = await broker.provision({ ref: "domain", name: "app.example.com", params: { project: "site" } });
+    expect(res).toEqual({ state: "in progress", operation: "site::app.example.com", instanceId: "site::app.example.com", outputs: { hostname: "app.example.com", url: "https://app.example.com" } });
+    expect(cf.calls.some((c) => c.method === "POST" && c.path.endsWith("/domains"))).toBe(true); // attached
+    const req = { ref: "domain", name: "app.example.com", instanceId: "site::app.example.com", operation: "site::app.example.com" };
+    expect((await broker.lastOperation!(req)).state).toBe("in progress"); // poll #1 → pending
+    expect((await broker.lastOperation!(req)).state).toBe("succeeded"); // poll #2 → active
+  });
+
+  test("apply drives the async create to done (the framework polls the cert to active)", async () => {
+    const cf = mockCfDomains("app.example.com");
+    const config: ProvisionConfig = { instances: [{ ref: "domain", service: "cloudflare-pages-domain", name: "app.example.com", params: { project: "site" }, bind: { url: "BASE_URL" } }] };
+    const store = memoryStore();
+    const sink = memorySink();
+    const res = await apply(config, { brokers: { "cloudflare-pages-domain": cloudflarePagesDomain(cf) }, store, sink, poll: { sleep: async () => {}, intervalMs: 0 } });
+    expect(res.steps[0]).toMatchObject({ ref: "domain", action: "create" });
+    expect(res.outputsByRef.domain).toEqual({ hostname: "app.example.com", url: "https://app.example.com" });
+    expect(sink.values).toEqual({ BASE_URL: "https://app.example.com" }); // the binding landed after the poll settled
+    expect(store.snapshot()[0].instanceId).toBe("site::app.example.com");
+  });
+
+  test("provision needs a params.project", async () => {
+    await expect(cloudflarePagesDomain(mockCfDomains("h")).provision({ ref: "d", name: "h", params: {} })).rejects.toThrow(/needs a params.project/);
+  });
+});

package/test/brokers.test.ts

@@ -0,0 +1,93 @@
+import { test, expect, describe } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cloudflareD1, cloudflareKv, cloudflareR2, cloudflareSecrets, envSink, fileStore, type InstanceState } from "../src/index";
+import type { CloudflareClient } from "@suluk/cloudflare";
+
+/**
+ * C047 build #2 — the Cloudflare brokers (over a MOCK CloudflareClient: we assert each maps its provisioner onto a
+ * binding output + hits the right delete), the @suluk/env sink (a temp .env), and the file-backed journal (a temp file).
+ */
+type Call = { method: string; path: string; opts?: { json?: unknown } };
+function mockCf(): CloudflareClient & { calls: Call[] } {
+  const calls: Call[] = [];
+  const handler = (method: string, path: string): unknown => {
+    if (method === "GET" && path.includes("/d1/database")) return [];
+    if (method === "POST" && path.includes("/d1/database")) return { uuid: "db-uuid", name: "app-db" };
+    if (method === "GET" && path.includes("/storage/kv/namespaces")) return [];
+    if (method === "POST" && path.includes("/storage/kv/namespaces")) return { id: "kv-id", title: "sessions" };
+    if (method === "GET" && path.includes("/r2/buckets")) return { buckets: [] };
+    if (method === "POST" && path.includes("/r2/buckets")) return { name: "media" };
+    return {};
+  };
+  const cf = {
+    resolveAccountId: async () => "acct1",
+    request: async (method: string, path: string, opts?: { json?: unknown }) => {
+      calls.push({ method, path, opts });
+      return handler(method, path);
+    },
+    calls,
+  };
+  return cf as unknown as CloudflareClient & { calls: Call[] };
+}
+
+describe("the Cloudflare brokers", () => {
+  test("cloudflare-d1: create-or-get → database_id; deprovision deletes by id", async () => {
+    const cf = mockCf();
+    const broker = cloudflareD1(cf);
+    expect((await broker.catalog()).services[0].id).toBe("cloudflare-d1");
+    const res = await broker.provision({ ref: "db", name: "app-db", params: {} });
+    expect(res).toEqual({ state: "succeeded", instanceId: "db-uuid", outputs: { database_id: "db-uuid" } });
+    await broker.deprovision!({ ref: "db", name: "app-db", instanceId: "db-uuid", operation: "deprovision" });
+    expect(cf.calls.at(-1)).toMatchObject({ method: "DELETE", path: "/accounts/acct1/d1/database/db-uuid" });
+  });
+
+  test("cloudflare-kv → namespace_id; cloudflare-r2 → bucket_name", async () => {
+    const kv = await cloudflareKv(mockCf()).provision({ ref: "kv", name: "sessions", params: {} });
+    expect(kv).toEqual({ state: "succeeded", instanceId: "kv-id", outputs: { namespace_id: "kv-id" } });
+    const r2 = await cloudflareR2(mockCf()).provision({ ref: "media", name: "media", params: {} });
+    expect(r2).toEqual({ state: "succeeded", instanceId: "media", outputs: { bucket_name: "media" } });
+  });
+
+  test("cloudflare-secrets: pushes the resolved secret set (skips empty), reports the names; needs a script", async () => {
+    const cf = mockCf();
+    const broker = cloudflareSecrets(cf);
+    const res = await broker.provision({ ref: "secrets", name: "worker-secrets", params: { script: "toolfactory-api", secrets: { A: "1", B: "2", C: undefined } } });
+    expect(res.outputs).toEqual({ secrets_set: "A,B" }); // C skipped (empty)
+    const puts = cf.calls.filter((c) => c.method === "PUT" && c.path.includes("/secrets"));
+    expect(puts.length).toBe(2);
+    expect(puts[0].opts?.json).toMatchObject({ name: "A", text: "1", type: "secret_text" });
+    await expect(broker.provision({ ref: "secrets", name: "s", params: { secrets: {} } })).rejects.toThrow(/needs a params.script/);
+  });
+});
+
+describe("the @suluk/env sink", () => {
+  test("lands each (output → env var) into a .env (plaintext here for the witness)", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "prov-env-"));
+    const envPath = join(dir, ".env");
+    const sink = envSink({ envPath, plain: () => true });
+    await sink.write(
+      { database_id: "db-uuid", token: "tok-secret", unused: "x" },
+      { database_id: "CLOUDFLARE_D1_ID", token: "CLOUDFLARE_D1_TOKEN" },
+    );
+    const content = await readFile(envPath, "utf8");
+    expect(content).toContain('CLOUDFLARE_D1_ID="db-uuid"');
+    expect(content).toContain('CLOUDFLARE_D1_TOKEN="tok-secret"');
+    expect(content).not.toContain("unused"); // only mapped outputs are written
+  });
+});
+
+describe("the file-backed journal", () => {
+  test("a missing file reads as empty; save then load round-trips", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "prov-store-"));
+    const store = fileStore(join(dir, "sub", "provision.json")); // nested → mkdir -p
+    expect(await store.load()).toEqual([]);
+    const state: InstanceState[] = [
+      { ref: "db", service: "cloudflare-d1", name: "app-db", instanceId: "db-uuid", outputs: { database_id: "db-uuid" }, fingerprint: "fp", provisionedAt: 1 },
+    ];
+    await store.save(state);
+    expect(await store.load()).toEqual(state);
+  });
+});

package/test/careful.test.ts

@@ -0,0 +1,152 @@
+import { test, expect, describe } from "bun:test";
+import {
+  pull, reconcile, discover, teardown, plan, apply, runCli, defineProvisionApp,
+  memoryStore, memorySink, type Broker, type InstanceSpec, type InstanceState, type ProvisionConfig,
+} from "../src/index";
+
+/** C047 build #5 — the careful features: `pull` (external-drift introspection), `teardown` (guarded destruction), and
+ *  the `protected` rail. */
+const st = (ref: string, service: string, outputs: Record<string, string>, extra: Partial<InstanceState> = {}): InstanceState => ({
+  ref, service, name: `${ref}-name`, instanceId: `${service}:${ref}`, outputs, fingerprint: "fp", provisionedAt: 1, ...extra,
+});
+
+function broker(id: string, impl: Partial<Broker> = {}): Broker {
+  return {
+    catalog: () => ({ services: [{ id, name: id, description: id, bindable: false, plans: [{ id: "standard", name: "S" }] }] }),
+    async provision(req) {
+      return { state: "succeeded", instanceId: `${id}:${req.name}`, outputs: {} };
+    },
+    async deprovision() {
+      return { state: "succeeded" };
+    },
+    ...impl,
+  };
+}
+
+describe("pull — external drift (journal vs provider)", () => {
+  test("classifies live / missing / drifted / unknown, and reconcile folds it back", async () => {
+    const state = [st("db", "d1", { database_id: "x" }), st("gone", "d1", { database_id: "y" }), st("moved", "d1", { database_id: "z" }), st("opaque", "mystery", { k: "v" })];
+    const brokers = {
+      d1: broker("d1", {
+        async fetch(req) {
+          if (req.ref === "gone") return { exists: false }; // deleted in the dashboard
+          if (req.ref === "moved") return { exists: true, outputs: { database_id: "z-NEW" } }; // id changed
+          return { exists: true, outputs: { database_id: "x" } }; // db: matches
+        },
+      }),
+      mystery: broker("mystery"), // no fetch → unknown
+    };
+    const report = await pull(state, brokers);
+    expect(report.entries.map((e) => `${e.ref}:${e.status}`)).toEqual(["db:live", "gone:missing", "moved:drifted", "opaque:unknown"]);
+    expect(report.clean).toBe(false);
+    expect(report.missing).toEqual(["gone"]);
+    expect(report.drifted).toEqual(["moved"]);
+
+    const fixed = reconcile(state, report);
+    expect(fixed.map((s) => s.ref)).toEqual(["db", "moved", "opaque"]); // "gone" dropped → next apply re-creates
+    expect(fixed.find((s) => s.ref === "moved")?.outputs).toEqual({ database_id: "z-NEW" }); // drifted output updated
+  });
+
+  test("discover finds live resources the journal doesn't track", async () => {
+    const state = [st("db", "d1", { database_id: "known" })];
+    const brokers = {
+      d1: broker("d1", {
+        async list() {
+          return [
+            { name: "app-db", instanceId: "d1:db", outputs: { database_id: "known" } }, // already tracked
+            { name: "stray-db", instanceId: "d1:stray", outputs: { database_id: "stray" } }, // untracked
+          ];
+        },
+      }),
+    };
+    expect(await discover(state, brokers)).toEqual([{ service: "d1", name: "stray-db", instanceId: "d1:stray", outputs: { database_id: "stray" } }]);
+  });
+});
+
+describe("teardown — guarded destruction", () => {
+  const twoInstances = [st("db", "d1", {}), st("token", "tok", {})]; // journal order = provision order
+  const recording = () => {
+    const order: string[] = [];
+    const rec = (req: { ref: string }) => {
+      order.push(req.ref);
+      return Promise.resolve({ state: "succeeded" as const });
+    };
+    return { order, brokers: { d1: broker("d1", { deprovision: rec }), tok: broker("tok", { deprovision: rec }) } };
+  };
+
+  test("tears down CONSUMERS-FIRST (reverse journal order) and empties the journal", async () => {
+    const { order, brokers } = recording();
+    const store = memoryStore(twoInstances);
+    const res = await teardown({ brokers, store });
+    expect(order).toEqual(["token", "db"]); // reverse of [db, token]
+    expect(res.torn).toEqual(["token", "db"]);
+    expect(store.snapshot()).toEqual([]);
+  });
+
+  test("dry run previews without calling any provider or saving", async () => {
+    const { order, brokers } = recording();
+    const store = memoryStore(twoInstances);
+    const res = await teardown({ brokers, store, dryRun: true });
+    expect(order).toEqual([]); // no provider touched
+    expect(res.torn).toEqual(["token", "db"]); // what WOULD go
+    expect(store.snapshot().length).toBe(2); // journal untouched
+  });
+
+  test("a PROTECTED instance is kept unless --force", async () => {
+    const withProtected = [st("db", "d1", {}, { protected: true }), st("token", "tok", {})];
+    const r1 = recording();
+    const store1 = memoryStore(withProtected);
+    const kept = await teardown({ brokers: r1.brokers, store: store1 });
+    expect(r1.order).toEqual(["token"]); // db (protected) skipped
+    expect(kept.kept).toEqual([{ ref: "db", reason: "protected" }]);
+    expect(store1.snapshot().map((s) => s.ref)).toEqual(["db"]); // protected survives
+
+    const r2 = recording();
+    const store2 = memoryStore(withProtected);
+    await teardown({ brokers: r2.brokers, store: store2, force: true });
+    expect(r2.order).toEqual(["token", "db"]); // force destroys the protected one too
+    expect(store2.snapshot()).toEqual([]);
+  });
+});
+
+describe("protected in plan/prune", () => {
+  test("a protected orphan is kept (not deprovisioned) under --prune, and doesn't count as drift", () => {
+    const config: ProvisionConfig = { instances: [] }; // everything is an orphan
+    const state = [st("db", "d1", {}, { protected: true }), st("cache", "kv", {})];
+    const p = plan(config, state, true);
+    expect(p.steps.find((s) => s.ref === "db")?.action).toBe("noop"); // protected → kept
+    expect(p.steps.find((s) => s.ref === "cache")?.action).toBe("deprovision"); // unprotected orphan → gone
+    expect(p.clean).toBe(false); // the unprotected orphan is still pending work
+  });
+});
+
+describe("the CLI — pull + teardown gates", () => {
+  const instances: InstanceSpec[] = [{ ref: "db", service: "mock", name: "app-db", protected: true }, { ref: "kv", service: "mock", name: "sessions" }];
+  const mkBrokers = () => ({ mock: broker("mock", { async provision(req) { return { state: "succeeded", instanceId: `mock:${req.name}`, outputs: { id: req.name } }; } }) });
+  const appWith = (store: ReturnType<typeof memoryStore>) => defineProvisionApp({ config: { instances }, brokers: mkBrokers(), store, sink: memorySink() });
+
+  test("`teardown` without --yes is a DRY RUN; `teardown --yes` destroys (protected needs --force)", async () => {
+    const store = memoryStore();
+    await runCli(appWith(store), ["apply"]); // seed the journal (db is protected)
+
+    const dry = await runCli(appWith(store), ["teardown"]);
+    expect(dry.output).toContain("DRY RUN");
+    expect(store.snapshot().length).toBe(2); // nothing destroyed
+
+    const yes = await runCli(appWith(store), ["teardown", "--yes"]);
+    expect(yes.output).toContain("torn down");
+    expect(store.snapshot().map((s) => s.ref)).toEqual(["db"]); // kv gone, db (protected) survives
+
+    await runCli(appWith(store), ["teardown", "--yes", "--force"]);
+    expect(store.snapshot()).toEqual([]); // --force destroys the protected db too
+  });
+
+  test("`pull` reports a clean journal after apply", async () => {
+    const store = memoryStore();
+    const brokers = { mock: broker("mock", { async provision(req) { return { state: "succeeded", instanceId: `mock:${req.name}`, outputs: {} }; }, async fetch() { return { exists: true }; } }) };
+    const app = defineProvisionApp({ config: { instances }, brokers, store, sink: memorySink() });
+    await runCli(app, ["apply"]);
+    const r = await runCli(app, ["pull"]);
+    expect(r.output).toContain("journal matches the provider");
+  });
+});

package/test/cli.test.ts

@@ -0,0 +1,75 @@
+import { test, expect, describe } from "bun:test";
+import { runCli, defineProvisionApp, memoryStore, memorySink, type Broker, type InstanceSpec, type ProvisionConfig, type StateStore } from "../src/index";
+
+/** C047 build #3 — the drizzle-kit-style CLI (plan / apply / check / status), witnessed via runCli (process-pure). */
+function sync(id: string, out: (name: string) => Record<string, string>): Broker {
+  return {
+    catalog: () => ({ services: [{ id, name: id, description: id, bindable: false, plans: [{ id: "standard", name: "Standard" }] }] }),
+    async provision(req) {
+      return { state: "succeeded", instanceId: `${id}:${req.name}`, outputs: out(req.name) };
+    },
+    async deprovision() {
+      return { state: "succeeded" };
+    },
+  };
+}
+const brokers = {
+  "mock-d1": sync("mock-d1", () => ({ database_id: "db-uuid" })),
+  "mock-kv": sync("mock-kv", () => ({ namespace_id: "kv-id" })),
+};
+const baseInstances: InstanceSpec[] = [
+  { ref: "db", service: "mock-d1", name: "app-db", bind: { database_id: "DB_ID" } },
+  { ref: "kv", service: "mock-kv", name: "sessions", bind: { namespace_id: "KV_ID" } },
+];
+const appWith = (config: ProvisionConfig, store: StateStore) => defineProvisionApp({ config, brokers, store, sink: memorySink() });
+
+describe("the provision CLI", () => {
+  test("plan on a fresh project lists creates", async () => {
+    const r = await runCli(appWith({ instances: baseInstances }, memoryStore()), ["plan"]);
+    expect(r.exitCode).toBe(0);
+    expect(r.output).toContain("+ create");
+    expect(r.output).toContain("plan: 2 create");
+  });
+
+  test("apply → check is clean → plan is in sync (the drizzle-kit loop)", async () => {
+    const store = memoryStore();
+    const apply = await runCli(appWith({ instances: baseInstances }, store), ["apply"]);
+    expect(apply.exitCode).toBe(0);
+    expect(apply.output).toContain("✓ applied:");
+
+    const check = await runCli(appWith({ instances: baseInstances }, store), ["check"]);
+    expect(check.exitCode).toBe(0);
+    expect(check.output).toContain("no drift");
+
+    const plan = await runCli(appWith({ instances: baseInstances }, store), ["plan"]);
+    expect(plan.output).toContain("✓ in sync");
+  });
+
+  test("check FAILS (exit 1) when the config drifts from the journal — the CI gate", async () => {
+    const store = memoryStore();
+    await runCli(appWith({ instances: baseInstances }, store), ["apply"]);
+    const drifted = baseInstances.map((i) => (i.ref === "kv" ? { ...i, name: "sessions-v2" } : i));
+    const r = await runCli(appWith({ instances: drifted }, store), ["check"]);
+    expect(r.exitCode).toBe(1);
+    expect(r.output).toContain("drift detected");
+    expect(r.output).toContain("kv");
+  });
+
+  test("status lists the provisioned instances + their bound outputs", async () => {
+    const store = memoryStore();
+    await runCli(appWith({ instances: baseInstances }, store), ["apply"]);
+    const r = await runCli(appWith({ instances: baseInstances }, store), ["status"]);
+    expect(r.output).toContain("db (mock-d1 · app-db) → database_id=db-uuid");
+    expect(r.output).toContain("kv (mock-kv · sessions) → namespace_id=kv-id");
+  });
+
+  test("apply --prune deprovisions an orphan; an unknown command exits 2", async () => {
+    const store = memoryStore();
+    await runCli(appWith({ instances: baseInstances }, store), ["apply"]);
+    const pruned = await runCli(appWith({ instances: baseInstances.filter((i) => i.ref === "db") }, store), ["apply", "--prune"]);
+    expect(pruned.output).toContain("-kv");
+
+    const bad = await runCli(appWith({ instances: baseInstances }, store), ["frobnicate"]);
+    expect(bad.exitCode).toBe(2);
+  });
+});