@ashlr/stack-core 0.1.1

package/src/__tests__/inference.test.ts

@@ -0,0 +1,326 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  ClaudeMCPBackend,
+  LocalSLMBackend,
+  NoInferenceBackendError,
+  getInferenceBackend,
+  parseRecipeDraft,
+} from "../ai/inference.ts";
+import { CostTracker } from "../ai/cost-tracker.ts";
+
+/**
+ * Inference backend tests. The local backend talks to an OpenAI-compatible
+ * HTTP API, so every test either injects a fake `fetchImpl` or monkey-patches
+ * `globalThis.fetch`. We never hit the network.
+ */
+
+// Minimal valid chat-completion response.
+function okChatResponse(content: string, usage?: { prompt_tokens?: number; completion_tokens?: number }) {
+  return new Response(
+    JSON.stringify({
+      choices: [{ message: { content } }],
+      usage,
+    }),
+    { status: 200, headers: { "content-type": "application/json" } },
+  );
+}
+
+const VALID_RECIPE_JSON = JSON.stringify({
+  providers: [
+    { name: "neon", rationale: "Managed Postgres with branching" },
+    { name: "clerk", rationale: "Drop-in auth UI" },
+  ],
+  notes: "Add Stripe later if billing shows up",
+});
+
+describe("getInferenceBackend — selection", () => {
+  test("STACK_MCP_MODE=1 selects ClaudeMCPBackend", async () => {
+    const backend = await getInferenceBackend({
+      env: { STACK_MCP_MODE: "1" },
+    });
+    expect(backend.name).toBe("claude-mcp");
+    expect(backend).toBeInstanceOf(ClaudeMCPBackend);
+  });
+
+  test("MCP_CLIENT set selects ClaudeMCPBackend", async () => {
+    const backend = await getInferenceBackend({
+      env: { MCP_CLIENT: "claude-code" },
+    });
+    expect(backend.name).toBe("claude-mcp");
+  });
+
+  test("no MCP env + reachable LM Studio → LocalSLMBackend", async () => {
+    const backend = await getInferenceBackend({
+      env: {},
+      localOptions: {
+        endpoints: [{ name: "lm-studio-fake", baseUrl: "http://fake/v1", model: "x" }],
+        fetchImpl: (async () => new Response("{}", { status: 200 })) as unknown as typeof fetch,
+      },
+    });
+    expect(backend.name).toBe("local-slm");
+    expect(backend).toBeInstanceOf(LocalSLMBackend);
+  });
+
+  test("preferLocal=true overrides MCP mode", async () => {
+    const backend = await getInferenceBackend({
+      preferLocal: true,
+      env: { STACK_MCP_MODE: "1" },
+      localOptions: {
+        endpoints: [{ name: "lm-studio-fake", baseUrl: "http://fake/v1", model: "x" }],
+        fetchImpl: (async () => new Response("{}", { status: 200 })) as unknown as typeof fetch,
+      },
+    });
+    expect(backend.name).toBe("local-slm");
+  });
+
+  test("local backend with both endpoints unreachable throws NoInferenceBackendError", async () => {
+    await expect(
+      getInferenceBackend({
+        env: {},
+        localOptions: {
+          endpoints: [
+            { name: "lm-studio-fake", baseUrl: "http://127.0.0.1:1/v1", model: "x" },
+            { name: "ollama-fake", baseUrl: "http://127.0.0.1:2/v1", model: "y" },
+          ],
+          fetchImpl: (async () => {
+            throw new Error("ECONNREFUSED");
+          }) as unknown as typeof fetch,
+        },
+      }),
+    ).rejects.toBeInstanceOf(NoInferenceBackendError);
+  });
+});
+
+describe("ClaudeMCPBackend", () => {
+  test("infer returns mcp-delegated mode with the grounding payload", async () => {
+    const backend = new ClaudeMCPBackend();
+    const result = await backend.infer({
+      query: "payments + auth",
+      catalogContext: "stripe — payments\nclerk — auth",
+      projectContext: { pkg: "my-app", frameworks: ["next"] },
+    });
+    expect(result.mode).toBe("mcp-delegated");
+    expect(result.recipe).toBeUndefined();
+    expect(result.delegatedPayload).toBeDefined();
+    const payload = result.delegatedPayload as Record<string, unknown>;
+    expect(payload.query).toBe("payments + auth");
+    expect(payload.catalogContext).toContain("stripe");
+    expect(payload.projectContext).toEqual({ pkg: "my-app", frameworks: ["next"] });
+  });
+
+  test("healthy resolves true without network", async () => {
+    expect(await new ClaudeMCPBackend().healthy()).toBe(true);
+  });
+});
+
+describe("LocalSLMBackend — infer", () => {
+  test("happy path — parses recipe + records usage with reported tokens", async () => {
+    const costTracker = new CostTracker();
+    const fetchImpl = (async () =>
+      okChatResponse(VALID_RECIPE_JSON, { prompt_tokens: 120, completion_tokens: 45 })) as unknown as typeof fetch;
+
+    const backend = new LocalSLMBackend({
+      endpoints: [{ name: "lm-studio-fake", baseUrl: "http://fake/v1", model: "test" }],
+      costTracker,
+      fetchImpl,
+    });
+
+    const result = await backend.infer({
+      query: "postgres + auth",
+      catalogContext: "neon — Postgres\nclerk — auth",
+    });
+
+    expect(result.mode).toBe("synth");
+    expect(result.recipe?.providers.map((p) => p.name)).toEqual(["neon", "clerk"]);
+    expect(result.usage?.inputTokens).toBe(120);
+    expect(result.usage?.outputTokens).toBe(45);
+    expect(result.usage?.costUsd).toBe(0);
+    expect(backend.lastEndpoint).toBe("lm-studio-fake");
+
+    const summary = costTracker.getSummary();
+    expect(summary.totalInputTokens).toBe(120);
+    expect(summary.totalOutputTokens).toBe(45);
+    expect(summary.totalCostUsd).toBe(0);
+  });
+
+  test("falls back to the second endpoint when the first fails", async () => {
+    let call = 0;
+    const fetchImpl = (async (input: string | URL | Request) => {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+      call++;
+      if (url.includes("primary")) {
+        throw new Error("ECONNREFUSED");
+      }
+      return okChatResponse(VALID_RECIPE_JSON);
+    }) as unknown as typeof fetch;
+
+    const backend = new LocalSLMBackend({
+      endpoints: [
+        { name: "primary", baseUrl: "http://primary/v1", model: "a" },
+        { name: "secondary", baseUrl: "http://secondary/v1", model: "b" },
+      ],
+      fetchImpl,
+      costTracker: new CostTracker(),
+    });
+
+    const result = await backend.infer({ query: "x", catalogContext: "" });
+    expect(result.mode).toBe("synth");
+    expect(backend.lastEndpoint).toBe("secondary");
+    expect(call).toBeGreaterThanOrEqual(2);
+  });
+
+  test("throws NoInferenceBackendError when every endpoint fails", async () => {
+    const fetchImpl = (async () => {
+      throw new Error("down");
+    }) as unknown as typeof fetch;
+
+    const backend = new LocalSLMBackend({
+      endpoints: [
+        { name: "a", baseUrl: "http://a/v1", model: "m" },
+        { name: "b", baseUrl: "http://b/v1", model: "m" },
+      ],
+      fetchImpl,
+      costTracker: new CostTracker(),
+    });
+
+    await expect(backend.infer({ query: "x", catalogContext: "" })).rejects.toBeInstanceOf(
+      NoInferenceBackendError,
+    );
+  });
+
+  test("circuit breaker opens after 3 consecutive failures and rejects immediately", async () => {
+    let calls = 0;
+    const fetchImpl = (async () => {
+      calls++;
+      throw new Error("boom");
+    }) as unknown as typeof fetch;
+
+    // Single-endpoint backend so the breaker state is easy to reason about.
+    const backend = new LocalSLMBackend({
+      endpoints: [{ name: "solo", baseUrl: "http://solo/v1", model: "m" }],
+      fetchImpl,
+      costTracker: new CostTracker(),
+      circuitBreakerThreshold: 3,
+      // Long reset — once open, stays open for the remainder of the test.
+      circuitBreakerWindowMs: 60_000,
+    });
+
+    for (let i = 0; i < 3; i++) {
+      await expect(backend.infer({ query: "x", catalogContext: "" })).rejects.toBeInstanceOf(
+        NoInferenceBackendError,
+      );
+    }
+    const callsAfterTrip = calls;
+    // Fourth call should short-circuit — no new fetch attempt.
+    await expect(backend.infer({ query: "x", catalogContext: "" })).rejects.toBeInstanceOf(
+      NoInferenceBackendError,
+    );
+    expect(calls).toBe(callsAfterTrip);
+  });
+
+  test("rejects non-2xx with a readable error message", async () => {
+    const fetchImpl = (async () =>
+      new Response("model not loaded", { status: 503 })) as unknown as typeof fetch;
+
+    const backend = new LocalSLMBackend({
+      endpoints: [{ name: "solo", baseUrl: "http://solo/v1", model: "m" }],
+      fetchImpl,
+      costTracker: new CostTracker(),
+    });
+
+    await expect(
+      backend.infer({ query: "x", catalogContext: "" }),
+    ).rejects.toBeInstanceOf(NoInferenceBackendError);
+  });
+
+  test("healthy pings /models and returns true when any endpoint responds", async () => {
+    const fetchImpl = (async (input: string | URL | Request) => {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+      if (url.endsWith("/models")) return new Response("[]", { status: 200 });
+      return new Response("", { status: 500 });
+    }) as unknown as typeof fetch;
+
+    const backend = new LocalSLMBackend({
+      endpoints: [{ name: "solo", baseUrl: "http://solo/v1", model: "m" }],
+      fetchImpl,
+    });
+    expect(await backend.healthy()).toBe(true);
+  });
+});
+
+describe("parseRecipeDraft", () => {
+  test("parses plain JSON", () => {
+    const draft = parseRecipeDraft(VALID_RECIPE_JSON);
+    expect(draft.providers).toHaveLength(2);
+    expect(draft.providers[0]!.name).toBe("neon");
+  });
+
+  test("tolerates markdown fences", () => {
+    const wrapped = "```json\n" + VALID_RECIPE_JSON + "\n```";
+    const draft = parseRecipeDraft(wrapped);
+    expect(draft.providers).toHaveLength(2);
+  });
+
+  test("tolerates leading prose", () => {
+    const draft = parseRecipeDraft(
+      "Sure! Here's the recipe:\n" + VALID_RECIPE_JSON + "\nLet me know!",
+    );
+    expect(draft.providers).toHaveLength(2);
+  });
+
+  test("throws when the object has no usable providers", () => {
+    expect(() => parseRecipeDraft('{"providers":[]}')).toThrow();
+  });
+
+  test("throws when the response is not JSON", () => {
+    expect(() => parseRecipeDraft("sorry, I can't help with that")).toThrow();
+  });
+});
+
+describe("CostTracker — math", () => {
+  test("zero rate yields $0 even for large token counts", () => {
+    const t = new CostTracker();
+    t.recordUsage("local", 10_000_000, 5_000_000);
+    const s = t.getSummary();
+    expect(s.totalInputTokens).toBe(10_000_000);
+    expect(s.totalOutputTokens).toBe(5_000_000);
+    expect(s.totalCostUsd).toBe(0);
+    expect(s.perBackend.local?.calls).toBe(1);
+  });
+
+  test("applies per-1M rate card correctly", () => {
+    const t = new CostTracker();
+    t.setRate("remote", { inputPer1M: 3, outputPer1M: 15 });
+    const rec = t.recordUsage("remote", 1_000_000, 500_000);
+    // 1M * $3 + 0.5M * $15 = 3 + 7.5 = 10.5
+    expect(rec.costUsd).toBeCloseTo(10.5, 6);
+    expect(t.getSummary().totalCostUsd).toBeCloseTo(10.5, 6);
+  });
+
+  test("aggregates across backends and calls", () => {
+    const t = new CostTracker();
+    t.setRate("a", { inputPer1M: 1, outputPer1M: 2 });
+    t.setRate("b", { inputPer1M: 4, outputPer1M: 8 });
+    t.recordUsage("a", 500_000, 500_000); // 0.5 + 1 = 1.5
+    t.recordUsage("a", 500_000, 500_000); // +1.5
+    t.recordUsage("b", 250_000, 250_000); // 1 + 2 = 3
+    const s = t.getSummary();
+    expect(s.perBackend.a?.calls).toBe(2);
+    expect(s.perBackend.b?.calls).toBe(1);
+    expect(s.totalCostUsd).toBeCloseTo(6, 6);
+  });
+});
+
+// Ensure the global fetch is untouched if any future test forgets to restore.
+describe("fetch safety net", () => {
+  const realFetch = globalThis.fetch;
+  beforeEach(() => {
+    globalThis.fetch = realFetch;
+  });
+  afterEach(() => {
+    globalThis.fetch = realFetch;
+  });
+  test("globalThis.fetch is restored", () => {
+    expect(globalThis.fetch).toBe(realFetch);
+  });
+});

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

