@ashlr/stack-core 0.1.1 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Ashlr / Mason Wyatt
+Copyright (c) 2026 AshlrAI, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,26 +2,30 @@
 
 > 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.
+This workspace package shares source between the [`@ashlr/stack`](https://www.npmjs.com/package/@ashlr/stack) CLI and [`ashlr-stack-mcp`](https://www.npmjs.com/package/ashlr-stack-mcp) server. Its export points at TypeScript source. The examples below target the reviewed workspace; they do not establish a separately published core package or Node-only execution support.
 
-## Install
+## Use in this workspace
+
+From the repository root, prepare the workspace dependencies with Bun 1.2+:
 
 ```bash
-bun add @ashlr/stack-core
-# or
-npm i @ashlr/stack-core
+bun install
 ```
 
+Use the selected CLI/MCP artifact and its documented runtime when installing
+those products. Source version `0.2.1` is distinct from recorded public
+CLI/MCP `0.1.1` packages; verify actual package contents separately.
+
 ## 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 |
+| `addService({ providerName, ... })` | Attempt login → create/attach → materialize → named-secret/MCP/config writes; inspect failures and partial state |
 | `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` |
+| `listProviderNames()` / `getProvider(name)` | Introspect the built-in 39-provider registry (`getProvider` is async) |
+| `scanSource(cwd)` | 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 |
 
@@ -35,18 +39,25 @@ import {
   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() });
+// With explicit user approval for provider and credential effects, attempt
+// Supabase setup, named-secret/MCP writes, and split-config persistence.
+await addService({ providerName: "supabase", cwd: process.cwd() });
 
 const cfg = await readConfig();
-console.log(cfg.services.map((s) => s.name));
+console.log(Object.keys(cfg.services));
 
 // Scan an existing checkout for providers already wired up.
