@ashlr/stack-core 0.3.0 → 0.3.6

package/src/ai/phantom-wire-carriage-return.test.ts

@@ -0,0 +1,125 @@
+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 as a provider name that
+// spells 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
+];
+
+describe("ai/phantom-wire known placeholder beside a carriage return", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-placeholder-cr-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "placeholder-cr",
+    query: "q",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: names.map((name) => ({ name })),
+  });
+
+  it.each(SLOT_TOKENS.flatMap((token) => [`${token}\r`, `\r${token}`]))(
+    "replaces every slot and preserves the carriage return beside the carried token in %j",
+    (name) => {
+      // The name is exactly one known placeholder token with a carriage
+      // return seated beside it — before it or after it, no ordinary text.
+      // Expansion fills the five name-carrying sites with the name itself,
+      // so the rendered stub holds the token and the CR still adjacent in
+      // the input's own order: a resolver would resolve the token away, a
+      // sanitizer would strip or escape the control byte, a newline
+      // normalization would rewrite it as CRLF. None of that runs.
+      const stub = webhookStubFor(name);
+      const token = name.replace("\r", "");
+
+      // The three case-preserving sites carry the name byte-for-byte —
+      // token, CR and all. `capitalize` folds only the first code point,
+      // and both `$` and `\r` uppercase to themselves, so the handler site
+      // holds the identical bytes.
+      expect(stub).toContain(`webhook handler stub for ${name}.`);
+      expect(stub).toContain(`forge a ${name} webhook.`);
+      expect(stub).toContain(`handle${name}Webhook(req: Request)`);
+      // The two `toUpperCase()` reveal sites carry the folded name; `\r`
+      // folds to itself, so the CR sits beside the folded token there too.
+      expect(stub.split(`phantom reveal ${name.toUpperCase()}_WEBHOOK_SECRET`).length - 1).toBe(2);
+
+      // Five name sites, five carriage returns — none stripped, doubled or
+      // moved. Each sits exactly where the name put it: adjacent to the
+      // carried token, on the same side it occupied in the input.
+      expect(stub.split("\r").length - 1).toBe(5);
+      const adjacent = name.startsWith("\r") ? /\r\$\{[^}]*\}/g : /\$\{[^}]*\}\r/g;
+      expect(stub.match(adjacent)).toHaveLength(5);
+      // The byte is data, not a line ending: the stub still contains no
+      // CRLF, and the template's own `.\n` still terminates the title line
+      // right after the CR-carrying name.
+      expect(stub).not.toContain("\r\n");
+      expect(stub).toContain(`${name}.\n`);
+
+      // Every `${...}` in the output is the carried token in that site's
+      // case — five expansion sites, five occurrences, none resolved away.
+      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 values in the same single pass:
+      // the generic signature header and the fallback hint — the carried
+      // token never reached their switch cases either.
+      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 CR-carrying placeholder 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 — token and carriage return
+    // intact — gets no stub on disk, and provokes no vault write. The
+    // known provider listed beside it wires normally, unaffected by the
+    // control-byte neighbour.
+    const name = "${provider}\r";
+    const stubPath = join(dir, ".stack", "webhooks", "github.ts");
+    const result = await wirePhantomForRecipe(recipe(name, "github"), { cwd: dir });
+
+    expect(result).toEqual({
+      present: [],
+      missing: ["github:GITHUB_TOKEN"],
+      webhooks: [stubPath],
+      skipped: [name],
+    });
+    expect(result.skipped[0]).toBe(name);
+
+    // Only github's documented stub lands — nothing for the CR-carrying
+    // name, and the stub on disk is the same render `webhookStubFor`
+    // returns.
+    expect(readdirSync(join(dir, ".stack", "webhooks"))).toEqual(["github.ts"]);
+    expect(readFileSync(stubPath, "utf-8")).toBe(webhookStubFor("github"));
+    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({});
+  });
+});

package/src/ai/phantom-wire-case-changed-placeholder.test.ts