@@ -0,0 +1,79 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import neon from "../providers/neon.ts";
+import type { ProviderContext } from "../providers/_base.ts";
+import { type Harness, readVault, setupFakePhantom } from "./_harness.ts";
+
+describe("neon provider (mocked fetch)", () => {
+  let h: Harness;
+  let realFetch: typeof fetch;
+
+  beforeEach(() => {
+    h = setupFakePhantom();
+    realFetch = globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = realFetch;
+    h.cleanup();
+  });
+
+  test("provision POSTs /projects and materialize fetches a connection URI", async () => {
+    const projectId = "proj_abc123";
+    const connectionUri = "postgresql://user:pw@ep-xx.us-east-2.aws.neon.tech/neondb";
+
+    globalThis.fetch = (async (url: string | URL | Request, init?: RequestInit) => {
+      const u = String(url);
+      const method = init?.method ?? "GET";
+
+      if (u.endsWith("/projects") && method === "POST") {
+        return new Response(
+          JSON.stringify({
+            project: { id: projectId, name: "stack-xyz", region_id: "aws-us-east-2" },
+            connection_uris: [{ connection_uri: connectionUri }],
+          }),
+          { status: 201 },
+        );
+      }
+      if (u.endsWith(`/projects/${projectId}/connection_uri`)) {
+        return new Response(JSON.stringify({ uri: connectionUri }), { status: 200 });
+      }
+      throw new Error(`unexpected ${method} ${u}`);
+    }) as unknown as typeof fetch;
+
+    const ctx: ProviderContext = { cwd: process.cwd(), interactive: false, log: () => {} };
+    const auth = { token: "neon_fake", identity: {} };
+
+    const resource = await neon.provision(ctx, auth, {});
+    expect(resource.id).toBe(projectId);
+    expect(resource.region).toBe("aws-us-east-2");
+
+    const materialized = await neon.materialize(ctx, resource, auth);
+    expect(materialized.secrets.NEON_API_KEY).toBe("neon_fake");
+    expect(materialized.secrets.DATABASE_URL).toBe(connectionUri);
+
+    // Provision stores a project-scoped copy so other providers can't stomp it.
+    const vault = await readVault(h.dir);
+    expect(vault[`NEON_DATABASE_URL_${projectId}`]).toBe(connectionUri);
+  });
+
+  test("healthcheck returns error when the project 404s", async () => {
+    const { addSecret } = await import("../phantom.ts");
+    await addSecret("NEON_API_KEY", "neon_cached");
+
+    globalThis.fetch = (async (url: string | URL | Request) => {
+      if (String(url).includes("/projects/")) {
+        return new Response("not found", { status: 404 });
+      }
+      return new Response("nope", { status: 404 });
+    }) as unknown as typeof fetch;
+
+    const ctx: ProviderContext = { cwd: process.cwd(), interactive: false, log: () => {} };
+    const status = await neon.healthcheck!(ctx, {
+      provider: "neon",
+      resource_id: "missing_proj",
+      secrets: ["NEON_API_KEY"],
+      created_at: new Date().toISOString(),
+    });
+    expect(status.kind).toBe("error");
+  });
+});

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

