@ashlr/stack-core 0.3.0 → 0.3.6

package/README.md

@@ -2,7 +2,7 @@
 
 > Shared library behind the [Ashlr Stack](https://stack.ashlr.ai) CLI and MCP server. Provider adapters, `.stack.toml` config, Phantom integration, source/env detection.
 
-This workspace package shares source between the [`@ashlr/stack`](https://www.npmjs.com/package/@ashlr/stack) CLI and [`ashlr-stack-mcp`](https://www.npmjs.com/package/ashlr-stack-mcp) server. Its export points at TypeScript source. The examples below target the reviewed workspace; they do not establish a separately published core package or Node-only execution support.
+This package shares source between the [`@ashlr/stack`](https://www.npmjs.com/package/@ashlr/stack) CLI and [`ashlr-stack-mcp`](https://www.npmjs.com/package/ashlr-stack-mcp) server. Its exports point at TypeScript source. The examples below describe workspace use; installing the package does not by itself establish Node-only execution support.
 
 ## Use in this workspace
 
@@ -13,8 +13,8 @@ bun install
 ```
 
 Use the selected CLI/MCP artifact and its documented runtime when installing
-those products. Source version `0.2.1` is distinct from recorded public
-CLI/MCP `0.1.1` packages; verify actual package contents separately.
+those products. Verify installed versions, package contents and runtime
+requirements separately.
 
 ## Public API
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashlr/stack-core",
-  "version": "0.3.0",
+  "version": "0.3.6",
   "description": "Ashlr Stack core — provider adapters, .stack.toml config, Phantom integration. Shared logic behind the Stack CLI and MCP server.",
   "license": "MIT",
   "author": {

package/src/__tests__/_harness.ts

@@ -1,4 +1,4 @@
-import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { __resetPhantomCache } from "../phantom.ts";
@@ -53,19 +53,60 @@ export function setupFakePhantom(
   writeFileSync(vaultPath, JSON.stringify(initial));
   writeFileSync(logPath, "");
 
-  // The vault/log paths are trusted (we created them), but ALL args ($1..$N)
-  // come from tests that may contain user-shaped secret values with quotes,
-  // newlines, backslashes, etc. Those must NEVER be interpolated into Python
-  // source — instead we pass them via sys.argv so the shell + Python handle
-  // quoting for us.
+  // Each fake-phantom call used to spawn python3 twice; interpreter startup
+  // dominated the suite. One tiny Bun helper (same runtime as the tests) does
+  // the JSON work instead. ALL args ($1..$N) may contain user-shaped values
+  // with quotes, newlines or backslashes, so they reach the helper only through
+  // argv and are never interpolated into source.
+  const helperPath = join(dir, "helper.mjs");
+  writeFileSync(
+    helperPath,
+    `import { appendFileSync, readFileSync, writeFileSync } from "node:fs";
+const [op, vault, ...rest] = process.argv.slice(2);
+const load = () => JSON.parse(readFileSync(vault, "utf8"));
+if (op === "log") {
+  appendFileSync(vault, JSON.stringify({ cmd: rest[0] ?? "", args: rest.slice(1) }) + "\\n");
+} else if (op === "add") {
+  const v = load();
+  if (rest[0] in v) {
+    process.stderr.write("Error: Secret '" + rest[0] + "' is already protected. phantom add creates new names only and refuses replacement before reading a value.\\n");
+    process.exit(1);
+  }
+  const value = readFileSync(0, "utf8").split("\\n")[0].replace(/\\r+$/, "");
+  if (!value) {
+    process.stderr.write("Error: Received empty value on stdin\\n");
+    process.exit(1);
+  }
+  v[rest[0]] = value;
+  writeFileSync(vault, JSON.stringify(v));
+} else if (op === "remove") {
+  const v = load();
+  delete v[rest[0]];
+  writeFileSync(vault, JSON.stringify(v));
+} else if (op === "list") {
+  const v = load();
+  const names = Object.keys(v);
+  if (rest.includes("--json")) {
+    console.log(JSON.stringify(names.map((name) => ({ name, detected_service: null })), null, 2));
+  } else {
+    console.log("-> " + names.length + " secret(s) in vault (encrypted-file):\\n");
+    for (const k of names) console.log("   - " + k);
+    console.log("\\nnote Values are never displayed. Use phantom add/remove to manage.");
+  }
+} else if (op === "reveal") {
+  console.log(load()[rest[0]] ?? "");
+}
+`,
+  );
   const script = `#!/usr/bin/env bash
 set -e
 VAULT=${JSON.stringify(vaultPath)}
 LOG=${JSON.stringify(logPath)}
+H() { ${JSON.stringify(process.execPath)} ${JSON.stringify(helperPath)} "$@"; }
 LEGACY_HEADLESS_REVEAL=${options.legacyHeadlessReveal ? 1 : 0}
 
 # Log the invocation as a single JSON line (args passed via argv, never interpolated).
-python3 -c 'import json,sys; open(sys.argv[1], "a").write(json.dumps({"cmd": sys.argv[2] if len(sys.argv) > 2 else "", "args": sys.argv[3:]}) + "\\n")' "$LOG" "$@" 2>/dev/null || true
+H log "$LOG" "$@" 2>/dev/null || true
 
 case "\${1:-}" in
   --version)
@@ -90,18 +131,7 @@ case "\${1:-}" in
       echo "Error: Positional secret values are disabled because command-line arguments can be exposed by process inspection. Omit the value for a hidden terminal prompt, or use --stdin." >&2
       exit 1
     fi
-    python3 -c 'import json,sys
-with open(sys.argv[1]) as f: v = json.load(f)
-if sys.argv[2] in v:
-    sys.stderr.write("Error: Secret %r is already protected. phantom add creates new names only and refuses replacement before reading a value.\\n" % sys.argv[2])
-    sys.exit(1)
-value = sys.stdin.readline().rstrip("\\r\\n")
-if not value:
-    sys.stderr.write("Error: Received empty value on stdin\\n")
-    sys.exit(1)
-v[sys.argv[2]] = value
-with open(sys.argv[1], "w") as f: json.dump(v, f)
-' "$VAULT" "$2"
+    H add "$VAULT" "$2"
     ;;
   remove)
     # Phantom Secrets >= 0.7.3: typed confirmation in an attached terminal.
@@ -109,23 +139,11 @@ with open(sys.argv[1], "w") as f: json.dump(v, f)
       echo "Error: phantom remove requires attached stdin, stdout, and stderr terminals and cannot run headlessly." >&2
       exit 1
     fi
-    python3 -c 'import json,sys
-with open(sys.argv[1]) as f: v = json.load(f)
-v.pop(sys.argv[2], None)
-with open(sys.argv[1], "w") as f: json.dump(v, f)
-' "$VAULT" "$2"
+    H remove "$VAULT" "$2"
     ;;
   list)
     # Real Phantom: \`list --json\` prints [{"name": ...}, ...] (names only).
