@ashlr/stack-core 0.3.1 → 0.3.6

package/src/ai/phantom-wire-placeholder-two-lines.test.ts

@@ -0,0 +1,196 @@
+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;
+const newlineCount = (s: string) => count(s, "\n");
+
+// 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 on each of two lines", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-two-line-placeholder-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "two-line-placeholder",
+    query: "q",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: names.map((name) => ({ name })),
+  });
+
+  it.each(SLOT_TOKENS)(
+    "carries both occurrences of %j and keeps the newline between them at every site",
+    (token) => {
+      // The name is exactly two lines, each holding the same known
+      // placeholder — the token on the first line, a newline, the token
+      // again on the second, no ordinary text. Both occurrences are data:
+      // expansion fills the five name-carrying sites with the name itself,
+      // so each site receives the pair in the input's own order with the
+      // line break between them. A resolver would resolve the tokens away,
+      // a sanitizer would strip or escape the 0x0A, line-ending
+      // normalization would rewrite it as CRLF. None of that runs.
+      const name = `${token}\n${token}`;
+      const stub = webhookStubFor(name);
+      const flat = webhookStubFor(`${token}${token}`);
+
+      // The three case-preserving sites carry the name byte-for-byte —
+      // both tokens and the break between them. `capitalize` folds only
+      // the first code point, and `$` uppercases to itself, 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; `\n`
+      // has no case mapping, so the folded pair sits line-broken there too.
+      expect(count(stub, `phantom reveal ${name.toUpperCase()}_WEBHOOK_SECRET`)).toBe(2);
+
+      // Both occurrences land at every site, each on its own line and in
+      // order: the exact-case pair at the three case-preserving sites, the
+      // folded pair at both reveal sites.
+      expect(count(stub, `${token}\n${token}`)).toBe(3);
+      expect(count(stub, `${token.toUpperCase()}\n${token.toUpperCase()}`)).toBe(2);
+
+      // The intervening byte is a real 0x0A — not an escape, not a CRLF.
+      // The first token closes its line (token then `\n`) and the second
+      // opens the next (`\n${`, no `//` prefix) at all five sites. Rendering
+      // the same pair on one line gives the flat baseline: the only
+      // difference is exactly five inserted line breaks, one per site.
+      const at = stub.indexOf(`${token}\n${token}`);
+      expect(stub.charCodeAt(at + token.length)).toBe(0x0a);
+      expect(count(stub, `${token}\n`)).toBe(3);
+      expect(count(stub, `${token.toUpperCase()}\n`)).toBe(2);
+      expect(count(stub, "\n${")).toBe(5);
+      expect(newlineCount(stub)).toBe(newlineCount(flat) + 5);
+      expect(stub).not.toContain("\\n");
+      expect(stub).not.toContain("\r");
+
+      // Ten `${...}` spans — two per site × five sites — every one the
+      // carried token in that site's case: six exact-case, four folded.
+      // Resolution would erase them, re-expansion would mint more, and
+      // nothing reorders the pair onto one line.
+      const tokens = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+      expect(tokens).toHaveLength(10);
+      for (const t of tokens) expect(t.toLowerCase()).toBe(token.toLowerCase());
+      expect(count(stub, token)).toBe(6);
+      expect(count(stub, token.toUpperCase())).toBe(4);
+
+      // The sibling slots took their own generic values in the same single
+      // pass — the carried pair never reached their switch cases either.
+      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 different known token on each line in line order at every site", () => {
+    // Two lines, a DIFFERENT known placeholder on each — `${provider}` on
+    // the first, `${signatureHeaderFor(provider)}` on the second, ordinary
+    // `pre`/`post` text at the name's edges. Both tokens ride along in the
+    // name's own order: the first-line token never drops to the second
+    // line and the second-line token never climbs to the first.
+    const first = "${provider}";
+    const second = "${signatureHeaderFor(provider)}";
+    const name = `pre${first}\n${second}post`;
+    const stub = webhookStubFor(name);
+    const flat = webhookStubFor(`pre${first}${second}post`);
+
+    // Case-preserving sites carry the name byte-for-byte; `capitalize`
+    // folds only the leading `p` → `Pre`, and the reveal sites fold the
+    // whole name — tokens, text, but not the newline.
+    expect(stub).toContain(`webhook handler stub for ${name}.`);
+    expect(stub).toContain(`forge a ${name} webhook.`);
+    expect(stub).toContain(`handlePre${first}\n${second}postWebhook(req: Request)`);
+    expect(
+      count(
+        stub,
+        `phantom reveal PRE${first.toUpperCase()}\n${second.toUpperCase()}POST_WEBHOOK_SECRET`,
+      ),
+    ).toBe(2);
+
+    // In order, on their own lines: exact-case at the three case-preserving
+    // sites, folded at both reveal sites — never transposed, never
+    // flattened onto one line, in either casing.
+    expect(count(stub, `${first}\n${second}`)).toBe(3);
+    expect(count(stub, `${first.toUpperCase()}\n${second.toUpperCase()}`)).toBe(2);
+    expect(stub).not.toContain(`${second}\n${first}`);
+    expect(stub).not.toContain(`${second.toUpperCase()}\n${first.toUpperCase()}`);
+    expect(newlineCount(stub)).toBe(newlineCount(flat) + 5);
+
+    // Ten spans — each is one of the two tokens in that site's case, still
+    // seated where the name put it: the `pre` text ahead of the first
+    // line's token, the `post` text behind the second line's.
+    const tokens = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+    expect(tokens).toHaveLength(10);
+    for (const t of tokens.map((t) => t.toLowerCase())) {
+      expect([first.toLowerCase(), second.toLowerCase()]).toContain(t);
+    }
+    expect(stub.match(/pre\$\{[^}]*\}\n/gi)).toHaveLength(5);
+    expect(stub.match(/\n\$\{[^}]*\}post/gi)).toHaveLength(5);
+
+    // The sibling slots resolved to their own generic values in the same
+    // single pass — the carried tokens never reached their switch cases.
+    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("skips a two-line 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 — both tokens and the newline
+    // between them intact — gets no stub on disk, and provokes no vault
+    // write. The known provider listed beside it wires normally,
+    // unaffected by the line-broken placeholder neighbour.
+    const name = "${provider}\n${provider}";
+    const stubPath = join(dir, ".stack", "webhooks", "clerk.ts");
+    const result = await wirePhantomForRecipe(recipe(name, "clerk"), { cwd: dir });
+
+    expect(result).toEqual({
+      present: [],
+      missing: ["clerk:CLERK_SECRET_KEY"],
+      webhooks: [stubPath],
+      skipped: [name],
+    });
+    expect(result.skipped[0]).toBe(name);
+    expect(result.skipped[0]?.charCodeAt("${provider}".length)).toBe(0x0a);
+
+    // Only clerk's documented stub lands — nothing for the two-line name,
+    // 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", `${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 line-broken name never leaks into it.
+    expect(verificationHintFor(name)).toBe(verificationHintFor("zzq"));
+  });
+});

