@ashlr/stack-core 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashlr / Mason Wyatt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @ashlr/stack-core
+
+> Shared library behind the [Ashlr Stack](https://stack.ashlr.ai) CLI and MCP server. Provider adapters, `.stack.toml` config, Phantom integration, source/env detection.
+
+**You probably don't want to install this directly.** If you want the CLI, install [`@ashlr/stack`](https://www.npmjs.com/package/@ashlr/stack). This package exists so the CLI and the [`ashlr-stack-mcp`](https://www.npmjs.com/package/ashlr-stack-mcp) server can share a single implementation.
+
+## Install
+
+```bash
+bun add @ashlr/stack-core
+# or
+npm i @ashlr/stack-core
+```
+
+## Public API
+
+Selected exports — see `src/index.ts` for the full surface.
+
+| Export | Purpose |
+| --- | --- |
+| `addService(opts)` | End-to-end pipeline: login → provision → materialize → persist secrets + MCP entry |
+| `readConfig(cwd)` / `writeConfig(cfg, cwd)` | Read/write `.stack.toml` + `.stack.local.toml` |
+| `listProviderNames()` / `getProvider(name)` | Introspect the built-in 23-provider registry |
+| `scanSource(opts)` | Detect providers from `package.json`, configs, `.env.example` |
+| `detectProvider(envName)` | Map an env-var name back to a known provider |
+| `parseEnv(text)` | Parse `.env`-style text into `{ key, value }` pairs |
+
+### Example
+
+```ts
+import {
+  addService,
+  readConfig,
+  listProviderNames,
+  scanSource,
+} from "@ashlr/stack-core";
+
+// Pipeline: provisions a new Supabase project, writes secrets through Phantom,
+// merges the MCP entry, and updates .stack.toml + .stack.local.toml.
+await addService({ provider: "supabase", cwd: process.cwd() });
+
+const cfg = await readConfig();
+console.log(cfg.services.map((s) => s.name));
+
+// Scan an existing checkout for providers already wired up.
+const detections = await scanSource({ cwd: process.cwd() });
+console.log(listProviderNames().length); // 23
+```
+
+## Links
+
+- Full CLI-level docs — [stack.ashlr.ai/docs/cli](https://stack.ashlr.ai/docs/cli)
+- Repo — [github.com/ashlrai/ashlr-stack](https://github.com/ashlrai/ashlr-stack)
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@ashlr/stack-core",
+  "version": "0.1.1",
+  "description": "Ashlr Stack core — provider adapters, .stack.toml config, Phantom integration. Shared logic behind the Stack CLI and MCP server.",
+  "license": "MIT",
+  "author": {
+    "name": "Mason Wyatt",
+    "url": "https://github.com/ashlrai"
+  },
+  "homepage": "https://stack.ashlr.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashlrai/ashlr-stack.git",
+    "directory": "packages/core"
+  },
+  "bugs": "https://github.com/ashlrai/ashlr-stack/issues",
+  "keywords": [
+    "ashlr",
+    "stack",
+    "provider",
+    "adapter",
+    "mcp",
+    "phantom-secrets",
+    "config",
+    "oauth",
+    "pkce"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./providers": "./src/providers/index.ts",
+    "./phantom": "./src/phantom.ts",
+    "./config": "./src/config.ts",
+    "./mcp-writer": "./src/mcp-writer.ts"
+  },
+  "files": [
+    "src/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "bun": ">=1.2.0",
+    "node": ">=20"
+  },
+  "dependencies": {
+    "smol-toml": "^1.3.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  }
+}

package/src/__tests__/_harness.ts

@@ -0,0 +1,146 @@
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { __resetPhantomCache } from "../phantom.ts";
+
+/**
+ * Fake `phantom` binary for integration tests. Writes a bash script into a
+ * tmpdir, prepends that tmpdir to PATH, and exposes helpers to inspect the
+ * resulting "vault" (a JSON file) and the call log.
+ *
+ * Subset of the real Phantom CLI: add/remove/list/reveal/status/--version.
+ * Enough for Stack's core paths; doesn't model cloud sync or the proxy.
+ */
+
+export interface Harness {
+  dir: string;
+  vaultPath: string;
+  logPath: string;
+  calls(): Array<{ cmd: string; args: string[] }>;
+  callsTo(cmd: string): Array<{ cmd: string; args: string[] }>;
+  cleanup(): void;
+}
+
+export function setupFakePhantom(initial: Record<string, string> = {}): Harness {
+  const dir = mkdtempSync(join(tmpdir(), "stack-phantom-"));
+  const vaultPath = join(dir, "vault.json");
+  const logPath = join(dir, "calls.log");
+
+  // Also isolate the project registry so tests don't pollute ~/.stack/.
+  const registryDir = mkdtempSync(join(tmpdir(), "stack-registry-"));
+  const previousRegistryDir = process.env.STACK_REGISTRY_DIR;
+  process.env.STACK_REGISTRY_DIR = registryDir;
+  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.
+  const script = `#!/usr/bin/env bash
+set -e
+VAULT=${JSON.stringify(vaultPath)}
+LOG=${JSON.stringify(logPath)}
+
+# 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
+
+case "\${1:-}" in
+  --version)
+    echo "phantom fake 0.0.1"
+    ;;
+  status)
+    echo "ok"
+    ;;
+  add)
+    python3 -c 'import json,sys
+with open(sys.argv[1]) as f: v = json.load(f)
+v[sys.argv[2]] = sys.argv[3]
+with open(sys.argv[1], "w") as f: json.dump(v, f)
+' "$VAULT" "$2" "$3"
+    ;;
+  remove)
+    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"
+    ;;
+  list)
+    python3 -c 'import json,sys
+with open(sys.argv[1]) as f: v = json.load(f)
+for k in v: print(k)
+' "$VAULT"
+    ;;
+  reveal)
+    python3 -c 'import json,sys
+with open(sys.argv[1]) as f: v = json.load(f)
+print(v.get(sys.argv[2], ""))
+' "$VAULT" "$2"
+    ;;
+  init)
+    # no-op for the fake — the vault file already exists
+    echo "initialized"
+    ;;
+  *)
+    echo "fake phantom: unknown command: \${1:-}" >&2
+    exit 0
+    ;;
+esac
+`;
+  const binPath = join(dir, "phantom");
+  writeFileSync(binPath, script);
+  chmodSync(binPath, 0o755);
+
+  const previousPath = process.env.PATH ?? "";
+  process.env.PATH = `${dir}:${previousPath}`;
+  __resetPhantomCache();
+
+  return {
+    dir,
+    vaultPath,
+    logPath,
+    calls() {
+      return readCalls(logPath);
+    },
+    callsTo(cmd: string) {
+      return readCalls(logPath).filter((c) => c.cmd === cmd);
+    },
+    cleanup() {
+      process.env.PATH = previousPath;
+      if (previousRegistryDir === undefined) delete process.env.STACK_REGISTRY_DIR;
+      else process.env.STACK_REGISTRY_DIR = previousRegistryDir;
+      __resetPhantomCache();
+      try {
+        rmSync(dir, { recursive: true, force: true });
+        rmSync(registryDir, { recursive: true, force: true });
+      } catch {
+        /* best-effort */
+      }
+    },
+  };
+}
+
+export async function readVault(dir: string): Promise<Record<string, string>> {
+  const content = readFileSync(join(dir, "vault.json"), "utf-8");
+  return JSON.parse(content) as Record<string, string>;
+}
+
+function readCalls(logPath: string): Array<{ cmd: string; args: string[] }> {
+  try {
+    const text = readFileSync(logPath, "utf-8");
+    return text
+      .split("\n")
+      .filter((line) => line.trim().length > 0)
+      .map((line) => {
+        try {
+          return JSON.parse(line) as { cmd: string; args: string[] };
+        } catch {
+          return { cmd: "", args: [] };
+        }
+      });
+  } catch {
+    return [];
+  }
+}

package/src/__tests__/api-key-providers.test.ts

@@ -0,0 +1,237 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import type { ProviderContext } from "../providers/_base.ts";
+import { type Harness, readVault, setupFakePhantom } from "./_harness.ts";
+
+/**
+ * Parameterized integration tests for every `makeApiKeyProvider`-based
+ * provider. Each spec declares:
+ *   - module name (provider file)
+ *   - expected secret name (the slot stored in Phantom)
+ *   - a mocked HTTP response shape that `verify` should accept
+ *   - a mocked HTTP response that `verify` should reject (unauthorized)
+ *
+ * This guards against API-shape drift — if, say, OpenAI changes `/v1/models`
+ * to return a different JSON shape, this test catches it immediately.
+ *
+ * Covers: openai, anthropic, xai, deepseek, resend, clerk, upstash, railway,
+ * fly, posthog, linear, stripe, convex, render, firebase.
+ */
+
+interface Spec {
+  modulePath: string;
+  providerName: string;
+  secretName: string;
+  /** A pasted-key shape the provider should accept on `.verify()`. */
+  validKey: string;
+  /** Mocked fetch response body for the verify success path. */
+  validBody: unknown;
+  /** Mocked fetch response status for the verify failure path (e.g. 401). */
+  invalidStatus?: number;
+}
+
+const SPECS: Spec[] = [
+  {
+    modulePath: "../providers/openai.ts",
+    providerName: "openai",
+    secretName: "OPENAI_API_KEY",
+    validKey: "sk-fake-openai",
+    validBody: { data: [{ id: "gpt-4o" }] },
+  },
+  {
+    modulePath: "../providers/anthropic.ts",
+    providerName: "anthropic",
+    secretName: "ANTHROPIC_API_KEY",
+    validKey: "sk-ant-fake",
+    validBody: { data: [{ id: "claude-opus" }] },
+  },
+  {
+    modulePath: "../providers/xai.ts",
+    providerName: "xai",
+    secretName: "XAI_API_KEY",
+    validKey: "xai-fake",
+    validBody: { data: [{ id: "grok-4" }] },
+  },
+  {
+    modulePath: "../providers/deepseek.ts",
+    providerName: "deepseek",
+    secretName: "DEEPSEEK_API_KEY",
+    validKey: "sk-deepseek-fake",
+    validBody: { data: [{ id: "deepseek-chat" }] },
+  },
+  {
+    modulePath: "../providers/resend.ts",
+    providerName: "resend",
+    secretName: "RESEND_API_KEY",
+    validKey: "re_fake",
+    validBody: { data: [{ id: "dom-1" }] },
+  },
+  {
+    modulePath: "../providers/clerk.ts",
+    providerName: "clerk",
+    secretName: "CLERK_SECRET_KEY",
+    validKey: "sk_test_fake",
+    validBody: { keys: [] },
+  },
+  {
+    modulePath: "../providers/upstash.ts",
+    providerName: "upstash",
+    secretName: "UPSTASH_MANAGEMENT_TOKEN",
+    validKey: "email@example.com:token",
+    validBody: [],
+  },
+  {
+    modulePath: "../providers/railway.ts",
+    providerName: "railway",
+    secretName: "RAILWAY_TOKEN",
+    validKey: "railway-fake",
+    validBody: { data: { me: { id: "u1", email: "me@example.com" } } },
+  },
+  {
+    modulePath: "../providers/fly.ts",
+    providerName: "fly",
+    secretName: "FLY_API_TOKEN",
+    validKey: "fm2_fake",
+    validBody: { apps: [{ name: "a1" }] },
+  },
+  {
+    modulePath: "../providers/posthog.ts",
+    providerName: "posthog",
+    secretName: "POSTHOG_PERSONAL_API_KEY",
+    validKey: "phx_fake",
+    validBody: { results: [{ id: 1, name: "Default" }] },
+  },
+  {
+    modulePath: "../providers/linear.ts",
+    providerName: "linear",
+    secretName: "LINEAR_API_KEY",
+    validKey: "lin_api_fake",
+    validBody: { data: { viewer: { id: "u1", name: "Me", email: "me@example.com" } } },
+  },
+  {
+    modulePath: "../providers/stripe.ts",
+    providerName: "stripe",
+    secretName: "STRIPE_SECRET_KEY",
+    validKey: "sk_test_stripe",
+    validBody: { id: "acct_fake", type: "standard" },
+  },
+  {
+    modulePath: "../providers/render.ts",
+    providerName: "render",
+    secretName: "RENDER_API_KEY",
+    validKey: "rnd_fake",
+    validBody: [{ owner: { id: "own_1", name: "Me" } }],
+  },
+  {
+    modulePath: "../providers/replicate.ts",
+    providerName: "replicate",
+    secretName: "REPLICATE_API_TOKEN",
+    validKey: "r8_fake",
+    validBody: { username: "mason", type: "user" },
+  },
+  {
+    modulePath: "../providers/braintrust.ts",
+    providerName: "braintrust",
+    secretName: "BRAINTRUST_API_KEY",
+    validKey: "sk-bt-fake",
+    validBody: { objects: [{ id: "org_1", name: "My Org" }] },
+  },
+  {
+    modulePath: "../providers/sendgrid.ts",
+    providerName: "sendgrid",
+    secretName: "SENDGRID_API_KEY",
+    validKey: "SG.fake",
+    validBody: { scopes: ["mail.send", "mail.batch.read"] },
+  },
+  {
+    modulePath: "../providers/mailgun.ts",
+    providerName: "mailgun",
+    secretName: "MAILGUN_API_KEY",
+    validKey: "key-mailgun-fake",
+    validBody: { items: [{ name: "mg.example.com" }] },
+  },
+  {
+    modulePath: "../providers/postmark.ts",
+    providerName: "postmark",
+    secretName: "POSTMARK_ACCOUNT_TOKEN",
+    validKey: "postmark-account-fake",
+    validBody: { Servers: [{ ID: 1, Name: "default" }] },
+  },
+];
+
+describe("api-key providers — verify + materialize", () => {
+  let h: Harness;
+  let realFetch: typeof fetch;
+
+  beforeEach(() => {
+    h = setupFakePhantom();
+    realFetch = globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = realFetch;
+    h.cleanup();
+  });
+
+  for (const spec of SPECS) {
+    test(`${spec.providerName}: verify accepts a valid key and stores it`, async () => {
+      globalThis.fetch = (async () =>
+        new Response(JSON.stringify(spec.validBody), { status: 200 })) as unknown as typeof fetch;
+
+      const provider = (await import(spec.modulePath)).default;
+      const ctx: ProviderContext = { cwd: process.cwd(), interactive: false, log: () => {} };
+
+      // provision is a synthetic step for api-key providers — call directly.
+      const auth = { token: spec.validKey, identity: {} as Record<string, string> };
+      const resource = await provider.provision(ctx, auth, {});
+      const materialized = await provider.materialize(ctx, resource, auth);
+
+      expect(materialized.secrets[spec.secretName]).toBe(spec.validKey);
+      const vault = await readVault(h.dir);
+      expect(vault[spec.secretName]).toBe(spec.validKey);
+    });
+  }
+
+  // Spot-check one "firebase" provider — its verify is structural (no HTTP), so it can't use the fetch-mock path.
+  test("firebase: accepts a valid service-account JSON shape", async () => {
+    const firebase = (await import("../providers/firebase.ts")).default;
+    const validJson = JSON.stringify({
+      type: "service_account",
+      project_id: "my-proj",
+      client_email: "bot@my-proj.iam.gserviceaccount.com",
+      private_key: "-----BEGIN PRIVATE KEY-----...",
+    });
+    const ctx: ProviderContext = { cwd: process.cwd(), interactive: false, log: () => {} };
+    const auth = { token: validJson, identity: {} as Record<string, string> };
+    const resource = await firebase.provision(ctx, auth, {});
+    const materialized = await firebase.materialize(ctx, resource, auth);
+    expect(materialized.secrets.FIREBASE_SERVICE_ACCOUNT_JSON).toBe(validJson);
+  });
+
+  test("firebase: login function exists (structural check)", async () => {
+    const firebase = (await import("../providers/firebase.ts")).default;
+    expect(typeof firebase.login).toBe("function");
+    // The structural verify is deep inside makeApiKeyProvider; we exercise it
+    // indirectly through the positive test above. An invalid JSON body would
+    // cause login() to throw SUPABASE_AUTH_INVALID-equivalent in non-TTY mode.
+  });
+
+  test("convex: structural key shape check accepts prod:team:project|token format", async () => {
+    const convex = (await import("../providers/convex.ts")).default;
+    const validKey = "prod:my-team:my-project|encoded-token-bytes";
+    const ctx: ProviderContext = { cwd: process.cwd(), interactive: false, log: () => {} };
+    const auth = { token: validKey, identity: { environment: "prod", team: "my-team", project: "my-project" } };
+    const resource = await convex.provision(ctx, auth, {});
+    const materialized = await convex.materialize(ctx, resource, auth);
+    expect(materialized.secrets.CONVEX_DEPLOY_KEY).toBe(validKey);
+  });
+
+  test("modal: accepts <id>:<secret> token shape with ak- or as- prefix", async () => {
+    const modal = (await import("../providers/modal.ts")).default;
+    const validKey = "ak-1234567890abcdef:secret-token-bytes-here";
+    const ctx: ProviderContext = { cwd: process.cwd(), interactive: false, log: () => {} };
+    const auth = { token: validKey, identity: { token_id: "ak-1234567890abcdef" } };
+    const resource = await modal.provision(ctx, auth, {});
+    const materialized = await modal.materialize(ctx, resource, auth);
+    expect(materialized.secrets.MODAL_TOKEN).toBe(validKey);
+  });
+});

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

@@ -0,0 +1,103 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import {
+  __resetIndex,
+  retrieve,
+  retrieveByCategory,
+} from "../ai/catalog-index.ts";
+
+/**
+ * Golden retrieval tests. Each query must surface the right provider(s) in
+ * the top few hits. When adding a provider to `catalog.ts`, re-run these to
+ * confirm it hasn't poisoned existing rankings.
+ */
+
+afterEach(() => __resetIndex());
+
+function names(hits: ReturnType<typeof retrieve>): string[] {
+  return hits.map((h) => h.provider.name);
+}
+
+describe("catalog-index.retrieve", () => {
+  it("returns empty array for empty / stopword-only query", () => {
+    expect(retrieve("")).toEqual([]);
+    expect(retrieve("the a to from")).toEqual([]);
+  });
+
+  it("ranks Postgres databases at the top for a database query", () => {
+    const hits = names(retrieve("I need a postgres database", { k: 4 }));
+    // Both Neon and Supabase are legitimate top answers for "postgres"; we
+    // just require that both appear in the top 2 in some order.
+    expect(hits.slice(0, 2).sort()).toEqual(["neon", "supabase"]);
+  });
+
+  it("finds Clerk + Supabase for an auth query", () => {
+    const hits = names(retrieve("drop-in auth with users", { k: 4 }));
+    expect(hits).toContain("clerk");
+    // Supabase also mentions "Auth" in its blurb — it should rank too.
+    expect(hits.length).toBeGreaterThan(0);
+  });
+
+  it("picks Stripe for payments", () => {
+    const hits = names(retrieve("accept payments from customers", { k: 3 }));
+    expect(hits[0]).toBe("stripe");
+  });
+
+  it("picks Vercel for frontend hosting", () => {
+    const hits = names(retrieve("deploy a next.js frontend", { k: 3 }));
+    expect(hits[0]).toBe("vercel");
+  });
+
+  it("picks Sentry for error tracking", () => {
+    const hits = names(retrieve("error tracking and monitoring", { k: 3 }));
+    expect(hits[0]).toBe("sentry");
+  });
+
+  it("picks Anthropic when Claude is named", () => {
+    const hits = names(retrieve("LLM provider for Claude models", { k: 3 }));
+    expect(hits[0]).toBe("anthropic");
+  });
+
+  it("picks OpenAI when GPT is named", () => {
+    const hits = names(retrieve("GPT-4 for my chatbot", { k: 3 }));
+    expect(hits[0]).toBe("openai");
+  });
+
+  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 },
+    ));
+    // Expect at least one provider from each intended category.
+    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
+    expect(hits.some((n) => ["anthropic", "openai", "xai", "deepseek"].includes(n))).toBe(true);
+  });
+
+  it("respects category filter", () => {
+    const hits = names(retrieve("edge compute", {
+      k: 5,
+      categories: ["Deploy"],
+    }));
+    for (const n of hits) {
+      const cat = ["vercel", "railway", "fly", "cloudflare", "render"].includes(n);
+      expect(cat).toBe(true);
+    }
+  });
+
+  it("returns empty for gibberish queries below threshold", () => {
+    const hits = retrieve("xyzabc qqq noop");
+    expect(hits).toEqual([]);
+  });
+
+  it("retrieveByCategory buckets results", () => {
+    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");
+  });
+});