@sponson/sim 0.0.0-stage → 0.5.0

package/dist/chaos.js

@@ -0,0 +1,80 @@
+/** No chaos: every request is answered normally and immediately. */
+export const DEFAULT_CHAOS = {
+    latency_ms: 0,
+    fail_next: 0,
+    status: 503,
+    drop_response_next: 0,
+    hang_next: 0,
+    hold_next: 0,
+    deploy: "ok",
+    deploy_ms: 0,
+    neon_op_ms: 0,
+    planetscale_ready_ms: 0,
+    supabase_ready_ms: 0,
+    page_size: 0,
+    env_upsert_fail: [],
+};
+/**
+ * Every key `POST /_chaos` accepts besides `drift`; anything else is rejected so a misspelt key cannot silently
+ * do nothing.
+ */
+export const CHAOS_KEYS = new Set([...Object.keys(DEFAULT_CHAOS), "fail_on", "retry_after"]);
+/** A fresh default config (no shared arrays). */
+export function defaultChaos() {
+    return { ...DEFAULT_CHAOS, env_upsert_fail: [] };
+}
+/**
+ * Decide what chaos does to this request, consuming one count of `c` when it does something.
+ * Writes are eligible when `fail_on` is absent or matches; reads only when a GET rule matches.
+ */
+export function chaosFor(c, method, path) {
+    if (c.hold_next <= 0 && c.hang_next <= 0 && c.drop_response_next <= 0 && c.fail_next <= 0)
+        return null;
+    return affected(c, method, path) ? consume(c) : null;
+}
+/** Whether `fail_on` lets chaos hit this request: writes by default, reads only when a GET rule names them. */
+function affected(c, method, path) {
+    const rules = c.fail_on === undefined ? [] : Array.isArray(c.fail_on) ? c.fail_on : [c.fail_on];
+    if (method === "GET" || method === "HEAD")
+        return rules.some((r) => ruleMethod(r) === "GET" && matchesRule(r, "GET", path));
+    return rules.length === 0 || rules.some((r) => matchesRule(r, method, path));
+}
+/** Use up one pending chaos action, in the order hold, hang, drop, fail. */
+function consume(c) {
+    if (c.hold_next > 0) {
+        c.hold_next -= 1;
+        return { kind: "hold" };
+    }
+    if (c.hang_next > 0) {
+        c.hang_next -= 1;
+        return { kind: "hang" };
+    }
+    if (c.drop_response_next > 0) {
+        c.drop_response_next -= 1;
+        return { kind: "drop" };
+    }
+    if (c.fail_next > 0) {
+        c.fail_next -= 1;
+        const headers = c.status === 429 && c.retry_after !== undefined ? { "retry-after": String(c.retry_after) } : {};
+        return { kind: "fail", status: c.status, headers };
+    }
+    return null;
+}
+/** `"DELETE /neon/*"`: method must match exactly (or be `*`), `*` in the path matches anything. */
+export function matchesRule(rule, method, path) {
+    const space = rule.indexOf(" ");
+    const m = ruleMethod(rule);
+    const ruleGlob = space < 0 ? "*" : rule.slice(space + 1).trim();
+    if (m !== "*" && m !== method.toUpperCase())
+        return false;
+    const re = new RegExp("^" + ruleGlob.split("*").map(escapeRe).join(".*") + "$");
+    return re.test(path);
+}
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function ruleMethod(rule) {
+    const space = rule.indexOf(" ");
+    return (space < 0 ? rule : rule.slice(0, space)).toUpperCase();
+}
+//# sourceMappingURL=chaos.js.map