@@ -0,0 +1,54 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import openai from "../providers/openai.ts";
+import type { ProviderContext } from "../providers/_base.ts";
+import { type Harness, readVault, setupFakePhantom } from "./_harness.ts";
+
+describe("openai provider (mocked fetch)", () => {
+  let h: Harness;
+  let realFetch: typeof fetch;
+
+  beforeEach(() => {
+    h = setupFakePhantom();
+    realFetch = globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = realFetch;
+    h.cleanup();
+  });
+
+  test("materialize stores the key under OPENAI_API_KEY", async () => {
+    globalThis.fetch = (async (url: string | URL | Request) => {
+      const u = String(url);
+      if (u.endsWith("/v1/models")) {
+        return new Response(JSON.stringify({ data: [{ id: "gpt-4o" }] }), { status: 200 });
+      }
+      throw new Error(`unexpected fetch ${u}`);
+    }) as typeof fetch;
+
+    const ctx: ProviderContext = { cwd: process.cwd(), interactive: false, log: () => {} };
+    const auth = { token: "sk-fake", identity: { models: "1" } };
+    const resource = await openai.provision(ctx, auth, {});
+    const materialized = await openai.materialize(ctx, resource, auth);
+
+    expect(materialized.secrets.OPENAI_API_KEY).toBe("sk-fake");
+    expect((await readVault(h.dir)).OPENAI_API_KEY).toBe("sk-fake");
+  });
+
+  test("healthcheck fails gracefully when the key is invalid", async () => {
+    globalThis.fetch = (async () =>
+      new Response("unauthorized", { status: 401 })) as unknown as typeof fetch;
+
+    // Pre-seed an invalid key so healthcheck has something to verify.
+    const { addSecret } = await import("../phantom.ts");
+    await addSecret("OPENAI_API_KEY", "sk-bad");
+
+    const ctx: ProviderContext = { cwd: process.cwd(), interactive: false, log: () => {} };
+    const status = await openai.healthcheck!(ctx, {
+      provider: "openai",
+      secrets: ["OPENAI_API_KEY"],
+      created_at: new Date().toISOString(),
+    });
+    expect(status.kind).toBe("error");
+  });
+});

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

