@ashlr/stack-core 0.3.1 → 0.3.7

package/src/ai/phantom-wire-mixed-placeholders.test.ts

@@ -0,0 +1,183 @@
+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;
+
+// A `${...}` token that spells none of the template's slots. Already
+// uppercase, so even the `toUpperCase()` secret-key sites hold identical
+// bytes — any difference it shows is the renderer's, not the fold's.
+const UNKNOWN = "${HOOK_URL}";
+
+describe("ai/phantom-wire a name mixing a known and an unknown placeholder", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-mixed-placeholders-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "mixed-placeholders",
+    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
+  ])(
+    "expands every known slot to the name while the unknown token in it stays literal: %j",
+    (slot) => {
+      // The name carries two `${...}` tokens separated by ordinary text:
+      // one spelling a real template slot (a known placeholder), one
+      // spelling nothing (unknown). The template's known placeholders
+      // still expand — each slot emits the whole name once — while both
+      // tokens inside the emitted name arrive unchanged: the known one is
+      // never offered a second pass, and the unknown one has no expansion
+      // to begin with.
+      const name = `pre${slot}mid${UNKNOWN}post`;
+      const stub = webhookStubFor(name);
+
+      // The `${provider}` and `${capitalize(provider)}` slots expanded to
+      // the full name — both tokens included — byte-for-byte at the three
+      // case-preserving sites; `capitalize` folds only the leading `p`.
+      expect(stub).toContain(`webhook handler stub for ${name}.`);
+      expect(stub).toContain(`forge a ${name} webhook.`);
+      expect(stub).toContain(`handlePre${slot}mid${UNKNOWN}postWebhook(req: Request)`);
+      // The `webhookSecretKeyFor(provider)` slot expanded too: both reveal
+      // lines hold the whole-name-uppercased replacement — the carried
+      // known token folded with it, the already-uppercase unknown token
+      // byte-identical.
+      expect(
+        count(stub, `phantom reveal PRE${slot.toUpperCase()}MID${UNKNOWN}POST_WEBHOOK_SECRET`),
+      ).toBe(2);
+
+      // Census: two tokens per name × five expansion sites, exactly half
+      // the known spelling and half the unknown — none resolved away,
+      // emptied, or minted into extra copies.
+      const tokens = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+      expect(tokens).toHaveLength(10);
+      expect(tokens.filter((t) => t.toLowerCase() === slot.toLowerCase())).toHaveLength(5);
+      expect(tokens.filter((t) => t === UNKNOWN)).toHaveLength(5);
+
+      // Order and seating per site: at each of the five sites the emitted
+      // name keeps the known token before `mid` and the unknown token
+      // after it — the unknown placeholder remains exactly where the name
+      // put it, never transposed or reseated beside injected text.
+      expect(stub.match(/pre\$\{[^}]*\}mid\$\{HOOK_URL\}post/gi)).toHaveLength(5);
+
+      // Single pass: a re-resolve of the carried known token would double
+      // the flanking text or drop the unknown token; neither happened.
+      expect(stub).not.toMatch(/prepre|midmid|postpost/i);
+
+      // The remaining known slots took their own generic values in the
+      // same pass — expansion ran everywhere it was defined.
+      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.each([
+    ["${provider}", UNKNOWN], // known spelling leads, unknown follows
+    [UNKNOWN, "${provider}"], // unknown leads, known spelling follows
+  ])(
+    "keeps the flush pair %j + %j adjacent and in order at every expansion site",
+    (known, unknown) => {
+      // The whole name is the two tokens back-to-back: a known slot
+      // spelling flush against an unknown one. The known placeholder in
+      // the template expands — the slots emit the pair as the replacement
+      // — while the pair itself stays data: in order, nothing spliced
+      // between the first token's `}` and the second's `${`, the unknown
+      // token unchanged.
+      const name = `${known}${unknown}`;
+      const other = `${unknown}${known}`;
+      const stub = webhookStubFor(name);
+
+      // The `$`-led name is carried byte-for-byte at the three
+      // case-preserving sites (`capitalize` leaves it) and whole-name
+      // uppercased at both secret-key sites.
+      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 flush pair occurs exact-case at the three mixed-case sites
+      // and uppercased together at the two reveal sites — at each site
+      // the second token starts on the very byte the first ends.
+      expect(stub.match(/\$\{[^}]*\}\$\{[^}]*\}/g)).toHaveLength(5);
+      expect(count(stub, name)).toBe(3);
+      expect(count(stub, name.toUpperCase())).toBe(2);
+
+      // The transposed order never lands, in either casing.
+      expect(stub).not.toContain(other);
+      expect(stub).not.toContain(other.toUpperCase());
+
+      // Census: five occurrences of each token — the known spelling and
+      // the unknown one — and nothing else placeholder-shaped.
+      const tokens = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+      expect(tokens).toHaveLength(10);
+      expect(tokens.filter((t) => t.toLowerCase() === known.toLowerCase())).toHaveLength(5);
+      expect(tokens.filter((t) => t.toLowerCase() === unknown.toLowerCase())).toHaveLength(5);
+
+      // The template's real slots still take their own known values.
+      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 mixed-token name byte-for-byte through wiring and writes nothing for it", async () => {
+    // Through `wirePhantomForRecipe` the mixed-token name matches no
+    // catalog provider: it returns in `skipped` byte-for-byte — the
+    // known-spelling token, the unknown token and the text between them
+    // intact — gets no stub on disk, and provokes no vault write. The
+    // known provider listed beside it wires normally: every one of its
+    // placeholders expands, unaffected by the placeholder-shaped
+    // neighbour.
+    const name = "pay${provider}load${HOOK_URL}end";
+    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);
+
+    // Only clerk's documented stub lands — fully expanded, no `${...}`
+    // left — and nothing is written under the mixed-token name.
+    expect(readdirSync(join(dir, ".stack", "webhooks"))).toEqual(["clerk.ts"]);
+    const stub = readFileSync(stubPath, "utf-8");
+    expect(stub).toBe(webhookStubFor("clerk"));
+    expect(stub).not.toContain("${");
+    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 — a token-carrying name provokes
+    // no write.
+    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-nested-placeholder.test.ts

