@ashlr/stack 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,124 @@
+# @ashlr/stack
+
+> The `stack` CLI — one command to provision, wire, and operate every third-party service in your project. 23 providers, MCP-native, Phantom-backed.
+
+Part of [Ashlr Stack](https://stack.ashlr.ai). See the monorepo at [ashlrai/ashlr-stack](https://github.com/ashlrai/ashlr-stack).
+
+## What it is
+
+`stack` collapses the "spin up ten services" phase of a project into a single command. Instead of tab-hopping between Supabase, Vercel, Sentry, Neon, etc. to create projects and paste secrets into `.env`, you run:
+
+```bash
+stack init --template nextjs-supabase-posthog-sentry
+```
+
+Stack does the OAuth dance per provider, creates the upstream resource, stores every secret in [Phantom Secrets](https://phantom.ashlr.ai), writes `.env` + `.mcp.json`, and hands you a project ready for `bun dev`.
+
+Secrets never live in Stack — only Phantom. `.stack.toml` is safe to commit; per-developer IDs live in the gitignored `.stack.local.toml`.
+
+## Install
+
+One-liner (recommended):
+
+```bash
+# macOS / Linux
+curl -fsSL stack.ashlr.ai/install.sh | bash
+
+# Windows (PowerShell)
+irm stack.ashlr.ai/install.ps1 | iex
+```
+
+Or install manually from the registry:
+
+```bash
+bun add -g @ashlr/stack ashlr-stack-mcp    # preferred
+# or
+npm i -g @ashlr/stack ashlr-stack-mcp
+```
+
+Prerequisites:
+
+- [Bun](https://bun.sh) >= 1.2 (or Node.js >= 20)
+- [Phantom Secrets](https://phantom.ashlr.ai) — the installer sets this up for you
+
+## Quickstart
+
+```bash
+stack init                            # interactive template picker
+stack add supabase                    # OAuth → new project → secrets → .mcp.json
+stack add                             # no arg = interactive provider picker
+stack doctor                          # verify every wired service is healthy
+stack doctor --all                    # run across every registered project
+stack list                            # show this project's stack at a glance
+stack providers                       # full catalog of 23 curated providers
+```
+
+Bring Stack to an existing repo:
+
+```bash
+stack scan                            # detect providers already in the code
+stack scan --auto                     # scans, then runs `stack add` for each
+stack import                          # inhale an existing .env into Phantom
+stack clone github.com/org/repo       # clone + scan someone else's project
+```
+
+Run your app with secrets injected by Phantom:
+
+```bash
+stack exec -- bun dev
+```
+
+## Commands
+
+22 commands total. A cheat sheet:
+
+| Command | What it does |
+| --- | --- |
+| `stack init [--template]` | Scaffold a new stack from a template |
+| `stack add [service]` | Add a provider (OAuth + provision + write secrets) |
+| `stack remove <service>` | Tear down one service (or `--all` for everything) |
+| `stack list` | Show services wired into this project |
+| `stack info <service>` | Deep-dive on one service (resource, region, docs, MCP name) |
+| `stack doctor [--all] [--fix] [--json]` | Healthcheck; `--fix` re-runs setup, `--json` for CI |
+| `stack scan [--auto]` | Detect providers from package manifests, configs, `.env.example` |
+| `stack import [--from <file>]` | Migrate an existing `.env` into Phantom + `.stack.toml` |
+| `stack clone <github-url>` | git-clone + scan + next-steps |
+| `stack providers` | Browse the full 23-provider catalog |
+| `stack templates` | List starter templates |
+| `stack deps` | ASCII tree of this stack grouped by category |
+| `stack env show` / `stack env diff` | Effective env-var surface vs vault vs config |
+| `stack env set <KEY> <VALUE>` / `stack env unset <KEY>` | Direct secret injection |
+| `stack exec -- <cmd>` | Run a command with Phantom secrets in the environment |
+| `stack projects list|register|remove|where` | Cross-project registry |
+| `stack ci init` | Scaffold a `.github/workflows/stack-ci.yml` |
+| `stack completion <bash\|zsh\|fish>` | Emit a shell-completion script |
+| `stack upgrade` | Check npm for a newer `@ashlr/stack` release |
+
+Full reference with flags, subcommands, and examples: **[stack.ashlr.ai/docs/cli](https://stack.ashlr.ai/docs/cli)**.
+
+## MCP integration
+
+`stack add` writes to your project's `.mcp.json` so Claude Code / Cursor / Windsurf can use the provider's MCP server immediately. See [ashlr-stack-mcp](https://www.npmjs.com/package/ashlr-stack-mcp) for Stack's own MCP server (17 tools + 3 resources) and [stack.ashlr.ai/docs/mcp](https://stack.ashlr.ai/docs/mcp) for wiring docs.
+
+## Configuration
+
+Stack splits config into two files:
+
+- `.stack.toml` — **committed**. Service names, secret slots, MCP wirings.
+- `.stack.local.toml` — **gitignored**. `project_id`, `resource_id`, timestamps. Unique per clone.
+
+Teammates who clone the repo run `stack doctor --fix` and Stack re-authenticates each service for them.
+
+Full schema: [stack.ashlr.ai/docs/config](https://stack.ashlr.ai/docs/config).
+
+## Links
+
+- Docs — [stack.ashlr.ai/docs](https://stack.ashlr.ai/docs)
+- Quickstart — [stack.ashlr.ai/docs/quickstart](https://stack.ashlr.ai/docs/quickstart)
+- Provider catalog — [stack.ashlr.ai/docs/providers](https://stack.ashlr.ai/docs/providers)
+- Repo — [github.com/ashlrai/ashlr-stack](https://github.com/ashlrai/ashlr-stack)
+- Issues — [github.com/ashlrai/ashlr-stack/issues](https://github.com/ashlrai/ashlr-stack/issues)
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@ashlr/stack",
+  "version": "0.1.1",
+  "description": "Ashlr Stack CLI — the control plane for your entire dev stack. One command to provision, wire, and operate every third-party service in your project. 23 providers, MCP-native.",
+  "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/cli"
+  },
+  "bugs": "https://github.com/ashlrai/ashlr-stack/issues",
+  "keywords": [
+    "ashlr",
+    "stack",
+    "cli",
+    "mcp",
+    "claude-code",
+    "phantom-secrets",
+    "supabase",
+    "neon",
+    "vercel",
+    "cloudflare",
+    "openai",
+    "anthropic",
+    "provisioning",
+    "devops",
+    "control-plane"
+  ],
+  "type": "module",
+  "bin": {
+    "stack": "./src/index.ts"
+  },
+  "files": [
+    "src/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "bun": ">=1.2.0",
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "dependencies": {
+    "@ashlr/stack-core": "^0.1.1",
+    "@clack/prompts": "^0.8.2",
+    "citty": "^0.1.6",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  }
+}

package/src/__tests__/apply.test.ts

@@ -0,0 +1,80 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * End-to-end test for `stack apply` — specifically the auto-init behaviour.
+ * The marketed golden path is `stack recommend --save && stack apply <id>`
+ * from a blank directory; that must not explode on a missing .stack.toml.
+ *
+ * We don't exercise the provider-provisioning side (real HTTP, OAuth, tokens
+ * required). `--noWire` + `--noRollback` isolate the init+pipeline behaviour.
+ */
+
+const CLI_ENTRY = join(dirname(fileURLToPath(import.meta.url)), "..", "index.ts");
+
+function runCli(args: string[], cwd?: string): { stdout: string; stderr: string; code: number } {
+  const result = spawnSync("bun", [CLI_ENTRY, ...args], {
+    encoding: "utf8",
+    cwd,
+    env: { ...process.env, NO_COLOR: "1", CI: "1" },
+  });
+  return {
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    code: result.status ?? 0,
+  };
+}
+
+const createdDirs: string[] = [];
+afterEach(() => {
+  while (createdDirs.length > 0) {
+    const dir = createdDirs.pop();
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function mkTmp(): string {
+  const dir = mkdtempSync(join(tmpdir(), "stack-apply-"));
+  createdDirs.push(dir);
+  return dir;
+}
+
+describe("stack apply", () => {
+  it("auto-inits .stack.toml when none exists, then runs against the recipe", () => {
+    const dir = mkTmp();
+
+    // Step 1: seed a recipe via `stack recommend --save`.
+    const rec = runCli(["recommend", "postgres database", "--save", "--json"], dir);
+    expect(rec.code).toBe(0);
+    const payload = JSON.parse(rec.stdout);
+    const recipeId: string = payload.recipe.id;
+    expect(existsSync(join(dir, ".stack.toml"))).toBe(false);
+
+    // Step 2: apply it from the same blank dir. Providers will fail at `stack
+    // add` because no OAuth/tokens are present, but `apply` must first create
+    // .stack.toml via the auto-init path.
+    const applied = runCli(["apply", recipeId, "--noWire", "--noRollback"], dir);
+
+    // Apply may exit non-zero because provider adds fail; that's expected.
+    // The invariant we care about: auto-init ran, so .stack.toml now exists.
+    expect(existsSync(join(dir, ".stack.toml"))).toBe(true);
+
+    // The banner breadcrumb should surface so the user understands the
+    // auto-init happened implicitly.
+    const out = applied.stdout + applied.stderr;
+    expect(out).toContain("auto-running");
+  });
+
+  it("rejects a missing recipe id with a clear error", () => {
+    const dir = mkTmp();
+    const { stdout, stderr, code } = runCli(["apply", "does-not-exist", "--noWire"], dir);
+    // Apply exits after pickRecipe fails; the surfaced error must name the
+    // recipe so the user knows what to fix.
+    expect(code).toBeGreaterThan(0);
+    expect(stdout + stderr).toContain("does-not-exist");
+  });
+});

package/src/__tests__/recommend.test.ts

@@ -0,0 +1,109 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Smoke tests for `stack recommend`. Spawns the CLI the same way the MCP
+ * server will (bun subprocess) to cover the full JSON contract end-to-end.
+ */
+
+const CLI_ENTRY = join(dirname(fileURLToPath(import.meta.url)), "..", "index.ts");
+
+function runCli(args: string[], cwd?: string): { stdout: string; stderr: string; code: number } {
+  const result = spawnSync("bun", [CLI_ENTRY, ...args], {
+    encoding: "utf8",
+    cwd,
+    env: { ...process.env, NO_COLOR: "1", CI: "1" },
+  });
+  return {
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    code: result.status ?? 0,
+  };
+}
+
+const createdDirs: string[] = [];
+afterEach(() => {
+  while (createdDirs.length > 0) {
+    const dir = createdDirs.pop();
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function mkTmp(): string {
+  const dir = mkdtempSync(join(tmpdir(), "stack-recommend-"));
+  createdDirs.push(dir);
+  return dir;
+}
+
+describe("stack recommend --json", () => {
+  it("returns structured JSON with hits for a SaaS query", () => {
+    const { stdout, code } = runCli(["recommend", "B2B SaaS with auth and payments", "--json"]);
+    expect(code).toBe(0);
+    const payload = JSON.parse(stdout);
+    expect(payload.query).toBe("B2B SaaS with auth and payments");
+    expect(Array.isArray(payload.hits)).toBe(true);
+    expect(payload.hits.length).toBeGreaterThan(0);
+    const hitNames = payload.hits.map((h: { name: string }) => h.name);
+    expect(hitNames).toContain("stripe");
+    // clerk or supabase should cover the auth side
+    expect(hitNames.some((n: string) => ["clerk", "supabase"].includes(n))).toBe(true);
+    expect(typeof payload.guidance).toBe("string");
+    expect(payload.byCategory).toBeDefined();
+  });
+
+  it("narrows to a category filter", () => {
+    const { stdout, code } = runCli([
+      "recommend",
+      "edge compute",
+      "--category",
+      "Deploy",
+      "--json",
+    ]);
+    expect(code).toBe(0);
+    const payload = JSON.parse(stdout);
+    for (const hit of payload.hits) {
+      expect(hit.category).toBe("Deploy");
+    }
+  });
+
+  it("with --save persists a recipe under .stack/recipes/", () => {
+    const dir = mkTmp();
+    const { stdout, code } = runCli(["recommend", "postgres database", "--save", "--json"], dir);
+    expect(code).toBe(0);
+    const payload = JSON.parse(stdout);
+    expect(payload.recipe).toBeDefined();
+    expect(payload.recipe.id).toBeDefined();
+    expect(payload.recipe.path).toContain(".stack/recipes");
+
+    const recipesDir = join(dir, ".stack", "recipes");
+    const files = readdirSync(recipesDir);
+    expect(files.length).toBe(1);
+    expect(files[0]).toMatch(/\.toml$/);
+    expect(files[0]).toBe(`${payload.recipe.id}.toml`);
+  });
+
+  it("without --save does not create .stack/recipes", () => {
+    const dir = mkTmp();
+    const { code } = runCli(["recommend", "postgres database", "--json"], dir);
+    expect(code).toBe(0);
+    try {
+      const files = readdirSync(join(dir, ".stack", "recipes"));
+      expect(files.length).toBe(0);
+    } catch (err) {
+      // ENOENT is the expected happy path — no dir created.
+      expect((err as NodeJS.ErrnoException).code).toBe("ENOENT");
+    }
+  });
+
+  it("emits an empty hits array with fallback guidance for a gibberish query", () => {
+    const { stdout, code } = runCli(["recommend", "xyzabcxyzabc nonsenseword", "--json"]);
+    expect(code).toBe(0);
+    const payload = JSON.parse(stdout);
+    expect(payload.hits).toEqual([]);
+    expect(payload.guidance).toContain("No strong matches");
+  });
+});

package/src/commands/add.ts

@@ -0,0 +1,163 @@
+import { defineCommand } from "citty";
+import {
+  addService,
+  assertPhantomInstalled,
+  getProvider,
+  hasConfig,
+  listProviderNames,
+} from "@ashlr/stack-core";
+import { colors, intro, logEvent, outro, outroError, prompts } from "../ui.ts";
+
+export const addCommand = defineCommand({
+  meta: {
+    name: "add",
+    description: "Provision a service and wire its secrets + MCP entry.",
+  },
+  args: {
+    service: {
+      type: "positional",
+      required: false,
+      description: "Service name (e.g. supabase, neon, vercel). Omit for interactive picker.",
+    },
+    use: {
+      type: "string",
+      description: "Attach to an existing resource by id instead of creating a new one.",
+    },
+    region: {
+      type: "string",
+      description: "Region hint for providers that need one (e.g. us-east-1).",
+    },
+    dryRun: {
+      type: "boolean",
+      default: false,
+      description:
+        "Preview what would happen (no network calls, no vault writes, no MCP edits).",
+    },
+  },
+  async run({ args }) {
+    if (!hasConfig()) {
+      intro("stack add");
+      outroError("No .stack.toml found. Run `stack init` first.");
+      return;
+    }
+
+    const available = listProviderNames();
+
+    // Interactive picker when no service argument is provided.
+    let service = args.service ? String(args.service) : undefined;
+    if (!service) {
+      if (!process.stdout.isTTY) {
+        intro("stack add");
+        outroError("No service specified. Usage: stack add <service>");
+        return;
+      }
+      const grouped = await groupProvidersForPicker(available);
+      const picked = await prompts.select({
+        message: "Which service to add?",
+        options: grouped,
+      });
+      if (prompts.isCancel(picked)) {
+        intro("stack add");
+        outroError("Cancelled.");
+        return;
+      }
+      service = String(picked);
+    }
+
+    intro(`stack add ${service}${args.dryRun ? colors.dim(" (dry-run)") : ""}`);
+
+    if (!args.dryRun) {
+      try {
+        await assertPhantomInstalled();
+      } catch (err) {
+        outroError((err as Error).message);
+        return;
+      }
+    }
+
+    if (!available.includes(service)) {
+      // Group the catalog by category so the suggestion doesn't wrap into an
+      // unreadable one-line comma list on narrow terminals.
+      const byCat: Record<string, string[]> = {};
+      for (const name of available) {
+        try {
+          const p = await getProvider(name);
+          (byCat[p.category] ??= []).push(p.name);
+        } catch {
+          /* skip */
+        }
+      }
+      const lines = Object.entries(byCat)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([cat, names]) => `  ${colors.bold(cat.padEnd(10))} ${names.sort().join("  ")}`);
+      console.log();
+      console.log(`  Unknown provider ${colors.red(`"${service}"`)}.`);
+      console.log();
+      console.log(colors.dim("  Available providers:"));
+      for (const line of lines) console.log(line);
+      console.log();
+      outroError("Pick one from the catalog above.");
+      return;
+    }
+
+    // Dry-run: describe what the flow would do without executing any step.
+    if (args.dryRun) {
+      const provider = await getProvider(service);
+      console.log();
+      console.log(
+        `  ${colors.bold(provider.displayName)} ${colors.dim(`(${provider.category} · ${provider.authKind})`)}`,
+      );
+      console.log(`    ${colors.dim("1.")} login       ${colors.dim("(prompt for PAT or run OAuth)")}`);
+      console.log(
+        `    ${colors.dim("2.")} provision   ${args.use ? `attach to existing resource ${colors.dim(String(args.use))}` : colors.dim("create a new upstream resource")}`,
+      );
+      console.log(`    ${colors.dim("3.")} materialize ${colors.dim("fetch credentials for the resource")}`);
+      console.log(`    ${colors.dim("4.")} persist     ${colors.dim("write secrets to Phantom + MCP + .stack.toml")}`);
+      console.log();
+      outro(colors.dim("dry-run complete — nothing written."));
+      return;
+    }
+
+    const spinner = prompts.spinner();
+    try {
+      spinner.start(`Wiring ${service}…`);
+      const result = await addService({
+        providerName: service,
+        existingResourceId: args.use ? String(args.use) : undefined,
+        hints: args.region ? { region: String(args.region) } : undefined,
+        interactive: process.stdout.isTTY === true,
+        log: (event) => {
+          spinner.stop();
+          logEvent(event);
+          spinner.start(`Wiring ${service}…`);
+        },
+      });
+      spinner.stop(
+        `${colors.green("●")} ${result.displayName} (${result.resourceId}) · ${result.secretCount} secrets${
+          result.mcpWired ? " · mcp wired" : ""
+        }`,
+      );
+      outro(`${colors.green("✓")} ${service} is live.`);
+    } catch (err) {
+      spinner.stop(colors.red("Failed."));
+      outroError((err as Error).message);
+    }
+  },
+});
+
+async function groupProvidersForPicker(names: string[]) {
+  const out: Array<{ label: string; value: string; hint?: string }> = [];
+  for (const name of names) {
+    try {
+      const p = await getProvider(name);
+      out.push({
+        value: p.name,
+        label: `${p.displayName} ${colors.dim(`· ${p.category}`)}`,
+        hint: p.authKind,
+      });
+    } catch {
+      /* skip */
+    }
+  }
+  return out.sort((a, b) => a.label.localeCompare(b.label));
+}