@@ -0,0 +1,44 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  addSecret,
+  isPhantomInstalled,
+  listSecrets,
+  removeSecret,
+  revealSecret,
+} from "../phantom.ts";
+import { type Harness, setupFakePhantom } from "./_harness.ts";
+
+describe("phantom wrapper against the fake harness", () => {
+  let h: Harness;
+
+  beforeEach(() => {
+    h = setupFakePhantom({ EXISTING_KEY: "preset-value" });
+  });
+
+  afterEach(() => {
+    h.cleanup();
+  });
+
+  test("isPhantomInstalled resolves true when the fake binary is on PATH", async () => {
+    expect(await isPhantomInstalled()).toBe(true);
+  });
+
+  test("addSecret writes to the fake vault", async () => {
+    await addSecret("NEW_KEY", "new-value");
+    expect(await revealSecret("NEW_KEY")).toBe("new-value");
+    expect(h.callsTo("add").length).toBe(1);
+  });
+
+  test("listSecrets returns vault keys", async () => {
+    await addSecret("ANOTHER", "v");
+    const keys = await listSecrets();
+    expect(keys).toContain("EXISTING_KEY");
+    expect(keys).toContain("ANOTHER");
+  });
+
+  test("removeSecret deletes from the fake vault", async () => {
+    await removeSecret("EXISTING_KEY");
+    const keys = await listSecrets();
+    expect(keys).not.toContain("EXISTING_KEY");
+  });
+});

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