-    python3 -c 'import json,sys
-with open(sys.argv[1]) as f: v = json.load(f)
-if "--json" in sys.argv[2:]:
-    print(json.dumps([{"name": k, "detected_service": None} for k in v], indent=2))
-else:
-    print("-> %d secret(s) in vault (encrypted-file):\\n" % len(v))
-    for k in v: print("   - " + k)
-    print("\\nnote Values are never displayed. Use phantom add/remove to manage.")
-' "$VAULT" "\${@:2}"
+    H list "$VAULT" "\${@:2}"
     ;;
   reveal)
     # Phantom Secrets >= 0.7.3: plaintext only into an attached terminal.
@@ -133,10 +151,7 @@ else:
       echo "Error: Refusing to reveal a secret without attached stdin and stderr terminals" >&2
       exit 1
     fi
-    python3 -c 'import json,sys
-with open(sys.argv[1]) as f: v = json.load(f)
-print(v.get(sys.argv[2], ""))
-' "$VAULT" "$2"
+    H reveal "$VAULT" "$2"
     ;;
   init)
     # no-op for the fake — the vault file already exists
@@ -149,8 +164,19 @@ print(v.get(sys.argv[2], ""))
 esac
 `;
   const binPath = join(dir, "phantom");
-  writeFileSync(binPath, script);
-  chmodSync(binPath, 0o755);
+  // Sandboxed runners and macOS Gatekeeper's provenance policy refuse to
+  // exec an extensionless file written by a non-platform process, while a
+  // `*.sh` target passes the check. Write the shim as `phantom.sh` and link
+  // `phantom` at it; fall back to the direct file where symlinks fail.
+  const realPath = join(dir, "phantom.sh");
+  writeFileSync(realPath, script);
+  chmodSync(realPath, 0o755);
+  try {
+    symlinkSync(realPath, binPath);
+  } catch {
+    writeFileSync(binPath, script);
+    chmodSync(binPath, 0o755);
+  }
 
   const previousPath = process.env.PATH ?? "";
   process.env.PATH = `${dir}:${previousPath}`;

package/src/__tests__/apply-placeholder-history.test.ts

@@ -0,0 +1,55 @@
+import { expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+
+const docUrl = new URL("../../../../docs/apply-placeholder-history.md", import.meta.url);
+const history = readFileSync(docUrl, "utf8");
+const location = readFileSync(
+  new URL("../../../../docs/apply-history-location.md", import.meta.url),
+  "utf8",
+);
+
+test.each([
+  [
+    "../CHANGELOG.md",
+    "010--2026-04-19-superseded-by-011",
+    "## 0.1.0 — 2026-04-19 (superseded by 0.1.1)",
+    "- **`stack apply [recipe-id]`**",
+  ],
+  [
+    "../packages/site/src/data/CHANGELOG.md",
+    "010--2026-04-19-superseded-by-011",
+    "## 0.1.0 — 2026-04-19 (superseded by 0.1.1)",
+    "- **`stack apply [recipe-id]`**",
+  ],
+  [
+    "../CHANGELOG.md",
+    "021-2026-10-16",
+    "## 0.2.1 (2026-10-16)",
+    "- **`stack apply` stops attempting to write placeholder secrets.**",
+  ],
+  [
+    "../packages/site/src/data/CHANGELOG.md",
+    "021-2026-10-16",
+    "## 0.2.1 (2026-10-16)",
+    "- **`stack apply` stops attempting to write placeholder secrets.**",
+  ],
+])("history links to the relevant entry in %s#%s", (path, anchor, heading, entryPrefix) => {
+  expect(history).toContain(`](${path}#${anchor})`);
+  expect(location).toContain(`](${path}#${anchor})`);
+  const changelog = readFileSync(new URL(path, docUrl), "utf8");
+  const release = changelog.split(`${heading}\n`)[1]?.split("\n## ")[0];
+  expect(release).toBeDefined();
+  const entry = release?.split("\n").find((line) => line.startsWith(entryPrefix));
+  expect(entry).toContain("TODO_STACK_APPLY");
+  expect(entry).toContain("failed");
+  expect(entry).toMatch(
+    /(?:does not write|never writes) to the vault or fills? (?:in )?missing values/,
+  );
+});
+
+test("location distinguishes failed historical attempts from the fix", () => {
+  expect(location).toContain("Phantom rejected those attempts");
+  expect(location).toContain("The 0.2.1 fix removed the attempts");
+  expect(location).toContain("provider setup may separately store real");
+  expect(location).toContain("](../CHANGELOG.md#022-2026-10-25)");
+});