@@ -0,0 +1,209 @@
+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 case-changed placeholder name", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-case-changed-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "case-changed",
+    query: "q",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: names.map((name) => ({ name })),
+  });
+
+  it.each([
+    ["${Provider}", "${provider}"], // name slot, first letter up
+    ["${CAPITALIZE(provider)}", "${capitalize(provider)}"], // handler slot, callee uppercased
+    ["${webhooksecretkeyfor(provider)}", "${webhookSecretKeyFor(provider)}"], // key slot, all lower
+    ["${SignatureHeaderFor(Provider)}", "${signatureHeaderFor(provider)}"], // header slot, mixed
+    ["${VERIFICATIONHINTFOR(PROVIDER)}", "${verificationHintFor(provider)}"], // hint slot, all caps
+  ])(
+    "keeps the case-changed spelling %j literal at every site — never normalized to %j",
+    (name, slot) => {
+      // Placeholder matching is case-sensitive end to end: only the exact
+      // spelling names a slot. A whole-name token in any other case is plain
+      // data — it reaches all five expansion sites in its own case (or
+      // folded at the `toUpperCase()` sites), is never rewritten to the
+      // slot's exact spelling, and never resolves into the value the exact
+      // spelling would name. The template's real slots take their generic
+      // values around it.
+      const stub = webhookStubFor(name);
+
+      // The name lands byte-for-byte at the three case-preserving sites and
+      // whole-name uppercased at the two secret-key sites; `capitalize`
+      // folds only a leading letter and `$` uppercases to itself.
+      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);
+
+      // The exact-case slot spelling appears nowhere: the carried token was
+      // emitted verbatim or folded, never recognized and re-emitted in
+      // canonical slot case.
+      expect(stub).not.toContain(slot);
+
+      // Five `${...}` spans — one per expansion site — every one the
+      // carried token in one of the two casings the name legitimately
+      // takes; none resolved away, none minted in the slot's own case.
+      const tokens = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+      expect(tokens).toHaveLength(5);
+      for (const token of tokens) expect(token.toLowerCase()).toBe(name.toLowerCase());
+
+      // Unrelated text renders normally around the carried token: the
+      // signature-header and hint slots took the generic values the
+      // case-sensitive switches fall through to for a non-provider name.
+      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 the ordinary text flanking a case-changed token byte-for-byte at every site", () => {
+    // `pre${Provider}post` seats a case-changed `${provider}`-lookalike
+    // between unrelated text. The flanks and the token's own case reach
+    // every expansion site untouched: the token is never folded to the
+    // exact slot spelling and the surrounding `pre`/`post` is never eaten,
+    // doubled, or merged into a value.
+    const name = "pre${Provider}post";
+    const stub = webhookStubFor(name);
+
+    // Case-preserving sites carry the whole name byte-for-byte;
+    // `capitalize` folds only the first letter; the two reveal sites fold
+    // token and flanks together.
+    expect(stub).toContain(`webhook handler stub for ${name}.`);
+    expect(stub).toContain(`forge a ${name} webhook.`);
+    expect(stub).toContain("handlePre${Provider}postWebhook(req: Request)");
+    expect(count(stub, "phantom reveal PRE${PROVIDER}POST_WEBHOOK_SECRET")).toBe(2);
+
+    // Each token still sits between exactly one `pre` and one `post`, in
+    // whatever case that site's transform gives them — five sites, five
+    // seated occurrences — and never in the all-lowercase spelling an
+    // exact-match resolver would have used.
+    expect(stub.match(/pre\$\{provider\}post/gi)).toHaveLength(5);
+    expect(stub).not.toContain("pre${provider}post");
+    // `pre`+token+`post` verbatim at title and forge, `Pre`-folded at the
+    // handler site, fully folded at both reveal sites.
+    expect(count(stub, "pre${Provider}post")).toBe(2);
+    expect(count(stub, "Pre${Provider}post")).toBe(1);
+    expect(count(stub, "PRE${PROVIDER}POST")).toBe(2);
+
+    // The remaining slots took their generic values in the same single 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.each(["Stripe", "STRIPE", "sTrIpE"])(
+    "misses every case-sensitive lookup for the case-changed provider name %s",
+    (name) => {
+      // `stripe` is a known provider only in its exact spelling. Changing
+      // any letter's case makes every match miss: the signature header and
+      // the verification hint fall through to their generic defaults
+      // instead of stripe's — the contract is byte equality, not folding.
+      const stub = webhookStubFor(name);
+      const capitalized = `${name[0].toUpperCase()}${name.slice(1)}`;
+
+      // The name sites still carry the supplied case verbatim.
+      expect(stub).toContain(`webhook handler stub for ${name}.`);
+      expect(stub).toContain(`forge a ${name} webhook.`);
+      expect(stub).toContain(`handle${capitalized}Webhook(req: Request)`);
+
+      // The misses: generic header, generic hint — stripe's own values
+      // appear nowhere in the render.
+      expect(count(stub, 'req.headers.get("x-webhook-signature")')).toBe(1);
+      expect(stub).not.toContain("stripe-signature");
+      expect(stub).toContain("//   // Verify per the provider's documented signature scheme.");
+      expect(stub).not.toContain("stripe.webhooks.constructEvent");
+      expect(verificationHintFor(name)).toBe(verificationHintFor("zzq"));
+
+      // Both reveal sites still spell `STRIPE_WEBHOOK_SECRET` — the default
+      // branch's whole-name `toUpperCase()`, not a match on stripe's case.
+      // Same bytes, different reason.
+      expect(count(stub, "phantom reveal STRIPE_WEBHOOK_SECRET")).toBe(2);
+    },
+  );
+
+  it("skips a case-changed provider name through wiring while the exact-case twin wires normally", async () => {
+    // `Stripe` differs from `stripe` by one letter's case. The catalog
+    // lookup and the webhook-provider set are case-sensitive: the variant
+    // returns in `skipped` byte-for-byte, writes no stub, provokes no vault
+    // write — while the exact-case name beside it wires normally.
+    const stubPath = join(dir, ".stack", "webhooks", "stripe.ts");
+    const result = await wirePhantomForRecipe(recipe("Stripe", "stripe"), { cwd: dir });
+
+    expect(result).toEqual({
+      present: [],
+      missing: ["stripe:STRIPE_SECRET_KEY"],
+      webhooks: [stubPath],
+      skipped: ["Stripe"],
+    });
+    // Byte-for-byte: the skipped name kept its case — not folded to `stripe`.
+    expect(result.skipped[0]).toBe("Stripe");
+
+    // Only stripe's documented stub lands — the directory listing holds
+    // exactly `stripe.ts` — and the stub on disk is the same render
+    // `webhookStubFor` returns. (`existsSync` can't stand in here: on a
+    // case-insensitive filesystem `Stripe.ts` resolves to `stripe.ts`, so
+    // the listing is the check that no second file was written.)
+    expect(readdirSync(join(dir, ".stack", "webhooks"))).toEqual(["stripe.ts"]);
+    expect(readFileSync(stubPath, "utf-8")).toBe(webhookStubFor("stripe"));
+
+    // 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({});
+  });
+
+  it("skips a whole-name case-changed token byte-for-byte through wiring and writes nothing for it", async () => {
+    // Through `wirePhantomForRecipe` the case-changed slot spelling matches
+    // no catalog provider: it returns in `skipped` byte-for-byte — its case
+    // intact, not normalized to the exact spelling — gets no stub on disk,
+    // and provokes no vault write. The known provider listed beside it
+    // wires normally, unaffected by the placeholder-shaped neighbour.
+    const name = "${Provider}";
+    const stubPath = join(dir, ".stack", "webhooks", "github.ts");
+    const result = await wirePhantomForRecipe(recipe(name, "github"), { cwd: dir });
+
+    expect(result).toEqual({
+      present: [],
+      missing: ["github:GITHUB_TOKEN"],
+      webhooks: [stubPath],
+      skipped: [name],
+    });
+    expect(result.skipped[0]).toBe(name);
+
+    // Only github's documented stub lands — nothing for the token name —
+    // and the stub on disk is the same render `webhookStubFor` returns.
+    expect(readdirSync(join(dir, ".stack", "webhooks"))).toEqual(["github.ts"]);
+    expect(readFileSync(stubPath, "utf-8")).toBe(webhookStubFor("github"));
+    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({});
+  });
+});