@@ -0,0 +1,149 @@
+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 known placeholder nested inside replacement text", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-nested-placeholder-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "nested-placeholder",
+    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
+  ])("never expands the inserted text a second time for the nested token %j", (slot) => {
+    // The name is ordinary text carrying one of the template's own slot
+    // spellings. This is the decisive re-expansion case: unlike an unknown
+    // `${...}` token, this one *would* resolve if the renderer ever fed
+    // inserted text back through the slots — a second pass would splice
+    // the whole name in again and double the flanking `pre`/`post` text
+    // (or recurse forever). The template literal evaluates each slot
+    // exactly once, so the carried token must arrive at every expansion
+    // site byte-for-byte, still seated between the name's own text.
+    const name = `pre${slot}post`;
+    const stub = webhookStubFor(name);
+
+    // Case-preserving sites emit the name — token plus surrounding text —
+    // byte-for-byte; `capitalize` folds only the first letter at the
+    // handler site.
+    expect(stub).toContain(`webhook handler stub for ${name}.`);
+    expect(stub).toContain(`forge a ${name} webhook.`);
+    expect(stub).toContain(`handlePre${slot}postWebhook(req: Request)`);
+    // `webhookSecretKeyFor(provider)` uppercases the whole name — token
+    // included — at both reveal lines.
+    expect(
+      stub.split(`phantom reveal PRE${slot.toUpperCase()}POST_WEBHOOK_SECRET`).length - 1,
+    ).toBe(2);
+
+    // Five `${...}` spans — one per expansion site — every one the carried
+    // token in that site's case, none resolved away or duplicated.
+    const tokens = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+    expect(tokens).toHaveLength(5);
+    for (const token of tokens) expect(token.toLowerCase()).toBe(slot.toLowerCase());
+
+    // The no-second-pass proof: each token still sits between exactly one
+    // `pre` and one `post` (in whatever case that site's transform gives
+    // them), and the flanking text is never doubled. A re-resolve would
+    // have produced `prepre${...}postpost` at every site.
+    expect(stub.match(/pre\$\{[^}]*\}post/gi)).toHaveLength(5);
+    expect(stub).not.toMatch(/prepre|postpost/i);
+
+    // 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("emits the nested `${provider}` token literally at all five sites — line-for-line", () => {
+    // The sharpest form: the carried token spells the name slot itself, so
+    // at the name sites the emitted text is indistinguishable from an
+    // unresolved slot. Exact-line equality pins every site: the inserted
+    // text arrived verbatim, once, with no re-expansion splicing extra
+    // copies of the name around it.
+    const stub = webhookStubFor("pre${provider}post");
+
+    expect(stub).toContain(
+      "// Auto-generated by `stack apply` — webhook handler stub for pre${provider}post.",
+    );
+    expect(stub).toContain("//   phantom reveal PRE${PROVIDER}POST_WEBHOOK_SECRET");
+    expect(stub).toContain(
+      "// export async function handlePre${provider}postWebhook(req: Request): Promise<Response> {",
+    );
+    expect(stub).toContain("//   // to this endpoint can forge a pre${provider}post webhook.");
+    expect(stub).toContain(
+      "//   // (`phantom reveal PRE${PROVIDER}POST_WEBHOOK_SECRET`) and compare in",
+    );
+
+    // Census: exactly five `${...}` spans — three in original case at the
+    // case-preserving sites, two uppercased at the reveal sites. A second
+    // pass would have re-resolved each `${provider}` into
+    // `pre${provider}post`, doubling the flanks; none appear.
+    const tokens = [...stub.matchAll(/\$\{[^}]*\}/g)].map((m) => m[0]);
+    expect(tokens).toEqual([
+      "${provider}",
+      "${PROVIDER}",
+      "${provider}",
+      "${provider}",
+      "${PROVIDER}",
+    ]);
+    expect(stub).not.toMatch(/prepre|postpost/i);
+  });
+
+  it("skips a nested-placeholder name byte-for-byte through wiring and writes nothing for it", async () => {
+    // Through `wirePhantomForRecipe` the nested-token name matches no
+    // catalog provider: it returns in `skipped` byte-for-byte — token and
+    // surrounding text 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}post";
+    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);
+
+    // Only clerk's documented stub lands — nothing for the nested-token
+    // 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({});
+  });
+});

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

