@ashlr/stack-core 0.1.1 → 0.3.0

package/src/__tests__/base-urls.test.ts

@@ -0,0 +1,208 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { LocalSLMBackend, defaultOllamaEndpoint } from "../ai/inference.ts";
+import {
+  DEFAULT_ANTHROPIC_BASE_URL,
+  DEFAULT_OLLAMA_BASE_URL,
+  DEFAULT_OPENAI_BASE_URL,
+  anthropicBaseUrl,
+  ollamaBaseUrl,
+  openaiBaseUrl,
+} from "../base-urls.ts";
+import type { ProviderContext } from "../providers/_base.ts";
+import anthropic from "../providers/anthropic.ts";
+import openai from "../providers/openai.ts";
+import { type Harness, setupFakePhantom } from "./_harness.ts";
+
+describe("defaults are unchanged", () => {
+  test("hosts match what Stack always called", () => {
+    expect(DEFAULT_ANTHROPIC_BASE_URL).toBe("https://api.anthropic.com");
+    expect(DEFAULT_OPENAI_BASE_URL).toBe("https://api.openai.com/v1");
+    expect(DEFAULT_OLLAMA_BASE_URL).toBe("http://localhost:11434");
+    expect(defaultOllamaEndpoint({}).baseUrl).toBe("http://localhost:11434/v1");
+  });
+  test("unset, empty and whitespace-only values fall back", () => {
+    for (const v of [undefined, "", "   ", "/", " // "]) {
+      expect(anthropicBaseUrl({ ANTHROPIC_BASE_URL: v })).toBe(DEFAULT_ANTHROPIC_BASE_URL);
+      expect(openaiBaseUrl({ OPENAI_BASE_URL: v })).toBe(DEFAULT_OPENAI_BASE_URL);
+      expect(ollamaBaseUrl({ OLLAMA_HOST: v })).toBe(DEFAULT_OLLAMA_BASE_URL);
+    }
+  });
+});
+
+describe("overrides are honored", () => {
+  test("anthropic and openai: used as given, trailing slashes trimmed", () => {
+    expect(anthropicBaseUrl({ ANTHROPIC_BASE_URL: "http://127.0.0.1:4000" })).toBe(
+      "http://127.0.0.1:4000",
+    );
+    expect(anthropicBaseUrl({ ANTHROPIC_BASE_URL: " https://gw.example/anthropic/// " })).toBe(
+      "https://gw.example/anthropic",
+    );
+    expect(openaiBaseUrl({ OPENAI_BASE_URL: "http://127.0.0.1:4000/v1/" })).toBe(
+      "http://127.0.0.1:4000/v1",
+    );
+  });
+  test("ollama host forms", () => {
+    expect(ollamaBaseUrl({ OLLAMA_HOST: "192.168.1.5:9999" })).toBe("http://192.168.1.5:9999");
+    expect(ollamaBaseUrl({ OLLAMA_HOST: "gpu-box:11435/" })).toBe("http://gpu-box:11435");
+    expect(ollamaBaseUrl({ OLLAMA_HOST: "gpu-box" })).toBe("http://gpu-box:11434");
+    expect(ollamaBaseUrl({ OLLAMA_HOST: ":8080" })).toBe("http://localhost:8080");
+    expect(ollamaBaseUrl({ OLLAMA_HOST: "[::1]:11434" })).toBe("http://[::1]:11434");
+    expect(ollamaBaseUrl({ OLLAMA_HOST: "[::1]" })).toBe("http://[::1]:11434");
+    expect(ollamaBaseUrl({ OLLAMA_HOST: "https://ollama.example.com/" })).toBe(
+      "https://ollama.example.com",
+    );
+    expect(defaultOllamaEndpoint({ OLLAMA_HOST: "gpu-box" }).baseUrl).toBe(
+      "http://gpu-box:11434/v1",
+    );
+  });
+  test.each(["/", "///"])("trailing %s does not duplicate composed separators", (slashes) => {
+    expect(
+      `${anthropicBaseUrl({ ANTHROPIC_BASE_URL: `https://gw.example/anthropic${slashes}` })}/v1/models`,
+    ).toBe("https://gw.example/anthropic/v1/models");
+    expect(
+      `${openaiBaseUrl({ OPENAI_BASE_URL: `https://gw.example/openai/v1${slashes}` })}/models`,
+    ).toBe("https://gw.example/openai/v1/models");
+    expect(
+      `${defaultOllamaEndpoint({ OLLAMA_HOST: `https://gw.example/ollama${slashes}` }).baseUrl}/models`,
+    ).toBe("https://gw.example/ollama/v1/models");
+  });
+});
+
+describe("callers read the variables at call time", () => {
+  const keys = ["ANTHROPIC_BASE_URL", "OPENAI_BASE_URL", "OLLAMA_HOST"] as const;
+  const saved = Object.fromEntries(keys.map((k) => [k, process.env[k]]));
+  let h: Harness;
+  let realFetch: typeof fetch;
+  let urls: string[];
+
+  beforeEach(() => {
+    // Exercises the HTTP call after a key is read; real Phantom 0.7.9 refuses headless reveal.
+    h = setupFakePhantom(
+      { ANTHROPIC_API_KEY: "sk-ant-fake", OPENAI_API_KEY: "sk-fake" },
+      { legacyHeadlessReveal: true },
+    );
+    realFetch = globalThis.fetch;
+    urls = [];
+    globalThis.fetch = (async (u: string | URL | Request) => {
+      urls.push(String(u));
+      return new Response(JSON.stringify({ data: [] }), { status: 200 });
+    }) as unknown as typeof fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = realFetch;
+    h.cleanup();
+    for (const k of keys) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  });
+
+  const ctx: ProviderContext = { cwd: process.cwd(), interactive: false, log: () => {} };
+  const entry = (provider: string, secret: string) => ({
+    provider,
+    secrets: [secret],
+    created_at: new Date().toISOString(),
+  });
+
+  test("key checks hit the default hosts when unset", async () => {
+    for (const k of keys) delete process.env[k];
+    expect((await anthropic.healthcheck!(ctx, entry("anthropic", "ANTHROPIC_API_KEY"))).kind).toBe(
+      "ok",
+    );
+    expect((await openai.healthcheck!(ctx, entry("openai", "OPENAI_API_KEY"))).kind).toBe("ok");
+    expect(urls).toEqual([
+      "https://api.anthropic.com/v1/models",
+      "https://api.openai.com/v1/models",
+    ]);
+  });
+
+  test("key checks follow ANTHROPIC_BASE_URL and OPENAI_BASE_URL", async () => {
+    process.env.ANTHROPIC_BASE_URL = "http://127.0.0.1:4000/";
+    process.env.OPENAI_BASE_URL = "http://127.0.0.1:4000/v1/";
+    await anthropic.healthcheck!(ctx, entry("anthropic", "ANTHROPIC_API_KEY"));
+    await openai.healthcheck!(ctx, entry("openai", "OPENAI_API_KEY"));
+    expect(urls).toEqual(["http://127.0.0.1:4000/v1/models", "http://127.0.0.1:4000/v1/models"]);
+  });
+
+  test.each(["", "/", "///"])(
+    "equivalent base URLs with trailing %j hit the same endpoints",
+    async (suffix) => {
+      process.env.ANTHROPIC_BASE_URL = `https://gw.example/anthropic${suffix}`;
+      process.env.OPENAI_BASE_URL = `https://gw.example/openai/v1${suffix}`;
+      process.env.OLLAMA_HOST = `https://gw.example/ollama${suffix}`;
+
+      expect(
+        (await anthropic.healthcheck!(ctx, entry("anthropic", "ANTHROPIC_API_KEY"))).kind,
+      ).toBe("ok");
+      expect((await openai.healthcheck!(ctx, entry("openai", "OPENAI_API_KEY"))).kind).toBe("ok");
+      expect(
+        await new LocalSLMBackend({
+          endpoints: [defaultOllamaEndpoint()],
+          fetchImpl: globalThis.fetch,
+        }).healthy(),
+      ).toBe(true);
+      expect(urls).toEqual([
+        "https://gw.example/anthropic/v1/models",
+        "https://gw.example/openai/v1/models",
+        "https://gw.example/ollama/v1/models",
+      ]);
+    },
+  );
+
+  test("the local SLM backend picks up OLLAMA_HOST when constructed", async () => {
+    process.env.OLLAMA_HOST = "gpu-box:11435/";
+    const seen: string[] = [];
+    const down = (async (u: string | URL | Request) => {
+      seen.push(String(u));
+      return new Response("down", { status: 503 });
+    }) as unknown as typeof fetch;
+    expect(await new LocalSLMBackend({ fetchImpl: down }).healthy()).toBe(false);
+    expect(seen).toContain("http://gpu-box:11435/v1/models");
+  });
+});
+
+describe("gateway rule for keyed providers", () => {
+  test("https anywhere and http to loopback literals are allowed", () => {
+    expect(anthropicBaseUrl({ ANTHROPIC_BASE_URL: "https://gw.example" })).toBe(
+      "https://gw.example",
+    );
+    expect(openaiBaseUrl({ OPENAI_BASE_URL: "http://[::1]:4000/v1" })).toBe("http://[::1]:4000/v1");
+  });
+  test.each([
+    "http://gw.example",
+    "http://localhost:4000",
+    "http://10.0.0.5:4000",
+    "ftp://127.0.0.1",
+    "not a url",
+  ])("%s is refused without echoing the URL", (v) => {
+    for (const [fn, name] of [
+      [anthropicBaseUrl, "ANTHROPIC_BASE_URL"],
+      [openaiBaseUrl, "OPENAI_BASE_URL"],
+    ] as const) {
+      let msg = "";
+      try {
+        fn({ [name]: v });
+      } catch (e) {
+        msg = (e as Error).message;
+      }
+      expect(msg).toContain(name);
+      expect(msg).not.toContain(v);
+    }
+  });
+  test("credentials in a refused URL are not echoed", () => {
+    expect(() => openaiBaseUrl({ OPENAI_BASE_URL: "http://user:sk-secret@gw.example" })).toThrow(
+      /^OPENAI_BASE_URL must use https/,
+    );
+  });
+});
+
+test.each([
+  ["gpu-box/models///", "http://gpu-box:11434/models"],
+  [":8080/models", "http://localhost:8080/models"],
+  ["[::1]/models", "http://[::1]:11434/models"],
+  ["[::1]:8080/models", "http://[::1]:8080/models"],
+  [" HTTPS://ollama.example/models/// ", "HTTPS://ollama.example/models"],
+])("Ollama normalizes %s", (input, expected) => {
+  expect(ollamaBaseUrl({ OLLAMA_HOST: input })).toBe(expected);
+});