package/dist/chaos.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,29 @@
+import { type SimHandle } from "./index.js";
+/** Where the command line writes and what it reads; the bin passes the process's. */
+export interface SimCliIO {
+    stdout(s: string): void;
+    stderr(s: string): void;
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+}
+/** What the arguments ask for. */
+export type SimCommand = {
+    kind: "serve";
+    port: number;
+    demo?: string;
+} | {
+    kind: "env";
+    port: number;
+} | {
+    kind: "help";
+};
+/** How the command ended: an exit code, or a running sim the caller keeps alive until a signal. */
+export type SimCliResult = {
+    code: number;
+    sim?: SimHandle;
+};
+export declare const USAGE = "usage: sponson-sim [--port N] [--demo <dir>]\n       sponson-sim env [--port N]\n\n  --port N      listen on 127.0.0.1:N (default: $SPONSON_SIM_PORT, else 4777)\n  --demo <dir>  also write a ready demo repository into <dir> (new or empty) and print what to run next\n  env           print the `export` lines that point sponson at a sim on that port, for eval \"$(sponson-sim env)\"\n";
+/** Parse argv (without node and the script). Throws with a message for the user on anything it does not know. */
+export declare function parseSimArgs(argv: string[], env: NodeJS.ProcessEnv): SimCommand;
+/** Run the command line. A started sim is returned running; the caller decides when to close it. */
+export declare function runSimCli(argv: string[], io: SimCliIO): Promise<SimCliResult>;

package/dist/cli.js

