@ashlr/stack-core 0.1.1

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

@@ -0,0 +1,147 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { scanSource } from "../detect-source.ts";
+
+function makeProject(files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), "stack-scan-"));
+  for (const [path, content] of Object.entries(files)) {
+    const full = join(dir, path);
+    const parent = join(full, "..");
+    mkdirSync(parent, { recursive: true });
+    writeFileSync(full, content);
+  }
+  return dir;
+}
+
+describe("source scanner — JS/TS", () => {
+  test("detects Supabase + Sentry + OpenAI from a Next.js package.json", async () => {
+    const cwd = makeProject({
+      "package.json": JSON.stringify({
+        dependencies: {
+          next: "15.0.0",
+          "@supabase/supabase-js": "^2.45.0",
+          "@supabase/ssr": "^0.5.0",
+          "@sentry/nextjs": "^7.0.0",
+          openai: "^4.0.0",
+          "posthog-js": "^1.0.0",
+        },
+      }),
+    });
+    const hits = await scanSource(cwd);
+    const names = hits.map((h) => h.provider).sort();
+    expect(names).toContain("supabase");
+    expect(names).toContain("sentry");
+    expect(names).toContain("openai");
+    expect(names).toContain("posthog");
+    const supabase = hits.find((h) => h.provider === "supabase");
+    expect(supabase?.confidence).toBe("high");
+    expect(supabase?.signals.some((s) => s.includes("@supabase/"))).toBe(true);
+  });
+
+  test("devDependencies count too", async () => {
+    const cwd = makeProject({
+      "package.json": JSON.stringify({
+        devDependencies: { "@anthropic-ai/sdk": "^0.20.0" },
+      }),
+    });
+    const hits = await scanSource(cwd);
+    expect(hits.some((h) => h.provider === "anthropic")).toBe(true);
+  });
+
+  test("detects Cloudflare (wrangler), Turso (@libsql), Convex", async () => {
+    const cwd = makeProject({
+      "package.json": JSON.stringify({
+        dependencies: {
+          "@libsql/client": "^0.4.0",
+          convex: "^1.10.0",
+        },
+        devDependencies: {
+          wrangler: "^3.0.0",
+        },
+      }),
+    });
+    const hits = await scanSource(cwd);
+    const names = hits.map((h) => h.provider);
+    expect(names).toContain("cloudflare");
+    expect(names).toContain("turso");
+    expect(names).toContain("convex");
+  });
+});
+
+describe("source scanner — config files", () => {
+  test("fly.toml + vercel.json + supabase/config.toml all get picked up", async () => {
+    const cwd = makeProject({
+      "fly.toml": "app = 'myapp'",
+      "vercel.json": "{}",
+      "supabase/config.toml": "[api]\nport = 54321",
+    });
+    const hits = await scanSource(cwd);
+    const names = hits.map((h) => h.provider);
+    expect(names).toContain("fly");
+    expect(names).toContain("vercel");
+    expect(names).toContain("supabase");
+  });
+
+  test(".github/workflows/*.yml wires up github", async () => {
+    const cwd = makeProject({
+      ".github/workflows/ci.yml": "name: CI\non: push",
+    });
+    const hits = await scanSource(cwd);
+    expect(hits.some((h) => h.provider === "github")).toBe(true);
+  });
+
+  test("wrangler.toml picks up Cloudflare", async () => {
+    const cwd = makeProject({
+      "wrangler.toml": "name = \"my-worker\"\nmain = \"src/index.ts\"",
+    });
+    const hits = await scanSource(cwd);
+    expect(hits.some((h) => h.provider === "cloudflare")).toBe(true);
+  });
+});
+
+describe("source scanner — .env.example", () => {
+  test("secret names in .env.example hint at providers", async () => {
+    const cwd = makeProject({
+      ".env.example": `
+OPENAI_API_KEY=
+SENTRY_AUTH_TOKEN=
+NODE_ENV=development
+`.trim(),
+    });
+    const hits = await scanSource(cwd);
+    const names = hits.map((h) => h.provider);
+    expect(names).toContain("openai");
+    expect(names).toContain("sentry");
+  });
+});
+
+describe("source scanner — Python + Go", () => {
+  test("requirements.txt picks up openai + sentry-sdk", async () => {
+    const cwd = makeProject({
+      "requirements.txt": "openai==1.0.0\nsentry-sdk>=2.0.0\nflask",
+    });
+    const hits = await scanSource(cwd);
+    const names = hits.map((h) => h.provider);
+    expect(names).toContain("openai");
+    expect(names).toContain("sentry");
+  });
+
+  test("go.mod picks up supabase + stripe", async () => {
+    const cwd = makeProject({
+      "go.mod": `module example.com/app
+
+go 1.22
+
+require (
+\tgithub.com/supabase-community/supabase-go v0.3.0
+\tgithub.com/stripe/stripe-go/v76 v76.0.0
+)`,
+    });
+    const hits = await scanSource(cwd);
+    const names = hits.map((h) => h.provider);
+    expect(names).toContain("supabase");
+    expect(names).toContain("stripe");
+  });
+});