package/src/__tests__/catalog-index.test.ts

@@ -1,9 +1,5 @@
 import { afterEach, describe, expect, it } from "bun:test";
-import {
-  __resetIndex,
-  retrieve,
-  retrieveByCategory,
-} from "../ai/catalog-index.ts";
+import { __resetIndex, retrieve, retrieveByCategory } from "../ai/catalog-index.ts";
 
 /**
  * Golden retrieval tests. Each query must surface the right provider(s) in
@@ -63,13 +59,12 @@ describe("catalog-index.retrieve", () => {
   });
 
   it("composes a B2B SaaS recipe across categories", () => {
-    const hits = names(retrieve(
-      "B2B SaaS with auth and payments and AI and error tracking",
-      { k: 8 },
-    ));
+    const hits = names(
+      retrieve("B2B SaaS with auth and payments and AI and error tracking", { k: 8 }),
+    );
     // Expect at least one provider from each intended category.
-    expect(hits).toContain("stripe");        // Payments
-    expect(hits).toContain("sentry");        // Errors
+    expect(hits).toContain("stripe"); // Payments
+    expect(hits).toContain("sentry"); // Errors
     // One of the auth providers
     expect(hits.some((n) => ["clerk", "supabase"].includes(n))).toBe(true);
     // One of the AI providers
@@ -77,12 +72,14 @@ describe("catalog-index.retrieve", () => {
   });
 
   it("respects category filter", () => {
-    const hits = names(retrieve("edge compute", {
-      k: 5,
-      categories: ["Deploy"],
-    }));
+    const hits = names(
+      retrieve("edge compute", {
+        k: 5,
+        categories: ["Deploy"],
+      }),
+    );
     for (const n of hits) {
-      const cat = ["vercel", "railway", "fly", "cloudflare", "render"].includes(n);
+      const cat = ["vercel", "railway", "fly", "cloudflare", "render", "modal"].includes(n);
       expect(cat).toBe(true);
     }
   });
@@ -93,10 +90,7 @@ describe("catalog-index.retrieve", () => {
   });
 
   it("retrieveByCategory buckets results", () => {
-    const grouped = retrieveByCategory(
-      "B2B SaaS with auth and payments and AI",
-      { k: 20 },
-    );
+    const grouped = retrieveByCategory("B2B SaaS with auth and payments and AI", { k: 20 });
     expect(Object.keys(grouped).length).toBeGreaterThan(1);
     expect(grouped.Payments?.[0]?.provider.name).toBe("stripe");
   });

package/src/__tests__/catalog.test.ts

@@ -0,0 +1,31 @@
+import { expect, test } from "bun:test";
+import {
+  PROVIDERS_REF,
+  PROVIDER_CATEGORIES,
+  findProviderRef,
+  groupByCategory,
+} from "../catalog.ts";
+
+test.each(PROVIDERS_REF)("catalog resolves $name by identity", (provider) => {
+  expect(findProviderRef(provider.name)).toBe(provider);
+  expect(PROVIDER_CATEGORIES).toContain(provider.category);
+});
+
+test.each(["", "OPENAI", " openai", "openai ", "constructor", "__proto__", "missing"])(
+  "catalog rejects noncanonical name %s",
+  (name) => expect(findProviderRef(name)).toBeUndefined(),
+);
+
+test("category groups partition the catalog without sharing mutable buckets", () => {
+  const groups = groupByCategory();
+  expect(Object.values(groups).flat()).toHaveLength(PROVIDERS_REF.length);
+  expect(new Set(PROVIDERS_REF.map((p) => p.name)).size).toBe(PROVIDERS_REF.length);
+  for (const [category, providers] of Object.entries(groups)) {
+    expect(providers).toEqual(PROVIDERS_REF.filter((p) => p.category === category));
+  }
+  const first = PROVIDERS_REF[0]!;
+  groups[first.category]!.pop();
+  expect(groupByCategory()[first.category]).toEqual(
+    PROVIDERS_REF.filter((p) => p.category === first.category),
+  );
+});

package/src/__tests__/cloudflare-provider.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import cloudflare from "../providers/cloudflare.ts";
 import type { ProviderContext } from "../providers/_base.ts";
+import cloudflare from "../providers/cloudflare.ts";
 import { type Harness, readVault, setupFakePhantom } from "./_harness.ts";
 
 describe("cloudflare provider (mocked fetch)", () => {
@@ -8,7 +8,8 @@ describe("cloudflare provider (mocked fetch)", () => {
   let realFetch: typeof fetch;
 
   beforeEach(() => {
-    h = setupFakePhantom();
+    // Provider logic after a token is read; real Phantom 0.7.9 refuses headless reveal.
+    h = setupFakePhantom({}, { legacyHeadlessReveal: true });
     realFetch = globalThis.fetch;
   });
 
@@ -24,10 +25,9 @@ describe("cloudflare provider (mocked fetch)", () => {
     globalThis.fetch = (async (url: string | URL | Request) => {
       const u = String(url);
       if (u.endsWith("/user/tokens/verify")) {
-        return new Response(
-          JSON.stringify({ result: { id: "tok1", status: "active" } }),
-          { status: 200 },
-        );
+        return new Response(JSON.stringify({ result: { id: "tok1", status: "active" } }), {
+          status: 200,
+        });
       }
       if (u.endsWith("/accounts")) {
         return new Response(JSON.stringify({ result: accounts }), { status: 200 });
@@ -54,10 +54,9 @@ describe("cloudflare provider (mocked fetch)", () => {
       const headers = init?.headers as Record<string, string> | undefined;
       if (headers?.Authorization) seenAuth = headers.Authorization;
       if (String(url).endsWith("/user/tokens/verify")) {
-        return new Response(
-          JSON.stringify({ result: { id: "tok1", status: "active" } }),
-          { status: 200 },
-        );
+        return new Response(JSON.stringify({ result: { id: "tok1", status: "active" } }), {
+          status: 200,
+        });
       }
       throw new Error(`unexpected ${url}`);
     }) as unknown as typeof fetch;
@@ -71,4 +70,27 @@ describe("cloudflare provider (mocked fetch)", () => {
     expect(status.kind).toBe("ok");
     expect(seenAuth).toBe("Bearer cf-cached");
   });
+
+  test("an empty 204 verification response does not verify a cached token", async () => {
+    const { addSecret } = await import("../phantom.ts");
+    await addSecret("CLOUDFLARE_API_TOKEN", "cf-cached");
+
+    let requests = 0;
+    globalThis.fetch = (async (url: string | URL | Request) => {
+      expect(String(url)).toBe("https://api.cloudflare.com/client/v4/user/tokens/verify");
+      requests++;
+      return new Response(null, { status: 204 });
+    }) as unknown as typeof fetch;
+
+    const ctx: ProviderContext = { cwd: process.cwd(), interactive: false, log: () => {} };
+    expect(
+      await cloudflare.healthcheck!(ctx, {
+        provider: "cloudflare",
+        secrets: ["CLOUDFLARE_API_TOKEN"],
+        created_at: new Date().toISOString(),
+      }),
+    ).toEqual({ kind: "error", detail: "token invalid" });
+    await expect(cloudflare.login(ctx)).rejects.toMatchObject({ code: "CLOUDFLARE_AUTH_REQUIRED" });
+    expect(requests).toBe(2);
+  });
 });

package/src/__tests__/completion-ci.test.ts

@@ -1,8 +1,17 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtempSync, readFileSync, existsSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { spawnSync } from "node:child_process";
+import { delimiter, dirname, join } from "node:path";
 
 const CLI = join(import.meta.dir, "..", "..", "..", "cli", "src", "index.ts");
 
@@ -34,29 +43,236 @@ describe("stack completion", () => {
   });
 });
 
-describe("stack ci init", () => {
-  test("writes a valid-looking workflow under .github/workflows/", async () => {
-    const cwd = mkdtempSync(join(tmpdir(), "stack-ci-"));
-    const registryDir = mkdtempSync(join(tmpdir(), "stack-ci-reg-"));
+const CI_UNAVAILABLE =
+  "CI health workflow unavailable: Phantom Cloud pull requires trusted-terminal approval. No workflow was written.";
 
-    // Seed a minimal .stack.toml so `ci init` is happy.
-    const { emptyConfig, writeConfig } = await import("../config.ts");
-    const prev = process.env.STACK_REGISTRY_DIR;
-    process.env.STACK_REGISTRY_DIR = registryDir;
-    await writeConfig(emptyConfig(), cwd);
+interface CiFixture {
+  cwd: string;
+  env: Record<string, string>;
+}
 
-    const res = spawnSync("bun", ["run", CLI, "ci", "init"], { encoding: "utf-8", cwd });
-    expect(res.status).toBe(0);
+async function withCiFixture(
+  configured: boolean,
+  run: (fixture: CiFixture) => Promise<void>,
+): Promise<void> {
+  const root = mkdtempSync(join(tmpdir(), "stack-ci-refusal-"));
+  try {
+    for (const dir of ["project", "home", "tmp", "registry", "xdg"]) {
+      mkdirSync(join(root, dir));
+    }
+    const cwd = join(root, "project");
+    if (configured) {
+      writeFileSync(
+        join(cwd, ".stack.toml"),
+        '[stack]\nversion = "1"\nproject_id = "synthetic-ci-project"\n',
+      );
+    }
+    const env: Record<string, string> = {
+      PATH: [dirname(process.execPath), "/usr/bin", "/bin"].join(delimiter),
+      HOME: join(root, "home"),
+      USERPROFILE: join(root, "home"),
+      TMPDIR: join(root, "tmp"),
+      TMP: join(root, "tmp"),
+      TEMP: join(root, "tmp"),
+      XDG_CONFIG_HOME: join(root, "xdg"),
+      XDG_CACHE_HOME: join(root, "xdg"),
+      XDG_DATA_HOME: join(root, "xdg"),
+      STACK_REGISTRY_DIR: join(root, "registry"),
+      CI: "true",
+      STACK_NO_UPDATE_CHECK: "1",
+      STACK_TELEMETRY: "0",
+      PHANTOM_CLOUD_TOKEN: "SYNTHETIC-CLOUD-DO-NOT-PRINT",
+      PHANTOM_VAULT_PASSPHRASE: "SYNTHETIC-VAULT-DO-NOT-PRINT",
+    };
+    if (process.env.SystemRoot) env.SystemRoot = process.env.SystemRoot;
+    await run({ cwd, env });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function projectSnapshot(cwd: string): Record<string, string> {
+  const snapshot: Record<string, string> = {};
+  function visit(dir: string, prefix = ""): void {
+    for (const name of readdirSync(dir).sort()) {
+      const file = join(dir, name);
+      const key = `${prefix}${name}`;
+      const stat = lstatSync(file);
+      if (stat.isDirectory()) {
+        snapshot[key] = `directory:${stat.mode}`;
+        visit(file, `${key}/`);
+      } else if (stat.isFile()) {
+        snapshot[key] = `file:${stat.mode}:${readFileSync(file).toString("hex")}`;
+      } else {
+        throw new Error("Unexpected CI fixture entry");
+      }
+    }
+  }
+  visit(cwd);
+  return snapshot;
+}
+
+// Reuse the existing async fixture transport: Bun 1.2's sync facade can
+// mislabel exit 1 and does not reliably enforce timeout/output bounds.
+function runBoundedCiFixture(
+  command: string,
+  args: string[],
+  cwd: string,
+  env: Record<string, string>,
+) {
+  return new Promise<{
+    status: number | null;
+    signal: NodeJS.Signals | null;
+    error?: Error;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    outputLimitExceeded: boolean;
+  }>((resolve) => {
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(command, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    } catch (error) {
+      // Bun 1.2 throws launch errors synchronously; newer runtimes emit error.
+      resolve({
+        status: null,
+        signal: null,
+        error: error instanceof Error ? error : new Error("fixture launch failed"),
+        stdout: "",
+        stderr: "",
+        timedOut: false,
+        outputLimitExceeded: false,
+      });
+      return;
+    }
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    let bytes = 0;
+    let timedOut = false;
+    let outputLimitExceeded = false;
+    let error: Error | undefined;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, 1500);
+    function capture(chunks: Buffer[], chunk: Buffer) {
+      if (outputLimitExceeded) return;
+      const remaining = 64 * 1024 - bytes;
+      const retained = chunk.subarray(0, remaining);
+      chunks.push(Buffer.from(retained));
+      bytes += retained.length;
+      if (chunk.length > remaining) {
+        outputLimitExceeded = true;
+        child.kill("SIGKILL");
+      }
+    }
+    child.stdout?.on("data", (chunk: Buffer) => capture(stdout, chunk));
+    child.stderr?.on("data", (chunk: Buffer) => capture(stderr, chunk));
+    child.once("error", (failure) => {
+      error = failure;
+      if (child.pid) child.kill("SIGKILL");
+    });
+    child.once("close", (status, signal) => {
+      clearTimeout(timer);
+      resolve({
+        status,
+        signal,
+        error,
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8"),
+        timedOut,
+        outputLimitExceeded,
+      });
+    });
+  });
+}
+
+async function runCi(fixture: CiFixture, args: string[] = []) {
+  const result = await runBoundedCiFixture(
+    process.execPath,
+    ["run", CLI, "ci", "init", ...args],
+    fixture.cwd,
+    fixture.env,
+  );
+  expect(result.error).toBeUndefined();
+  expect(result.timedOut).toBe(false);
+  expect(result.outputLimitExceeded).toBe(false);
+  expect(result.signal).toBeNull();
+  expect(result.status).not.toBeNull();
+  const output = result.stdout + result.stderr;
+  expect(output).not.toContain("SYNTHETIC-CLOUD-DO-NOT-PRINT");
+  expect(output).not.toContain("SYNTHETIC-VAULT-DO-NOT-PRINT");
+  return { result, output };
+}
+
+async function expectUnavailable(fixture: CiFixture, args: string[] = []): Promise<void> {
+  const before = projectSnapshot(fixture.cwd);
+  const { result, output } = await runCi(fixture, args);
+  expect(result.status).toBe(1);
+  expect(output).toContain(CI_UNAVAILABLE);
+  expect(output).not.toContain("CI workflow scaffolded.");
+  expect(output).not.toContain("PHANTOM_CLOUD_TOKEN");
+  expect(output).not.toContain("PHANTOM_VAULT_PASSPHRASE");
+  expect(projectSnapshot(fixture.cwd)).toEqual(before);
+}
+
+describe("stack ci init", async () => {
+  test("preserves missing-config refusal without creating workflow parents", async () => {
+    await withCiFixture(false, async (fixture) => {
+      const before = projectSnapshot(fixture.cwd);
+      const { result, output } = await runCi(fixture);
+      expect(result.status).toBe(1);
+      expect(output).toContain("No .stack.toml found. Run `stack init` first.");
+      expect(projectSnapshot(fixture.cwd)).toEqual(before);
+      expect(existsSync(join(fixture.cwd, ".github"))).toBe(false);
+    });
+  });
 
-    const workflowPath = join(cwd, ".github", "workflows", "stack-ci.yml");
-    expect(existsSync(workflowPath)).toBe(true);
-    const content = readFileSync(workflowPath, "utf-8");
-    expect(content).toContain("name: Stack doctor");
-    expect(content).toContain("stack doctor --json");
-    expect(content).toContain("PHANTOM_CLOUD_TOKEN");
-    expect(content).toContain("actions/upload-artifact@v4");
+  test("refuses the unsupported Cloud scaffold before creating either parent", async () => {
+    await withCiFixture(true, async (fixture) => {
+      await expectUnavailable(fixture);
+      expect(existsSync(join(fixture.cwd, ".github"))).toBe(false);
+    });
+  });
+
+  test("leaves an existing workflow directory and unrelated file unchanged", async () => {
+    await withCiFixture(true, async (fixture) => {
+      const dir = join(fixture.cwd, ".github", "workflows");
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(join(dir, "owned.yml"), "owner sentinel\n");
+      await expectUnavailable(fixture);
+    });
+  });
+
+  test("preserves the existing-file guard without force", async () => {
+    await withCiFixture(true, async (fixture) => {
+      const dir = join(fixture.cwd, ".github", "workflows");
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(join(dir, "stack-ci.yml"), "owner sentinel\n");
+      const before = projectSnapshot(fixture.cwd);
+      const { result, output } = await runCi(fixture);
+      expect(result.status).toBe(1);
+      expect(output).toContain("already exists. It was not changed.");
+      expect(projectSnapshot(fixture.cwd)).toEqual(before);
+    });
+  });
+
+  test("force cannot overwrite an existing workflow with an unsupported scaffold", async () => {
+    await withCiFixture(true, async (fixture) => {
+      const dir = join(fixture.cwd, ".github", "workflows");
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(join(dir, "stack-ci.yml"), "owner sentinel\n");
+      await expectUnavailable(fixture, ["--force"]);
+    });
+  });
 
-    if (prev === undefined) delete process.env.STACK_REGISTRY_DIR;
-    else process.env.STACK_REGISTRY_DIR = prev;
+  test("preserves help and the force flag without creating files", async () => {
+    await withCiFixture(false, async (fixture) => {
+      const before = projectSnapshot(fixture.cwd);
+      const { result, output } = await runCi(fixture, ["--help"]);
+      expect(result.status).toBe(0);
+      expect(output).toContain("--force");
+      expect(projectSnapshot(fixture.cwd)).toEqual(before);
+    });
   });
 });