@@ -0,0 +1,99 @@
+/**
+ * The `sponson-sim` command line, kept out of bin.ts so it can be tested in-process:
+ *   sponson-sim [--port N]               start the fake cloud and print the env that points sponson at it
+ *   sponson-sim --demo <dir> [--port N]  the same, plus a ready demo repository in <dir> and what to run next
+ *   sponson-sim env [--port N]           print only the `export` lines, for `eval "$(sponson-sim env)"`
+ * The demo lives here rather than in the `sponson` CLI, whose command set is fixed (docs/adr/0002-three-commands.md),
+ * and because it is about the fake cloud: it only makes sense with a sim running.
+ */
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { demoInstructions, envExports, writeDemo } from "./demo.js";
+import { startSim } from "./index.js";
+export const USAGE = `usage: sponson-sim [--port N] [--demo <dir>]
+       sponson-sim env [--port N]
+
+  --port N      listen on 127.0.0.1:N (default: $SPONSON_SIM_PORT, else 4777)
+  --demo <dir>  also write a ready demo repository into <dir> (new or empty) and print what to run next
+  env           print the \`export\` lines that point sponson at a sim on that port, for eval "$(sponson-sim env)"
+`;
+/** Parse argv (without node and the script). Throws with a message for the user on anything it does not know. */
+export function parseSimArgs(argv, env) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: { port: { type: "string" }, demo: { type: "string" }, help: { type: "boolean", short: "h" } },
+        allowPositionals: true,
+        strict: true,
+    });
+    if (values.help)
+        return { kind: "help" };
+    const port = portFrom(values.port, env);
+    const [command, ...rest] = positionals;
+    if (rest.length > 0 || (command !== undefined && command !== "env"))
+        throw new Error(`unexpected argument: ${[command, ...rest].join(" ")}`);
+    if (command === "env") {
+        if (values.demo !== undefined)
+            throw new Error("--demo starts a sim; it cannot be combined with `env`");
+        return { kind: "env", port };
+    }
+    if (values.demo !== undefined && values.demo.trim() === "")
+        throw new Error("--demo needs a directory");
+    return { kind: "serve", port, ...(values.demo !== undefined ? { demo: values.demo } : {}) };
+}
+/** `--port`, else SPONSON_SIM_PORT, else 4777. */
+function portFrom(flag, env) {
+    // A blank SPONSON_SIM_PORT is "not set", as CI systems export variables that do not apply.
+    const fromEnv = env.SPONSON_SIM_PORT?.trim();
+    const raw = flag ?? (fromEnv === undefined || fromEnv === "" ? "4777" : fromEnv);
+    const port = Number(raw);
+    if (raw.trim() === "" || !Number.isInteger(port) || port < 0 || port > 65535)
+        throw new Error(`invalid port: ${raw}`);
+    return port;
+}
+/** Run the command line. A started sim is returned running; the caller decides when to close it. */
+export async function runSimCli(argv, io) {
+    let cmd;
+    try {
+        cmd = parseSimArgs(argv, io.env);
+    }
+    catch (e) {
+        io.stderr(`sponson-sim: ${e.message}\n${USAGE}`);
+        return { code: 2 };
+    }
+    if (cmd.kind === "help") {
+        io.stdout(USAGE);
+        return { code: 0 };
+    }
+    if (cmd.kind === "env") {
+        io.stdout(`${envExports(`http://127.0.0.1:${String(cmd.port)}`).join("\n")}\n`);
+        return { code: 0 };
+    }
+    return serve(cmd, io);
+}
+async function serve(cmd, io) {
+    let sim;
+    try {
+        sim = await startSim({ port: cmd.port });
+    }
+    catch (e) {
+        const busy = e.code === "EADDRINUSE";
+        io.stderr(`sponson-sim: ${busy ? `port ${String(cmd.port)} is in use (another sponson-sim?); pass --port N or set SPONSON_SIM_PORT` : e.message}\n`);
+        return { code: 1 };
+    }
+    if (cmd.demo === undefined) {
+        io.stdout(`sponson-sim listening on ${sim.url}\n# paste into another shell to point sponson at the sim:\n${envExports(sim.url).join("\n")}\n`);
+        return { code: 0, sim };
+    }
+    try {
+        // Written after the port is ours: a busy port must not leave a demo behind that points at someone else's sim.
+        await writeDemo(resolve(io.cwd, cmd.demo), sim.url);
+    }
+    catch (e) {
+        await sim.close();
+        io.stderr(`sponson-sim: ${e.message}\n`);
+        return { code: 1 };
+    }
+    io.stdout(demoInstructions(cmd.demo, sim.url));
+    return { code: 0, sim };
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAkB,MAAM,YAAY,CAAC;AAgBtD,MAAM,CAAC,MAAM,KAAK,GAAG;;;;;;CAMpB,CAAC;AAEF,iHAAiH;AACjH,MAAM,UAAU,YAAY,CAAC,IAAc,EAAE,GAAsB;IACjE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC;QACxC,IAAI,EAAE,IAAI;QACV,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QACtG,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE,IAAI;KACb,CAAC,CAAC;IACH,IAAI,MAAM,CAAC,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACzC,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACxC,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,WAAW,CAAC;IACvC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC7I,IAAI,OAAO,KAAK,KAAK,EAAE,CAAC;QACtB,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QACxG,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC/B,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;IACxG,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC9F,CAAC;AAED,kDAAkD;AAClD,SAAS,QAAQ,CAAC,IAAwB,EAAE,GAAsB;IAChE,2FAA2F;IAC3F,MAAM,OAAO,GAAG,GAAG,CAAC,gBAAgB,EAAE,IAAI,EAAE,CAAC;IAC7C,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACjF,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,iBAAiB,GAAG,EAAE,CAAC,CAAC;IACtH,OAAO,IAAI,CAAC;AACd,CAAC;AAED,oGAAoG;AACpG,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAc,EAAE,EAAY;IAC1D,IAAI,GAAe,CAAC;IACpB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,EAAE,CAAC,MAAM,CAAC,gBAAiB,CAAW,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC,CAAC;QAC5D,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IACrB,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACxB,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACjB,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IACrB,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QACvB,EAAE,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,oBAAoB,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChF,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IACrB,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACxB,CAAC;AAED,KAAK,UAAU,KAAK,CAAC,GAAoC,EAAE,EAAY;IACrE,IAAI,GAAc,CAAC;IACnB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,GAAI,CAA2B,CAAC,IAAI,KAAK,YAAY,CAAC;QAChE,EAAE,CAAC,MAAM,CAAC,gBAAgB,IAAI,CAAC,CAAC,CAAC,QAAQ,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,0EAA0E,CAAC,CAAC,CAAE,CAAW,CAAC,OAAO,IAAI,CAAC,CAAC;QAChK,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IACrB,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC3B,EAAE,CAAC,MAAM,CAAC,4BAA4B,GAAG,CAAC,GAAG,8DAA8D,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/I,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC;IAC1B,CAAC;IACD,IAAI,CAAC;QACH,8GAA8G;QAC9G,MAAM,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC;QAClB,EAAE,CAAC,MAAM,CAAC,gBAAiB,CAAW,CAAC,OAAO,IAAI,CAAC,CAAC;QACpD,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IACrB,CAAC;IACD,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/C,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC;AAC1B,CAAC"}

package/dist/demo.d.ts

@@ -0,0 +1,39 @@
+/** The branch the demo commit is on; Vercel variables are written for it. */
+export declare const DEMO_BRANCH = "feat/checkout";
+/** The pull request the demo pretends to be, so the scope reads `pr-42` as in the README. */
+export declare const DEMO_PR = "42";
+/** The file `source` loads in the second terminal. */
+export declare const DEMO_ENV_FILE = "sim.env";
+/**
+ * Comments carry the explanation, because a newcomer reads this file before running anything. It uses only the
+ * projects every provider's default seed creates (`prj_demo`, `proj_demo`; Clerk needs none).
+ */
+export declare const DEMO_PLAN = "# A release plan for a preview of this branch, against the fake cloud started by `sponson-sim --demo`.\nversion: 1\n# Receipts (what each run did) go to .sponson/receipts in this directory: the demo has no git remote.\nreceipts: local\nproviders:\n  vercel: { project: prj_demo }\n  neon: { project: proj_demo }\n\nchanges:\n  # 1. A Neon database branch for this preview, forked from main.\n  - id: db\n    adapter: neon\n    op: branch\n    parent: main\n    environments: [preview]\n\n  # 2. The branch's connection string as the preview's DATABASE_URL. A reference, never a value: nobody copies\n  #    a password between consoles, and it is masked in every line Sponson prints.\n  - id: env\n    adapter: vercel\n    op: env\n    target: preview\n    values:\n      DATABASE_URL: { from: db.connection_string }\n    environments: [preview]\n\n  # 3. The preview's URL as an allowed Clerk redirect. The URL exists only once Vercel has deployed this commit,\n  #    so this line waits for the deploy.\n  - id: callback\n    adapter: clerk\n    op: redirect_allow\n    url: { from: env.preview_url }\n    environments: [preview]\n";
+/** A console edit, as the sim's drift control applies it: someone pastes another database into DATABASE_URL. */
+export declare const DEMO_DRIFT: {
+    "vercel.env.preview.DATABASE_URL": string;
+};
+/**
+ * What to run in the second terminal, in order. No inline comments: interactive zsh (macOS's default shell)
+ * treats `#` as an argument unless `interactivecomments` is set, so a pasted comment would break the command.
+ */
+export declare function demoSteps(dir: string): string[];
+/**
+ * The env file: the sim's URLs and placeholder tokens (`simEnv`), `SPONSON_SIM_URL` for the drift command, and the
+ * pull request number. Setting `SPONSON_CTX_PR` also keeps `sponson` from asking `gh` which pull request this is,
+ * which in a repository without a remote only costs time. Without a global install, `sponson` falls back to npx.
+ */
+export declare function demoEnvFile(url: string): string;
+/** `export NAME=value` for everything a shell needs to point `sponson` at the sim at `url`. */
+export declare function envExports(url: string): string[];
+/**
+ * Write the demo into `dir`: the plan, a .gitignore, the env file, and one commit on `DEMO_BRANCH`. The commit's
+ * author, dates and contents are fixed, so its sha (and with it the preview URL the sim derives from it) is the
+ * same on every machine. The env file is ignored: it holds the port, which differs between runs.
+ * Refuses a non-empty directory rather than mixing the demo into someone's files.
+ */
+export declare function writeDemo(dir: string, url: string): Promise<void>;
+/** The walkthrough printed once the sim is up and the demo is written. */
+export declare function demoInstructions(dir: string, url: string): string;
+/** Quote a path for a POSIX shell only when it needs it, so the common case reads naturally. */
+export declare function shellQuote(s: string): string;

package/dist/demo.js

@@ -0,0 +1,168 @@
+/**
+ * The zero-account demo behind `sponson-sim --demo <dir>`: a git repository holding a plan wired to the projects
+ * the sim seeds by default, an env file that points `sponson` at the running sim, and the commands to run next.
+ * The README's "Try it in 60 seconds" block is these commands verbatim; `scenarios/docs/try-it.test.ts` runs that
+ * block and checks it against what `demoSteps` prints, so the two cannot drift apart.
+ */
+import { execFile } from "node:child_process";
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { simEnv } from "./index.js";
+const exec = promisify(execFile);
+/** The branch the demo commit is on; Vercel variables are written for it. */
+export const DEMO_BRANCH = "feat/checkout";
+/** The pull request the demo pretends to be, so the scope reads `pr-42` as in the README. */
+export const DEMO_PR = "42";
+/** The file `source` loads in the second terminal. */
+export const DEMO_ENV_FILE = "sim.env";
+/**
+ * Comments carry the explanation, because a newcomer reads this file before running anything. It uses only the
+ * projects every provider's default seed creates (`prj_demo`, `proj_demo`; Clerk needs none).
+ */
+export const DEMO_PLAN = `# A release plan for a preview of this branch, against the fake cloud started by \`sponson-sim --demo\`.
+version: 1
+# Receipts (what each run did) go to .sponson/receipts in this directory: the demo has no git remote.
+receipts: local
+providers:
+  vercel: { project: prj_demo }
+  neon: { project: proj_demo }
+
+changes:
+  # 1. A Neon database branch for this preview, forked from main.
+  - id: db
+    adapter: neon
+    op: branch
+    parent: main
+    environments: [preview]
+
+  # 2. The branch's connection string as the preview's DATABASE_URL. A reference, never a value: nobody copies
+  #    a password between consoles, and it is masked in every line Sponson prints.
+  - id: env
+    adapter: vercel
+    op: env
+    target: preview
+    values:
+      DATABASE_URL: { from: db.connection_string }
+    environments: [preview]
+
+  # 3. The preview's URL as an allowed Clerk redirect. The URL exists only once Vercel has deployed this commit,
+  #    so this line waits for the deploy.
+  - id: callback
+    adapter: clerk
+    op: redirect_allow
+    url: { from: env.preview_url }
+    environments: [preview]
+`;
+/** A console edit, as the sim's drift control applies it: someone pastes another database into DATABASE_URL. */
+export const DEMO_DRIFT = { "vercel.env.preview.DATABASE_URL": "postgres://typed-in-the-console" };
+/**
+ * What to run in the second terminal, in order. No inline comments: interactive zsh (macOS's default shell)
+ * treats `#` as an argument unless `interactivecomments` is set, so a pasted comment would break the command.
+ */
+export function demoSteps(dir) {
+    return [
+        `cd ${shellQuote(dir)} && source ${DEMO_ENV_FILE}`,
+        "sponson plan",
+        "sponson apply",
+        "sponson apply",
+        `curl -s -o /dev/null "$SPONSON_SIM_URL/_chaos" -d '${JSON.stringify({ drift: DEMO_DRIFT })}'`,
+        "sponson plan",
+        "sponson apply --destroy",
+    ];
+}
+/** One line per step of `demoSteps`, for the printed walkthrough. */
+const STEP_NOTES = [
+    "point sponson at the fake cloud (placeholder tokens, no accounts)",
+    "the diff: a branch to create, a variable and a callback waiting on it",
+    "creates the branch, injects DATABASE_URL by reference, finds the preview deploy, allows its URL",
+    "again: every line unchanged, zero writes",
+    "play a human editing DATABASE_URL in the Vercel console",
+    "the drift is caught: that line is blocked until you `sponson apply --reconcile`",
+    "removes everything this scope created, in reverse order",
+];
+/**
+ * The env file: the sim's URLs and placeholder tokens (`simEnv`), `SPONSON_SIM_URL` for the drift command, and the
+ * pull request number. Setting `SPONSON_CTX_PR` also keeps `sponson` from asking `gh` which pull request this is,
+ * which in a repository without a remote only costs time. Without a global install, `sponson` falls back to npx.
+ */
+export function demoEnvFile(url) {
+    const lines = [
+        "# Points sponson at the fake cloud started by `sponson-sim --demo`. Load it with: source sim.env",
+        ...envExports(url),
+        "# The demo pretends this branch is pull request #42 (scope pr-42).",
+        `export SPONSON_CTX_PR=${DEMO_PR}`,
+        "# Not installed globally? Run the published CLI through npx.",
+        'command -v sponson >/dev/null 2>&1 || sponson() { npx --yes sponson "$@"; }',
+    ];
+    return `${lines.join("\n")}\n`;
+}
+/** `export NAME=value` for everything a shell needs to point `sponson` at the sim at `url`. */
+export function envExports(url) {
+    return [`export SPONSON_SIM_URL=${url}`, ...Object.entries(simEnv(url)).map(([k, v]) => `export ${k}=${v}`)];
+}
+/**
+ * Write the demo into `dir`: the plan, a .gitignore, the env file, and one commit on `DEMO_BRANCH`. The commit's
+ * author, dates and contents are fixed, so its sha (and with it the preview URL the sim derives from it) is the
+ * same on every machine. The env file is ignored: it holds the port, which differs between runs.
+ * Refuses a non-empty directory rather than mixing the demo into someone's files.
+ */
+export async function writeDemo(dir, url) {
+    const existing = await readdir(dir).catch((e) => {
+        if (e.code === "ENOENT")
+            return [];
+        throw e;
+    });
+    if (existing.length > 0)
+        throw new Error(`${dir} is not empty; pass a new directory to --demo (or delete this one)`);
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, "release.plan.yaml"), DEMO_PLAN);
+    await writeFile(join(dir, ".gitignore"), `.sponson/\n${DEMO_ENV_FILE}\n`);
+    await writeFile(join(dir, DEMO_ENV_FILE), demoEnvFile(url));
+    await git(dir, ["init", "-q"]);
+    await git(dir, ["checkout", "-q", "-b", DEMO_BRANCH]);
+    await git(dir, ["add", "release.plan.yaml", ".gitignore"]);
+    await git(dir, ["commit", "-q", "--no-verify", "-m", "Add the Sponson demo plan"]);
+}
+/** The walkthrough printed once the sim is up and the demo is written. */
+export function demoInstructions(dir, url) {
+    const steps = demoSteps(dir);
+    return [
+        `Fake cloud (Vercel, Neon and Clerk APIs) listening on ${url}. State lives in memory; Ctrl-C stops it.`,
+        `Demo repository written to ${dir}: release.plan.yaml creates a Neon branch, puts its connection string`,
+        "into Vercel's DATABASE_URL by reference, waits for the preview deploy, then allows its URL in Clerk.",
+        "",
+        "In a second terminal, run these one at a time:",
+        "",
+        ...steps.map((s) => `  ${s}`),
+        "",
+        "What each one does:",
+        "",
+        ...STEP_NOTES.map((note, i) => `  ${String(i + 1)}. ${note}`),
+        "",
+    ].join("\n");
+}
+/**
+ * Git with the demo's fixed identity. Inherited GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE would point it at
+ * another repository (they are set inside git hooks), and a user's signing or hook settings would change the
+ * commit, so both are overridden.
+ */
+async function git(cwd, args) {
+    const { GIT_DIR: _d, GIT_WORK_TREE: _w, GIT_INDEX_FILE: _i, ...env } = process.env;
+    const fixed = { GIT_AUTHOR_NAME: "Sponson demo", GIT_AUTHOR_EMAIL: "demo@sponson.invalid", GIT_COMMITTER_NAME: "Sponson demo", GIT_COMMITTER_EMAIL: "demo@sponson.invalid", GIT_AUTHOR_DATE: "2026-01-01T00:00:00Z", GIT_COMMITTER_DATE: "2026-01-01T00:00:00Z" };
+    const config = ["-c", "commit.gpgsign=false", "-c", "core.autocrlf=false", "-c", "init.defaultBranch=main"];
+    try {
+        await exec("git", [...config, ...args], { cwd, env: { ...env, ...fixed } });
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === "ENOENT")
+            throw new Error("the demo needs git on PATH (Sponson reads the branch and commit from it)");
+        throw new Error(`git ${args.join(" ")} failed: ${(err.stderr ?? err.message).trim()}`);
+    }
+}
+/** Quote a path for a POSIX shell only when it needs it, so the common case reads naturally. */
+export function shellQuote(s) {
+    return /^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replaceAll("'", `'\\''`)}'`;
+}
+//# sourceMappingURL=demo.js.map