package/src/__tests__/detect.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import { detectProvider, groupByProvider, parseEnv } from "../detect.ts";
+
+describe("provider detection", () => {
+  test("canonical secret names map to their provider", () => {
+    expect(detectProvider("SUPABASE_URL")).toBe("supabase");
+    expect(detectProvider("NEXT_PUBLIC_SUPABASE_URL")).toBe("supabase");
+    expect(detectProvider("OPENAI_API_KEY")).toBe("openai");
+    expect(detectProvider("ANTHROPIC_API_KEY")).toBe("anthropic");
+    expect(detectProvider("SENTRY_AUTH_TOKEN")).toBe("sentry");
+    expect(detectProvider("SENTRY_DSN")).toBe("sentry");
+    expect(detectProvider("GITHUB_TOKEN")).toBe("github");
+    expect(detectProvider("AWS_ACCESS_KEY_ID")).toBe("aws");
+    // DATABASE_URL is intentionally unattributed — it's generic Postgres
+    // convention, used by Supabase, Railway, Render, PlanetScale, etc.
+    expect(detectProvider("DATABASE_URL")).toBeUndefined();
+    expect(detectProvider("CLOUDFLARE_API_TOKEN")).toBe("cloudflare");
+    expect(detectProvider("CF_ACCOUNT_ID")).toBe("cloudflare");
+    expect(detectProvider("TURSO_DATABASE_URL")).toBe("turso");
+    expect(detectProvider("CONVEX_DEPLOY_KEY")).toBe("convex");
+    expect(detectProvider("NEXT_PUBLIC_CONVEX_URL")).toBe("convex");
+  });
+
+  test("unattributed names return undefined", () => {
+    expect(detectProvider("NODE_ENV")).toBeUndefined();
+    expect(detectProvider("PORT")).toBeUndefined();
+    expect(detectProvider("SOME_RANDOM_VAR")).toBeUndefined();
+  });
+
+  test("groupByProvider buckets names into providers", () => {
+    const result = groupByProvider([
+      "SUPABASE_URL",
+      "SUPABASE_ANON_KEY",
+      "OPENAI_API_KEY",
+      "NODE_ENV",
+    ]);
+    expect(result.supabase).toEqual(["SUPABASE_URL", "SUPABASE_ANON_KEY"]);
+    expect(result.openai).toEqual(["OPENAI_API_KEY"]);
+    expect(result.NODE_ENV).toBeUndefined();
+  });
+});
+
+describe(".env parser", () => {
+  test("parses KEY=VALUE pairs", () => {
+    const pairs = parseEnv(
+      `# comment line
+FOO=bar
+BAZ = "quoted value"
+EMPTY=
+# trailing comment
+QUOTED='single'`,
+    );
+    expect(pairs).toEqual([
+      { key: "FOO", value: "bar" },
+      { key: "BAZ", value: "quoted value" },
+      { key: "EMPTY", value: "" },
+      { key: "QUOTED", value: "single" },
+    ]);
+  });
+
+  test("ignores malformed lines", () => {
+    expect(parseEnv("not a key\n:colon_line\nlowercase=ok\nOK=ok")).toEqual([
+      { key: "lowercase", value: "ok" },
+      { key: "OK", value: "ok" },
+    ]);
+  });
+});

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