@@ -0,0 +1,136 @@
+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 newlineCount = (s: string) => s.split("\n").length - 1;
+
+describe("ai/phantom-wire replacement text containing a newline", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-newline-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "newline",
+    query: "q",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: names.map((name) => ({ name })),
+  });
+
+  it("emits the literal newline byte at all five expansion sites", () => {
+    // A newline inside the replacement text is ordinary data: carried
+    // through the template's single pass it must arrive as a real 0x0A byte
+    // at every expansion site — not collapsed, not stripped, and not
+    // emitted as the two-character escape `\n`. Rendering the same letters
+    // without the break (`ab`) gives the flat baseline: the only difference
+    // between the two stubs is exactly five inserted line breaks, one per
+    // site that splices the name.
+    const stub = webhookStubFor("a\nb");
+    const flat = webhookStubFor("ab");
+
+    // Case-preserving sites emit the name byte-for-byte — newline included.
+    expect(stub).toContain("webhook handler stub for a\nb.");
+    expect(stub).toContain("forge a a\nb webhook.");
+    // `capitalize` folds only the first code point; the newline is untouched.
+    expect(stub).toContain("handleA\nbWebhook(req: Request)");
+    // `webhookSecretKeyFor` uppercases the letters around the break; it
+    // survives at both reveal lines.
+    expect(stub.split("phantom reveal A\nB_WEBHOOK_SECRET").length - 1).toBe(2);
+
+    // Exactly five extra line breaks over the flat render — one per
+    // expansion site, none eaten or doubled by the pass.
+    expect(newlineCount(stub)).toBe(newlineCount(flat) + 5);
+
+    // Byte-level pin: the character after `stub for a` is 0x0A itself, and
+    // no escaped `\n` two-character sequence or `${...}` residue appears
+    // anywhere in the output.
+    expect(stub.charCodeAt(stub.indexOf("stub for a") + "stub for a".length)).toBe(0x0a);
+    expect(stub).not.toContain("\\n");
+    expect(stub).not.toContain("${");
+
+    // Proof the byte is a real line break and not an escape: each site's
+    // tail continues on a fresh line with no `//` comment prefix.
+    expect(stub).toContain("\nb.\n");
+    expect(stub).toContain("\nbWebhook(req: Request): Promise<Response> {\n");
+    expect(stub).toContain("\nb webhook.\n");
+    expect(stub.split("\nB_WEBHOOK_SECRET").length - 1).toBe(2);
+
+    // The remaining slots resolved to their own generic values in the same
+    // pass — the newline-bearing name 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("a\nb")).toBe(verificationHintFor("zzq"));
+  });
+
+  it.each(["\nx", "x\n", "a\nb\nc", "\n", "a\n\nb"])(
+    "keeps every literal newline in %j at all five expansion sites",
+    (name) => {
+      // Leading, trailing, adjacent, and repeated breaks are the same data.
+      // `capitalize` and `toUpperCase` leave 0x0A untouched — a newline has
+      // no case mapping — so each break in the name lands once per
+      // expansion site and the count scales with the newline count.
+      const stub = webhookStubFor(name);
+      const flat = webhookStubFor(name.replace(/\n/g, ""));
+      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);
+
+      // Five expansion sites carry the name; each preserves every newline
+      // in it. Escaped sequences would not raise the line count, and
+      // stripping would lower it below the flat baseline's own breaks.
+      expect(newlineCount(stub)).toBe(newlineCount(flat) + 5 * newlineCount(name));
+      expect(stub).not.toContain("\\n");
+      expect(stub).not.toContain("${");
+    },
+  );
+
+  it("skips a newline name byte-for-byte through wiring and writes nothing for it", async () => {
+    // Through `wirePhantomForRecipe` the newline-bearing name matches no
+    // catalog provider: it returns in `skipped` byte-for-byte — the 0x0A
+    // intact — gets no stub on disk, and provokes no vault write. The
+    // known provider listed beside it wires normally, unaffected by the
+    // line-break-shaped neighbour.
+    const name = "a\nb";
+    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(1)).toBe(0x0a);
+
+    // Only clerk's documented stub lands — nothing for the newline 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({});
+  });
+});

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