package/src/ai/phantom-wire-repeated-known-placeholder.test.ts

@@ -0,0 +1,241 @@
+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 repeated known placeholder in a provider name", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-repeated-known-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "repeated-known",
+    query: "q",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: names.map((name) => ({ name })),
+  });
+
+  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
+  ])("carries both occurrences of the repeated token %j to every expansion site", (slot) => {
+    // The name is ordinary text carrying the SAME template-slot spelling
+    // twice — a repeated known placeholder. Both occurrences are data, not
+    // slots: unlike a non-global `.replace`, which would touch only the
+    // first, every occurrence must be carried with the name to all five
+    // expansion sites (three case-preserving, one first-letter-folded, two
+    // whole-name-uppercased), and none may resolve to the value its
+    // spelling names — there is no second pass.
+    const name = `pre${slot}mid${slot}post`;
+    const stub = webhookStubFor(name);
+
+    // The name — both repeats included — lands byte-for-byte at the three
+    // case-preserving sites and whole-name uppercased at both secret-key
+    // sites. `capitalize` folds only the first letter: `pre` → `Pre`.
+    expect(stub).toContain(`webhook handler stub for ${name}.`);
+    expect(stub).toContain(`forge a ${name} webhook.`);
+    expect(stub).toContain(`handlePre${slot}mid${slot}postWebhook(req: Request)`);
+    expect(
+      count(
+        stub,
+        `phantom reveal PRE${slot.toUpperCase()}MID${slot.toUpperCase()}POST_WEBHOOK_SECRET`,
+      ),
+    ).toBe(2);
+
+    // Census: two repeats per site × five sites = ten `${...}` spans, every
+    // one the carried token in that site's case — six exact-case at the
+    // case-preserving sites, four uppercased at the reveal sites. None
+    // resolved away, none dropped, none duplicated.
+    const tokens = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+    expect(tokens).toHaveLength(10);
+    for (const token of tokens) expect(token.toLowerCase()).toBe(slot.toLowerCase());
+    expect(count(stub, slot)).toBe(6);
+    expect(count(stub, slot.toUpperCase())).toBe(4);
+
+    // Per-occurrence proof: at every occurrence of the token — both repeats,
+    // all sites — the immediate left flank is the name's `pre`/`mid` and the
+    // right flank the name's `mid`/`post` (the `$` of the sibling token for
+    // the first repeat). Each occurrence received identical carry-through;
+    // no occurrence was resolved to a value or reseated next to spliced text.
+    for (const [variant, sites] of [
+      [slot, 3],
+      [slot.toUpperCase(), 2],
+    ] as const) {
+      const contexts: string[] = [];
+      for (let at = stub.indexOf(variant); at !== -1; at = stub.indexOf(variant, at + 1)) {
+        const left = stub.slice(at - 3, at);
+        const right = stub.slice(at + variant.length, at + variant.length + 4);
+        contexts.push(`${left}|${right}`.toLowerCase());
+      }
+      const expected = Array.from({ length: sites }, () => ["pre|mid$", "mid|post"]).flat();
+      expect(contexts.sort()).toEqual(expected.sort());
+    }
+
+    // A second pass would have re-resolved each carried token into the whole
+    // name again, doubling the flanking text; no flank doubles anywhere.
+    expect(stub.match(/pre\$\{[^}]*\}mid\$\{[^}]*\}post/gi)).toHaveLength(5);
+    expect(stub).not.toMatch(/prepre|midmid|postpost/i);
+
+    // The sibling slots took their own generic values in the same single
+    // pass — the repeated token never reached their switch cases either.
+    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("emits a repeated `${provider}` token at the name's edges literally at all five sites — line-for-line", () => {
+    // The sharpest form: the repeated token spells the name slot itself and
+    // sits at BOTH edges of the name, so at the name sites the emitted text
+    // is indistinguishable from unfilled slots — and `capitalize`'s fold of
+    // the first code point lands on `$`, which uppercases to itself. Exact
+    // lines pin every site: both repeats arrived verbatim, once each.
+    const name = "${provider}and${provider}";
+    const stub = webhookStubFor(name);
+
+    expect(stub).toContain(
+      "// Auto-generated by `stack apply` — webhook handler stub for ${provider}and${provider}.\n",
+    );
+    expect(stub).toContain("//   phantom reveal ${PROVIDER}AND${PROVIDER}_WEBHOOK_SECRET");
+    expect(stub).toContain(
+      "// export async function handle${provider}and${provider}Webhook(req: Request): Promise<Response> {",
+    );
+    expect(stub).toContain(
+      "//   // to this endpoint can forge a ${provider}and${provider} webhook.",
+    );
+    expect(stub).toContain(
+      "//   // (`phantom reveal ${PROVIDER}AND${PROVIDER}_WEBHOOK_SECRET`) and compare in",
+    );
+
+    // Census: ten `${...}` spans — both repeats at each site, in site order:
+    // title, reveal, handler, forge (all case-preserving), reveal (folded).
+    const tokens = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+    expect(tokens).toEqual([
+      "${provider}",
+      "${provider}",
+      "${PROVIDER}",
+      "${PROVIDER}",
+      "${provider}",
+      "${provider}",
+      "${provider}",
+      "${provider}",
+      "${PROVIDER}",
+      "${PROVIDER}",
+    ]);
+    expect(count(stub, "${provider}")).toBe(6);
+    expect(count(stub, "${PROVIDER}")).toBe(4);
+
+    // No re-expansion: a second pass would splice the name into each carried
+    // token again, producing `and${provider}and` chains; the `and` flank
+    // stays single everywhere.
+    expect(stub.match(/\$\{provider\}and\$\{provider\}/g)).toHaveLength(3);
+    expect(stub.match(/\$\{PROVIDER\}AND\$\{PROVIDER\}/g)).toHaveLength(2);
+    expect(stub).not.toMatch(/andand/i);
+
+    // Sibling slots resolved to 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("carries three repeats of the same known token — every occurrence at every site", () => {
+    // Repeat count generalizes: three occurrences of the same slot spelling
+    // each ride along as data — fifteen spans total, nine exact-case, six
+    // folded — and every occurrence sits between the name's own flanks.
+    const slot = "${signatureHeaderFor(provider)}";
+    const name = `a${slot}b${slot}c${slot}d`;
+    const stub = webhookStubFor(name);
+
+    expect(stub).toContain(`webhook handler stub for ${name}.`);
+    expect(stub).toContain(`forge a ${name} webhook.`);
+    expect(stub).toContain(`handleA${slot}b${slot}c${slot}dWebhook(req: Request)`);
+    expect(
+      count(
+        stub,
+        `phantom reveal A${slot.toUpperCase()}B${slot.toUpperCase()}C${slot.toUpperCase()}D_WEBHOOK_SECRET`,
+      ),
+    ).toBe(2);
+
+    const tokens = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+    expect(tokens).toHaveLength(15);
+    for (const token of tokens) expect(token.toLowerCase()).toBe(slot.toLowerCase());
+    expect(count(stub, slot)).toBe(9);
+    expect(count(stub, slot.toUpperCase())).toBe(6);
+
+    // Every occurrence is flanked by the letters the name supplied — `a|b`,
+    // `b|c`, `c|d` in order — three of each per case-preserving site, two of
+    // each per folded site. None resolved, reordered, or reseated.
+    for (const [variant, sites] of [
+      [slot, 3],
+      [slot.toUpperCase(), 2],
+    ] as const) {
+      const contexts: string[] = [];
+      for (let at = stub.indexOf(variant); at !== -1; at = stub.indexOf(variant, at + 1)) {
+        const left = stub.slice(at - 1, at);
+        const right = stub.slice(at + variant.length, at + variant.length + 1);
+        contexts.push(`${left}|${right}`.toLowerCase());
+      }
+      const expected = Array.from({ length: sites }, () => ["a|b", "b|c", "c|d"]).flat();
+      expect(contexts.sort()).toEqual(expected.sort());
+    }
+
+    // A second pass would have re-resolved each carried token into the whole
+    // name again, minting extra spans and doubling the flanks; the complete
+    // a<tok>b<tok>c<tok>d shape appears exactly once per site and the census
+    // above already counted every `${...}` span there is.
+    expect(stub.match(/a\$\{[^}]*\}b\$\{[^}]*\}c\$\{[^}]*\}d/gi)).toHaveLength(5);
+  });
+
+  it("skips a repeated-placeholder name byte-for-byte through wiring and writes nothing for it", async () => {
+    // Through `wirePhantomForRecipe` the repeated-token name matches no
+    // catalog provider: it returns in `skipped` byte-for-byte — both
+    // occurrences intact — 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 = "pre${provider}mid${provider}post";
+    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 repeated-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({});
+
+    // The hint is a fixed string: a repeated-token name never leaks into it.
+    expect(verificationHintFor(name)).toBe(verificationHintFor("zzq"));
+  });
+});