@@ -0,0 +1,65 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import github from "../providers/github.ts";
+import type { ProviderContext } from "../providers/_base.ts";
+import { type Harness, readVault, setupFakePhantom } from "./_harness.ts";
+
+describe("github provider (mocked fetch)", () => {
+  let h: Harness;
+  let realFetch: typeof fetch;
+
+  beforeEach(() => {
+    h = setupFakePhantom();
+    realFetch = globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = realFetch;
+    h.cleanup();
+  });
+
+  test("materialize writes GITHUB_TOKEN + wires the official MCP server", async () => {
+    const ctx: ProviderContext = { cwd: process.cwd(), interactive: false, log: () => {} };
+    const auth = { token: "ghp_fake", identity: { login: "mason" } };
+    const resource = { id: "mason", displayName: "@mason" };
+    const materialized = await github.materialize(ctx, resource, auth);
+    expect(materialized.secrets.GITHUB_TOKEN).toBe("ghp_fake");
+    expect(materialized.mcp?.name).toBe("github");
+    expect(materialized.mcp?.command).toBe("npx");
+  });
+
+  test("healthcheck accepts a cached token that validates via /user", async () => {
+    const { addSecret } = await import("../phantom.ts");
+    await addSecret("GITHUB_TOKEN", "ghp_cached");
+
+    globalThis.fetch = (async (url: string | URL | Request) => {
+      if (String(url).endsWith("/user")) {
+        return new Response(JSON.stringify({ login: "mason", id: 42 }), { status: 200 });
+      }
+      return new Response("nope", { status: 404 });
+    }) as unknown as typeof fetch;
+
+    const ctx: ProviderContext = { cwd: process.cwd(), interactive: false, log: () => {} };
+    const status = await github.healthcheck!(ctx, {
+      provider: "github",
+      secrets: ["GITHUB_TOKEN"],
+      created_at: new Date().toISOString(),
+    });
+    expect(status.kind).toBe("ok");
+  });
+
+  test("healthcheck reports error when the token is rejected", async () => {
+    const { addSecret } = await import("../phantom.ts");
+    await addSecret("GITHUB_TOKEN", "ghp_bad");
+
+    globalThis.fetch = (async () =>
+      new Response("unauthorized", { status: 401 })) as unknown as typeof fetch;
+
+    const ctx: ProviderContext = { cwd: process.cwd(), interactive: false, log: () => {} };
+    const status = await github.healthcheck!(ctx, {
+      provider: "github",
+      secrets: ["GITHUB_TOKEN"],
+      created_at: new Date().toISOString(),
+    });
+    expect(status.kind).toBe("error");
+  });
+});

package/src/__tests__/helpers.test.ts

@@ -0,0 +1,38 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { addSecret } from "../phantom.ts";
+import { bearerJsonHeaders, tryRevealSecret } from "../providers/_helpers.ts";
+import { type Harness, setupFakePhantom } from "./_harness.ts";
+
+/**
+ * The `_helpers` module backs every provider's PAT/API-key flow. Regressions
+ * here would silently corrupt secret reads across the catalog.
+ */
+
+describe("provider helpers", () => {
+  let h: Harness;
+  beforeEach(() => {
+    h = setupFakePhantom({ PRESENT_KEY: "hello-world" });
+  });
+  afterEach(() => h.cleanup());
+
+  test("tryRevealSecret returns the value when present", async () => {
+    expect(await tryRevealSecret("PRESENT_KEY")).toBe("hello-world");
+  });
+
+  test("tryRevealSecret returns undefined for an empty value", async () => {
+    await addSecret("EMPTY_KEY", "");
+    expect(await tryRevealSecret("EMPTY_KEY")).toBeUndefined();
+  });
+
+  test("tryRevealSecret returns undefined rather than throwing when phantom fails", async () => {
+    // Never-stored key — phantom reveal returns an empty string, helper returns undefined.
+    expect(await tryRevealSecret("NEVER_STORED_KEY")).toBeUndefined();
+  });
+
+  test("bearerJsonHeaders returns the canonical shape", () => {
+    const headers = bearerJsonHeaders("my-token") as Record<string, string>;
+    expect(headers.Authorization).toBe("Bearer my-token");
+    expect(headers["content-type"]).toBe("application/json");
+    expect(headers.Accept).toBe("application/json");
+  });
+});