package/dist/demo.js.map

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

package/dist/graphql.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What the GraphQL sims (routes/railway.ts, routes/fly.ts) share: reading an operation's kind and root field from a
+ * request body, and answering in the GraphQL envelope. They do not parse GraphQL: a simulated schema is a table of
+ * root fields, each resolved from the request's variables, so a plan line must pass its inputs as variables (as the
+ * official clients do), not inline.
+ */
+import { Reply } from "./provider.js";
+/** One GraphQL request as the sims see it. */
+export interface GraphqlOperation {
+    kind: "query" | "mutation";
+    /** The first selected top-level field (after an alias). */
+    root: string;
+    variables: Record<string, unknown>;
+}
+/** The operation of a request body; a 400 GRAPHQL_PARSE_FAILED answer when the body is not one. */
+export declare function graphqlOperation(body: unknown): GraphqlOperation | Reply;
+/** A successful answer: `{ data }`. */
+export declare function graphqlData(data: unknown): Reply;
+/** A failed answer: `{ errors: [{ message, extensions: { code } }], data: null }`, HTTP 200 unless said otherwise. */
+export declare function graphqlError(message: string, code: string, status?: number): Reply;
+/** True when a request body is a mutation: only those change state (the write log). */
+export declare function isMutation(body: unknown): boolean;