@@ -0,0 +1,85 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { wirePhantomForRecipe } from "../ai/phantom-wire.ts";
+import type { Recipe } from "../ai/recipe.ts";
+import { setupFakePhantom, type Harness } from "./_harness.ts";
+
+describe("ai/phantom-wire", () => {
+  let harness: Harness;
+
+  beforeEach(() => {
+    harness = setupFakePhantom();
+  });
+  afterEach(() => {
+    harness.cleanup();
+  });
+
+  const STRIPE_RECIPE: Recipe = {
+    id: "stripe-only",
+    query: "payments",
+    createdAt: "2026-04-18T00:00:00.000Z",
+    providers: [{ name: "stripe" }],
+  };
+
+  it("calls `phantom add STRIPE_SECRET_KEY` and writes a webhook stub", async () => {
+    const result = await wirePhantomForRecipe(STRIPE_RECIPE, { cwd: harness.dir });
+
+    expect(result.envelopes).toContain("stripe:STRIPE_SECRET_KEY");
+
+    // Fake phantom treats `--rotate` as an unknown arg and succeeds anyway
+    // (our fake echoes success for unknown cases via the `*` branch exit 0),
+    // but we always log the call — so the `add` log should mention the key.
+    const adds = harness.callsTo("add");
+    const keys = adds.flatMap((c) => c.args);
+    expect(keys).toContain("STRIPE_SECRET_KEY");
+
+    const stubPath = join(harness.dir, ".stack/webhooks/stripe.ts");
+    expect(existsSync(stubPath)).toBe(true);
+    const stub = readFileSync(stubPath, "utf-8");
+    expect(stub).toContain("stripe-signature");
+    expect(stub).toContain("STRIPE_WEBHOOK_SECRET");
+    expect(result.webhooks).toHaveLength(1);
+  });
+
+  it("noWire: true skips envelopes and webhooks entirely", async () => {
+    const result = await wirePhantomForRecipe(STRIPE_RECIPE, {
+      cwd: harness.dir,
+      noWire: true,
+    });
+    expect(result).toEqual({ envelopes: [], webhooks: [], skipped: [] });
+
+    const stubPath = join(harness.dir, ".stack/webhooks/stripe.ts");
+    expect(existsSync(stubPath)).toBe(false);
+    expect(harness.callsTo("add")).toEqual([]);
+  });
+
+  it("creates envelopes for every secret on a multi-secret provider", async () => {
+    const recipe: Recipe = {
+      id: "supa",
+      query: "database",
+      createdAt: "2026-04-18T00:00:00.000Z",
+      providers: [{ name: "supabase" }],
+    };
+    const result = await wirePhantomForRecipe(recipe, { cwd: harness.dir });
+    expect(result.envelopes).toEqual([
+      "supabase:SUPABASE_URL",
+      "supabase:SUPABASE_ANON_KEY",
+      "supabase:SUPABASE_SERVICE_ROLE_KEY",
+    ]);
+    // Supabase is webhook-capable in our moat list.
+    expect(result.webhooks).toHaveLength(1);
+  });
+
+  it("skips providers with no webhook stub without crashing", async () => {
+    const recipe: Recipe = {
+      id: "neon",
+      query: "database",
+      createdAt: "2026-04-18T00:00:00.000Z",
+      providers: [{ name: "neon" }],
+    };
+    const result = await wirePhantomForRecipe(recipe, { cwd: harness.dir });
+    expect(result.webhooks).toEqual([]);
+    expect(result.envelopes.length).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/pipeline-integration.test.ts

@@ -0,0 +1,95 @@
+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 { emptyConfig, writeConfig } from "../config.ts";
+import { addService } from "../pipeline.ts";
+import type { Provider } from "../providers/_base.ts";
+import { providers } from "../providers/index.ts";
+import { type Harness, readVault, setupFakePhantom } from "./_harness.ts";
+
+/**
+ * End-to-end pipeline test: register a stub provider, run addService, and
+ * verify the .stack.toml + fake vault + .mcp.json all get the right writes.
+ */
+describe("addService full loop", () => {
+  let h: Harness;
+  let cwd: string;
+  let originalCwd: string;
+
+  beforeEach(async () => {
+    h = setupFakePhantom();
+    cwd = mkdtempSync(join(tmpdir(), "stack-pipeline-"));
+    originalCwd = process.cwd();
+    process.chdir(cwd);
+    await writeConfig(emptyConfig("test-template"), cwd);
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    h.cleanup();
+  });
+
+  test("stub provider runs login → provision → materialize → writes everything", async () => {
+    const stubProvider: Provider = {
+      name: "stubsvc",
+      displayName: "Stub Service",
+      category: "database",
+      authKind: "api_key",
+      async login() {
+        return { token: "stub-token", identity: { id: "user-1" } };
+      },
+      async provision() {
+        return { id: "stub-resource-1", displayName: "stub-resource-1", region: "us-east-1" };
+      },
+      async materialize(_ctx, resource) {
+        return {
+          secrets: {
+            STUB_URL: `https://${resource.id}.example.com`,
+            STUB_API_KEY: "secret-value",
+          },
+          mcp: {
+            name: "stubsvc",
+            type: "stdio",
+            command: "npx",
+            args: ["-y", "fake-mcp"],
+          },
+        };
+      },
+    };
+
+    // Hot-register the stub in the provider loader.
+    providers.stubsvc = async () => stubProvider;
+
+    const result = await addService({
+      providerName: "stubsvc",
+      cwd,
+      interactive: false,
+    });
+
+    expect(result.providerName).toBe("stubsvc");
+    expect(result.resourceId).toBe("stub-resource-1");
+    expect(result.secretCount).toBe(2);
+    expect(result.mcpWired).toBe(true);
+
+    // Secrets landed in the fake vault.
+    const vault = await readVault(h.dir);
+    expect(vault.STUB_URL).toBe("https://stub-resource-1.example.com");
+    expect(vault.STUB_API_KEY).toBe("secret-value");
+
+    // .stack.toml got an entry.
+    const { readConfig } = await import("../config.ts");
+    const config = await readConfig(cwd);
+    expect(config.services.stubsvc).toBeDefined();
+    expect(config.services.stubsvc.resource_id).toBe("stub-resource-1");
+    expect(config.services.stubsvc.secrets.sort()).toEqual(["STUB_API_KEY", "STUB_URL"]);
+    expect(config.services.stubsvc.mcp).toBe("stubsvc");
+
+    // .mcp.json got merged.
+    const mcpRaw = await Bun.file(join(cwd, ".mcp.json")).text();
+    const mcp = JSON.parse(mcpRaw) as { mcpServers: Record<string, unknown> };
+    expect(mcp.mcpServers.stubsvc).toBeDefined();
+
+    delete providers.stubsvc;
+  });
+});