@ashlr/stack-core 0.3.1 → 0.3.7

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

@@ -0,0 +1,122 @@
+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 name whose only byte has no case mapping: `capitalize` folds it to itself
+// and `toUpperCase` leaves it, so it lands byte-identically at all five
+// name-fed expansion sites — while still exercising the normal codePointAt
+// path, since the `s === ""` early return only fires for the truly empty name.
+const SENTINEL = "\u0000";
+
+describe("ai/phantom-wire known placeholder replaced with an empty value", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-empty-replacement-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "empty-replacement",
+    query: "q",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: names.map((name) => ({ name })),
+  });
+
+  it("replaces the known placeholder with the empty string and leaves all surrounding text byte-for-byte", () => {
+    // Whole-stub differential oracle: the sentinelled render marks every
+    // expansion site, and deleting each mark must reproduce the empty render
+    // exactly — the strongest form of "surrounding text remains", covering
+    // every byte of the template, not just the lines the placeholder sits on.
+    const sent = webhookStubFor(SENTINEL);
+
+    // The sentinel reached exactly five sites — one per name-fed slot — so
+    // the oracle below is not vacuous: every placeholder was exercised.
+    expect(count(sent, SENTINEL)).toBe(5);
+
+    // Removing the placeholder's replacement value leaves the empty render:
+    // the slot emitted "" and nothing else moved anywhere in the output.
+    expect(sent.replaceAll(SENTINEL, "")).toBe(webhookStubFor(""));
+  });
+
+  it("emits the empty replacement at all five sites with each surrounding line intact", () => {
+    // Full-line equality (not substring presence): each placeholder line is
+    // byte-exact — the slot vanished into "" and the rest of the line kept
+    // its fixed text with no extra residue appended to it.
+    const stub = webhookStubFor("");
+    const lines = stub.split("\n");
+
+    // `${provider}` sites: the name vanished between the fixed prose — a
+    // trailing period after "for " and a doubled space inside "forge a".
+    expect(lines).toContain("// Auto-generated by `stack apply` — webhook handler stub for .");
+    expect(lines).toContain("//   // to this endpoint can forge a  webhook.");
+
+    // `${capitalize(provider)}` site: the `s === ""` early return keeps
+    // `codePointAt(0)`'s undefined out of `String.fromCodePoint`, which
+    // would throw a RangeError on NaN — the handler name is just "handle".
+    expect(lines).toContain(
+      "// export async function handleWebhook(req: Request): Promise<Response> {",
+    );
+
+    // `${webhookSecretKeyFor(provider)}` sites: `"".toUpperCase()` is "" —
+    // the default switch case emitted the bare `_WEBHOOK_SECRET` suffix at
+    // both reveal lines, each otherwise byte-exact.
+    expect(lines).toContain("//   phantom reveal _WEBHOOK_SECRET");
+    expect(lines).toContain("//   // (`phantom reveal _WEBHOOK_SECRET`) and compare in");
+    expect(count(stub, "phantom reveal _WEBHOOK_SECRET")).toBe(2);
+
+    // Single pass, every slot resolved: no `${...}` residue anywhere.
+    expect(stub).not.toContain("${");
+
+    // The sibling slots took their generic defaults in the same pass — the
+    // empty name reaches none of the known-provider switch cases.
+    expect(lines).toContain('//   const signature = req.headers.get("x-webhook-signature");');
+    expect(lines).toContain("//   // Verify per the provider's documented signature scheme.");
+    expect(verificationHintFor("")).toBe(verificationHintFor("zzq"));
+  });
+
+  it("reports the empty name in skipped byte-for-byte beside a wired known provider", async () => {
+    // Through `wirePhantomForRecipe` the empty name matches no catalog
+    // provider: `skipped` holds the empty string itself — pushed, not
+    // dropped — while the known provider listed beside it wires normally,
+    // unaffected by the empty neighbour.
+    const stubPath = join(dir, ".stack", "webhooks", "github.ts");
+    const result = await wirePhantomForRecipe(recipe("", "github"), { cwd: dir });
+
+    expect(result).toEqual({
+      present: [],
+      missing: ["github:GITHUB_TOKEN"],
+      webhooks: [stubPath],
+      skipped: [""],
+    });
+    expect(result.skipped).toHaveLength(1);
+    expect(result.skipped[0]).toBe("");
+
+    // Only github's documented stub lands — nothing for the empty 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", ".ts"))).toBe(false);
+
+    // The whole call log is reads (`--version`, `list`); the vault file
+    // still parses to an empty object — an empty 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-empty-stderr.test.ts

@@ -0,0 +1,145 @@
+import { afterEach, beforeEach, describe, expect, it, setDefaultTimeout } from "bun:test";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { type Harness, setupFakePhantom } from "../__tests__/_harness.ts";
+import { exec, isPhantomInstalled, listSecrets } from "../phantom.ts";
+import { wirePhantomForRecipe } from "./phantom-wire.ts";
+import type { Recipe } from "./recipe.ts";
+
+// Each test spawns the fake `phantom` shim (bash + python3).
+setDefaultTimeout(30_000);
+
+const RECIPE: Recipe = {
+  id: "silent-failure",
+  query: "payments",
+  createdAt: "2026-04-18T00:00:00.000Z",
+  providers: [{ name: "stripe" }, { name: "neon" }],
+};
+
+/**
+ * Rewrite the harness `phantom`'s `list` arm to exit nonzero without a single
+ * stderr byte — a real crash shape (a killed wrapper, a denied helper, a
+ * build that prints nothing). `--version` still answers so the install probe
+ * passes and `list --json` is the subprocess that fails. The logging preamble
+ * is preserved so `callsTo` still sees every spawned command. `stdout`
+ * optionally carries output the failed call must not legitimise.
+ */
+function failListSilently(h: Harness, stdout = ""): void {
+  const bin = join(h.dir, "phantom");
+  const shim = readFileSync(bin, "utf-8");
+  expect(shim).toContain("  list)\n");
+  writeFileSync(
+    bin,
+    shim.replace("  list)\n", `  list)\n    printf '%s' '${stdout}'\n    exit 9\n`),
+  );
+}
+
+/**
+ * Rewrite only the `--version` arm to exit nonzero with empty stderr, so the
+ * install probe itself is the silently failing subprocess.
+ */
+function failVersionSilently(h: Harness): void {
+  const bin = join(h.dir, "phantom");
+  const shim = readFileSync(bin, "utf-8");
+  expect(shim).toContain("  --version)\n");
+  writeFileSync(bin, shim.replace("  --version)\n", "  --version)\n    exit 9\n"));
+}
+
+describe("ai/phantom-wire when the subprocess exits nonzero with empty stderr", () => {
+  let harness: Harness;
+
+  beforeEach(() => {
+    // The vault file really holds STRIPE_SECRET_KEY: a successful inventory
+    // would report it `present`. The failed `list` must not.
+    harness = setupFakePhantom({ STRIPE_SECRET_KEY: "x" });
+  });
+  afterEach(() => {
+    harness.cleanup();
+  });
+
+  it("keeps a silently failing inventory distinct from a successful read and reports why", async () => {
+    failListSilently(harness);
+
+    // The returned exec failure is distinguishable from success on its own:
+    // nonzero code, an "exited" completion, and genuinely empty streams.
+    const result = await exec(["list", "--json"], { cwd: harness.dir, allowFailure: true });
+    expect(result).toMatchObject({ code: 9, stderr: "", stdout: "", completion: "exited" });
+    expect(result.code).not.toBe(0);
+
+    // The thrown diagnostic names the unavailable inventory outright — it
+    // never depended on stderr carrying a message.
+    await expect(listSecrets(harness.dir)).rejects.toMatchObject({
+      code: "PHANTOM_METADATA_UNAVAILABLE",
+      message: "Phantom secret inventory is unavailable; stored names are unknown.",
+    });
+
+    // Wire keeps both providers in `skipped` — the failure stays
+    // distinguishable from a successful read, which would have put
+    // `stripe:STRIPE_SECRET_KEY` in `present` and the Neon secrets in
+    // `missing`. Neither success-shaped entry may appear.
+    const stubPath = join(harness.dir, ".stack/webhooks/stripe.ts");
+    expect(await wirePhantomForRecipe(RECIPE, { cwd: harness.dir })).toEqual({
+      present: [],
+      missing: [],
+      webhooks: [stubPath],
+      skipped: ["stripe", "neon"],
+    });
+    expect(existsSync(stubPath)).toBe(true);
+    expect(readFileSync(stubPath, "utf-8")).toContain("stripe-signature");
+    expect(harness.callsTo("add")).toEqual([]);
+  });
+
+  it("never treats stdout from a silently failed list as a successful inventory", async () => {
+    // A plausible-looking payload on stdout does not upgrade a nonzero exit
+    // to success: the vault stays unread and every provider is skipped.
+    failListSilently(harness, '[{"name":"STRIPE_SECRET_KEY"}]');
+
+    await expect(listSecrets(harness.dir)).rejects.toMatchObject({
+      code: "PHANTOM_METADATA_UNAVAILABLE",
+    });
+    const wire = await wirePhantomForRecipe(RECIPE, { cwd: harness.dir });
+    expect(wire.present).toEqual([]);
+    expect(wire.missing).toEqual([]);
+    expect(wire.skipped).toEqual(["stripe", "neon"]);
+    expect(wire.webhooks).toEqual([join(harness.dir, ".stack/webhooks/stripe.ts")]);
+  });
+
+  it("maps a silently crashing --version probe to not-installed, never to success", async () => {
+    failVersionSilently(harness);
+
+    // The probe reads the nonzero close as missing — distinguishable from an
+    // installed phantom — and the typed diagnostic carries the install hint.
+    expect(await isPhantomInstalled()).toBe(false);
+    await expect(listSecrets(harness.dir)).rejects.toMatchObject({
+      code: "PHANTOM_NOT_INSTALLED",
+    });
+
+    // Wire skips every provider, still writes the stub, and never reaches
+    // the inventory subprocess at all.
+    const stubPath = join(harness.dir, ".stack/webhooks/stripe.ts");
+    expect(await wirePhantomForRecipe(RECIPE, { cwd: harness.dir })).toEqual({
+      present: [],
+      missing: [],
+      webhooks: [stubPath],
+      skipped: ["stripe", "neon"],
+    });
+    expect(existsSync(stubPath)).toBe(true);
+    expect(harness.callsTo("--version")).toEqual([{ cmd: "--version", args: [] }]);
+    expect(harness.callsTo("list")).toEqual([]);
+    expect(harness.callsTo("add")).toEqual([]);
+  });
+
+  it("keeps the command and exit code in the rejection when stderr is empty", async () => {
+    failListSilently(harness);
+
+    // Callers that do not allowFailure get a rejection that still diagnoses:
+    // the argv and exit code are interpolated into the message, not the
+    // (empty) stderr text.
+    await expect(exec(["list", "--json"], { cwd: harness.dir })).rejects.toMatchObject({
+      code: "PHANTOM_EXEC_FAILED",
+    });
+    await expect(exec(["list", "--json"], { cwd: harness.dir })).rejects.toThrow(
+      /phantom list --json failed \(exit 9\)/,
+    );
+  });
+});

package/src/ai/phantom-wire-empty-template.test.ts

@@ -0,0 +1,81 @@
+import { afterEach, beforeEach, describe, expect, it, setDefaultTimeout } from "bun:test";
+import { 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 empty template (the empty name as replacement text)", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "wire-empty-template-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "empty-template",
+    query: "q",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: names.map((name) => ({ name })),
+  });
+
+  it("substitutes the empty string at every expansion site", () => {
+    // The name is the empty template: every slot the name feeds resolves
+    // to the empty string. Substitution returns "" — the slot vanishes
+    // between the template's own fixed text instead of leaving residue.
+    const stub = webhookStubFor("");
+
+    // Case-preserving sites collapse to nothing: `forge a  webhook.` keeps
+    // the double space where the name sat, proving the slot emitted ""
+    // rather than being skipped (a skipped slot would print `${provider}`).
+    expect(stub).toContain("webhook handler stub for .");
+    expect(stub).toContain("forge a  webhook.");
+
+    // `capitalize("")` must return "": its `s === ""` early return is the
+    // only thing keeping `codePointAt(0)`'s undefined out of
+    // `String.fromCodePoint`, which would throw a RangeError on NaN.
+    expect(stub).toContain("handleWebhook(req: Request)");
+
+    // `"".toUpperCase()` is "" at both reveal sites — the secret-key slot
+    // ran through the default switch case and emitted the bare suffix.
+    expect(stub.split("phantom reveal _WEBHOOK_SECRET").length - 1).toBe(2);
+
+    // Single pass, every slot resolved: the render holds zero `${...}`
+    // spans and no doubled placeholder text.
+    expect(stub).not.toContain("${");
+
+    // The sibling slots took their generic defaults in the same pass — ""
+    // reaches none of the known-provider switch cases.
+    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("reports the empty name in skipped byte-for-byte and writes nothing for it", async () => {
+    // "" matches no catalog provider and no webhook set: `skipped` is a
+    // single-element array holding the empty string itself — pushed, not
+    // dropped — and no stub lands on disk.
+    const result = await wirePhantomForRecipe(recipe(""), { cwd: dir });
+
+    expect(result).toEqual({ present: [], missing: [], webhooks: [], skipped: [""] });
+    expect(result.skipped).toHaveLength(1);
+    expect(readdirSync(dir)).toEqual([]);
+
+    // The whole call log is reads (`--version`, `list`); the vault file
+    // still parses to an empty object — an empty 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-empty-values.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, it, setDefaultTimeout } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type Harness, setupFakePhantom } from "../__tests__/_harness.ts";
+import { wirePhantomForRecipe } from "./phantom-wire.ts";
+import type { Recipe } from "./recipe.ts";
+
+// Each test spawns the fake `phantom` shim (bash + python3).
+setDefaultTimeout(30_000);
+
+const EMPTY_RESULT = { present: [], missing: [], webhooks: [], skipped: [] };
+
+describe("ai/phantom-wire empty set of requested values", () => {
+  let harness: Harness;
+  let dir: string;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+    dir = mkdtempSync(join(tmpdir(), "stack wire empty-values-"));
+  });
+  afterEach(() => {
+    harness.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const recipe = (...names: string[]): Recipe => ({
+    id: "empty-values",
+    query: "q",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: names.map((name) => ({ name })),
+  });
+
+  const vaultText = () => readFileSync(harness.vaultPath, "utf-8");
+  // Every logged phantom call must be a read: the install probe or `list`.
+  // A placeholder write could only arrive through `add`/`init`/`remove`/`sync`.
+  const onlyReadCalls = () =>
+    harness.calls().every((c) => c.cmd === "--version" || c.cmd === "list");
+
+  it("writes no placeholder for a recipe with no providers", async () => {
+    const before = vaultText();
+    const result = await wirePhantomForRecipe(recipe(), { cwd: dir });
+
+    // Nothing was requested, so nothing can be present, missing, skipped or
+    // stubbed — the documented empty result.
+    expect(result).toEqual(EMPTY_RESULT);
+    expect(onlyReadCalls()).toBe(true);
+    expect(harness.callsTo("add")).toEqual([]);
+    // The vault file is byte-identical and no placeholder artifact lands on
+    // disk: no `.stack/` tree, no `.env`, nothing.
+    expect(vaultText()).toBe(before);
+    expect(JSON.parse(vaultText())).toEqual({});
+    expect(readdirSync(dir)).toEqual([]);
+  });
+
+  it("makes no external process calls for a recipe with no providers", async () => {
+    const result = await wirePhantomForRecipe(recipe(), { cwd: dir });
+
+    // Not even the `--version` install probe or `list --json` may run.
+    expect(result).toEqual(EMPTY_RESULT);
+    expect(harness.calls()).toEqual([]);
+  });
+
+  it("leaves a populated vault byte-identical when nothing is requested", async () => {
+    writeFileSync(
+      harness.vaultPath,
+      JSON.stringify({ STRIPE_SECRET_KEY: "stored-real-value", GITHUB_TOKEN: "gh-tok" }),
+    );
+    const before = vaultText();
+
+    const result = await wirePhantomForRecipe(recipe(), { cwd: dir });
+
+    // An empty request reports nothing — not even the stored names — and
+    // must not reconcile the vault: nothing moves to `present`, no stored
+    // name is dropped or rewritten.
+    expect(result).toEqual(EMPTY_RESULT);
+    expect(onlyReadCalls()).toBe(true);
+    expect(harness.callsTo("add")).toEqual([]);
+    expect(vaultText()).toBe(before);
+    expect(JSON.parse(vaultText())).toEqual({
+      STRIPE_SECRET_KEY: "stored-real-value",
+      GITHUB_TOKEN: "gh-tok",
+    });
+    expect(readdirSync(dir)).toEqual([]);
+  });
+
+  it("writes no placeholder when every named provider misses the catalog", async () => {
+    const before = vaultText();
+    const result = await wirePhantomForRecipe(recipe("nope", "also-nope"), { cwd: dir });
+
+    // Unknown names resolve no secret list, so the requested set stays
+    // empty: they are reported skipped, never missing, and no stub lands.
+    expect(result).toEqual({
+      present: [],
+      missing: [],
+      webhooks: [],
+      skipped: ["nope", "also-nope"],
+    });
+    expect(onlyReadCalls()).toBe(true);
+    expect(harness.callsTo("add")).toEqual([]);
+    expect(vaultText()).toBe(before);
+    expect(readdirSync(dir)).toEqual([]);
+  });
+
+  it("writes no placeholder when the vault cannot be read", async () => {
+    // Corrupt the vault file so `list --json` exits nonzero. The requested
+    // set is still empty and the failed read must not trigger a write.
+    writeFileSync(harness.vaultPath, "not json");
+
+    const result = await wirePhantomForRecipe(recipe(), { cwd: dir });
+
+    expect(result).toEqual(EMPTY_RESULT);
+    expect(onlyReadCalls()).toBe(true);
+    expect(harness.callsTo("add")).toEqual([]);
+    // The unreadable file is left alone — no repair write, no placeholder.
+    expect(vaultText()).toBe("not json");
+    expect(readdirSync(dir)).toEqual([]);
+  });
+
+  it("spawns nothing at all when the empty request opts out with noWire", async () => {
+    const before = vaultText();
+    const result = await wirePhantomForRecipe(recipe(), { cwd: dir, noWire: true });
+
+    expect(result).toEqual(EMPTY_RESULT);
+    expect(harness.calls()).toEqual([]);
+    expect(vaultText()).toBe(before);
+    expect(existsSync(join(dir, ".stack"))).toBe(false);
+  });
+});