package/src/ai/phantom-wire-closing-brace.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "bun:test";
+import { webhookStubFor } from "./phantom-wire.ts";
+
+describe("webhook stub closing braces", () => {
+  it("preserves a lone closing brace and its surrounding interpolated prose", () => {
+    const stub = webhookStubFor("before}after");
+
+    expect(stub.split("\n")[0]).toBe(
+      "// Auto-generated by `stack apply` — webhook handler stub for before}after.",
+    );
+    expect(stub).toContain("//   // to this endpoint can forge a before}after webhook.\n");
+    expect(stub).toContain(
+      '//   // parse, trust, or act on the body.\n//   return new Response("ok", { status: 200 });\n// }\n',
+    );
+  });
+});

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

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "bun:test";
+import { verificationHintFor, webhookStubFor } from "./phantom-wire.ts";
+
+const crlfCount = (s: string) => s.split("\r\n").length - 1;
+
+describe("ai/phantom-wire replacement text containing CRLF", () => {
+  it("keeps the exact CRLF bytes at all five expansion sites", () => {
+    // CR+LF in the name is data: it must come out as the two bytes 0x0D 0x0A
+    // at every site, not normalized to LF, not split, not escaped.
+    const stub = webhookStubFor("a\r\nb");
+    const flat = webhookStubFor("ab");
+
+    expect(stub).toContain("webhook handler stub for a\r\nb.");
+    expect(stub).toContain("forge a a\r\nb webhook.");
+    expect(stub).toContain("handleA\r\nbWebhook(req: Request)");
+    expect(stub.split("phantom reveal A\r\nB_WEBHOOK_SECRET").length - 1).toBe(2);
+
+    // Template is LF-only, so every CRLF in the output is one we inserted.
+    expect(crlfCount(webhookStubFor("a\nb"))).toBe(0);
+    expect(crlfCount(stub)).toBe(5);
+    expect(stub.split("\r").length - 1).toBe(5);
+    expect(stub.split("\n").length - 1).toBe(flat.split("\n").length - 1 + 5);
+    expect(stub).not.toContain("\\r");
+    expect(stub).not.toContain("\\n");
+    expect(stub).not.toContain("${");
+
+    // Byte-level pin right after the first site.
+    const at = stub.indexOf("stub for a") + "stub for a".length;
+    expect([stub.charCodeAt(at), stub.charCodeAt(at + 1)]).toEqual([0x0d, 0x0a]);
+
+    expect(verificationHintFor("a\r\nb")).toBe(verificationHintFor("zzq"));
+  });
+
+  it.each(["\r\n", "x\r\n", "\r\nx", "a\r\n\r\nb", "a\n\rb"])(
+    "preserves every CR and LF byte of %j in order",
+    (name) => {
+      const stub = webhookStubFor(name);
+      const flat = webhookStubFor(name.replace(/[\r\n]/g, ""));
+      const count = (s: string, ch: string) => s.split(ch).length - 1;
+
+      expect(stub).toContain(`webhook handler stub for ${name}.`);
+      expect(stub).toContain(`forge a ${name} webhook.`);
+      expect(count(stub, "\r")).toBe(count(flat, "\r") + 5 * count(name, "\r"));
+      expect(count(stub, "\n")).toBe(count(flat, "\n") + 5 * count(name, "\n"));
+      expect(crlfCount(stub)).toBe(crlfCount(flat) + 5 * crlfCount(name));
+    },
+  );
+});