package/dist/graphql.js

@@ -0,0 +1,36 @@
+/**
+ * What the GraphQL sims (routes/railway.ts, routes/fly.ts) share: reading an operation's kind and root field from a
+ * request body, and answering in the GraphQL envelope. They do not parse GraphQL: a simulated schema is a table of
+ * root fields, each resolved from the request's variables, so a plan line must pass its inputs as variables (as the
+ * official clients do), not inline.
+ */
+import { Reply } from "./provider.js";
+/** The operation of a request body; a 400 GRAPHQL_PARSE_FAILED answer when the body is not one. */
+export function graphqlOperation(body) {
+    if (typeof body !== "object" || body === null)
+        return graphqlError("request body must be a JSON object { query, variables }", "GRAPHQL_PARSE_FAILED", 400);
+    const { query, variables } = body;
+    if (typeof query !== "string")
+        return graphqlError("`query` is required", "GRAPHQL_PARSE_FAILED", 400);
+    const text = query.replace(/#[^\n]*/g, "").trim();
+    const kind = /^mutation\b/.test(text) ? "mutation" : "query";
+    const m = /^\s*([_A-Za-z]\w*)(\s*:\s*([_A-Za-z]\w*))?/.exec(text.slice(text.indexOf("{") + 1));
+    if (!m)
+        return graphqlError("no field selected", "GRAPHQL_PARSE_FAILED", 400);
+    const vars = typeof variables === "object" && variables !== null && !Array.isArray(variables) ? variables : {};
+    return { kind, root: m[3] ?? m[1], variables: vars };
+}
+/** A successful answer: `{ data }`. */
+export function graphqlData(data) {
+    return new Reply(200, { data });
+}
+/** A failed answer: `{ errors: [{ message, extensions: { code } }], data: null }`, HTTP 200 unless said otherwise. */
+export function graphqlError(message, code, status = 200) {
+    return new Reply(status, { errors: [{ message, extensions: { code } }], data: null });
+}
+/** True when a request body is a mutation: only those change state (the write log). */
+export function isMutation(body) {
+    const op = graphqlOperation(body);
+    return !(op instanceof Reply) && op.kind === "mutation";
+}
+//# sourceMappingURL=graphql.js.map

package/dist/graphql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql.js","sourceRoot":"","sources":["../src/graphql.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAUtC,mGAAmG;AACnG,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC5C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,YAAY,CAAC,yDAAyD,EAAE,sBAAsB,EAAE,GAAG,CAAC,CAAC;IAC3J,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,IAA+B,CAAC;IAC7D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,YAAY,CAAC,qBAAqB,EAAE,sBAAsB,EAAE,GAAG,CAAC,CAAC;IACvG,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAClD,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC;IAC7D,MAAM,CAAC,GAAG,4CAA4C,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC/F,IAAI,CAAC,CAAC;QAAE,OAAO,YAAY,CAAC,mBAAmB,EAAE,sBAAsB,EAAE,GAAG,CAAC,CAAC;IAC9E,MAAM,IAAI,GAAG,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAE,SAAqC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5I,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AACxD,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,WAAW,CAAC,IAAa;IACvC,OAAO,IAAI,KAAK,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;AAClC,CAAC;AAED,sHAAsH;AACtH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,IAAY,EAAE,MAAM,GAAG,GAAG;IACtE,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AACxF,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,CAAC,CAAC,EAAE,YAAY,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,KAAK,UAAU,CAAC;AAC1D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { SimState, type SimSeed } from "./state.js";
+export * from "./chaos.js";
+export * from "./provider.js";
+export * from "./state.js";
+export * from "./routes/vercel.js";
+export * from "./routes/neon.js";
+export * from "./routes/clerk.js";
+export * from "./routes/netlify.js";
+export * from "./routes/planetscale.js";
+export * from "./routes/launchdarkly.js";
+export * from "./routes/rest.js";
+export * from "./routes/supabase.js";
+export * from "./routes/aws.js";
+export * from "./routes/railway.js";
+export * from "./routes/fly.js";
+export * from "./routes/cloudflare.js";
+export * from "./routes/algolia.js";
+export * from "./routes/xata.js";
+export * from "./routes/digitalocean.js";
+export { createSimServer } from "./server.js";
+/**
+ * A running sim: its base URL (`simEnv` turns it into adapter environment), its live state for seeding and
+ * assertions, and `close`.
+ */
+export interface SimHandle {
+    url: string;
+    port: number;
+    state: SimState;
+    close(): Promise<void>;
+}
+/** Start the fake cloud on 127.0.0.1. Port 0 picks a free one, which is what tests want. */
+export declare function startSim(opts?: {
+    port?: number;
+    seed?: Partial<SimSeed>;
+}): Promise<SimHandle>;
+/** A placeholder credential per provider (`VERCEL_TOKEN: "tok_vercel"`, …). The sim accepts any non-empty token. */
+export declare const SIM_TOKENS: Readonly<Record<string, string>>;
+/**
+ * The env that points every provider's adapter at a sim (or at a proxy in front of one): each `*_API_URL`
+ * and, unless `tokens: false`, the placeholder credentials of SIM_TOKENS.
+ */
+export declare function simEnv(sim: {
+    url: string;
+} | string, opts?: {
+    tokens?: boolean;
+}): Record<string, string>;

package/dist/index.js

@@ -0,0 +1,54 @@
+import { createSimServer } from "./server.js";
+import { providerEntries, SimState } from "./state.js";
+export * from "./chaos.js";
+export * from "./provider.js";
+export * from "./state.js";
+export * from "./routes/vercel.js";
+export * from "./routes/neon.js";
+export * from "./routes/clerk.js";
+export * from "./routes/netlify.js";
+export * from "./routes/planetscale.js";
+export * from "./routes/launchdarkly.js";
+export * from "./routes/rest.js";
+export * from "./routes/supabase.js";
+export * from "./routes/aws.js";
+export * from "./routes/railway.js";
+export * from "./routes/fly.js";
+export * from "./routes/cloudflare.js";
+export * from "./routes/algolia.js";
+export * from "./routes/xata.js";
+export * from "./routes/digitalocean.js";
+export { createSimServer } from "./server.js";
+/** Start the fake cloud on 127.0.0.1. Port 0 picks a free one, which is what tests want. */
+export async function startSim(opts = {}) {
+    const state = new SimState(opts.seed);
+    const server = createSimServer(state);
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(opts.port ?? 0, "127.0.0.1", () => resolve());
+    });
+    const port = server.address().port;
+    return {
+        url: `http://127.0.0.1:${port}`,
+        port,
+        state,
+        close: () => new Promise((resolve, reject) => {
+            server.closeAllConnections();
+            server.close((e) => (e ? reject(e) : resolve()));
+        }),
+    };
+}
+/** A placeholder credential per provider (`VERCEL_TOKEN: "tok_vercel"`, …). The sim accepts any non-empty token. */
+export const SIM_TOKENS = Object.fromEntries(providerEntries().flatMap(([, p]) => [[p.env.token, p.env.testToken], ...Object.entries(p.env.more ?? {})]));
+/**
+ * The env that points every provider's adapter at a sim (or at a proxy in front of one): each `*_API_URL`
+ * and, unless `tokens: false`, the placeholder credentials of SIM_TOKENS.
+ */
+export function simEnv(sim, opts = {}) {
+    const base = typeof sim === "string" ? sim : sim.url;
+    const env = opts.tokens === false ? {} : { ...SIM_TOKENS };
+    for (const [name, p] of providerEntries())
+        env[p.env.url] = `${base}/${name}`;
+    return env;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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