package/src/ai/phantom-wire-repeated-unknown-placeholder.test.ts

@@ -0,0 +1,55 @@
+import { afterEach, beforeEach, describe, expect, it, setDefaultTimeout } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type Harness, setupFakePhantom } from "../__tests__/_harness.ts";
+import { webhookStubFor } from "./phantom-wire.ts";
+
+setDefaultTimeout(30_000);
+
+describe("ai/phantom-wire repeated unknown placeholders", () => {
+  let harness: Harness;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+  });
+  afterEach(() => {
+    harness.cleanup();
+  });
+
+  it("keeps both occurrences of repeated unknown placeholders unchanged at every expansion site", () => {
+    // A provider name carrying two distinct unknown placeholders. Each must
+    // survive all five expansion sites in the stub unchanged (three case-
+    // preserving, two uppercased for the reveal lines). The expansion sites
+    // are: the title line, the forge line, the handler name (first-letter
+    // capitalized), and the two `phantom reveal` lines (uppercased).
+    const name = "pre${ALPHA}mid${BETA}post";
+
+    const stub = webhookStubFor(name);
+
+    // Three case-preserving sites: the placeholders keep their original case.
+    expect(stub).toContain(`webhook handler stub for ${name}.`);
+    expect(stub).toContain("forge a pre${ALPHA}mid${BETA}post webhook.");
+    expect(stub).toContain("handlePre${ALPHA}mid${BETA}postWebhook(req: Request)");
+
+    // Two uppercased reveal lines: both placeholders are folded with the
+    // surrounding text by `toUpperCase()`, but neither is resolved or lost.
+    expect(stub.split("phantom reveal PRE${ALPHA}MID${BETA}POST_WEBHOOK_SECRET").length - 1).toBe(
+      2,
+    );
+
+    // Every `${...}` token in the stub is one of the two carried placeholders
+    // — five expansion sites × two tokens = ten occurrences.
+    const tokens = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+    expect(tokens).toHaveLength(10);
+
+    // Five occurrences of each token (one per expansion site), each still
+    // seated between the surrounding text.
+    expect(stub.split("${ALPHA}").length - 1).toBe(5);
+    expect(stub.split("${BETA}").length - 1).toBe(5);
+
+    // Lowercased reveal lines: both placeholders folded together.
+    expect(stub.toLowerCase().split("${alpha}").length - 1).toBe(5);
+    expect(stub.toLowerCase().split("${beta}").length - 1).toBe(5);
+  });
+});

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