package/src/ai/phantom-wire-dollar-amp.test.ts

@@ -0,0 +1,128 @@
+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);
+
+describe("ai/phantom-wire literal `$&` in replacement text", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-dollar-amp-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "dollar-amp",
+    query: "q",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: names.map((name) => ({ name })),
+  });
+
+  it("keeps the bare `$&` match token as the whole name byte-for-byte at every site", () => {
+    // `$&` is the String.replace replacement pattern that splices in the
+    // matched substring — the slot spelling itself here. If expansion ever
+    // ran through replace, a whole name of `$&` would vanish into
+    // `${provider}` (or `${webhookSecretKeyFor(provider)}`, etc.) at every
+    // site: the two characters gone, placeholder-shaped residue in their
+    // place. Carried as data through a single template pass the name is
+    // just `$&` — and since neither `$` nor `&` has a case mapping, even
+    // the `capitalize` and `toUpperCase` sites emit the identical bytes.
+    const stub = webhookStubFor("$&");
+
+    expect(stub).toContain("webhook handler stub for $&.");
+    expect(stub).toContain("handle$&Webhook(req: Request)");
+    expect(stub).toContain("forge a $& webhook.");
+    expect(stub.split("phantom reveal $&_WEBHOOK_SECRET").length - 1).toBe(2);
+
+    // Five expansion sites, one `$&` each — none spliced into the match. A
+    // replace-driven render would show zero `$&` and `${...}` residue.
+    expect(stub.split("$&").length - 1).toBe(5);
+    expect(stub).not.toContain("${");
+
+    // The remaining slots resolved to their own values in the same pass:
+    // the generic signature header and the fallback hint.
+    expect(stub).toContain('req.headers.get("x-webhook-signature")');
+    expect(stub).toContain("//   // Verify per the provider's documented signature scheme.");
+    expect(verificationHintFor("$&")).toBe(verificationHintFor("zzq"));
+  });
+
+  it.each(["$&hook", "hook$&", "$&$&", "a$&$&b"])(
+    "keeps every literal `$&` in %j at all five expansion sites",
+    (name) => {
+      // Leading, trailing, and adjacent tokens are the same data. Under
+      // replace semantics each `$&` would splice in the match — `a$&$&b`
+      // would come out `a${provider}${provider}b`. Rendered as a name every
+      // token survives at all five sites; the case folds touch only the
+      // letters around them, never the two characters themselves.
+      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(stub.split(`phantom reveal ${name.toUpperCase()}_WEBHOOK_SECRET`).length - 1).toBe(2);
+
+      // Each `$&` in the name lands once per expansion site — the count
+      // scales with the token count — and no `${...}` residue was spliced.
+      expect(stub.split("$&").length - 1).toBe(5 * (name.split("$&").length - 1));
+      expect(stub).not.toContain("${");
+    },
+  );
+
+  it("preserves `$&` after an astral initial at every expansion site", () => {
+    const stub = webhookStubFor("𐐨$&tail");
+
+    expect(stub).toContain("webhook handler stub for 𐐨$&tail.");
+    expect(stub).toContain("handle𐐀$&tailWebhook(req: Request)");
+    expect(stub).toContain("forge a 𐐨$&tail webhook.");
+    expect(stub.split("phantom reveal 𐐀$&TAIL_WEBHOOK_SECRET")).toHaveLength(3);
+    expect(stub.split("$&")).toHaveLength(6);
+  });
+
+  it("skips `$&` names byte-for-byte through wiring and writes nothing for them", async () => {
+    // Through `wirePhantomForRecipe` the bare and doubled tokens match no
+    // catalog provider: both return in `skipped` byte-for-byte — every `$`
+    // and `&` intact, in order — get no stub on disk, and provoke no vault
+    // write. The known provider listed beside them wires normally,
+    // unaffected by the match-token-shaped neighbours.
+    const stubPath = join(dir, ".stack", "webhooks", "clerk.ts");
+    const result = await wirePhantomForRecipe(recipe("$&", "$&$&", "clerk"), { cwd: dir });
+
+    expect(result).toEqual({
+      present: [],
+      missing: ["clerk:CLERK_SECRET_KEY"],
+      webhooks: [stubPath],
+      skipped: ["$&", "$&$&"],
+    });
+    // Byte-level pin: `$` is 0x24 and `&` is 0x26 — the pair survives the
+    // catalog lookup and the skip path unconsumed.
+    expect(result.skipped[0]?.charCodeAt(0)).toBe(0x24);
+    expect(result.skipped[0]?.charCodeAt(1)).toBe(0x26);
+    expect(result.skipped[1]?.split("$&").length - 1).toBe(2);
+
+    // Only clerk's documented stub lands — nothing for the `$&` names, and
+    // the stub on disk is the same render `webhookStubFor` returns.
+    expect(readdirSync(join(dir, ".stack", "webhooks"))).toEqual(["clerk.ts"]);
+    expect(readFileSync(stubPath, "utf-8")).toBe(webhookStubFor("clerk"));
+    expect(existsSync(join(dir, ".stack", "webhooks", "$&.ts"))).toBe(false);
+    expect(existsSync(join(dir, ".stack", "webhooks", "$&$&.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({});
+  });
+});

package/src/ai/phantom-wire-double-quote.test.ts

@@ -0,0 +1,135 @@
+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);
+
+describe("ai/phantom-wire double quote in replacement text", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-double-quote-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "double-quote",
+    query: "q",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: names.map((name) => ({ name })),
+  });
+
+  // The template carries its own quotes: two around the fixed signature
+  // header in `req.headers.get("...")`, two in `new Response("Missing
+  // signature", ...)` and two in `new Response("ok", ...)`. Measure them off
+  // a quote-free name so the arithmetic tracks template drift instead of
+  // pinning a count by hand.
+  const templateDoubles = webhookStubFor("zzq").split('"').length - 1;
+
+  it.each([
+    'pay"hook', // interior quote
+    '"hook', // leading quote
+    'hook"', // trailing quote
+    'a""b', // adjacent pair inside the name
+    '"', // the entire name is one quote
+    '""', // the entire name is a quote pair
+  ])("renders the double quote byte-for-byte at every expansion site for %j", (name) => {
+    const stub = webhookStubFor(name);
+    const nameQuotes = name.split('"').length - 1;
+
+    // Raw sites: the title line and the forgery warning carry the name
+    // unchanged — the quote is data, never escaped, encoded, or dropped.
+    expect(stub).toContain(`webhook handler stub for ${name}.`);
+    expect(stub).toContain(`forge a ${name} webhook.`);
+
+    // `capitalize(name)` site: only the first code point folds; `"` has no
+    // case mapping, so every quote in the name survives into the handler.
+    expect(stub).toContain(
+      `handle${name[0]?.toUpperCase() ?? ""}${name.slice(1)}Webhook(req: Request)`,
+    );
+
+    // `webhookSecretKeyFor(name)` sites: `toUpperCase()` leaves `"` alone,
+    // so the quote-bearing key lands in both `phantom reveal` lines.
+    expect(stub.split(`phantom reveal ${name.toUpperCase()}_WEBHOOK_SECRET`).length - 1).toBe(2);
+
+    // Five expansion sites per name; the stub holds exactly the template's
+    // own quotes plus the ones the name carried in — none lost to escaping.
+    expect(stub.split('"').length - 1).toBe(templateDoubles + nameQuotes * 5);
+  });
+
+  it.each(['pay"hook', '"', 'a""b'])(
+    "emits no escaped or encoded form of the quote for %j",
+    (name) => {
+      const stub = webhookStubFor(name);
+      // A JSON.stringify-style pass would emit `\"`; an HTML/URI encoder
+      // would emit an entity or %22. None of those run: the quote is
+      // interpolated as plain text inside line comments.
+      for (const encoded of ['\\"', """, """, """, "%22", "\\u0022"]) {
+        expect(stub).not.toContain(encoded);
+      }
+    },
+  );
+
+  it("keeps every quote inside `//` comments and the template's own string literals intact", () => {
+    // The only real string literals in the stub are the template's own:
+    // a `"` reaching one of those positions would corrupt the generated
+    // code's syntax. Every provider-name site sits in a line comment, so
+    // the carried quote can never terminate a literal — and the literals
+    // themselves keep exactly their template text.
+    const stub = webhookStubFor('pay"hook');
+    expect(stub).toContain('req.headers.get("x-webhook-signature")');
+    expect(stub).toContain('new Response("Missing signature", { status: 400 })');
+    expect(stub).toContain('new Response("ok", { status: 200 })');
+    expect(stub.split("\n").every((line) => line === "" || line.startsWith("//"))).toBe(true);
+  });
+
+  it("returns the fallback hint unchanged for a quote-bearing name", () => {
+    // The hint is a fixed string per provider with no name interpolation:
+    // the quote in the replacement text never reaches it.
+    expect(verificationHintFor('pay"hook')).toBe(
+      "Verify per the provider's documented signature scheme.",
+    );
+    expect(verificationHintFor('"')).toBe(verificationHintFor("zzq"));
+  });
+
+  it("skips a quote-bearing name byte-for-byte through wiring and writes nothing for it", async () => {
+    // `stripe"` matches no catalog provider (the lookup compares exact
+    // bytes): it returns in `skipped` with U+0022 intact, gets no stub on
+    // disk, and provokes no vault write. The known provider listed beside
+    // it wires normally, unaffected by the quoted neighbour.
+    const name = 'stripe"';
+    const stubPath = join(dir, ".stack", "webhooks", "github.ts");
+    const result = await wirePhantomForRecipe(recipe(name, "github"), { cwd: dir });
+
+    expect(result).toEqual({
+      present: [],
+      missing: ["github:GITHUB_TOKEN"],
+      webhooks: [stubPath],
+      skipped: [name],
+    });
+    expect(result.skipped[0]?.charCodeAt(6)).toBe(0x22);
+
+    // Only github's documented stub lands — nothing for the quoted name —
+    // and the stub on disk is the same render `webhookStubFor` returns.
+    expect(readdirSync(join(dir, ".stack", "webhooks"))).toEqual(["github.ts"]);
+    expect(readFileSync(stubPath, "utf-8")).toBe(webhookStubFor("github"));
+    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({});
+  });
+});