@ashlr/stack-core 0.3.1 → 0.3.6

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

@@ -1,9 +1,9 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync } from "node:fs";
+import { mkdtempSync, writeFileSync } 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 { type Recipe, readRecipe, writeRecipe } from "../ai/recipe.ts";
 import { emptyConfig, writeConfig } from "../config.ts";
 import { addService } from "../pipeline.ts";
 import type { Provider } from "../providers/_base.ts";
@@ -94,6 +94,30 @@ describe("addService full loop", () => {
 
     Reflect.deleteProperty(providers, "stubsvc");
   });
+
+  test("stack apply reports every missing value without writing placeholders", async () => {
+    const vault = { NEON_API_KEY: "existing-value", UNRELATED_KEY: "keep-me" };
+    writeFileSync(h.vaultPath, JSON.stringify(vault));
+    const recipe: Recipe = {
+      id: "missing-values",
+      query: "database and ai",
+      createdAt: "2026-04-18T00:00:00.000Z",
+      providers: [{ name: "neon" }, { name: "openai" }, { name: "anthropic" }],
+    };
+    await writeRecipe(recipe, cwd);
+
+    // Apply reads the saved recipe and uses this wiring result for its report.
+    const result = await wirePhantomForRecipe(await readRecipe(recipe.id, cwd), { cwd });
+    expect(result).toEqual({
+      present: ["neon:NEON_API_KEY"],
+      missing: ["neon:DATABASE_URL", "openai:OPENAI_API_KEY", "anthropic:ANTHROPIC_API_KEY"],
+      webhooks: [],
+      skipped: [],
+    });
+    expect(h.callsTo("list").length).toBeGreaterThan(0);
+    expect(h.callsTo("add")).toEqual([]);
+    expect(await readVault(h.dir)).toEqual(vault);
+  });
 });
 
 test("apply wiring preserves an existing value and leaves missing values absent", async () => {

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

@@ -33,8 +33,8 @@ 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.
+// `wirePhantomForRecipe` spawns the fake `phantom` shim (bash + a Bun JSON
+// helper), which takes multiple seconds on loaded machines.
 setDefaultTimeout(30_000);
 
 describe("recommend → apply e2e", () => {

package/src/__tests__/secret-redaction.test.ts

@@ -92,7 +92,7 @@ describe("phantom error formatting — regression guard for formatArgsForError",
    * exercise the error path.
    */
   function setupAlwaysFailingPhantom(): { cleanup(): void } {
-    const { chmodSync, mkdtempSync, rmSync, writeFileSync } = require("node:fs") as typeof import("node:fs"); // biome-ignore format: Bun parser rejects split typeof import()
+    const { chmodSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } = require("node:fs") as typeof import("node:fs"); // biome-ignore format: Bun parser rejects split typeof import()
     const { tmpdir } = require("node:os") as typeof import("node:os");
     const { join } = require("node:path") as typeof import("node:path");
     const { __resetPhantomCache } = require("../phantom.ts") as typeof import("../phantom.ts");
@@ -104,9 +104,19 @@ case "\${1:-}" in
   *) echo "boom" >&2; exit 1 ;;
 esac
 `;
+    // Sandboxed runners and macOS Gatekeeper's provenance policy refuse to
+    // exec an extensionless file written by a non-platform process, while a
+    // `*.sh` target passes the check: point `phantom` at a `phantom.sh` shim.
     const binPath = join(dir, "phantom");
-    writeFileSync(binPath, script);
-    chmodSync(binPath, 0o755);
+    const realPath = join(dir, "phantom.sh");
+    writeFileSync(realPath, script);
+    chmodSync(realPath, 0o755);
+    try {
+      symlinkSync(realPath, binPath);
+    } catch {
+      writeFileSync(binPath, script);
+      chmodSync(binPath, 0o755);
+    }
 
     const previousPath = process.env.PATH ?? "";
     process.env.PATH = `${dir}:${previousPath}`;

package/src/ai/phantom-wire-adjacent-different-providers.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, beforeEach, describe, expect, it, setDefaultTimeout } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type Harness, setupFakePhantom } from "../__tests__/_harness.ts";
+import { verificationHintFor, webhookStubFor, wirePhantomForRecipe } from "./phantom-wire.ts";
+import type { Recipe } from "./recipe.ts";
+
+setDefaultTimeout(30_000);
+
+// Each known provider's own values for the stub's placeholders.
+const OWN = {
+  stripe: { header: "stripe-signature", secret: "STRIPE_WEBHOOK_SECRET", cap: "Stripe" },
+  clerk: { header: "svix-signature", secret: "CLERK_WEBHOOK_SECRET", cap: "Clerk" },
+  supabase: { header: "x-supabase-signature", secret: "SUPABASE_WEBHOOK_SECRET", cap: "Supabase" },
+  github: { header: "x-hub-signature-256", secret: "GITHUB_WEBHOOK_SECRET", cap: "Github" },
+} as const;
+type Known = keyof typeof OWN;
+const KNOWN = Object.keys(OWN) as Known[];
+
+/** Assert a stub carries this provider's values and none of the others'. */
+function expectOwnValuesOnly(stub: string, provider: Known) {
+  const own = OWN[provider];
+  expect(stub).toContain(`webhook handler stub for ${provider}.`);
+  expect(stub).toContain(`export async function handle${own.cap}Webhook(`);
+  expect(stub).toContain(`req.headers.get("${own.header}")`);
+  expect(stub).toContain(verificationHintFor(provider));
+  expect(stub.split(`phantom reveal ${own.secret}`).length - 1).toBe(2);
+  for (const other of KNOWN.filter((k) => k !== provider)) {
+    expect(stub).not.toContain(OWN[other].header);
+    expect(stub).not.toContain(OWN[other].secret);
+    expect(stub).not.toContain(`handle${OWN[other].cap}Webhook`);
+    expect(stub).not.toContain(verificationHintFor(other));
+  }
+}
+
+describe("ai/phantom-wire adjacent different known providers", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-adjacent-different-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it.each(KNOWN)("renders %s with only its own values", (provider) => {
+    expectOwnValuesOnly(webhookStubFor(provider), provider);
+  });
+
+  it("gives each adjacent provider its own stub, secrets and result slot, in order", async () => {
+    const recipe: Recipe = {
+      id: "adjacent-different",
+      query: "q",
+      createdAt: "2026-04-18T00:00:00.000Z",
+      providers: KNOWN.map((name) => ({ name })),
+    };
+    const result = await wirePhantomForRecipe(recipe, { cwd: dir });
+
+    // Webhook paths follow recipe order, one per provider.
+    expect(result.webhooks).toEqual(KNOWN.map((p) => join(dir, ".stack", "webhooks", `${p}.ts`)));
+    // Every reported secret is prefixed by its own provider, grouped in order.
+    const order = [...result.present, ...result.missing].map((e) => e.split(":")[0]);
+    const firstSeen = [...new Set(order)];
+    expect(firstSeen).toEqual(KNOWN.filter((p) => firstSeen.includes(p)));
+    expect(result.skipped).toEqual([]);
+
+    // Each file on disk carries its own provider's values only.
+    for (const [i, provider] of KNOWN.entries()) {
+      expectOwnValuesOnly(readFileSync(result.webhooks[i] as string, "utf-8"), provider);
+    }
+    // Wiring only reads the vault.
+    expect(harness.callsTo("add")).toEqual([]);
+  });
+});

package/src/ai/phantom-wire-adjacent-known-placeholders.test.ts

@@ -0,0 +1,266 @@
+import { afterEach, beforeEach, describe, expect, it, setDefaultTimeout } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type Harness, setupFakePhantom } from "../__tests__/_harness.ts";
+import { verificationHintFor, webhookStubFor, wirePhantomForRecipe } from "./phantom-wire.ts";
+import type { Recipe } from "./recipe.ts";
+
+// The wiring check spawns the fake `phantom` shim (bash + python3); keep the
+// sibling files' raised timeout.
+setDefaultTimeout(30_000);
+
+const count = (s: string, needle: string) => s.split(needle).length - 1;
+
+describe("ai/phantom-wire adjacent known placeholders in a provider name", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-adjacent-known-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "adjacent-known",
+    query: "q",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: names.map((name) => ({ name })),
+  });
+
+  it.each([
+    "${provider}${signatureHeaderFor(provider)}", // pair is the whole name
+    "${signatureHeaderFor(provider)}${provider}", // reversed order
+    "pay${capitalize(provider)}${webhookSecretKeyFor(provider)}ment", // pair mid-name
+    "hook${verificationHintFor(provider)}${provider}line", // hint slot beside the name slot
+    "${capitalize(provider)}${signatureHeaderFor(provider)}hook", // pair leads the name
+    "pay${webhookSecretKeyFor(provider)}${verificationHintFor(provider)}", // pair ends the name
+  ])("keeps the adjacent pair %j flush and in order at every expansion site", (name) => {
+    // Each token in the pair spells one of the template's own slots — both
+    // are known placeholders — but arriving inside the name they are data.
+    // They must land at all five expansion sites flush against each other,
+    // in the order the name gave them: nothing spliced between the first
+    // token's `}` and the second's `${`, neither token resolved to the value
+    // its spelling names, neither reordered.
+    const stub = webhookStubFor(name);
+    const pair = name.match(/\$\{[^}]*\}\$\{[^}]*\}/)?.[0] as string;
+    const first = pair.match(/^\$\{[^}]*\}/)?.[0] as string;
+    const second = pair.slice(first.length);
+
+    // The name — pair included — lands byte-for-byte at the three
+    // case-preserving sites and whole-name uppercased at both secret-key
+    // sites. `capitalize` folds only a leading letter; a `$`-led name is
+    // carried unchanged.
+    expect(stub).toContain(`webhook handler stub for ${name}.`);
+    expect(stub).toContain(`forge a ${name} webhook.`);
+    expect(stub).toContain(`handle${name[0].toUpperCase()}${name.slice(1)}Webhook(req: Request)`);
+    expect(count(stub, `phantom reveal ${name.toUpperCase()}_WEBHOOK_SECRET`)).toBe(2);
+
+    // Both values appear in order without extra characters: the flush pair
+    // occurs exact-case at the three mixed-case sites and uppercased
+    // together at the two secret-key sites — and at each occurrence the
+    // second token starts on the very next byte after the first ends.
+    for (const [variant, sites] of [
+      [pair, 3],
+      [pair.toUpperCase(), 2],
+    ] as const) {
+      const f = variant === pair ? first : first.toUpperCase();
+      const s = variant === pair ? second : second.toUpperCase();
+      let occurrences = 0;
+      for (let at = stub.indexOf(variant); at !== -1; at = stub.indexOf(variant, at + 1)) {
+        occurrences++;
+        expect(stub.startsWith(f, at)).toBe(true);
+        // Zero bytes between the two values: second begins exactly where
+        // first ends — no separator inserted, no byte of either eaten.
+        expect(stub.startsWith(s, at + f.length)).toBe(true);
+      }
+      expect(occurrences).toBe(sites);
+    }
+    // The pair never lands transposed, in either casing.
+    expect(stub).not.toContain(second + first);
+    expect(stub).not.toContain(second.toUpperCase() + first.toUpperCase());
+
+    // Two tokens per name × five sites: no `${` minted, dropped, or
+    // re-expanded into the value its spelling names.
+    expect(count(stub, "${")).toBe(10);
+    // The template's real slots still take their own known values, once
+    // each — the generic signature header at its own site, the fallback
+    // hint at its own — never re-spliced into a name site.
+    expect(count(stub, 'req.headers.get("x-webhook-signature")')).toBe(1);
+    expect(count(stub, "//   // Verify per the provider's documented signature scheme.")).toBe(1);
+    expect(stub).not.toContain("WEBHOOK_SECRET_WEBHOOK_SECRET");
+  });
+
+  it.each([
+    "${provider}", // the name slot's own spelling
+    "${capitalize(provider)}", // the handler-name slot's spelling
+    "${webhookSecretKeyFor(provider)}", // the secret-key slot's spelling
+    "${signatureHeaderFor(provider)}", // the header slot's spelling
+    "${verificationHintFor(provider)}", // the hint slot's spelling
+  ])(
+    "keeps the doubled token %j flush — both copies in order, nothing between — at every expansion site",
+    (slot) => {
+      // The whole name is one known placeholder spelling written twice,
+      // back-to-back: an adjacent pair whose two values are identical, so
+      // "in order" is purely positional — the first copy occupies its span
+      // and the second begins on the very byte the first ends. Each copy is
+      // data: neither may resolve to the value its spelling names, merge
+      // into a single span, gain a separator, or re-expand into a third.
+      const name = `${slot}${slot}`;
+      const stub = webhookStubFor(name);
+
+      // The name — both copies included — lands byte-for-byte at the three
+      // case-preserving sites and whole-name uppercased at both secret-key
+      // sites. `capitalize` leaves the `$`-led name unchanged.
+      expect(stub).toContain(`webhook handler stub for ${name}.`);
+      expect(stub).toContain(`forge a ${name} webhook.`);
+      expect(stub).toContain(`handle${name}Webhook(req: Request)`);
+      expect(count(stub, `phantom reveal ${name.toUpperCase()}_WEBHOOK_SECRET`)).toBe(2);
+
+      // Both values appear in order without added characters: the flush
+      // pair occurs exact-case at the three mixed-case sites and uppercased
+      // together at the two secret-key sites — at each occurrence the first
+      // copy fills its span and the second starts on the byte it ends.
+      for (const [pair, sites] of [
+        [slot + slot, 3],
+        [(slot + slot).toUpperCase(), 2],
+      ] as const) {
+        const v = pair === slot + slot ? slot : slot.toUpperCase();
+        let occurrences = 0;
+        for (let at = stub.indexOf(pair); at !== -1; at = stub.indexOf(pair, at + 1)) {
+          occurrences++;
+          expect(stub.startsWith(v, at)).toBe(true);
+          // Zero bytes between the two values: the second copy begins
+          // exactly where the first ends — no separator inserted, no byte
+          // of either eaten.
+          expect(stub.startsWith(v, at + v.length)).toBe(true);
+        }
+        expect(occurrences).toBe(sites);
+
+        // Every single-token occurrence belongs to a flush pair: scan the
+        // lone spelling and require a sibling touching it on exactly one
+        // side — a lone token or a pair with a spliced separator fails here.
+        let singles = 0;
+        for (let at = stub.indexOf(v); at !== -1; at = stub.indexOf(v, at + 1)) {
+          singles++;
+          const leftSibling = at >= v.length && stub.startsWith(v, at - v.length);
+          const rightSibling = stub.startsWith(v, at + v.length);
+          expect(leftSibling !== rightSibling).toBe(true);
+        }
+        expect(singles).toBe(sites * 2);
+      }
+
+      // No third copy: a duplication or re-expansion would mint a longer
+      // run — absent in either casing.
+      expect(stub).not.toContain(slot + slot + slot);
+      expect(stub).not.toContain((slot + slot + slot).toUpperCase());
+
+      // Two copies per name × five sites: no `${` minted, dropped, or
+      // fused — each copy stays its own `${...}` span.
+      expect(count(stub, "${")).toBe(10);
+      const tokens = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+      expect(tokens).toHaveLength(10);
+      for (const token of tokens) expect(token.toLowerCase()).toBe(slot.toLowerCase());
+
+      // The template's real slots still take their own known values, once
+      // each — never re-spliced into a name site.
+      expect(count(stub, 'req.headers.get("x-webhook-signature")')).toBe(1);
+      expect(count(stub, "//   // Verify per the provider's documented signature scheme.")).toBe(1);
+      expect(verificationHintFor(name)).toBe(verificationHintFor("zzq"));
+    },
+  );
+
+  it("keeps a three-token run flush and in order at every expansion site", () => {
+    // Adjacency generalizes: three known spellings back-to-back inside the
+    // name. The run is data — each site's expansion emits all three tokens
+    // in the name's order, the next starting on the byte the previous ends,
+    // with no inserted separator and the middle token neither dropped nor
+    // reseated.
+    const t1 = "${provider}";
+    const t2 = "${capitalize(provider)}";
+    const t3 = "${signatureHeaderFor(provider)}";
+    const name = `${t1}${t2}${t3}trail`;
+    const run = t1 + t2 + t3;
+    const stub = webhookStubFor(name);
+
+    // The name — run included — lands byte-for-byte at the three
+    // case-preserving sites and whole-name uppercased at both secret-key
+    // sites. `capitalize` leaves the `$`-led name unchanged.
+    expect(stub).toContain(`webhook handler stub for ${name}.`);
+    expect(stub).toContain(`forge a ${name} webhook.`);
+    expect(stub).toContain(`handle${name}Webhook(req: Request)`);
+    expect(count(stub, `phantom reveal ${name.toUpperCase()}_WEBHOOK_SECRET`)).toBe(2);
+
+    // At every occurrence, in both casings: the three values sit in the
+    // name's order, each starting on the byte the previous one ends.
+    for (const [variant, sites] of [
+      [run, 3],
+      [run.toUpperCase(), 2],
+    ] as const) {
+      const [a, b, c] =
+        variant === run ? [t1, t2, t3] : [t1.toUpperCase(), t2.toUpperCase(), t3.toUpperCase()];
+      let occurrences = 0;
+      for (let at = stub.indexOf(variant); at !== -1; at = stub.indexOf(variant, at + 1)) {
+        occurrences++;
+        expect(stub.startsWith(a, at)).toBe(true);
+        // Zero bytes between values: b begins exactly where a ends, c
+        // exactly where b ends — no separator inserted, no byte eaten.
+        expect(stub.startsWith(b, at + a.length)).toBe(true);
+        expect(stub.startsWith(c, at + a.length + b.length)).toBe(true);
+      }
+      expect(occurrences).toBe(sites);
+    }
+
+    // No reordering: neither adjacent swap nor the reversed run appears,
+    // in either casing.
+    for (const swapped of [t2 + t1, t3 + t2, t3 + t2 + t1]) {
+      expect(stub).not.toContain(swapped);
+      expect(stub).not.toContain(swapped.toUpperCase());
+    }
+
+    // Three tokens per name × five sites: no `${` minted, dropped, or
+    // re-expanded into the value its spelling names.
+    expect(count(stub, "${")).toBe(15);
+    // The template's real slots still take their own values, once each.
+    expect(count(stub, 'req.headers.get("x-webhook-signature")')).toBe(1);
+    expect(count(stub, "//   // Verify per the provider's documented signature scheme.")).toBe(1);
+  });
+
+  it("skips a pair-carrying name byte-for-byte through wiring and writes nothing for it", async () => {
+    // Through `wirePhantomForRecipe` the name matches no catalog provider:
+    // it returns in `skipped` byte-for-byte — both tokens and their flush
+    // adjacency intact — gets no stub on disk, and provokes no vault write.
+    // The known provider listed beside it wires normally.
+    const name = "pay${capitalize(provider)}${webhookSecretKeyFor(provider)}ment";
+    const stubPath = join(dir, ".stack", "webhooks", "stripe.ts");
+    const result = await wirePhantomForRecipe(recipe(name, "stripe"), { cwd: dir });
+
+    expect(result).toEqual({
+      present: [],
+      missing: ["stripe:STRIPE_SECRET_KEY"],
+      webhooks: [stubPath],
+      skipped: [name],
+    });
+    expect(result.skipped[0]).toBe(name);
+
+    // Only stripe's documented stub lands — nothing for the pair-carrying
+    // name, and the stub on disk is the same render `webhookStubFor`
+    // returns, fully substituted.
+    expect(readdirSync(join(dir, ".stack", "webhooks"))).toEqual(["stripe.ts"]);
+    expect(readFileSync(stubPath, "utf-8")).toBe(webhookStubFor("stripe"));
+    expect(existsSync(join(dir, ".stack", "webhooks", `${name}.ts`))).toBe(false);
+
+    // The whole call log is reads (`--version`, `list`); the vault file
+    // still parses to an empty object.
+    expect(harness.calls().every((c) => c.cmd === "--version" || c.cmd === "list")).toBe(true);
+    expect(harness.callsTo("add")).toEqual([]);
+    expect(JSON.parse(readFileSync(harness.vaultPath, "utf-8"))).toEqual({});
+
+    // The hint is a fixed string: a pair-carrying name never leaks into it.
+    expect(verificationHintFor(name)).toBe(verificationHintFor("zzq"));
+  });
+});

package/src/ai/phantom-wire-args.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, beforeEach, describe, expect, it, setDefaultTimeout } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type Harness, setupFakePhantom } from "../__tests__/_harness.ts";
+import { exec } from "../phantom.ts";
+import { wirePhantomForRecipe } from "./phantom-wire.ts";
+import type { Recipe } from "./recipe.ts";
+
+// Each test spawns the fake `phantom` shim (bash + python3).
+setDefaultTimeout(30_000);
+
+describe("ai/phantom-wire argv handling with spaces", () => {
+  let harness: Harness;
+  let spaced: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom({ STRIPE_SECRET_KEY: "x" });
+    spaced = join(mkdtempSync(join(tmpdir(), "stack wire args-")), "my project dir");
+    mkdirSync(spaced, { recursive: true });
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(join(spaced, ".."), { recursive: true, force: true });
+  });
+
+  const recipe = (name: string): Recipe => ({
+    id: "spaces",
+    query: "q",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: [{ name }],
+  });
+
+  it("runs phantom with fixed argv and a project path containing spaces intact", async () => {
+    const result = await wirePhantomForRecipe(recipe("stripe"), { cwd: spaced });
+
+    // The spaced path is the child's cwd, never split into argv.
+    const list = harness.callsTo("list");
+    expect(list).toHaveLength(1);
+    expect(list[0]?.args).toEqual(["--json"]);
+    expect(result.present).toContain("stripe:STRIPE_SECRET_KEY");
+    expect(result.webhooks).toEqual([join(spaced, ".stack", "webhooks", "stripe.ts")]);
+    expect(readFileSync(result.webhooks[0] as string, "utf-8")).toContain("stripe");
+  });
+
+  it("never forwards a provider name containing spaces to phantom", async () => {
+    const result = await wirePhantomForRecipe(recipe("my provider name"), { cwd: spaced });
+
+    expect(result.skipped).toEqual(["my provider name"]);
+    for (const call of harness.calls()) {
+      expect(call.args.join("\0")).not.toContain("my provider name");
+    }
+  });
+
+  it("delivers an argument containing spaces to the subprocess as one argument", async () => {
+    const value = "SECRET WITH  SPACES";
+    await exec(["remove", value], { cwd: spaced, allowFailure: true });
+
+    const calls = harness.callsTo("remove");
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.args).toEqual([value]);
+  });
+});

package/src/ai/phantom-wire-blank-lines.test.ts

@@ -0,0 +1,174 @@
+import { afterEach, beforeEach, describe, expect, it, setDefaultTimeout } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type Harness, setupFakePhantom } from "../__tests__/_harness.ts";
+import { verificationHintFor, webhookStubFor, wirePhantomForRecipe } from "./phantom-wire.ts";
+import type { Recipe } from "./recipe.ts";
+
+// The wiring check spawns the fake `phantom` shim (bash + python3); keep the
+// sibling files' raised timeout.
+setDefaultTimeout(30_000);
+
+// Each of the template's own slot spellings, usable inside a provider name
+// as a known placeholder.
+const SLOT_TOKENS = [
+  "${provider}", // the name slot's own spelling
+  "${capitalize(provider)}", // the handler-name slot's spelling
+  "${webhookSecretKeyFor(provider)}", // the secret-key slot's spelling
+  "${signatureHeaderFor(provider)}", // the header slot's spelling
+  "${verificationHintFor(provider)}", // the hint slot's spelling
+];
+
+// A blank line is a newline with another newline right behind it. Counting
+// the `\n`s that run straight into a second `\n` needs no assumptions about
+// where the run sits: a run of k consecutive newlines — leading, trailing,
+// or interior — always scores k-1 blank lines, and a run of one scores 0.
+const blankLines = (s: string) => s.match(/\n(?=\n)/g)?.length ?? 0;
+
+const count = (s: string, needle: string) => s.split(needle).length - 1;
+
+describe("ai/phantom-wire known placeholder in a multiline template with blank lines", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-blank-lines-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "blank-lines",
+    query: "q",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: names.map((name) => ({ name })),
+  });
+
+  it.each(SLOT_TOKENS.map((token) => `alpha\n\n${token}\n\nomega`))(
+    "preserves the blank lines around the carried token %j at every expansion site",
+    (name) => {
+      // The name is itself a little multiline template: ordinary text, a
+      // blank line, one of the stub's own slot spellings on a line of its
+      // own, another blank line, more text. As replacement text the whole
+      // thing is data — a resolver would resolve the token away, a
+      // whitespace normalizer would collapse the doubled newlines. The
+      // template's single pass does neither: the name lands at each of the
+      // five expansion sites with token and blank lines intact.
+      const stub = webhookStubFor(name);
+      const token = name.match(/\$\{[^}]*\}/)?.[0] as string;
+      const capitalized = `${name[0].toUpperCase()}${name.slice(1)}`;
+
+      // The three case-preserving sites carry the name — blank lines and
+      // carried token included — byte-for-byte; `capitalize` folds only
+      // the name's first letter at the handler site.
+      expect(stub).toContain(`webhook handler stub for ${name}.`);
+      expect(stub).toContain(`forge a ${name} webhook.`);
+      expect(stub).toContain(`handle${capitalized}Webhook(req: Request)`);
+      // `webhookSecretKeyFor(provider)` uppercases the whole name: the
+      // letters fold, the newline bytes and the token's `$`/`{`/`}` do
+      // not. Both reveal lines hold the folded name, blank runs and all.
+      expect(count(stub, `phantom reveal ${name.toUpperCase()}_WEBHOOK_SECRET`)).toBe(2);
+
+      // The stub template itself contains not one blank line — its comment
+      // lines all carry at least `//` — so every blank line in the output
+      // is one the name carried. Two blank lines in the name x five
+      // expansion sites: substitution preserved all ten, collapsing none
+      // and minting none.
+      expect(blankLines(webhookStubFor("plain"))).toBe(0);
+      expect(blankLines(name)).toBe(2);
+      expect(blankLines(stub)).toBe(5 * blankLines(name));
+
+      // The carried token still sits on its own line between the name's
+      // two blank lines at every site — in original case at the two
+      // verbatim sites plus the handler site (interior text is
+      // untouched), uppercased at the two reveal sites.
+      expect(count(stub, `\n\n${token}\n\n`)).toBe(3);
+      expect(count(stub, `\n\n${token.toUpperCase()}\n\n`)).toBe(2);
+
+      // Five `${...}` spans — one per expansion site — every one the
+      // carried token in that site's case, none resolved away or doubled.
+      const tokens = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+      expect(tokens).toHaveLength(5);
+      for (const t of tokens) expect(t.toLowerCase()).toBe(token.toLowerCase());
+
+      // The remaining slots took their own generic values in the same
+      // single pass — the carried token never reached their switch cases.
+      expect(stub).toContain('req.headers.get("x-webhook-signature")');
+      expect(stub).toContain("//   // Verify per the provider's documented signature scheme.");
+      expect(verificationHintFor(name)).toBe(verificationHintFor("zzq"));
+    },
+  );
+
+  it.each([
+    "${provider}\n\nbody", // token on the first line, one blank line after
+    "head\n\n\n${provider}\n\n\ntail", // two blank lines on each side
+    "one\n\ntwo\n\n${provider}", // stacked blanks, token on the last line
+    "\n\n${provider}\n\n", // nothing but blank lines around the token
+  ])("preserves the blank lines in %j around the carried token", (name) => {
+    // Leading, trailing, and doubled blank runs are the same data. `\n`
+    // has no case mapping — `capitalize` and `toUpperCase` both leave
+    // every newline byte alone — so each blank line lands once per
+    // expansion site and the count scales exactly with the name's.
+    const stub = webhookStubFor(name);
+    const capitalized = `${name[0].toUpperCase()}${name.slice(1)}`;
+
+    expect(stub).toContain(`webhook handler stub for ${name}.`);
+    expect(stub).toContain(`forge a ${name} webhook.`);
+    expect(stub).toContain(`handle${capitalized}Webhook(req: Request)`);
+    expect(count(stub, `phantom reveal ${name.toUpperCase()}_WEBHOOK_SECRET`)).toBe(2);
+
+    // The name's blank lines survive verbatim at the case-preserving
+    // sites: `stub for ${name}.` holds every run the name contains.
+    // Escaped sequences would show as literal `\` `n` pairs instead.
+    expect(blankLines(stub)).toBe(5 * blankLines(name));
+    expect(stub).not.toContain("\\n");
+
+    // Still five expansion sites, still one carried `${provider}` token at
+    // each — blank lines change nothing about the substitution's arity.
+    const tokens = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+    expect(tokens).toHaveLength(5);
+    for (const t of tokens) expect(t.toLowerCase()).toBe("${provider}");
+
+    // The fixed slots resolved to their generic values in the same pass.
+    expect(stub).toContain('req.headers.get("x-webhook-signature")');
+    expect(stub).toContain("//   // Verify per the provider's documented signature scheme.");
+    expect(verificationHintFor(name)).toBe(verificationHintFor("zzq"));
+  });
+
+  it("skips a blank-line template name byte-for-byte through wiring and writes nothing for it", async () => {
+    // Through `wirePhantomForRecipe` the multiline name matches no catalog
+    // provider: it returns in `skipped` byte-for-byte — token, text, and
+    // both blank lines intact — gets no stub on disk, and provokes no
+    // vault write. The known provider listed beside it wires normally,
+    // unaffected by the template-shaped neighbour.
+    const name = "alpha\n\n${provider}\n\nomega";
+    const stubPath = join(dir, ".stack", "webhooks", "stripe.ts");
+    const result = await wirePhantomForRecipe(recipe(name, "stripe"), { cwd: dir });
+
+    expect(result).toEqual({
+      present: [],
+      missing: ["stripe:STRIPE_SECRET_KEY"],
+      webhooks: [stubPath],
+      skipped: [name],
+    });
+    expect(result.skipped[0]).toBe(name);
+    expect(blankLines(result.skipped[0] ?? "")).toBe(2);
+
+    // Only stripe's documented stub lands — nothing for the multiline
+    // name, and the stub on disk is the same render `webhookStubFor`
+    // returns.
+    expect(readdirSync(join(dir, ".stack", "webhooks"))).toEqual(["stripe.ts"]);
+    expect(readFileSync(stubPath, "utf-8")).toBe(webhookStubFor("stripe"));
+    expect(existsSync(join(dir, ".stack", "webhooks", `${name}.ts`))).toBe(false);
+
+    // The whole call log is reads (`--version`, `list`); the vault file
+    // still parses to an empty object.
+    expect(harness.calls().every((c) => c.cmd === "--version" || c.cmd === "list")).toBe(true);
+    expect(harness.callsTo("add")).toEqual([]);
+    expect(JSON.parse(readFileSync(harness.vaultPath, "utf-8"))).toEqual({});
+  });
+});