package/src/__tests__/apply-placeholder-operator-checklist.test.ts

@@ -0,0 +1,28 @@
+import { expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+
+const checklist = readFileSync(
+  new URL("../../../../docs/apply-placeholder-operator-checklist.md", import.meta.url),
+  "utf8",
+);
+const changelog = readFileSync(new URL("../../../../CHANGELOG.md", import.meta.url), "utf8");
+
+it("identifies the historical marker as a failed attempt, never an operator value", () => {
+  const marker = "TODO_STACK_APPLY";
+  expect(changelog).toContain(marker);
+  expect(checklist).toContain(marker);
+  expect(checklist).toContain("attempts failed");
+  expect(checklist).toContain("Do not use the marker as a secret value");
+  for (const block of checklist.matchAll(/```[^\n]*\n([\s\S]*?)```/g)) {
+    expect(block[1]).not.toContain(marker);
+  }
+});
+
+it("directs operators to enter real values and treats incomplete inventory as unknown", () => {
+  expect(checklist).toContain("`phantom add <NAME>`");
+  expect(checklist).toContain("`phantom add OPENAI_API_KEY`");
+  expect(checklist).toContain("enter the real value when prompted");
+  expect(checklist).toContain("do not put the value in command");
+  expect(checklist).toContain("`skipped`, not missing");
+  expect(checklist).toContain("`--noWire` skips both name checks and webhook");
+});

package/src/__tests__/apply-terminology-examples.test.ts

@@ -0,0 +1,46 @@
+import { afterEach, beforeEach, expect, it, setDefaultTimeout } from "bun:test";
+import { readFileSync, writeFileSync } from "node:fs";
+import { wirePhantomForRecipe } from "../ai/phantom-wire.ts";
+import type { Recipe } from "../ai/recipe.ts";
+import { type Harness, setupFakePhantom } from "./_harness.ts";
+
+setDefaultTimeout(30_000);
+
+const doc = readFileSync(
+  new URL("../../../../docs/apply-terminology-examples.md", import.meta.url),
+  "utf-8",
+);
+const examples = [...doc.matchAll(/```json\n([^\n]+)\n```/g)].map((match) => JSON.parse(match[1]));
+const recipe: Recipe = {
+  id: "example",
+  query: "example",
+  createdAt: "2026-04-18T00:00:00.000Z",
+  providers: [{ name: "openai" }],
+};
+
+let harness: Harness;
+beforeEach(() => {
+  harness = setupFakePhantom({ OPENAI_API_KEY: "test-value" });
+});
+afterEach(() => harness.cleanup());
+
+it("documents the readable inventory examples without writing placeholders", async () => {
+  expect(examples).toHaveLength(3);
+  expect(await wirePhantomForRecipe(recipe, { cwd: harness.dir })).toEqual(examples[0]);
+  writeFileSync(harness.vaultPath, "{}");
+  expect(await wirePhantomForRecipe(recipe, { cwd: harness.dir })).toEqual(examples[1]);
+  expect(harness.callsTo("add")).toEqual([]);
+});
+
+it("documents an unreadable inventory alongside the generated Stripe stub", async () => {
+  writeFileSync(harness.vaultPath, "not json");
+  const result = await wirePhantomForRecipe(
+    { ...recipe, providers: [{ name: "stripe" }] },
+    { cwd: harness.dir },
+  );
+  expect({
+    ...result,
+    webhooks: result.webhooks.map((path) => path.replace(harness.dir, "<project>")),
+  }).toEqual(examples[2]);
+  expect(harness.callsTo("add")).toEqual([]);
+});

package/src/__tests__/config.test.ts

@@ -68,6 +68,42 @@ describe("config", () => {
     expect(roundTripped.services.supabase).toEqual(original.services.supabase);
   });
 
+  test("a full configuration survives serialize → parse with every value preserved", async () => {
+    const cwd = freshCwd();
+    const original = emptyConfig("saas");
+    original.services.supabase = {
+      provider: "supabase",
+      resource_id: "abcd1234",
+      region: "us-east-1",
+      secrets: ["SUPABASE_URL", "SUPABASE_ANON_KEY"],
+      mcp: "supabase",
+      meta: { plan: "free", replicas: 2, nested: { ok: true, tags: ["a", "b"] } },
+      created_at: "2026-04-17T05:00:00Z",
+      created_by: "test",
+    };
+    original.services.sentry = {
+      provider: "sentry",
+      secrets: [],
+      created_at: "2026-04-18T05:00:00Z",
+    };
+    original.environments = [
+      { name: "dev", default: true },
+      { name: "prod", overrides: { SUPABASE_URL: "SUPABASE_URL_PROD" } },
+    ];
+
+    await writeConfig(original, cwd);
+    const parsed = await readConfig(cwd);
+    expect(parsed).toEqual(original);
+
+    // Re-serializing the parsed config is stable: the files do not drift.
+    const shapeBefore = readFileSync(join(cwd, CONFIG_FILENAME), "utf-8");
+    const localBefore = readFileSync(join(cwd, LOCAL_FILENAME), "utf-8");
+    await writeConfig(parsed, cwd);
+    expect(readFileSync(join(cwd, CONFIG_FILENAME), "utf-8")).toBe(shapeBefore);
+    expect(readFileSync(join(cwd, LOCAL_FILENAME), "utf-8")).toBe(localBefore);
+    expect(await readConfig(cwd)).toEqual(original);
+  });
+
   test("readConfig throws ConfigNotFoundError when file is missing", async () => {
     const cwd = freshCwd();
     await expect(readConfig(cwd)).rejects.toThrow(/No .stack.toml at/);

package/src/__tests__/credential-staging.test.ts

@@ -242,12 +242,13 @@ describe("operation-owned credential persistence", () => {
   });
   test("reads/writes stay at captured absolute cwd despite ctx and opts mutation", async () => {
     // Add cwd metadata to the inert producer log, never secret input values.
-    const bin = join(h.dir, "phantom");
+    const helper = join(h.dir, "helper.mjs");
     writeFileSync(
-      bin,
-      readFileSync(bin, "utf8")
-        .replace("import json,sys; open", "import json,sys,os; open")
-        .replace('{"cmd": sys.argv[2]', '{"cwd": os.getcwd(), "cmd": sys.argv[2]'),
+      helper,
+      readFileSync(helper, "utf8").replace(
+        "JSON.stringify({ cmd: rest[0]",
+        "JSON.stringify({ cwd: process.cwd(), cmd: rest[0]",
+      ),
     );
     const opts = { providerName: "stagefixture", cwd, interactive: true };
     const p = factory();
@@ -267,7 +268,7 @@ describe("operation-owned credential persistence", () => {
       .trim()
       .split("\n")
       .map((line) => JSON.parse(line));
-    // Python getcwd resolves filesystem aliases such as macOS /var.
+    // process.cwd() resolves filesystem aliases such as macOS /var.
     for (const row of rows.filter((r) => ["status", "reveal", "add"].includes(r.cmd)))
       expect(row.cwd).toBe(realpathSync(cwd));
     expect((await readConfig(cwd)).services.stagefixture).toBeDefined();

package/src/__tests__/deps.test.ts

@@ -2,9 +2,22 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { buildDepsReport } from "../../../cli/src/commands/deps.ts";
 import { emptyConfig, writeConfig } from "../config.ts";
 import { getProvider, listProviderNames } from "../providers/index.ts";
 
+test("an empty service list resolves to an empty dependency report", async () => {
+  const config = emptyConfig();
+  expect(await buildDepsReport(config)).toEqual({
+    schema: "ashlr.stack.deps/v1",
+    project_id: config.stack.project_id,
+    template: null,
+    categories: [],
+    unresolved: [],
+    totals: { services: 0, secrets: 0, mcp: 0 },
+  });
+});
+
 describe("provider loading — wave 9 additions", () => {
   test("render + firebase are in the catalog", () => {
     const names = listProviderNames();
@@ -56,4 +69,26 @@ describe("config carrying 21+ provider entries still round-trips", () => {
     const roundtrip = await readConfig(cwd);
     expect(Object.keys(roundtrip.services).length).toBe(listProviderNames().length);
   });
+  test("duplicate secret entries are preserved verbatim (no dedupe on round-trip)", async () => {
+    const config = emptyConfig("dupes");
+    config.services.render = {
+      provider: "render",
+      secrets: ["RENDER_API_KEY", "RENDER_API_KEY"],
+      created_at: new Date().toISOString(),
+    };
+    await writeConfig(config, cwd);
+    const { readConfig } = await import("../config.ts");
+    const roundtrip = await readConfig(cwd);
+    expect(roundtrip.services.render?.secrets).toEqual(["RENDER_API_KEY", "RENDER_API_KEY"]);
+  });
+
+  test("a duplicated [services.x] table in .stack.toml is rejected, not merged", async () => {
+    const { readConfig, CONFIG_FILENAME } = await import("../config.ts");
+    const toml =
+      '[stack]\nversion = "1"\n\n' +
+      '[services.render]\nprovider = "render"\nsecrets = ["A"]\n\n' +
+      '[services.render]\nprovider = "render"\nsecrets = ["B"]\n';
+    await Bun.write(join(cwd, CONFIG_FILENAME), toml);
+    await expect(readConfig(cwd)).rejects.toThrow();
+  });
 });

package/src/__tests__/detect-source.test.ts

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync
 import { tmpdir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
 import { scanSource } from "../detect-source.ts";
+import { SourceDirectoryNotFoundError } from "../errors.ts";
 
 const projects: string[] = [];
 afterEach(() => {
@@ -152,6 +153,26 @@ require (
   });
 });
 
+test.each([
+  ["dependencies", "openai"],
+  ["dependencies", ["openai"]],
+  ["devDependencies", "openai"],
+  ["devDependencies", ["openai"]],
+] as const)("invalid %s section %j preserves a valid sibling", async (section, invalid) => {
+  const sibling = section === "dependencies" ? "devDependencies" : "dependencies";
+  const hits = await scanSource(
+    makeProject({
+      "package.json": JSON.stringify({
+        [section]: invalid,
+        [sibling]: { openai: "^4.0.0" },
+      }),
+    }),
+  );
+  expect(hits).toEqual([
+    { provider: "openai", confidence: "high", signals: ["package.json:openai"] },
+  ]);
+});
+
 test.each(["{broken", "null", "{}"])(
   "malformed or empty package %s does not hide other evidence",
   async (raw) => {
@@ -218,6 +239,36 @@ test("deduplicates dependency evidence and upgrades confidence without losing si
   ]);
 });
 
+test("repeated scans of an unchanged project return the same unique detections", async () => {
+  const cwd = makeProject({
+    "package.json": JSON.stringify({
+      dependencies: { openai: "1", "@vercel/kv": "1" },
+      devDependencies: { openai: "1" },
+    }),
+    "requirements.txt": "openai==1\nopenai>=1\n",
+    "vercel.json": "{}",
+    ".env.example": "OPENAI_API_KEY=\nOPENAI_API_KEY=\nVERCEL_TOKEN=",
+  });
+  const expected: Awaited<ReturnType<typeof scanSource>> = [
+    {
+      provider: "openai",
+      confidence: "high",
+      signals: ["package.json:openai", "requirements.txt:openai", ".env.example:OPENAI_API_KEY"],
+    },
+    {
+      provider: "vercel",
+      confidence: "high",
+      signals: ["package.json:@vercel/kv", "vercel.json", ".env.example:VERCEL_TOKEN"],
+    },
+  ];
+
+  const first = await scanSource(cwd);
+  const second = await scanSource(cwd);
+
+  expect(first).toEqual(expected);
+  expect(second).toEqual(expected);
+});
+
 test("scans a project directory containing spaces and reports relative file paths", async () => {
   const root = makeProject({
     "project with spaces/package.json": JSON.stringify({ dependencies: { openai: "1" } }),
@@ -279,6 +330,32 @@ test("empty project has no detections", async () => {
   expect(await scanSource(makeProject({}))).toEqual([]);
 });
 
+test("unrelated text file with provider-like content has no detections", async () => {
+  const cwd = makeProject({
+    "notes.txt": 'openai\nOPENAI_API_KEY=\n{"dependencies":{"@supabase/supabase-js":"1"}}',
+  });
+
+  expect(await scanSource(cwd)).toEqual([]);
+});
+
+test("an empty scan root ignores provider markers in its parent and stays empty", async () => {
+  const parent = makeProject({
+    "package.json": JSON.stringify({ dependencies: { openai: "1" } }),
+    "vercel.json": "{}",
+    ".env.example": "ANTHROPIC_API_KEY=",
+  });
+  const root = join(parent, "empty project");
+  mkdirSync(root);
+
+  expect((await scanSource(parent)).map((hit) => hit.provider)).toEqual([
+    "openai",
+    "vercel",
+    "anthropic",
+  ]);
+  expect(await scanSource(root)).toEqual([]);
+  expect(readdirSync(root)).toEqual([]);
+});
+
 test.each([["--json"], ["--yes"]])(
   "scan %s rejects a nonexistent project without creating files",
   async (flag) => {
@@ -324,3 +401,23 @@ test.each([
 ] as const)("empty dependency manifest %s produces no detections", async (file, content) => {
   expect(await scanSource(makeProject({ [file]: content }))).toEqual([]);
 });
+
+describe("source scanner — missing project directory", () => {
+  test("fails clearly and does not create the directory", async () => {
+    const parent = makeProject({});
+    const missing = join(parent, "no-such-project");
+    const err = await scanSource(missing).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(SourceDirectoryNotFoundError);
+    expect(err).toMatchObject({ code: "SOURCE_DIRECTORY_NOT_FOUND" });
+    expect((err as Error).message).toContain(missing);
+    expect((err as Error).message).toBe(`Source directory not found: ${missing}`);
+    expect(existsSync(missing)).toBe(false);
+  });
+
+  test("rejects a path that exists but is not a directory", async () => {
+    const cwd = makeProject({ "package.json": "{}" });
+    const file = join(cwd, "package.json");
+    await expect(scanSource(file)).rejects.toThrow(SourceDirectoryNotFoundError);
+    expect(existsSync(file)).toBe(true);
+  });
+});

package/src/__tests__/fixtures/stack-manifest.v1.json

@@ -2,9 +2,9 @@
   "schema_version": 1,
   "kind": "ashlr-stack-manifest",
   "components": [
-    { "id": "core", "name": "@ashlr/stack-core", "version": "0.3.0", "distribution": "npm" },
-    { "id": "cli", "name": "@ashlr/stack", "version": "0.3.0", "distribution": "npm" },
-    { "id": "mcp", "name": "ashlr-stack-mcp", "version": "0.3.0", "distribution": "npm" },
+    { "id": "core", "name": "@ashlr/stack-core", "version": "0.3.6", "distribution": "npm" },
+    { "id": "cli", "name": "@ashlr/stack", "version": "0.3.6", "distribution": "npm" },
+    { "id": "mcp", "name": "ashlr-stack-mcp", "version": "0.3.6", "distribution": "npm" },
     { "id": "plugin", "name": "stack", "version": "0.1.0", "distribution": "claude-code-plugin" }
   ]
 }

package/src/__tests__/phantom-process.test.ts

@@ -1,6 +1,14 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { spawnSync } from "node:child_process";
-import { chmodSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { delimiter, join, resolve } from "node:path";
 import { PhantomNotInstalledError } from "../errors.ts";
@@ -18,8 +26,18 @@ afterEach(() => {
 const name = process.platform === "win32" ? "phantom.exe" : "phantom";
 function binary(dir: string, script = "#!/bin/sh\nexit 0\n"): string {
   const path = join(dir, name);
-  writeFileSync(path, script);
-  chmodSync(path, 0o755);
+  // Sandboxed runners and macOS Gatekeeper's provenance policy refuse to
+  // exec an extensionless file written by a non-platform process, while a
+  // `*.sh` target passes the check: point `phantom` at a `phantom.sh` shim.
+  const real = join(dir, `${name}.sh`);
+  writeFileSync(real, script);
+  chmodSync(real, 0o755);
+  try {
+    symlinkSync(real, path);
+  } catch {
+    writeFileSync(path, script);
+    chmodSync(path, 0o755);
+  }
   return path;
 }