@saacms/cli 0.1.0

package/README.md

@@ -0,0 +1,23 @@
+# @saacms/cli
+
+The `saacms` binary. A thin orchestrator over codegen, migrations, publish, log fetching, and environment health checks. Per ADR 0011, it is **not** a server — the host framework's own dev command runs the show.
+
+## Surface
+
+- `saacms init` — bootstrap saacms into an existing host project (v1 alpha: Astro only).
+- `saacms codegen [--watch]` — Effect Schema → Drizzle / OpenAPI / TS-types / Puck-fields projections.
+- `saacms dev` — sugar that runs the host's `dev` script alongside `saacms codegen --watch`.
+- `saacms migrate generate | run | check` — DB and content migrations.
+- `saacms publish` — commit drafts + generated routes to the developer's Git repo.
+- `saacms logs <deploy-id>` — fetch deploy/runtime logs.
+- `saacms doctor` — environment health report.
+
+## Reading order (relevant ADRs)
+
+- [0011 — Dev workflow: piggyback the host's dev server](../../docs/adr/0011-dev-workflow.md)
+- [0012 — Migrations: schema (DB) and content (Page JSON)](../../docs/adr/0012-migrations-schema-and-content.md)
+- [0024 — v1 alpha scope: Astro + Cloudflare Pages + D1 + R2](../../docs/adr/0024-v1-alpha-scope-astro-cloudflare.md)
+
+## Status
+
+Scaffold. Sub-commands are wired through citty; handlers print what they would do and reference the relevant ADR. No real work is performed yet.

package/dist/commands/codegen.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `saacms codegen` — Effect Schema -> Drizzle / OpenAPI / TS-types / Puck-fields
+ * projections. Output goes to `.saacms/` (gitignored). Per ADR 0005 + 0011.
+ *
+ * Reads the user's `saacms.config.ts` (default export from `defineConfig`) and
+ * emits four artefacts per Collection plus one aggregate OpenAPI document. The
+ * generators live in `@saacms/core`; this command composes them and handles I/O.
+ *
+ * Per-Collection errors are isolated: if one Collection's Schema can't project,
+ * we log the error, set `process.exitCode = 1`, and continue with the next.
+ */
+export declare const codegenCommand: import("citty").CommandDef<{
+    cwd: {
+        type: "string";
+        description: string;
+        required: false;
+    };
+    out: {
+        type: "string";
+        description: string;
+        required: false;
+    };
+    watch: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+}>;
+//# sourceMappingURL=codegen.d.ts.map

package/dist/commands/codegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/commands/codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA8KH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;EAmEzB,CAAA"}

package/dist/commands/codegen.js

@@ -0,0 +1,24 @@
+/**
+ * `saacms codegen` — Effect Schema -> Drizzle / OpenAPI / TS-types / Puck-fields
+ * projections. Output goes to `.saacms/` (gitignored). Per ADR 0005 + 0011.
+ *
+ * Scaffold only. The generators live in `@saacms/core` and are tracked in
+ * ADR 0005; this command will compose them once they land.
+ */
+import { defineCommand } from "citty";
+export const codegenCommand = defineCommand({
+    meta: {
+        name: "codegen",
+        description: "Run Schema -> Drizzle / OpenAPI / TS-types / Puck-fields projections (writes to .saacms/).",
+    },
+    args: {
+        watch: {
+            type: "boolean",
+            description: "Re-run on changes to saacms/**/*.ts.",
+            default: false,
+        },
+    },
+    run({ args }) {
+        console.log(`saacms codegen — watch=${args.watch ? "on" : "off"} — not implemented; tracking ADR 0005.`);
+    },
+});

package/dist/commands/dev.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `saacms dev` — DX sugar that runs the host framework's own dev command in
+ * parallel with `saacms codegen --watch`. Per ADR 0011, saacms is **not** a
+ * server; the host's normal dev command serves /admin and /api/saacms/* by
+ * virtue of saacms's runtime handler being mounted into the host's routing.
+ *
+ * Supervision contract (v0.1):
+ *   - Both children inherit the parent's stdio by default.
+ *   - SIGINT / SIGTERM on the parent → forward to both children, then wait
+ *     for them to exit, then exit with the host-dev's exit code.
+ *   - If host-dev exits before any signal → kill the codegen watcher, exit
+ *     with host-dev's code.
+ *   - If the codegen watcher exits non-zero while host-dev is still running,
+ *     warn but do NOT kill host-dev (codegen failures are non-fatal during
+ *     dev iteration).
+ *
+ * The body is factored into `startDev()` so tests (and future programmatic
+ * callers) can drive it without going through citty / process.exit.
+ *
+ * NOTE on signal-forwarding: SIGINT/SIGTERM end-to-end behaviour is awkward
+ * to assert in-process (you'd kill the test runner). It is documented here
+ * and left as a manual integration test. TODO: figure out a hermetic harness.
+ */
+export type DevStdio = "inherit" | "pipe";
+export interface StartDevOptions {
+    cwd?: string;
+    noCodegen?: boolean;
+    /** "inherit" (default) hands stdout/stderr straight to the parent's tty.
+     *  "pipe" captures both streams and returns the concatenated text on the
+     *  result — used by the test suite. */
+    stdio?: DevStdio;
+}
+export interface DevResult {
+    hostExitCode: number;
+    codegenExitCode: number | null;
+    hostStdout: string;
+    hostStderr: string;
+    codegenStdout: string;
+    codegenStderr: string;
+}
+export declare function startDev(opts?: StartDevOptions): Promise<DevResult>;
+export declare const devCommand: import("citty").CommandDef<{
+    cwd: {
+        type: "string";
+        description: string;
+        required: false;
+    };
+    "no-codegen": {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+}>;
+//# sourceMappingURL=dev.d.ts.map

package/dist/commands/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA6EH,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAA;AAEzC,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;2CAEuC;IACvC,KAAK,CAAC,EAAE,QAAQ,CAAA;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAA;IACpB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;CACtB;AAOD,wBAAsB,QAAQ,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,SAAS,CAAC,CA0H7E;AAED,eAAO,MAAM,UAAU;;;;;;;;;;;EAwBrB,CAAA"}

package/dist/commands/dev.js

@@ -0,0 +1,26 @@
+/**
+ * `saacms dev` — DX sugar that runs the host framework's own dev command in
+ * parallel with `saacms codegen --watch`. Per ADR 0011, saacms is **not** a
+ * server; the host's normal dev command serves /admin and /api/saacms/* by
+ * virtue of saacms's runtime handler being mounted into the host's routing.
+ *
+ * Scaffold only — concurrent process orchestration lands later.
+ */
+import { defineCommand } from "citty";
+export const devCommand = defineCommand({
+    meta: {
+        name: "dev",
+        description: "Run the host's dev command alongside `saacms codegen --watch` (DX sugar; not a server).",
+    },
+    args: {
+        cwd: {
+            type: "string",
+            description: "Working directory. Defaults to process.cwd().",
+            required: false,
+        },
+    },
+    run({ args: _args }) {
+        console.log("saacms dev launches the host's dev command + `saacms codegen --watch` (not implemented yet).");
+        console.log("Per ADR 0011: saacms is not a server. The host serves /admin and /api/saacms/*.");
+    },
+});

package/dist/commands/doctor.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `saacms doctor` — environment health report. Checks that the user's
+ * project has every binding, tool, and adapter saacms expects to find,
+ * and reports each in the "What / Why / Fix / Learn more" format mandated
+ * by ADR 0022 ("Errors with fix-link").
+ *
+ * The check ordering is contractual: cheap/foundational checks first
+ * (runtime, package.json) so later checks (host, peers, storage) can
+ * assume their preconditions were already surfaced to the user.
+ */
+type CheckStatus = "pass" | "info" | "warn" | "fail";
+export interface CheckResult {
+    readonly name: string;
+    readonly status: CheckStatus;
+    readonly message: string;
+    readonly why?: string;
+    readonly fix?: string;
+    readonly learn?: string;
+}
+interface Summary {
+    pass: number;
+    info: number;
+    warn: number;
+    fail: number;
+}
+/**
+ * Parse a `major.minor.patch` string (ignoring any pre-release/build suffix)
+ * into a numeric triple. Non-numeric segments collapse to 0 so a garbage
+ * version is treated as "ancient" and fails the check loudly rather than
+ * silently passing.
+ */
+export declare function parseSemver(version: string): [number, number, number];
+/** True iff `version` is >= `MIN_BUN` under semver ordering. */
+export declare function isBunVersionOk(version: string): boolean;
+/**
+ * Run the full ordered checklist against `cwd`. Pure: returns results, never
+ * touches stdout or `process.exitCode` (the command wrapper does that). This
+ * makes the checklist directly unit-testable.
+ */
+export declare function runChecks(cwd: string): CheckResult[];
+export declare function summarize(results: readonly CheckResult[]): Summary;
+export declare const doctorCommand: import("citty").CommandDef<{
+    cwd: {
+        type: "string";
+        description: string;
+        required: false;
+    };
+    json: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+}>;
+export {};
+//# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAUH,KAAK,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;AAEpD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,UAAU,OAAO;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb;AA0ED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAOrE;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CASvD;AAID;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,EAAE,CAiKpD;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,CAIlE;AAmBD,eAAO,MAAM,aAAa;;;;;;;;;;;EA+BxB,CAAA"}

package/dist/commands/doctor.js

@@ -0,0 +1,25 @@
+/**
+ * `saacms doctor` — environment health report. Checks that the user's
+ * project has every binding, credential, and tool saacms expects to find,
+ * and reports each in the "What / Why / Fix / Learn more" format mandated
+ * by ADR 0022 ("Errors with fix-link").
+ *
+ * Scaffold only.
+ */
+import { defineCommand } from "citty";
+export const doctorCommand = defineCommand({
+    meta: {
+        name: "doctor",
+        description: "Report environment health: bindings, credentials, host adapter, storage adapter, runtime version.",
+    },
+    args: {
+        json: {
+            type: "boolean",
+            description: "Emit machine-readable JSON instead of the human-readable report.",
+            default: false,
+        },
+    },
+    run({ args }) {
+        console.log(`saacms doctor${args.json ? " --json" : ""} — would report environment health (bindings, credentials, host + storage adapter wiring).`);
+    },
+});

package/dist/commands/init.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `saacms init` — bootstrap saacms into an existing host-framework project.
+ *
+ * Per ADR 0024, v1 alpha only recognises **Astro** as a host. Other hosts
+ * (Next.js, SvelteKit, Nuxt) are deferred to v1.x. The handler detects the
+ * host by inspecting `package.json` and framework-specific config files in
+ * the current working directory.
+ *
+ * Two modes:
+ *   - `--dry-run`            : log the intended actions (the v0.1 behaviour).
+ *   - default (no --dry-run) : actually scaffold the project on disk.
+ */
+export declare const initCommand: import("citty").CommandDef<{
+    host: {
+        type: "string";
+        description: string;
+        required: false;
+    };
+    storage: {
+        type: "string";
+        description: string;
+        default: string;
+    };
+    cwd: {
+        type: "string";
+        description: string;
+        required: false;
+    };
+    "dry-run": {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+}>;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA6HH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;EA0HtB,CAAA"}

package/dist/commands/init.js

@@ -0,0 +1,106 @@
+/**
+ * `saacms init` — bootstrap saacms into an existing host-framework project.
+ *
+ * Per ADR 0024, v1 alpha only recognises **Astro** as a host. Other hosts
+ * (Next.js, SvelteKit, Nuxt) are deferred to v1.x. The handler detects the
+ * host by inspecting `package.json` and framework-specific config files in
+ * the current working directory.
+ *
+ * This is a scaffold: it logs what it *would* do rather than touching the
+ * filesystem. Real init lands alongside `@saacms/host-astro`.
+ */
+import { defineCommand } from "citty";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const ASTRO_CONFIG_FILES = [
+    "astro.config.ts",
+    "astro.config.mjs",
+    "astro.config.js",
+    "astro.config.cjs",
+];
+const NEXTJS_CONFIG_FILES = [
+    "next.config.ts",
+    "next.config.mjs",
+    "next.config.js",
+];
+const SVELTEKIT_CONFIG_FILES = ["svelte.config.js", "svelte.config.ts"];
+const NUXT_CONFIG_FILES = ["nuxt.config.ts", "nuxt.config.js"];
+function readPackageJson(cwd) {
+    const path = join(cwd, "package.json");
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function hasDep(pkg, name) {
+    if (!pkg)
+        return false;
+    return Boolean(pkg.dependencies?.[name] ??
+        pkg.devDependencies?.[name] ??
+        pkg.peerDependencies?.[name]);
+}
+function hasAnyFile(cwd, files) {
+    return files.some((file) => existsSync(join(cwd, file)));
+}
+function detectHost(cwd) {
+    const pkg = readPackageJson(cwd);
+    if (hasAnyFile(cwd, ASTRO_CONFIG_FILES) || hasDep(pkg, "astro"))
+        return "astro";
+    if (hasAnyFile(cwd, NEXTJS_CONFIG_FILES) || hasDep(pkg, "next"))
+        return "nextjs";
+    if (hasAnyFile(cwd, SVELTEKIT_CONFIG_FILES) || hasDep(pkg, "@sveltejs/kit"))
+        return "sveltekit";
+    if (hasAnyFile(cwd, NUXT_CONFIG_FILES) || hasDep(pkg, "nuxt"))
+        return "nuxt";
+    return "unknown";
+}
+export const initCommand = defineCommand({
+    meta: {
+        name: "init",
+        description: "Bootstrap saacms into an existing host-framework project (v1 alpha: Astro only).",
+    },
+    args: {
+        host: {
+            type: "string",
+            description: "Host framework to scaffold for. Defaults to auto-detection from package.json + config files. v1 alpha only accepts 'astro'.",
+            required: false,
+        },
+        storage: {
+            type: "string",
+            description: "Storage adapter to wire into saacms.config.ts. v1 alpha defaults to 'r2' (Cloudflare R2).",
+            default: "r2",
+        },
+        cwd: {
+            type: "string",
+            description: "Working directory to scaffold into. Defaults to process.cwd().",
+            required: false,
+        },
+    },
+    run({ args }) {
+        const cwd = args.cwd ?? process.cwd();
+        const host = args.host ?? detectHost(cwd);
+        const storage = args.storage;
+        console.log(`saacms init — target dir: ${cwd}`);
+        console.log(`detected host: ${host}`);
+        console.log(`storage adapter: ${storage}`);
+        if (host !== "astro") {
+            throw new Error(`init for host '${host}' not supported in v1 alpha. ` +
+                "Per ADR 0024, v1 alpha only ships @saacms/host-astro. " +
+                "Other hosts (Next.js, SvelteKit, Nuxt) are deferred to v1.x. " +
+                "If this is an Astro project, pass --host=astro explicitly.");
+        }
+        console.log("would create: saacms.config.ts (root)");
+        console.log("would create: saacms/collections/.gitkeep");
+        console.log("would create: saacms/blocks/.gitkeep");
+        console.log("would create: saacms/pages/.gitkeep");
+        console.log("would create: src/pages/api/saacms/[...slug].ts (mount point)");
+        console.log("would create: src/pages/admin/[...slug].astro (admin mount)");
+        console.log("would add: predeploy script -> 'saacms migrate check --strict'");
+        console.log(`would install peer deps: @saacms/core @saacms/host-astro @saacms/storage-${storage}`);
+        console.log("scaffold only — no filesystem changes performed yet.");
+    },
+});

package/dist/commands/logs.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `saacms logs <deploy-id>` — fetch build / runtime logs for a given deploy.
+ * Per ADR 0024, v1 alpha targets Cloudflare Pages, so logs are pulled via
+ * the Cloudflare API. The deploy-log reader subsystem inside the runtime
+ * also surfaces these into the admin UI.
+ *
+ * The Cloudflare transport is injected (`LogsDeps.fetchFn`) so the whole
+ * command is unit-testable against canned `Response` objects with no real
+ * network. `runLogs` is pure w.r.t. process state: it returns the intended
+ * exit code and the citty `run()` wrapper applies it to `process.exitCode`.
+ */
+export interface LogsArgs {
+    readonly deployId: string;
+    readonly follow?: boolean;
+    readonly project?: string;
+    readonly account?: string;
+    readonly token?: string;
+}
+export interface LogsDeps {
+    readonly fetchFn?: typeof fetch;
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Fetch (and optionally follow) the logs for a Cloudflare Pages deployment.
+ * Returns the intended process exit code (0 success, 1 failure/canceled).
+ */
+export declare function runLogs(args: LogsArgs, deps?: LogsDeps): Promise<number>;
+export declare const logsCommand: import("citty").CommandDef<{
+    deployId: {
+        type: "positional";
+        description: string;
+        required: true;
+    };
+    follow: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+    project: {
+        type: "string";
+        description: string;
+        required: false;
+    };
+    account: {
+        type: "string";
+        description: string;
+        required: false;
+    };
+    token: {
+        type: "string";
+        description: string;
+        required: false;
+    };
+}>;
+//# sourceMappingURL=logs.d.ts.map

package/dist/commands/logs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs.d.ts","sourceRoot":"","sources":["../../src/commands/logs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAuCH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAA;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/C;AA2ED;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,QAAQ,EACd,IAAI,GAAE,QAAa,GAClB,OAAO,CAAC,MAAM,CAAC,CA8CjB;AAED,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;EAyCtB,CAAA"}

package/dist/commands/logs.js

@@ -0,0 +1,30 @@
+/**
+ * `saacms logs <deploy-id>` — fetch build / runtime logs for a given deploy.
+ * Per ADR 0024, v1 alpha targets Cloudflare Pages, so logs are pulled via
+ * the Cloudflare API. The deploy-log reader subsystem inside the runtime
+ * also surfaces these into the admin UI.
+ *
+ * Scaffold only.
+ */
+import { defineCommand } from "citty";
+export const logsCommand = defineCommand({
+    meta: {
+        name: "logs",
+        description: "Fetch build + runtime logs for a deploy (v1 alpha: Cloudflare Pages).",
+    },
+    args: {
+        deployId: {
+            type: "positional",
+            description: "Deploy identifier as reported by Cloudflare Pages.",
+            required: true,
+        },
+        follow: {
+            type: "boolean",
+            description: "Stream logs (tail mode) instead of one-shot fetch.",
+            default: false,
+        },
+    },
+    run({ args }) {
+        console.log(`saacms logs ${args.deployId}${args.follow ? " --follow" : ""} — would call the Cloudflare API and stream deploy logs (ADR 0024).`);
+    },
+});

package/dist/commands/migrate.d.ts

@@ -0,0 +1,95 @@
+/**
+ * `saacms migrate` — DB and content migrations. Per ADR 0012:
+ *
+ *  - `generate` projects each Collection's Effect Schema to D1 DDL, compares it
+ *    against the last snapshot, and emits a SQL migration file per new/changed
+ *    Collection into `saacms/migrations/db/`. The v1 MVP emits the full desired
+ *    `CREATE TABLE IF NOT EXISTS` (idempotent), NOT an ALTER-diff — true diffing
+ *    is a v1.x dispatch.
+ *  - `run` applies pending migrations against the configured target. Still a
+ *    documented stub: it needs a live D1 binding / `wrangler` invocation, which
+ *    is a v1.x dispatch.
+ *  - `check` is a read-only predeploy gate: it reports per-Collection drift and
+ *    (with --strict) exits non-zero. It never writes anything.
+ */
+declare const generateSubCommand: import("citty").CommandDef<{
+    name: {
+        type: "positional";
+        description: string;
+        required: false;
+    };
+    cwd: {
+        type: "string";
+        description: string;
+        required: false;
+    };
+    rename: {
+        type: "string";
+        description: string;
+        required: false;
+    };
+}>;
+interface ExecResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface MigrateRunDeps {
+    readonly exec?: (cmd: string[], cwd: string) => Promise<ExecResult>;
+}
+export interface MigrateRunArgs {
+    readonly cwd?: string;
+    readonly target?: string;
+    readonly database?: string;
+    readonly dry?: boolean;
+}
+/**
+ * Apply pending `saacms/migrations/db/*.sql` files to a Cloudflare D1
+ * database via `wrangler d1 execute`, idempotently. Already-applied files
+ * are tracked in `.saacms/migrations/applied.json` so re-runs skip them; the
+ * ledger is persisted after EACH success so a mid-batch failure never loses
+ * the record of what already applied. Returns the intended exit code.
+ */
+declare function runMigrateRun(args: MigrateRunArgs, deps?: MigrateRunDeps): Promise<number>;
+declare const runSubCommand: import("citty").CommandDef<{
+    target: {
+        type: "string";
+        description: string;
+        default: string;
+    };
+    cwd: {
+        type: "string";
+        description: string;
+        required: false;
+    };
+    database: {
+        type: "string";
+        description: string;
+        required: false;
+    };
+    dry: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+}>;
+declare const checkSubCommand: import("citty").CommandDef<{
+    strict: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+    cwd: {
+        type: "string";
+        description: string;
+        required: false;
+    };
+    "break-glass": {
+        type: "string";
+        description: string;
+        required: false;
+    };
+}>;
+export { generateSubCommand, runSubCommand, checkSubCommand, runMigrateRun };
+export declare const migrateCommand: import("citty").CommandDef<import("citty").ArgsDef>;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/commands/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAsMH,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;EA8JtB,CAAA;AAIF,UAAU,UAAU;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,CACd,GAAG,EAAE,MAAM,EAAE,EACb,GAAG,EAAE,MAAM,KACR,OAAO,CAAC,UAAU,CAAC,CAAA;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CACvB;AA6CD;;;;;;GAMG;AACH,iBAAe,aAAa,CAC1B,IAAI,EAAE,cAAc,EACpB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,MAAM,CAAC,CAiFjB;AAED,QAAA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;EAsCjB,CAAA;AAEF,QAAA,MAAM,eAAe;;;;;;;;;;;;;;;;EAsInB,CAAA;AAEF,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,eAAe,EAAE,aAAa,EAAE,CAAA;AAE5E,eAAO,MAAM,cAAc,qDAUzB,CAAA"}

package/dist/commands/migrate.js

@@ -0,0 +1,81 @@
+/**
+ * `saacms migrate` — DB and content migrations. Per ADR 0012:
+ *
+ *  - `generate` diffs Effect Schemas against the last snapshot and emits
+ *    Drizzle SQL files into `saacms/migrations/db/` and content-transform TS
+ *    files into `saacms/migrations/content/`.
+ *  - `run` applies pending migrations against the configured target.
+ *  - `check` exits non-zero on pending migrations or detected Schema drift;
+ *    intended for `predeploy` CI use.
+ *
+ * Scaffold only. Each sub-command logs what it would do.
+ */
+import { defineCommand } from "citty";
+const generateSubCommand = defineCommand({
+    meta: {
+        name: "generate",
+        description: "Diff Schemas and emit DB + content migration files (saacms/migrations/{db,content}/).",
+    },
+    args: {
+        name: {
+            type: "positional",
+            description: "Human-readable name for the migration (becomes the file slug).",
+            required: false,
+        },
+        rename: {
+            type: "string",
+            description: "Explicit rename hint, e.g. --rename=posts.body:posts.content. Skips the interactive prompt.",
+            required: false,
+        },
+    },
+    run({ args }) {
+        const name = args.name ?? "<unnamed>";
+        console.log(`saacms migrate generate '${name}' — would diff schemas and emit migrations (ADR 0012).`);
+        if (args.rename) {
+            console.log(`  rename hint: ${args.rename}`);
+        }
+    },
+});
+const runSubCommand = defineCommand({
+    meta: {
+        name: "run",
+        description: "Apply pending DB + content migrations against the configured target.",
+    },
+    args: {
+        target: {
+            type: "string",
+            description: "Migration target: 'local' (default) or 'remote'.",
+            default: "local",
+        },
+    },
+    run({ args }) {
+        console.log(`saacms migrate run --target=${args.target} — would apply pending migrations (ADR 0012).`);
+    },
+});
+const checkSubCommand = defineCommand({
+    meta: {
+        name: "check",
+        description: "Exit non-zero if migrations are pending or Schema drift is detected. Use as a `predeploy` step.",
+    },
+    args: {
+        strict: {
+            type: "boolean",
+            description: "Treat any pending migration or Schema drift as an error.",
+            default: false,
+        },
+    },
+    run({ args }) {
+        console.log(`saacms migrate check --strict=${args.strict} — would compare Schema fingerprint to migration ledger (ADR 0012).`);
+    },
+});
+export const migrateCommand = defineCommand({
+    meta: {
+        name: "migrate",
+        description: "Generate, run, or check DB + content migrations (per ADR 0012).",
+    },
+    subCommands: {
+        generate: generateSubCommand,
+        run: runSubCommand,
+        check: checkSubCommand,
+    },
+});