@@ -0,0 +1,173 @@
+import { afterAll, afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { EventEmitter } from "node:events";
+import { chmodSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { __resetPhantomCache, __setPhantomSpawn } from "../phantom.ts";
+import { wirePhantomForRecipe } from "./phantom-wire.ts";
+import type { Recipe } from "./recipe.ts";
+
+// Stubbed `phantom` subprocess: `--version` succeeds (unless `installed` is
+// false) and `list --json` returns the names in `vault`.
+let installed = true;
+let vault: string[] | "unreadable" = [];
+
+function fakeSpawn(_bin: string, args: string[]) {
+  const child = new EventEmitter() as EventEmitter & Record<string, unknown>;
+  const out = new EventEmitter();
+  const err = new EventEmitter();
+  Object.assign(child, {
+    stdout: Object.assign(out, { destroy() {} }),
+    stderr: Object.assign(err, { destroy() {} }),
+    stdin: { on() {}, write() {}, end() {}, destroy() {} },
+    pid: undefined,
+    kill() {},
+    unref() {},
+  });
+  queueMicrotask(() => {
+    if (!installed) {
+      child.emit("error", Object.assign(new Error("ENOENT"), { code: "ENOENT" }));
+      return;
+    }
+    if (args[0] === "list") {
+      if (vault === "unreadable") {
+        child.emit("close", 1, null);
+        return;
+      }
+      out.emit("data", Buffer.from(JSON.stringify(vault.map((name) => ({ name })))));
+    }
+    child.emit("close", 0, null);
+  });
+  return child;
+}
+
+function recipeOf(...names: string[]): Recipe {
+  return {
+    id: "order",
+    query: "order",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: names.map((name) => ({ name })),
+  };
+}
+
+describe("ai/phantom-wire result ordering with multiple providers", () => {
+  const savedPath = process.env.PATH;
+  let dir: string;
+
+  beforeEach(() => {
+    dir = realpathSync(mkdtempSync(join(tmpdir(), "wire-order-")));
+    // Binary only needs to resolve on PATH; spawn is stubbed. `.sh` target
+    // matches the sibling failing-subprocess test (macOS provenance policy).
+    writeFileSync(join(dir, "phantom.sh"), "#!/bin/sh\n");
+    chmodSync(join(dir, "phantom.sh"), 0o755);
+    symlinkSync(join(dir, "phantom.sh"), join(dir, "phantom"));
+    process.env.PATH = dir;
+    installed = true;
+    vault = [];
+    __resetPhantomCache();
+    __setPhantomSpawn(fakeSpawn as never);
+  });
+
+  afterEach(() => {
+    process.env.PATH = savedPath;
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  afterAll(() => {
+    __setPhantomSpawn();
+    __resetPhantomCache();
+  });
+
+  it("reports present and missing secrets in recipe order, then catalog secret order", async () => {
+    vault = ["OPENAI_API_KEY", "SUPABASE_ANON_KEY"];
+    const r = await wirePhantomForRecipe(recipeOf("stripe", "supabase", "openai", "github"), {
+      cwd: dir,
+    });
+    expect(r.present).toEqual(["supabase:SUPABASE_ANON_KEY", "openai:OPENAI_API_KEY"]);
+    expect(r.missing).toEqual([
+      "stripe:STRIPE_SECRET_KEY",
+      "supabase:SUPABASE_URL",
+      "supabase:SUPABASE_SERVICE_ROLE_KEY",
+      "github:GITHUB_TOKEN",
+    ]);
+    expect(r.skipped).toEqual([]);
+  });
+
+  it("follows input order, not alphabetical or catalog order", async () => {
+    const forward = await wirePhantomForRecipe(recipeOf("github", "stripe", "clerk"), { cwd: dir });
+    const reversed = await wirePhantomForRecipe(recipeOf("clerk", "stripe", "github"), {
+      cwd: dir,
+    });
+    const names = (r: { webhooks: string[] }) =>
+      r.webhooks.map((p) => p.split("/").pop()?.replace(/\.ts$/, ""));
+    expect(names(forward)).toEqual(["github", "stripe", "clerk"]);
+    expect(names(reversed)).toEqual(["clerk", "stripe", "github"]);
+    expect(forward.missing.map((m) => m.split(":")[0])).toEqual(["github", "stripe", "clerk"]);
+    expect(reversed.missing.map((m) => m.split(":")[0])).toEqual(["clerk", "stripe", "github"]);
+  });
+
+  it("keeps unknown providers in place in skipped and still orders the rest", async () => {
+    const r = await wirePhantomForRecipe(
+      recipeOf("zzz-unknown", "stripe", "aaa-unknown", "github"),
+      {
+        cwd: dir,
+      },
+    );
+    expect(r.skipped).toEqual(["zzz-unknown", "aaa-unknown"]);
+    expect(r.missing).toEqual(["stripe:STRIPE_SECRET_KEY", "github:GITHUB_TOKEN"]);
+    expect(r.webhooks.map((p) => p.split("/").pop())).toEqual(["stripe.ts", "github.ts"]);
+  });
+
+  it("marks every provider skipped, in input order, when the vault is unreadable", async () => {
+    vault = "unreadable";
+    const r = await wirePhantomForRecipe(recipeOf("github", "openai", "stripe"), { cwd: dir });
+    expect(r.skipped).toEqual(["github", "openai", "stripe"]);
+    expect(r.present).toEqual([]);
+    expect(r.missing).toEqual([]);
+    expect(r.webhooks.map((p) => p.split("/").pop())).toEqual(["github.ts", "stripe.ts"]);
+  });
+
+  it("lists skipped providers and webhook stubs in input order when phantom is missing", async () => {
+    installed = false;
+    const r = await wirePhantomForRecipe(recipeOf("stripe", "openai", "clerk", "github"), {
+      cwd: dir,
+    });
+    expect(r.skipped).toEqual(["stripe", "openai", "clerk", "github"]);
+    expect(r.webhooks.map((p) => p.split("/").pop())).toEqual([
+      "stripe.ts",
+      "clerk.ts",
+      "github.ts",
+    ]);
+    expect(r.present).toEqual([]);
+    expect(r.missing).toEqual([]);
+  });
+
+  it("repeats duplicate providers once per input entry, in order", async () => {
+    vault = ["STRIPE_SECRET_KEY"];
+    const r = await wirePhantomForRecipe(recipeOf("stripe", "github", "stripe"), { cwd: dir });
+    expect(r.present).toEqual(["stripe:STRIPE_SECRET_KEY", "stripe:STRIPE_SECRET_KEY"]);
+    expect(r.missing).toEqual(["github:GITHUB_TOKEN"]);
+    expect(r.webhooks.map((p) => p.split("/").pop())).toEqual([
+      "stripe.ts",
+      "github.ts",
+      "stripe.ts",
+    ]);
+  });
+
+  it("is deterministic across repeated runs of the same recipe", async () => {
+    vault = ["SENTRY_DSN", "RESEND_API_KEY"];
+    const recipe = recipeOf("sentry", "nope", "resend", "stripe", "supabase");
+    const first = await wirePhantomForRecipe(recipe, { cwd: dir });
+    for (let i = 0; i < 5; i++) {
+      expect(await wirePhantomForRecipe(recipe, { cwd: dir })).toEqual(first);
+    }
+  });
+
+  it("returns empty ordered lists for an empty recipe and for noWire", async () => {
+    const empty = { present: [], missing: [], webhooks: [], skipped: [] };
+    expect(await wirePhantomForRecipe(recipeOf(), { cwd: dir })).toEqual(empty);
+    expect(
+      await wirePhantomForRecipe(recipeOf("stripe", "github"), { cwd: dir, noWire: true }),
+    ).toEqual(empty);
+  });
+});