-const detections = await scanSource({ cwd: process.cwd() });
-console.log(listProviderNames().length); // 23
+const detections = await scanSource(process.cwd());
+console.log(detections);
+console.log(listProviderNames().length); // 39 in this source snapshot
 ```
 
+The setup path can contact providers and write credentials, MCP entries and
+split config. It handles values in memory; writes and rollback are not an
+atomic transaction. Examples describe reviewed source and require the selected
+artifact, runtime, project directory, user authorization and provider access.
+A package installation does not establish those later steps.
+
 ## Links
 
 - Full CLI-level docs — [stack.ashlr.ai/docs/cli](https://stack.ashlr.ai/docs/cli)
@@ -54,4 +65,4 @@ console.log(listProviderNames().length); // 23
 
 ## License
 
-MIT. See [LICENSE](./LICENSE).
+MIT. See [LICENSE](../../LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashlr/stack-core",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Ashlr Stack core — provider adapters, .stack.toml config, Phantom integration. Shared logic behind the Stack CLI and MCP server.",
   "license": "MIT",
   "author": {

package/src/__tests__/_harness.ts

@@ -10,6 +10,11 @@ import { __resetPhantomCache } from "../phantom.ts";
  *
  * 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.
+ *
+ * Behaviour follows Phantom Secrets 0.7.9 (checked against the real binary by
+ * `phantom-contract.test.ts`): `add` takes values only via `--stdin` and never
+ * replaces a name; `reveal` and `remove` refuse without an attached terminal;
+ * `list` prints a decorated table unless `--json` is passed.
  */
 
 export interface Harness {
@@ -21,7 +26,22 @@ export interface Harness {
   cleanup(): void;
 }
 
-export function setupFakePhantom(initial: Record<string, string> = {}): Harness {
+export interface HarnessOptions {
+  /** Synthetic config observation; never claims vault readiness or authority. */
+  initialized?: boolean;
+  /**
+   * Let `reveal` print values to a pipe, as Phantom did before 0.7.3. Real
+   * Phantom Secrets 0.7.9 refuses this, so production Stack can never read a
+   * stored token back. Only provider tests that exercise HTTP logic *after* a
+   * token is read should opt in.
+   */
+  legacyHeadlessReveal?: boolean;
+}
+
+export function setupFakePhantom(
+  initial: Record<string, string> = {},
+  options: HarnessOptions = {},
+): Harness {
   const dir = mkdtempSync(join(tmpdir(), "stack-phantom-"));
   const vaultPath = join(dir, "vault.json");
   const logPath = join(dir, "calls.log");
@@ -42,6 +62,7 @@ export function setupFakePhantom(initial: Record<string, string> = {}): Harness
 set -e
 VAULT=${JSON.stringify(vaultPath)}
 LOG=${JSON.stringify(logPath)}
+LEGACY_HEADLESS_REVEAL=${options.legacyHeadlessReveal ? 1 : 0}
 
 # 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
@@ -51,16 +72,43 @@ case "\${1:-}" in
     echo "phantom fake 0.0.1"
     ;;
   status)
-    echo "ok"
+    if [ "\${2:-}" = "--json" ]; then
+      echo '{"schema_version":1,"initialized":${options.initialized !== false},"inspection":"metadata-only","managed_dotenv":{"inspected":false},"vault":{"inspected":false},"proxy":{"lifecycle_lock":"not-inspected","listener_authenticated":false},"issues":[]}'
+    else
+      echo "ok"
+    fi
     ;;
   add)
+    # Phantom Secrets >= 0.7.3: values only via --stdin, create-only names.
+    if [ "\${3:-}" != "--stdin" ] || [ "$#" -ne 3 ]; then
+      for a in "$@"; do
+        if [ "$a" = "--rotate" ]; then
+          echo "error: unexpected argument '--rotate' found" >&2
+          exit 2
+        fi
+      done
+      echo "Error: Positional secret values are disabled because command-line arguments can be exposed by process inspection. Omit the value for a hidden terminal prompt, or use --stdin." >&2
+      exit 1
+    fi
     python3 -c 'import json,sys
 with open(sys.argv[1]) as f: v = json.load(f)
-v[sys.argv[2]] = sys.argv[3]
+if sys.argv[2] in v:
+    sys.stderr.write("Error: Secret %r is already protected. phantom add creates new names only and refuses replacement before reading a value.\\n" % sys.argv[2])
+    sys.exit(1)
+value = sys.stdin.readline().rstrip("\\r\\n")
+if not value:
+    sys.stderr.write("Error: Received empty value on stdin\\n")
+    sys.exit(1)
+v[sys.argv[2]] = value
 with open(sys.argv[1], "w") as f: json.dump(v, f)
-' "$VAULT" "$2" "$3"
+' "$VAULT" "$2"
     ;;
   remove)
+    # Phantom Secrets >= 0.7.3: typed confirmation in an attached terminal.
+    if [ ! -t 0 ] || [ ! -t 1 ] || [ ! -t 2 ]; then
+      echo "Error: phantom remove requires attached stdin, stdout, and stderr terminals and cannot run headlessly." >&2
+      exit 1
+    fi
     python3 -c 'import json,sys
 with open(sys.argv[1]) as f: v = json.load(f)
 v.pop(sys.argv[2], None)
@@ -68,12 +116,23 @@ with open(sys.argv[1], "w") as f: json.dump(v, f)
 ' "$VAULT" "$2"
     ;;
   list)
+    # Real Phantom: \`list --json\` prints [{"name": ...}, ...] (names only).
     python3 -c 'import json,sys
 with open(sys.argv[1]) as f: v = json.load(f)
-for k in v: print(k)
-' "$VAULT"
+if "--json" in sys.argv[2:]:
+    print(json.dumps([{"name": k, "detected_service": None} for k in v], indent=2))
+else:
+    print("-> %d secret(s) in vault (encrypted-file):\\n" % len(v))
+    for k in v: print("   - " + k)
+    print("\\nnote Values are never displayed. Use phantom add/remove to manage.")
+' "$VAULT" "\${@:2}"
     ;;
   reveal)
+    # Phantom Secrets >= 0.7.3: plaintext only into an attached terminal.
+    if { [ ! -t 0 ] || [ ! -t 2 ]; } && [ "$LEGACY_HEADLESS_REVEAL" != 1 ]; then
+      echo "Error: Refusing to reveal a secret without attached stdin and stderr terminals" >&2
+      exit 1
+    fi
     python3 -c 'import json,sys
 with open(sys.argv[1]) as f: v = json.load(f)
 print(v.get(sys.argv[2], ""))
@@ -109,7 +168,8 @@ esac
     },
     cleanup() {
       process.env.PATH = previousPath;
-      if (previousRegistryDir === undefined) delete process.env.STACK_REGISTRY_DIR;
+      if (previousRegistryDir === undefined)
+        Reflect.deleteProperty(process.env, "STACK_REGISTRY_DIR");
       else process.env.STACK_REGISTRY_DIR = previousRegistryDir;
       __resetPhantomCache();
       try {

package/src/__tests__/agent-onboard.test.ts

@@ -0,0 +1,279 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  applyOnboarding,
+  configPathFor,
+  planOnboarding,
+  undoOnboarding,
+} from "../agent-onboard.ts";
+
+let home: string;
+let emptyBin: string;
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "stack-onboard-"));
+  emptyBin = join(home, "empty-bin");
+  mkdirSync(emptyBin);
+});
+afterEach(() => rmSync(home, { recursive: true, force: true }));
+
+const opts = () => ({ home, pathEnv: emptyBin });
+
+function tree(dir: string): string {
+  const out: string[] = [];
+  const walk = (d: string) => {
+    for (const n of readdirSync(d).sort()) {
+      const f = join(d, n);
+      const st = readdirSyncSafe(f);
+      if (st) walk(f);
+      else out.push(`${f.slice(dir.length)}:${readFileSync(f, "utf-8")}`);
+    }
+  };
+  walk(dir);
+  return out.join("\n");
+}
+function readdirSyncSafe(p: string): boolean {
+  try {
+    readdirSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe("planOnboarding", () => {
+  it("reports every client not-detected on a clean home and writes nothing", () => {
+    const before = tree(home);
+    const plan = planOnboarding(opts());
+    expect(plan.map((p) => [p.client, p.state, p.willWrite])).toEqual([
+      ["claude", "not-detected", false],
+      ["codex", "not-detected", false],
+      ["cursor", "not-detected", false],
+      ["gemini", "not-detected", false],
+    ]);
+    expect(tree(home)).toBe(before);
+  });
+
+  it("detects by config directory and by binary on PATH", () => {
+    mkdirSync(join(home, ".gemini"));
+    writeFileSync(join(emptyBin, "codex"), "#!/bin/sh\n");
+    const plan = planOnboarding(opts());
+    const by = Object.fromEntries(plan.map((p) => [p.client, p]));
+    expect(by.gemini?.detected).toBe(true);
+    expect(by.gemini?.state).toBe("not-wired");
+    expect(by.codex?.detected).toBe(true);
+    expect(by.cursor?.detected).toBe(false);
+  });
+
+  it("classifies wired, differs and error without touching files", () => {
+    mkdirSync(join(home, ".cursor"));
+    mkdirSync(join(home, ".gemini"));
+    writeFileSync(
+      configPathFor("cursor", home),
+      JSON.stringify({ mcpServers: { "ashlr-hub": { command: "ashlr", args: ["mcp"] } } }),
+    );
+    writeFileSync(
+      configPathFor("gemini", home),
+      JSON.stringify({ mcpServers: { "ashlr-hub": { command: "other", args: ["mcp"] } } }),
+    );
+    mkdirSync(join(home, ".codex"));
+    writeFileSync(
+      configPathFor("codex", home),
+      '[mcp_servers.ashlr-hub]\ncommand = "ashlr"\nargs = ["mcp"]\n',
+    );
+    writeFileSync(join(home, ".claude.json"), "{ not json");
+    const by = Object.fromEntries(planOnboarding(opts()).map((p) => [p.client, p]));
+    expect(by.cursor?.state).toBe("wired");
+    expect(by.gemini?.state).toBe("differs");
+    expect(by.gemini?.willWrite).toBe(false);
+    expect(by.codex?.state).toBe("wired");
+    expect(by.claude?.state).toBe("error");
+    expect(by.claude?.willWrite).toBe(false);
+  });
+});
+
+describe("applyOnboarding and undoOnboarding", () => {
+  function seed() {
+    mkdirSync(join(home, ".cursor"));
+    mkdirSync(join(home, ".gemini"));
+    mkdirSync(join(home, ".codex"));
+    mkdirSync(join(home, ".claude"));
+    writeFileSync(
+      configPathFor("cursor", home),
+      `${JSON.stringify({ mcpServers: { other: { command: "x" } } }, null, 4)}\n`,
+    );
+    writeFileSync(
+      configPathFor("codex", home),
+      'model = "x"\n\n[mcp_servers.other]\ncommand = "y"\n',
+    );
+    // gemini settings with unrelated keys; claude has no config file at all
+    writeFileSync(configPathFor("gemini", home), JSON.stringify({ theme: "dark" }));
+  }
+
+  it("takes all detected clients from not wired to wired, then undo restores byte for byte", async () => {
+    seed();
+    const res = await applyOnboarding(opts());
+    expect(res.written.map((w) => w.client).sort()).toEqual([
+      "claude",
+      "codex",
+      "cursor",
+      "gemini",
+    ]);
+    expect(res.verified.every((p) => p.state === "wired")).toBe(true);
+
+    const cursor = JSON.parse(readFileSync(configPathFor("cursor", home), "utf-8"));
+    expect(cursor.mcpServers.other).toEqual({ command: "x" });
+    expect(cursor.mcpServers["ashlr-hub"]).toEqual({ command: "ashlr", args: ["mcp"] });
+    const gemini = JSON.parse(readFileSync(configPathFor("gemini", home), "utf-8"));
+    expect(gemini.theme).toBe("dark");
+    const claude = JSON.parse(readFileSync(join(home, ".claude.json"), "utf-8"));
+    expect(claude.mcpServers["ashlr-hub"]).toEqual({
+      type: "stdio",
+      command: "ashlr",
+      args: ["mcp"],
+      env: {},
+    });
+    const toml = readFileSync(configPathFor("codex", home), "utf-8");
+    expect(toml).toContain('model = "x"');
+    expect(toml).toContain("[mcp_servers.other]");
+    expect(toml).toContain('[mcp_servers.ashlr-hub]\ncommand = "ashlr"\nargs = ["mcp"]');
+
+    // idempotent: a second apply writes nothing
+    const again = await applyOnboarding(opts());
+    expect(again.written).toEqual([]);
+
+    const undo = await undoOnboarding({ home });
+    expect(undo.refused).toEqual([]);
+    expect(undo.restored).toHaveLength(4);
+    // claude config did not exist before, so undo removes it; backups and manifest remain/clean
+    expect(existsSync(join(home, ".claude.json"))).toBe(false);
+    for (const c of ["cursor", "codex", "gemini"] as const) {
+      expect(readFileSync(configPathFor(c, home), "utf-8")).toBe(
+        c === "cursor"
+          ? `${JSON.stringify({ mcpServers: { other: { command: "x" } } }, null, 4)}\n`
+          : c === "codex"
+            ? 'model = "x"\n\n[mcp_servers.other]\ncommand = "y"\n'
+            : JSON.stringify({ theme: "dark" }),
+      );
+    }
+    expect(existsSync(join(home, ".ashlr-stack", "onboard-manifest.json"))).toBe(false);
+  });
+
+  it("never overwrites a differing entry", async () => {
+    mkdirSync(join(home, ".cursor"));
+    const differing = JSON.stringify({
+      mcpServers: { "ashlr-hub": { command: "custom", args: [] } },
+    });
+    writeFileSync(configPathFor("cursor", home), differing);
+    const res = await applyOnboarding({ ...opts(), clients: ["cursor"] });
+    expect(res.written).toEqual([]);
+    expect(readFileSync(configPathFor("cursor", home), "utf-8")).toBe(differing);
+    expect(res.verified[0]?.state).toBe("differs");
+  });
+
+  it("refuses to undo a file that changed after onboarding", async () => {
+    mkdirSync(join(home, ".cursor"));
+    writeFileSync(configPathFor("cursor", home), "{}");
+    await applyOnboarding({ ...opts(), clients: ["cursor"] });
+    const edited = `${readFileSync(configPathFor("cursor", home), "utf-8")}\n`;
+    writeFileSync(configPathFor("cursor", home), edited);
+    const undo = await undoOnboarding({ home });
+    expect(undo.restored).toEqual([]);
+    expect(undo.refused[0]?.reason).toContain("changed");
+    expect(readFileSync(configPathFor("cursor", home), "utf-8")).toBe(edited);
+  });
+
+  it("errors on undo with no manifest", async () => {
+    await expect(undoOnboarding({ home })).rejects.toThrow("nothing to undo");
+  });
+
+  it("skips undetected clients unless includeUndetected is set", async () => {
+    const res = await applyOnboarding({ ...opts(), clients: ["gemini"] });
+    expect(res.written).toEqual([]);
+    expect(existsSync(configPathFor("gemini", home))).toBe(false);
+    const forced = await applyOnboarding({
+      ...opts(),
+      clients: ["gemini"],
+      includeUndetected: true,
+    });
+    expect(forced.written).toHaveLength(1);
+    expect(existsSync(configPathFor("gemini", home))).toBe(true);
+  });
+
+  it("does not put secret-looking values into the gateway entry", async () => {
+    mkdirSync(join(home, ".gemini"));
+    await applyOnboarding({ ...opts(), clients: ["gemini"] });
+    expect(readFileSync(configPathFor("gemini", home), "utf-8")).not.toMatch(/key|token|secret/i);
+  });
+});
+
+it.each(["null", "[]", "42", '{"mcpServers":null}', '{"mcpServers":42}', "{broken"])(
+  "refuses malformed JSON config %s without writing",
+  async (raw) => {
+    const path = configPathFor("claude", home);
+    writeFileSync(path, raw);
+    const result = await applyOnboarding({ ...opts(), clients: ["claude"] });
+    expect(result.written).toEqual([]);
+    expect(result.manifestPath).toBeNull();
+    expect(result.skipped[0]?.state).toBe("error");
+    expect(result.skipped[0]?.error).toBeTruthy();
+    expect(readFileSync(path, "utf-8")).toBe(raw);
+  },
+);
+
+it.each([
+  ["", "not-wired"],
+  ['[mcp_servers.other]\ncommand = "ashlr"', "not-wired"],
+  [
+    '[mcp_servers."ashlr-hub"] # gateway\r\ncommand = "ashlr" # command\r\nargs = ["mcp"]\r\n[other]\r\ncommand = "different"',
+    "wired",
+  ],
+  ['[mcp_servers.ashlr-hub]\ncommand = "ashlr"\nargs = []', "differs"],
+  ['[mcp_servers.ashlr-hub]\nargs = ["mcp"]', "differs"],
+] as const)("inspects TOML %s", (raw, state) => {
+  const path = configPathFor("codex", home);
+  mkdirSync(join(home, ".codex"));
+  writeFileSync(path, raw);
+  expect(planOnboarding({ ...opts(), clients: ["codex"] })[0]?.state).toBe(state);
+  expect(readFileSync(path, "utf-8")).toBe(raw);
+});
+
+it.each(["missing config", "missing backup"])(
+  "undo retains manifest for %s and permits retry",
+  async (mode) => {
+    const path = configPathFor("claude", home);
+    writeFileSync(path, "{}");
+    const applied = await applyOnboarding({
+      ...opts(),
+      clients: ["claude"],
+      includeUndetected: true,
+    });
+    const entry = applied.written[0]!;
+    const target = mode === "missing config" ? path : entry.backupPath!;
+    const original = readFileSync(target, "utf-8");
+    rmSync(target);
+    const result = await undoOnboarding({ home });
+    expect(result.restored).toEqual([]);
+    expect(result.refused).toEqual([
+      {
+        entry,
+        reason:
+          mode === "missing config" ? "config file no longer exists" : "backup file is missing",
+      },
+    ]);
+    expect(JSON.parse(readFileSync(applied.manifestPath!, "utf-8")).entries).toEqual([entry]);
+    writeFileSync(target, original);
+    expect((await undoOnboarding({ home })).restored).toEqual([entry]);
+    expect(readFileSync(path, "utf-8")).toBe("{}");
+    expect(existsSync(applied.manifestPath!)).toBe(false);
+  },
+);

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

@@ -163,7 +163,8 @@ describe("api-key providers — verify + materialize", () => {
   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;
   });
 
@@ -219,7 +220,10 @@ describe("api-key providers — verify + materialize", () => {
     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 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);