@ashlr/stack-core 0.2.2 → 0.3.1

package/src/__tests__/phantom-wire.test.ts

@@ -1,10 +1,15 @@
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { afterEach, beforeEach, describe, expect, it, setDefaultTimeout } from "bun:test";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { wirePhantomForRecipe } from "../ai/phantom-wire.ts";
-import type { Recipe } from "../ai/recipe.ts";
+import { type Recipe, readRecipe, writeRecipe } from "../ai/recipe.ts";
+import { listSecrets } from "../phantom.ts";
 import { type Harness, setupFakePhantom } from "./_harness.ts";
 
+// Every test spawns the fake `phantom` shim (bash + several python3 calls),
+// which takes multiple seconds on loaded machines — well past the 5s default.
+setDefaultTimeout(30_000);
+
 describe("ai/phantom-wire", () => {
   let harness: Harness;
 
@@ -41,6 +46,226 @@ describe("ai/phantom-wire", () => {
     expect(result.webhooks).toHaveLength(1);
   });
 
+  it("wires an altered local recipe without authenticating its contents", async () => {
+    const path = await writeRecipe(STRIPE_RECIPE, harness.dir);
+    const original = readFileSync(path, "utf-8");
+    expect(original).toContain("stripe");
+    writeFileSync(path, original.replace('stripe"', 'github"'));
+
+    const recipe = await readRecipe(STRIPE_RECIPE.id, harness.dir);
+    expect(recipe.providers).toEqual([{ name: "github" }]);
+    const result = await wirePhantomForRecipe(recipe, { cwd: harness.dir });
+    expect(result.missing).toContain("github:GITHUB_TOKEN");
+    expect(result.webhooks).toEqual([join(harness.dir, ".stack/webhooks/github.ts")]);
+  });
+
+  it("generates a commented request handler and response for every webhook provider", async () => {
+    const providers = ["stripe", "clerk", "supabase", "github"];
+    const recipe: Recipe = {
+      ...STRIPE_RECIPE,
+      providers: providers.map((name) => ({ name })),
+    };
+    const result = await wirePhantomForRecipe(recipe, { cwd: harness.dir });
+    expect(result.webhooks).toEqual(
+      providers.map((provider) => join(harness.dir, ".stack/webhooks", `${provider}.ts`)),
+    );
+
+    for (const [index, provider] of providers.entries()) {
+      const stub = readFileSync(result.webhooks[index], "utf-8");
+      const handlerName = `handle${provider[0].toUpperCase()}${provider.slice(1)}Webhook`;
+      const example = stub.match(/^\/\/ export async function [\s\S]*?^\/\/ }$/m)?.[0];
+      expect(example).toBeDefined();
+      expect(example).toContain(
+        `// export async function ${handlerName}(req: Request): Promise<Response> {`,
+      );
+      expect(example).toContain('//   return new Response("ok", { status: 200 });');
+    }
+  });
+
+  it.each([
+    ["stripe", "handleStripeWebhook"],
+    ["clerk", "handleClerkWebhook"],
+    ["supabase", "handleSupabaseWebhook"],
+    ["github", "handleGithubWebhook"],
+  ])("returns the unsigned %s response without reading the body", async (provider, name) => {
+    const recipe: Recipe = { ...STRIPE_RECIPE, providers: [{ name: provider }] };
+    const result = await wirePhantomForRecipe(recipe, { cwd: harness.dir });
+    const stub = readFileSync(result.webhooks[0], "utf-8");
+    const example = stub.match(/^\/\/ export async function [\s\S]*?^\/\/ }$/m)?.[0];
+    if (!example) throw new Error(`Missing ${provider} webhook example`);
+    const examplePath = join(harness.dir, `${provider}-unsigned-example.ts`);
+    writeFileSync(examplePath, example.replace(/^\/\/ ?/gm, ""));
+    const handler: unknown = (await import(examplePath))[name];
+    if (typeof handler !== "function") throw new Error(`Missing ${name}`);
+
+    const request = new Request("https://example.com", {
+      method: "POST",
+      body: "untrusted webhook payload",
+    });
+    const response: Response = await handler(request);
+    expect(response.status).toBe(400);
+    expect(await response.text()).toBe("Missing signature");
+    expect(request.bodyUsed).toBe(false);
+  });
+
+  it.each([
+    ["stripe", "stripe-signature", "handleStripeWebhook"],
+    ["clerk", "svix-signature", "handleClerkWebhook"],
+    ["supabase", "x-supabase-signature", "handleSupabaseWebhook"],
+    ["github", "x-hub-signature-256", "handleGithubWebhook"],
+  ])("rejects missing signatures and interrupted %s requests", async (provider, header, name) => {
+    const recipe: Recipe = { ...STRIPE_RECIPE, providers: [{ name: provider }] };
+    const result = await wirePhantomForRecipe(recipe, { cwd: harness.dir });
+    expect(result.webhooks).toHaveLength(1);
+
+    const stub = readFileSync(result.webhooks[0], "utf-8");
+    expect(stub.split("\n").every((line) => line === "" || line.startsWith("//"))).toBe(true);
+    expect(stub).toContain("This entire example is commented out and does not verify signatures.");
+    expect(stub).toContain(
+      "If uncommented as-is, it accepts any non-empty signature header and returns\n" +
+        "// 200 without authenticating the request. Implement verification first.",
+    );
+    const example = stub.match(/^\/\/ export async function [\s\S]*?^\/\/ }$/m)?.[0];
+    if (!example) throw new Error(`Missing ${provider} webhook example`);
+    expect(example).toContain(
+      "//   // TODO(security): signature verification is NOT implemented here. The\n" +
+        "//   // header check above proves only that a signature header arrived; its\n" +
+        "//   // value is never compared to anything.",
+    );
+    expect(example).toContain(
+      `//   // is unauthenticated, attacker-controlled input — anyone who can POST\n//   // to this endpoint can forge a ${provider} webhook.`,
+    );
+    expect(example).toContain(
+      "//   // constant time; reject missing or invalid signatures, and only then\n" +
+        "//   // parse, trust, or act on the body.",
+    );
+    const examplePath = join(harness.dir, `${provider}-example.ts`);
+    writeFileSync(examplePath, example.replace(/^\/\/ ?/gm, ""));
+    const handler: unknown = (await import(examplePath))[name];
+    expect(typeof handler).toBe("function");
+    if (typeof handler !== "function") throw new Error(`Missing ${name}`);
+
+    const missingHeaders: HeadersInit[] = [
+      {},
+      { "x-unrelated-signature": "present" },
+      { [header]: "" },
+    ];
+    for (const headers of missingHeaders) {
+      const response: Response = await handler(new Request("https://example.com", { headers }));
+      expect(response.status).toBe(400);
+      expect(await response.text()).toBe("Missing signature");
+    }
+
+    // A non-empty header reaches the placeholder; it is not signature verification.
+    const response: Response = await handler(
+      new Request("https://example.com", {
+        method: "POST",
+        headers: { [header]: "placeholder" },
+        body: "unverified webhook payload",
+      }),
+    );
+    expect(response.status).toBe(200);
+
+    const networkError = new Error("request body connection lost");
+    const interruptedBody = new ReadableStream<Uint8Array>({
+      pull(controller) {
+        controller.error(networkError);
+      },
+    });
+    const interruptedRequest = new Request("https://example.com", {
+      method: "POST",
+      headers: { [header]: "placeholder" },
+      body: interruptedBody,
+    });
+    await expect(handler(interruptedRequest)).rejects.toBe(networkError);
+  });
+
+  it.each([
+    ["stripe", "stripe-signature", "handleStripeWebhook"],
+    ["clerk", "svix-signature", "handleClerkWebhook"],
+    ["supabase", "x-supabase-signature", "handleSupabaseWebhook"],
+    ["github", "x-hub-signature-256", "handleGithubWebhook"],
+  ])(
+    "returns the successful %s webhook response after reading the body",
+    async (provider, header, name) => {
+      const recipe: Recipe = { ...STRIPE_RECIPE, providers: [{ name: provider }] };
+      const result = await wirePhantomForRecipe(recipe, { cwd: harness.dir });
+      const stub = readFileSync(result.webhooks[0], "utf-8");
+      const example = stub.match(/^\/\/ export async function [\s\S]*?^\/\/ }$/m)?.[0];
+      if (!example) throw new Error(`Missing ${provider} webhook example`);
+      const examplePath = join(harness.dir, `${provider}-success-example.ts`);
+      writeFileSync(examplePath, example.replace(/^\/\/ ?/gm, ""));
+      const handler: unknown = (await import(examplePath))[name];
+      if (typeof handler !== "function") throw new Error(`Missing ${name}`);
+
+      const request = new Request("https://example.com", {
+        method: "POST",
+        headers: { [header]: "placeholder" },
+        body: "unverified webhook payload",
+      });
+      const response: Response = await handler(request);
+      expect(request.bodyUsed).toBe(true);
+      expect(response.status).toBe(200);
+      expect(await response.text()).toBe("ok");
+    },
+  );
+
+  it.each(["stripe", "clerk", "supabase", "github"])(
+    "places the signature verification TODO before trusting the %s webhook body",
+    async (provider) => {
+      const recipe: Recipe = { ...STRIPE_RECIPE, providers: [{ name: provider }] };
+      const result = await wirePhantomForRecipe(recipe, { cwd: harness.dir });
+      expect(result.webhooks).toHaveLength(1);
+      const stub = readFileSync(result.webhooks[0], "utf-8");
+      const example = stub.match(/^\/\/ export async function [\s\S]*?^\/\/ }$/m)?.[0];
+      if (!example) throw new Error(`Missing ${provider} webhook example`);
+
+      // Reading the raw body supplies an input to verification; no executable
+      // handling of it should appear before the verification reminder.
+      expect(example).toContain(
+        "//   const body = await req.text();\n" +
+          "//   // TODO(security): signature verification is NOT implemented here.",
+      );
+      const todo = example.indexOf("TODO(security): signature verification is NOT implemented");
+      const success = example.indexOf('return new Response("ok", { status: 200 })');
+      expect(todo).toBeGreaterThanOrEqual(0);
+      expect(success).toBeGreaterThan(todo);
+    },
+  );
+
+  it.each([
+    ["stripe", "stripe.webhooks.constructEvent"],
+    ["clerk", "new Webhook(secret).verify(body, headers)"],
+    ["supabase", "`x-supabase-signature` per Supabase's documented webhook scheme"],
+    ["github", "`sha256=` + HMAC-SHA256"],
+  ])(
+    "points the %s stub at the provider's verification scheme without claiming it ran",
+    async (provider, hint) => {
+      const recipe: Recipe = { ...STRIPE_RECIPE, providers: [{ name: provider }] };
+      const result = await wirePhantomForRecipe(recipe, { cwd: harness.dir });
+      const example = readFileSync(result.webhooks[0], "utf-8").match(
+        /^\/\/ export async function [\s\S]*?^\/\/ }$/m,
+      )?.[0];
+      if (!example) throw new Error(`Missing ${provider} webhook example`);
+
+      // The TODO names where verification belongs and how the provider does it.
+      expect(example).toContain(hint);
+
+      // No comment may describe the request as already verified, and the
+      // uncommented handler must contain no verification code — the TODO's
+      // "NOT implemented" claim has to be true, not aspirational.
+      expect(example).not.toMatch(
+        /signature verified|verified signature|request is authenticated/i,
+      );
+      const runnable = example
+        .replace(/^\/\/ ?/gm, "")
+        .split("\n")
+        .filter((line) => !line.trimStart().startsWith("//"))
+        .join("\n");
+      expect(runnable).not.toMatch(/createHmac|timingSafeEqual|\.verify\(/);
+    },
+  );
+
   it("noWire: true skips the vault check and webhooks entirely", async () => {
     const result = await wirePhantomForRecipe(STRIPE_RECIPE, {
       cwd: harness.dir,
@@ -82,6 +307,151 @@ describe("ai/phantom-wire", () => {
     expect(harness.callsTo("add")).toEqual([]);
   });
 
+  it("surfaces a failed inventory command as unavailable and skips providers", async () => {
+    const phantomPath = join(harness.dir, "phantom");
+    const shim = readFileSync(phantomPath, "utf-8");
+    // Even plausible inventory on stdout is not evidence when the command fails.
+    expect(shim).toContain("  list)\n");
+    writeFileSync(
+      phantomPath,
+      shim.replace(
+        "  list)\n",
+        `  list)\n    echo '[{"name":"STRIPE_SECRET_KEY"}]'\n    echo 'inventory unavailable' >&2\n    exit 1\n`,
+      ),
+    );
+
+    await expect(listSecrets(harness.dir)).rejects.toMatchObject({
+      code: "PHANTOM_METADATA_UNAVAILABLE",
+      message: "Phantom secret inventory is unavailable; stored names are unknown.",
+    });
+    const recipe: Recipe = { ...STRIPE_RECIPE, providers: [{ name: "stripe" }, { name: "neon" }] };
+    const stubPath = join(harness.dir, ".stack/webhooks/stripe.ts");
+    expect(await wirePhantomForRecipe(recipe, { cwd: harness.dir })).toEqual({
+      present: [],
+      missing: [],
+      webhooks: [stubPath],
+      skipped: ["stripe", "neon"],
+    });
+    expect(existsSync(stubPath)).toBe(true);
+    expect(harness.callsTo("list")).toEqual([
+      { cmd: "list", args: ["--json"] },
+      { cmd: "list", args: ["--json"] },
+    ]);
+    expect(harness.callsTo("add")).toEqual([]);
+    expect(JSON.parse(readFileSync(harness.vaultPath, "utf-8"))).toEqual({});
+  });
+
+  it("treats surrounding whitespace in vault inventory JSON the same as compact JSON", async () => {
+    const inventory = '[{"name":"STRIPE_SECRET_KEY"}]';
+    const setListOutput = (output: string) => {
+      writeFileSync(
+        join(harness.dir, "phantom"),
+        `#!/usr/bin/env bash\ncase "$1" in\n  --version) echo "phantom fake 0.0.1" ;;\n  list) printf '%s' '${output}' ;;\n  *) exit 1 ;;\nesac\n`,
+      );
+    };
+
+    setListOutput(inventory);
+    const compact = await wirePhantomForRecipe(STRIPE_RECIPE, { cwd: harness.dir });
+    expect(compact).toEqual({
+      present: ["stripe:STRIPE_SECRET_KEY"],
+      missing: [],
+      skipped: [],
+      webhooks: [join(harness.dir, ".stack/webhooks/stripe.ts")],
+    });
+
+    setListOutput(` \t\r\n${inventory}\n\t `);
+    expect(await wirePhantomForRecipe(STRIPE_RECIPE, { cwd: harness.dir })).toEqual(compact);
+  });
+
+  it("rejects malformed vault inventory JSON and keeps the provider's secrets unknown", async () => {
+    // A successful command may still return a truncated inventory containing a plausible name.
+    writeFileSync(
+      join(harness.dir, "phantom"),
+      `#!/usr/bin/env bash\ncase "$1" in\n  --version) echo "phantom fake 0.0.1" ;;\n  list) printf '%s' '[{"name":"STRIPE_SECRET_KEY"}' ;;\n  *) exit 1 ;;\nesac\n`,
+    );
+
+    await expect(listSecrets(harness.dir)).rejects.toMatchObject({
+      code: "PHANTOM_OUTPUT_UNRECOGNIZED",
+      message:
+        "phantom list --json did not return JSON; upgrade Phantom Secrets to 0.7.9 or newer.",
+    });
+    const result = await wirePhantomForRecipe(STRIPE_RECIPE, { cwd: harness.dir });
+    expect(result).toEqual({
+      present: [],
+      missing: [],
+      skipped: ["stripe"],
+      webhooks: [join(harness.dir, ".stack/webhooks/stripe.ts")],
+    });
+    expect(existsSync(result.webhooks[0])).toBe(true);
+    expect(JSON.parse(readFileSync(harness.vaultPath, "utf-8"))).toEqual({});
+  });
+
+  it("rejects a JSON number from the vault inventory and skips the provider", async () => {
+    // Return valid JSON from a successful list command, but not the required array.
+    writeFileSync(
+      join(harness.dir, "phantom"),
+      '#!/usr/bin/env bash\ncase "$1" in\n  --version) echo "phantom fake 0.0.1" ;;\n  list) echo 42 ;;\n  *) exit 1 ;;\nesac\n',
+    );
+
+    await expect(listSecrets(harness.dir)).rejects.toMatchObject({
+      code: "PHANTOM_OUTPUT_UNRECOGNIZED",
+      message: "phantom list --json did not return an array.",
+    });
+    const result = await wirePhantomForRecipe(STRIPE_RECIPE, { cwd: harness.dir });
+    expect(result).toEqual({
+      present: [],
+      missing: [],
+      skipped: ["stripe"],
+      webhooks: [join(harness.dir, ".stack/webhooks/stripe.ts")],
+    });
+    expect(existsSync(result.webhooks[0])).toBe(true);
+  });
+
+  it.each(["true", "false"])(
+    "rejects JSON boolean %s from the vault inventory and skips the provider",
+    async (output) => {
+      writeFileSync(
+        join(harness.dir, "phantom"),
+        `#!/usr/bin/env bash\ncase "$1" in\n  --version) echo "phantom fake 0.0.1" ;;\n  list) echo ${output} ;;\n  *) exit 1 ;;\nesac\n`,
+      );
+
+      await expect(listSecrets(harness.dir)).rejects.toMatchObject({
+        code: "PHANTOM_OUTPUT_UNRECOGNIZED",
+        message: "phantom list --json did not return an array.",
+      });
+      const result = await wirePhantomForRecipe(STRIPE_RECIPE, { cwd: harness.dir });
+      expect(result).toEqual({
+        present: [],
+        missing: [],
+        skipped: ["stripe"],
+        webhooks: [join(harness.dir, ".stack/webhooks/stripe.ts")],
+      });
+      expect(existsSync(result.webhooks[0])).toBe(true);
+      expect(harness.callsTo("add")).toEqual([]);
+    },
+  );
+
+  it("does not report a JSON string vault response as a verified secret", async () => {
+    // A successful command returning the expected name as a scalar is not an inventory.
+    writeFileSync(
+      join(harness.dir, "phantom"),
+      `#!/usr/bin/env bash\ncase "$1" in\n  --version) echo "phantom fake 0.0.1" ;;\n  list) printf '%s' '"STRIPE_SECRET_KEY"' ;;\n  *) exit 1 ;;\nesac\n`,
+    );
+
+    await expect(listSecrets(harness.dir)).rejects.toMatchObject({
+      code: "PHANTOM_OUTPUT_UNRECOGNIZED",
+      message: "phantom list --json did not return an array.",
+    });
+    const result = await wirePhantomForRecipe(STRIPE_RECIPE, { cwd: harness.dir });
+    expect(result).toEqual({
+      present: [],
+      missing: [],
+      skipped: ["stripe"],
+      webhooks: [join(harness.dir, ".stack/webhooks/stripe.ts")],
+    });
+    expect(existsSync(result.webhooks[0])).toBe(true);
+  });
+
   it("skips providers with no webhook stub without crashing", async () => {
     const recipe: Recipe = {
       id: "neon",

package/src/__tests__/pipeline-integration.test.ts

@@ -2,6 +2,8 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { wirePhantomForRecipe } from "../ai/phantom-wire.ts";
+import { readRecipe, writeRecipe } from "../ai/recipe.ts";
 import { emptyConfig, writeConfig } from "../config.ts";
 import { addService } from "../pipeline.ts";
 import type { Provider } from "../providers/_base.ts";
@@ -93,3 +95,33 @@ describe("addService full loop", () => {
     Reflect.deleteProperty(providers, "stubsvc");
   });
 });
+
+test("apply wiring preserves an existing value and leaves missing values absent", async () => {
+  const initialVault = {
+    NEON_API_KEY: "existing-test-value",
+    UNRELATED_KEY: "unrelated-test-value",
+  };
+  const h = setupFakePhantom(initialVault);
+  try {
+    const recipe = {
+      id: "preserve-existing-value",
+      query: "database",
+      createdAt: "2026-04-18T00:00:00.000Z",
+      providers: [{ name: "neon" }],
+    };
+    await writeRecipe(recipe, h.dir);
+    const loaded = await readRecipe(recipe.id, h.dir);
+
+    // This is the vault-wiring phase used by stack apply after provisioning.
+    const result = await wirePhantomForRecipe(loaded, { cwd: h.dir });
+    expect(result.present).toEqual(["neon:NEON_API_KEY"]);
+    expect(result.missing).toEqual(["neon:DATABASE_URL"]);
+    expect(result.skipped).toEqual([]);
+    expect(h.callsTo("list")).toEqual([{ cmd: "list", args: ["--json"] }]);
+    expect(h.callsTo("add")).toEqual([]);
+    expect(h.callsTo("remove")).toEqual([]);
+    expect(await readVault(h.dir)).toEqual(initialVault);
+  } finally {
+    h.cleanup();
+  }
+});

package/src/__tests__/publish-script.test.ts

@@ -151,7 +151,6 @@ describe("publish script early parser (copied script, inert commands)", () => {
       join(bin, "node-reader.cjs"),
       `const {readFileSync, appendFileSync} = require('node:fs');
 const {createHash} = require('node:crypto');
-const {spawnSync} = require('node:child_process');
 const input = readFileSync(0);
 const args = process.argv.slice(2);
 if (args.length !== 3 || args[0] !== '--input-type=module' || args[1] !== '-'
@@ -159,12 +158,14 @@ if (args.length !== 3 || args[0] !== '--input-type=module' || args[1] !== '-'
   appendFileSync(process.env.SCRIPT_FIXTURE_TRACE, 'node\\n'); process.exit(97);
 }
 appendFileSync(process.env.VALIDATOR_TRACE, 'read\\n');
-const result = spawnSync(${JSON.stringify(realNode)}, args, {
-  cwd: process.cwd(), env: process.env, input, timeout: 1000, maxBuffer: 64 * 1024,
-});
-if (result.error || result.signal || result.status === null) process.exit(98);
-process.stdout.write(result.stdout); process.stderr.write(result.stderr);
-process.exit(result.status);
+// Run the hash-checked module in this Node process: a second Node startup
+// can exhaust the outer 1500ms fixture bound under coverage instrumentation.
+process.argv = [process.execPath, '-', args[2]];
+const timer = setTimeout(() => process.exit(98), 1000);
+import('data:text/javascript;base64,' + input.toString('base64')).then(
+  () => clearTimeout(timer),
+  () => process.exit(98),
+);
 `,
       { mode: 0o700 },
     );
@@ -398,6 +399,37 @@ process.exit(result.status);
       ).toBeUndefined();
     }
   });
+  for (const alteration of ["source", "arguments"] as const) {
+    test(`validator wrapper refuses altered ${alteration} before evaluation`, async () => {
+      removeFixtureBackups();
+      const original = readFileSync(script, "utf8");
+      const altered =
+        alteration === "source"
+          ? original.replace(
+              "import { lstatSync, readFileSync }",
+              "/* changed */ import { lstatSync, readFileSync }",
+            )
+          : original.replace(
+              'node --input-type=module - "$VERSION"',
+              'node --input-type=module - "$VERSION" extra',
+            );
+      expect(altered).not.toBe(original);
+      writeFileSync(script, altered);
+      const result = await runBackupCase();
+      expect(result.status).toBe(1);
+      expect(result.output).toContain("source version validation failed");
+      expect(readFileSync(trace, "utf8")).toBe("node\n");
+      expect(readFileSync(env.VALIDATOR_TRACE, "utf8")).toBe("");
+      for (const name of ["core", "mcp", "cli"]) {
+        expect(
+          lstatSync(join(root, "packages", name, "package.json.bak"), {
+            throwIfNoEntry: false,
+          }),
+        ).toBeUndefined();
+      }
+    });
+  }
+
   function inputs() {
     return [
       ...preserved.map((file) => file.path),
@@ -570,14 +602,17 @@ fi
 
   async function preflight(
     name: string,
-    version: string,
+    tag: string,
     otp: string,
-    ref = "refs/heads/synthetic",
+    ref = "refs/heads/main",
+    event = "workflow_dispatch",
   ) {
     const block = workflowBlock(name);
-    env.RELEASE_INPUT_VERSION = version;
+    // Workflow-level RELEASE_TAG: the pushed tag, or the dispatch tag input.
+    env.RELEASE_TAG = tag;
     env.RELEASE_INPUT_OTP = otp;
     env.GITHUB_REF = ref;
+    env.GITHUB_EVENT_NAME = event;
     env.GITHUB_OUTPUT = join(root, "github-output");
     writeFileSync(env.GITHUB_OUTPUT, "", { mode: 0o600 });
     const before = inputs();
@@ -597,7 +632,7 @@ fi
   ]) {
     for (const otp of ["synthetic-otp-secret", " ", "$(synthetic-otp-secret)"]) {
       test(`${name} refuses nonempty unsupported OTP before subprocesses ${JSON.stringify(otp)}`, async () => {
-        const result = await preflight(name, "0.2.1", otp);
+        const result = await preflight(name, "v0.2.1", otp);
         expect(result.status).toBe(1);
         expect(result.output).toContain("release input/source validation failed");
         expect(result.output).not.toContain(otp.trim() || "OTP");
@@ -605,25 +640,35 @@ fi
         expect(readFileSync(env.GITHUB_OUTPUT, "utf8")).toBe("");
       });
     }
-    test(`${name} actually validates branch source and exports only its version`, async () => {
-      const result = await preflight(name, "0.2.1", "");
+    test(`${name} validates dispatched tag source and exports only its version`, async () => {
+      cannedGit("same", "same");
+      const result = await preflight(name, "v0.2.1", "");
       expect(result.status).toBe(0);
       expect(readFileSync(env.VALIDATOR_TRACE, "utf8")).toBe("read\n");
       expect(readFileSync(env.GITHUB_OUTPUT, "utf8")).toBe("version=0.2.1\n");
     });
-    test(`${name} refuses absent, malformed and mismatched version inputs`, async () => {
-      for (const version of ["", "synthetic-version-secret", "0.2.2"]) {
-        const result = await preflight(name, version, "");
+    test(`${name} refuses absent, malformed and mismatched dispatch tags`, async () => {
+      cannedGit("same", "same");
+      for (const tag of ["", "vsynthetic-version-secret", "v0.2.2"]) {
+        const result = await preflight(name, tag, "");
         expect(result.status).toBe(1);
         expect(result.output).not.toContain("synthetic-version-secret");
         expect(readFileSync(env.GITHUB_OUTPUT, "utf8")).toBe("");
       }
     });
+    test(`${name} refuses a dispatched tag that is not the checked-out HEAD`, async () => {
+      cannedGit("tag", "head");
+      const result = await preflight(name, "v0.2.1", "");
+      expect(result.status).toBe(1);
+      // Source validation ran, so the refusal is the tag/HEAD check.
+      expect(readFileSync(env.VALIDATOR_TRACE, "utf8")).toBe("read\n");
+      expect(readFileSync(env.GITHUB_OUTPUT, "utf8")).toBe("");
+    });
     test(`${name} validates actual selected-tag coherence`, async () => {
       cannedGit("same", "same");
-      const matching = await preflight(name, "0.2.1", "", "refs/tags/v0.2.1");
+      const matching = await preflight(name, "v0.2.1", "", "refs/tags/v0.2.1", "push");
       expect(matching.status).toBe(0);
-      const mismatch = await preflight(name, "0.2.2", "", "refs/tags/v0.2.1");
+      const mismatch = await preflight(name, "v0.2.2", "", "refs/tags/v0.2.1", "push");
       expect(mismatch.status).toBe(1);
       expect(readFileSync(env.GITHUB_OUTPUT, "utf8")).toBe("");
     });

package/src/__tests__/recipe.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { parseRecipeDraft } from "../ai/inference.ts";
 import {
   type Recipe,
   listRecipes,
@@ -20,6 +21,28 @@ function scratchDir(): { dir: string; cleanup: () => void } {
 }
 
 describe("ai/recipe", () => {
+  it("rejects a draft with no provider steps", () => {
+    expect(() => parseRecipeDraft('{"providers":[]}')).toThrow(
+      "Inference response contained no usable providers",
+    );
+  });
+
+  it("round-trips a saved recipe with no provider steps", async () => {
+    const { dir, cleanup } = scratchDir();
+    try {
+      const recipe: Recipe = {
+        id: "empty",
+        query: "no providers",
+        createdAt: "2026-01-01T00:00:00.000Z",
+        providers: [],
+      };
+      await writeRecipe(recipe, dir);
+      expect(await readRecipe(recipe.id, dir)).toEqual(recipe);
+    } finally {
+      cleanup();
+    }
+  });
+
   it("round-trips a Recipe through write → read with fields preserved", async () => {
     const { dir, cleanup } = scratchDir();
     try {

package/src/__tests__/recommend-apply-e2e.test.ts

@@ -18,7 +18,7 @@
  * hitting the user's actual vault. We assert on its call log.
  */
 
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { afterEach, beforeEach, describe, expect, it, setDefaultTimeout } from "bun:test";
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -33,6 +33,10 @@ import {
 } from "../ai/recipe.ts";
 import { type Harness, setupFakePhantom } from "./_harness.ts";
 
+// `wirePhantomForRecipe` spawns the fake `phantom` shim (bash + several
+// python3 calls), which takes multiple seconds on loaded machines.
+setDefaultTimeout(30_000);
+
 describe("recommend → apply e2e", () => {
   let harness: Harness;
   // A project-scratch cwd, separate from the phantom harness's own dir, so
@@ -101,6 +105,17 @@ describe("recommend → apply e2e", () => {
     expect(harness.callsTo("add")).toEqual([]);
     const vault = JSON.parse(readFileSync(harness.vaultPath, "utf-8")) as Record<string, string>;
     expect(vault).toEqual({ NEON_API_KEY: "neon_real" });
+
+    // Simulate a user adding one missing value, then check again.
+    const updatedVault = { ...vault, OPENAI_API_KEY: "openai_real" };
+    writeFileSync(harness.vaultPath, JSON.stringify(updatedVault));
+    const rechecked = await wirePhantomForRecipe(loaded, { cwd: projectDir });
+    expect(rechecked.present).toEqual(["neon:NEON_API_KEY", "openai:OPENAI_API_KEY"]);
+    expect(rechecked.missing).toEqual(
+      result.missing.filter((name) => name !== "openai:OPENAI_API_KEY"),
+    );
+    expect(harness.callsTo("add")).toEqual([]);
+    expect(JSON.parse(readFileSync(harness.vaultPath, "utf-8"))).toEqual(updatedVault);
   });
 
   it("noWire: true performs zero phantom vault calls and writes no webhook stubs", async () => {