package/src/__tests__/http.test.ts

@@ -0,0 +1,235 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { fetchWithRetry, parseRetryAfter } from "../http.ts";
+
+/**
+ * `fetchWithRetry` is the single retry loop the rest of core leans on. If it
+ * regressed (retrying POSTs, ignoring Retry-After, infinite loop on 5xx) we'd
+ * either over-charge provider APIs or burn through rate-limit budgets. These
+ * tests exercise each of the contract guarantees.
+ */
+
+describe("fetchWithRetry", () => {
+  let realFetch: typeof fetch;
+  beforeEach(() => {
+    realFetch = globalThis.fetch;
+  });
+  afterEach(() => {
+    globalThis.fetch = realFetch;
+  });
+
+  test("happy path — returns the first successful response, no retry", async () => {
+    let calls = 0;
+    globalThis.fetch = (async () => {
+      calls++;
+      return new Response("ok", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const res = await fetchWithRetry("https://example.com/", undefined, {
+      baseDelayMs: 1,
+      maxDelayMs: 2,
+    });
+    expect(res.status).toBe(200);
+    expect(calls).toBe(1);
+  });
+
+  test("429 triggers a retry, then succeeds", async () => {
+    let calls = 0;
+    globalThis.fetch = (async () => {
+      calls++;
+      if (calls === 1) return new Response("rate limited", { status: 429 });
+      return new Response("ok", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const res = await fetchWithRetry("https://example.com/", undefined, {
+      baseDelayMs: 1,
+      maxDelayMs: 2,
+    });
+    expect(res.status).toBe(200);
+    expect(calls).toBe(2);
+  });
+
+  test("500 retries `retries` times then returns the final failing response", async () => {
+    let calls = 0;
+    globalThis.fetch = (async () => {
+      calls++;
+      return new Response("server error", { status: 500 });
+    }) as unknown as typeof fetch;
+
+    const res = await fetchWithRetry("https://example.com/", undefined, {
+      retries: 2,
+      baseDelayMs: 1,
+      maxDelayMs: 2,
+    });
+    expect(res.status).toBe(500);
+    // 1 initial + 2 retries = 3 total
+    expect(calls).toBe(3);
+  });
+
+  test("honors Retry-After header (integer seconds form)", async () => {
+    let calls = 0;
+    const timestamps: number[] = [];
+    globalThis.fetch = (async () => {
+      calls++;
+      timestamps.push(Date.now());
+      if (calls === 1) {
+        return new Response("slow down", {
+          status: 429,
+          headers: { "retry-after": "1" },
+        });
+      }
+      return new Response("ok", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const start = Date.now();
+    const res = await fetchWithRetry("https://example.com/", undefined, {
+      baseDelayMs: 10,
+      // Cap is high enough to let the 1-second Retry-After pass through.
+      maxDelayMs: 5000,
+    });
+    const elapsed = Date.now() - start;
+    expect(res.status).toBe(200);
+    // Server said to wait 1 second. We should have waited roughly that — at
+    // minimum significantly longer than the 10ms baseDelayMs we configured.
+    expect(elapsed).toBeGreaterThanOrEqual(900);
+    expect(calls).toBe(2);
+  });
+
+  test("POST does NOT retry by default (non-idempotent)", async () => {
+    let calls = 0;
+    globalThis.fetch = (async () => {
+      calls++;
+      return new Response("server error", { status: 500 });
+    }) as unknown as typeof fetch;
+
+    const res = await fetchWithRetry(
+      "https://example.com/charge",
+      { method: "POST", body: "{}" },
+      { retries: 3, baseDelayMs: 1, maxDelayMs: 2 },
+    );
+    // Got back the 500 on the first try — never retried.
+    expect(res.status).toBe(500);
+    expect(calls).toBe(1);
+  });
+
+  test("idempotent: true overrides method-based default, letting a POST retry", async () => {
+    let calls = 0;
+    globalThis.fetch = (async () => {
+      calls++;
+      if (calls === 1) return new Response("nope", { status: 503 });
+      return new Response("ok", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const res = await fetchWithRetry(
+      "https://example.com/graphql",
+      { method: "POST", body: '{"query":"{ me { id } }"}' },
+      { idempotent: true, baseDelayMs: 1, maxDelayMs: 2 },
+    );
+    expect(res.status).toBe(200);
+    expect(calls).toBe(2);
+  });
+
+  test("network errors retry for idempotent requests", async () => {
+    let calls = 0;
+    globalThis.fetch = (async () => {
+      calls++;
+      if (calls === 1) throw new TypeError("fetch failed");
+      return new Response("ok", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const res = await fetchWithRetry("https://example.com/", undefined, {
+      baseDelayMs: 1,
+      maxDelayMs: 2,
+    });
+    expect(res.status).toBe(200);
+    expect(calls).toBe(2);
+  });
+
+  test("network errors on non-idempotent requests bubble up immediately", async () => {
+    let calls = 0;
+    globalThis.fetch = (async () => {
+      calls++;
+      throw new TypeError("fetch failed");
+    }) as unknown as typeof fetch;
+
+    await expect(
+      fetchWithRetry(
+        "https://example.com/charge",
+        { method: "POST", body: "{}" },
+        { retries: 3, baseDelayMs: 1, maxDelayMs: 2 },
+      ),
+    ).rejects.toThrow(/fetch failed/);
+    expect(calls).toBe(1);
+  });
+
+  test("custom retryOn is respected", async () => {
+    let calls = 0;
+    globalThis.fetch = (async () => {
+      calls++;
+      return new Response("teapot", { status: 418 });
+    }) as unknown as typeof fetch;
+
+    const res = await fetchWithRetry("https://example.com/", undefined, {
+      retries: 2,
+      baseDelayMs: 1,
+      maxDelayMs: 2,
+      retryOn: (r) => r.status === 418,
+    });
+    expect(res.status).toBe(418);
+    expect(calls).toBe(3); // initial + 2 retries
+  });
+
+  test("respects an external AbortSignal and stops mid-retry", async () => {
+    let calls = 0;
+    const controller = new AbortController();
+    globalThis.fetch = (async () => {
+      calls++;
+      // Abort once we've made it past the initial try — the subsequent sleep
+      // should be interrupted, not slept through.
+      setTimeout(() => controller.abort(), 5);
+      return new Response("slow", { status: 503 });
+    }) as unknown as typeof fetch;
+
+    await expect(
+      fetchWithRetry("https://example.com/", undefined, {
+        retries: 5,
+        baseDelayMs: 1000,
+        maxDelayMs: 2000,
+        signal: controller.signal,
+      }),
+    ).rejects.toThrow();
+    // At least one call happened; we aborted before burning through all 5 retries.
+    expect(calls).toBeGreaterThanOrEqual(1);
+    expect(calls).toBeLessThan(6);
+  });
+});
+
+describe("parseRetryAfter", () => {
+  test("parses integer seconds", () => {
+    expect(parseRetryAfter("5")).toBe(5000);
+    expect(parseRetryAfter("0")).toBe(0);
+  });
+
+  test("returns undefined for empty / null", () => {
+    expect(parseRetryAfter(null)).toBeUndefined();
+    expect(parseRetryAfter("")).toBeUndefined();
+    expect(parseRetryAfter("   ")).toBeUndefined();
+  });
+
+  test("parses HTTP-date form", () => {
+    const future = new Date(Date.now() + 10_000).toUTCString();
+    const parsed = parseRetryAfter(future);
+    expect(parsed).toBeDefined();
+    // Allow drift from test overhead; we just need it to be in the right ballpark.
+    expect(parsed!).toBeGreaterThan(5_000);
+    expect(parsed!).toBeLessThanOrEqual(12_000);
+  });
+
+  test("HTTP-date in the past clamps to 0", () => {
+    const past = new Date(Date.now() - 10_000).toUTCString();
+    expect(parseRetryAfter(past)).toBe(0);
+  });
+
+  test("garbage input falls through to undefined", () => {
+    expect(parseRetryAfter("not-a-date-or-number")).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,87 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  addSecret,
+  emptyConfig,
+  groupByProvider,
+  listSecrets,
+  parseEnv,
+  readConfig,
+  toServiceEntry,
+  writeConfig,
+} from "../index.ts";
+import { type Harness, readVault, setupFakePhantom } from "./_harness.ts";
+
+/**
+ * Exercises the logic behind `stack import`: parse .env, group by provider,
+ * write each secret to the fake vault, and emit .stack.toml service entries.
+ */
+describe("import pipeline", () => {
+  let h: Harness;
+  let cwd: string;
+  let originalCwd: string;
+
+  beforeEach(() => {
+    h = setupFakePhantom();
+    cwd = mkdtempSync(join(tmpdir(), "stack-import-"));
+    originalCwd = process.cwd();
+    process.chdir(cwd);
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    h.cleanup();
+  });
+
+  test("typical Next.js .env gets parsed, stored, and mapped to services", async () => {
+    const envContent = `
+# mixed real-world contents
+NODE_ENV=development
+NEXT_PUBLIC_SUPABASE_URL=https://abcd.supabase.co
+SUPABASE_ANON_KEY=anon-value
+SUPABASE_SERVICE_ROLE_KEY=service-value
+OPENAI_API_KEY=sk-fake
+SENTRY_DSN=https://abc@sentry.io/123
+SENTRY_AUTH_TOKEN=sntryu_fake
+PORT=3000
+`.trim();
+    writeFileSync(join(cwd, ".env"), envContent);
+
+    const parsed = parseEnv(envContent);
+    expect(parsed.map((p) => p.key)).toContain("OPENAI_API_KEY");
+    expect(parsed.map((p) => p.key)).toContain("NODE_ENV");
+
+    const grouped = groupByProvider(parsed.map((p) => p.key));
+    expect(grouped.supabase).toContain("SUPABASE_ANON_KEY");
+    expect(grouped.supabase).toContain("NEXT_PUBLIC_SUPABASE_URL");
+    expect(grouped.openai).toEqual(["OPENAI_API_KEY"]);
+    expect(grouped.sentry).toContain("SENTRY_AUTH_TOKEN");
+    expect(grouped.NODE_ENV).toBeUndefined();
+    expect(grouped.PORT).toBeUndefined();
+
+    // Store each secret in the fake vault.
+    for (const { key, value } of parsed) {
+      if (value.length > 0) await addSecret(key, value);
+    }
+
+    // Verify vault state.
+    const vault = await readVault(h.dir);
+    expect(vault.OPENAI_API_KEY).toBe("sk-fake");
+    expect(vault.NODE_ENV).toBe("development");
+    expect((await listSecrets()).length).toBeGreaterThanOrEqual(8);
+
+    // Build a .stack.toml from the detected groups.
+    const config = emptyConfig("import-test");
+    for (const provider of Object.keys(grouped)) {
+      config.services[provider] = toServiceEntry(provider, grouped[provider]);
+    }
+    await writeConfig(config, cwd);
+
+    const roundTripped = await readConfig(cwd);
+    expect(roundTripped.services.supabase).toBeDefined();
+    expect(roundTripped.services.openai).toBeDefined();
+    expect(roundTripped.services.sentry.mcp).toBe("sentry");
+  });
+});