@@ -0,0 +1,170 @@
+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 $-substitution patterns in replacement text", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-dollar-replacement-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "dollar-replacement",
+    query: "q",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: names.map((name) => ({ name })),
+  });
+
+  /**
+   * The stub a literal renderer must produce for `name`. The provider name
+   * is replacement text: `$1`, `$$`, `$&`, `` $` `` and `$'` are directives
+   * to `String.prototype.replace` — a `.replace`-based renderer would splice
+   * a capture group in for `$1`, collapse `$$` to one dollar, inject the
+   * matched slot for `$&`, or inject the template text around the match for
+   * `` $` ``/`$'`. Template literals have no substitution pattern at all, so
+   * the `$` bytes must arrive as inert data.
+   *
+   * The oracle renders a sentinel name — the same letters with each `$x`
+   * swapped for NUL, a byte with no special meaning in either syntax — then
+   * substitutes each NUL back to its pattern through a replacer FUNCTION,
+   * whose return value is also exempt from `$`-pattern interpretation.
+   * Whole-stub equality against this oracle catches every replace-semantics
+   * failure anywhere in the output, not just at the five expansion sites.
+   */
+  const literalRender = (name: string): string => {
+    const patterns = [...name.matchAll(/\$./g)].map((m) => m[0]);
+    const sentinel = name.replaceAll(/\$./g, "\u0000");
+    // Each expansion site replays the name's pattern sequence in order, so
+    // the i-th NUL maps to patterns[i mod patterns.length].
+    let i = 0;
+    return webhookStubFor(sentinel).replaceAll("\u0000", () => patterns[i++ % patterns.length]);
+  };
+
+  it.each(["svc$1pay", "$1", "pay$1", "a$1$2$9z"])(
+    "inserts the $1-carrying name %j literally at every site — the characters, not a capture group",
+    (name) => {
+      const stub = webhookStubFor(name);
+      const capitalized = `${name[0].toUpperCase()}${name.slice(1)}`;
+
+      // The decisive differential: byte-for-byte equal to the sentinel
+      // render — the `$`-pattern bytes behaved exactly like inert data at
+      // every expansion site and everywhere between them.
+      expect(stub).toBe(literalRender(name));
+
+      // The characters appear literally in the result: the name at the
+      // three case-preserving sites, first-letter-folded at the handler
+      // site, whole-name-folded at both reveal sites.
+      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);
+
+      // Dollar census: only the `$` the name itself carries, times the five
+      // sites — none dropped by a `$$` collapse or minted by a splice — and
+      // every `$1` still seated inside the name's own bytes.
+      expect(count(stub, "$")).toBe(count(name, "$") * 5);
+      expect(count(stub, "$1")).toBe(count(name, "$1") * 5);
+      expect(stub).not.toContain("${");
+
+      // The sibling slots resolved to their own values in the same pass —
+      // the pattern 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(["svc$$pay", "svc$&pay", "svc$`pay", "svc$'pay"])(
+    "inserts the replace-directive name %j literally at every site",
+    (name) => {
+      // Same scenario for the rest of the replace-pattern family: `$$`
+      // collapses to `$`, `$&` splices the match, `` $` ``/`$'` splice the
+      // template text flanking the match. All are `toUpperCase`-invariant,
+      // so the sentinel differential applies unchanged.
+      const stub = webhookStubFor(name);
+      const capitalized = `${name[0].toUpperCase()}${name.slice(1)}`;
+
+      expect(stub).toBe(literalRender(name));
+
+      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);
+
+      // Two `$` for `$$`, one for the rest — all carried, never resolved.
+      expect(count(stub, "$")).toBe(count(name, "$") * 5);
+      expect(stub).not.toContain("${");
+
+      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("inserts the named-capture pattern `$<ref>` literally, folding only its letters at the reveal sites", () => {
+    // `$<name>` splices a named capture group under replace semantics. Its
+    // letters fold with the rest of the name at the `toUpperCase()` sites,
+    // so the differential oracle does not apply — assert the sites and the
+    // census directly.
+    const name = "svc$<ref>pay";
+    const stub = webhookStubFor(name);
+
+    expect(count(stub, "svc$<ref>pay")).toBe(2); // title + forge
+    expect(stub).toContain("handleSvc$<ref>payWebhook(req: Request)");
+    expect(count(stub, "phantom reveal SVC$<REF>PAY_WEBHOOK_SECRET")).toBe(2);
+    expect(count(stub, "$")).toBe(5);
+    expect(stub).not.toContain("${");
+
+    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 $1-carrying name byte-for-byte through wiring and writes nothing for it", async () => {
+    // Through `wirePhantomForRecipe` the `$1` name matches no catalog
+    // provider: it returns in `skipped` byte-for-byte — the capture-group
+    // spelling intact — gets no stub on disk, and provokes no vault write.
+    // The known provider listed beside it wires normally, unaffected by the
+    // replace-pattern-shaped neighbour.
+    const name = "svc$1pay";
+    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 `$1` 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({});
+  });
+});