@ashlr/stack-core 0.1.1 → 0.2.2

package/src/phantom.ts

@@ -11,6 +11,16 @@ export interface PhantomExecResult {
   stdout: string;
   stderr: string;
   code: number;
+  signal?: NodeJS.Signals;
+  completion?: "exited" | "signal" | "unknown";
+}
+
+/** Interpret close fields only; this does not attest provider or vault state. */
+export function completionForClose(
+  code: number | null,
+  signal: NodeJS.Signals | null,
+): NonNullable<PhantomExecResult["completion"]> {
+  return signal ? "signal" : code === null ? "unknown" : "exited";
 }
 
 let cachedInstalled: boolean | undefined;
@@ -19,7 +29,7 @@ export async function isPhantomInstalled(): Promise<boolean> {
   if (cachedInstalled !== undefined) return cachedInstalled;
   try {
     const result = await exec(["--version"], { allowFailure: true });
-    cachedInstalled = result.code === 0;
+    cachedInstalled = result.code === 0 && result.completion === "exited";
   } catch {
     cachedInstalled = false;
   }
@@ -56,6 +66,9 @@ export async function exec(args: string[], opts: ExecOptions = {}): Promise<Phan
         stderr += chunk.toString();
       });
       if (opts.stdin !== undefined) {
+        // Phantom may refuse (e.g. an existing name) and exit before reading
+        // stdin; the exit code reports that, so a broken pipe is not fatal.
+        child.stdin?.on("error", () => {});
         child.stdin?.write(opts.stdin);
         child.stdin?.end();
       }
@@ -69,13 +82,22 @@ export async function exec(args: string[], opts: ExecOptions = {}): Promise<Phan
       reject(err);
     });
 
-    child.on("close", (code) => {
-      const result: PhantomExecResult = { stdout, stderr, code: code ?? 0 };
-      if (code !== 0 && !opts.allowFailure) {
+    child.on("close", (code, signal) => {
+      // A signal/unknown exit is not evidence that a vault mutation committed.
+      const result: PhantomExecResult = {
+        stdout,
+        stderr,
+        code: signal ? code || 1 : (code ?? 1),
+        completion: completionForClose(code, signal),
+        ...(signal ? { signal } : {}),
+      };
+      if (result.code !== 0 && !opts.allowFailure) {
         reject(
           new StackError(
             "PHANTOM_EXEC_FAILED",
-            `phantom ${formatArgsForError(args)} failed (exit ${code}): ${stderr.trim() || stdout.trim()}`,
+            result.completion === "exited"
+              ? `phantom ${formatArgsForError(args)} failed (exit ${result.code}): ${stderr.trim() || stdout.trim()}`
+              : `phantom ${formatArgsForError(args)} did not complete (${result.completion}); result unconfirmed`,
           ),
         );
         return;
@@ -85,29 +107,185 @@ export async function exec(args: string[], opts: ExecOptions = {}): Promise<Phan
   });
 }
 
+/**
+ * Store a NEW secret. The value goes over stdin (`phantom add KEY --stdin`):
+ * Phantom Secrets >= 0.7.3 rejects a positional value because argv is visible
+ * to process inspection. Phantom never replaces an existing name, so a
+ * every completed collision surfaces as `PHANTOM_SECRET_EXISTS`. Historical
+ * input equality is never evidence that the current vault still has that value.
+ */
 export async function addSecret(key: string, value: string, cwd?: string): Promise<void> {
+  // Phantom 0.7.9 reads one stdin line and strips CR/LF. Refuse values it
+  // cannot preserve before any subprocess, rather than silently truncating.
+  if (/[\r\n]/.test(value)) {
+    throw new StackError(
+      "PHANTOM_SECRET_VALUE_UNSUPPORTED",
+      "Phantom Secrets accepts one line per secret; CR/LF values cannot be stored unchanged.",
+    );
+  }
   await assertPhantomInstalled();
-  await exec(["add", key, value], { cwd });
+  const result = await exec(["add", key, "--stdin"], { cwd, stdin: value, allowFailure: true });
+  // Collision wording from an interrupted child cannot attest a completed
+  // create-only refusal.
+  if (result.completion !== "exited") {
+    throw new StackError(
+      "PHANTOM_EXEC_FAILED",
+      "Phantom add did not complete; secret storage is unconfirmed.",
+    );
+  }
+  if (result.code === 0) {
+    return;
+  }
+  const detail = result.stderr.trim() || result.stdout.trim();
+  if (/already protected|already exists/i.test(detail)) {
+    throw new StackError(
+      "PHANTOM_SECRET_EXISTS",
+      `${key} is already stored in Phantom, and Phantom never replaces a stored secret. Run \`phantom remove ${key}\` in your terminal, then retry.`,
+    );
+  }
+  throw new StackError(
+    "PHANTOM_EXEC_FAILED",
+    `phantom add ${key} --stdin failed (exit ${result.code}): ${detail}`,
+  );
 }
 
-export async function removeSecret(key: string, cwd?: string): Promise<void> {
+/**
+ * Remove a secret. Phantom Secrets requires a typed confirmation in an
+ * attached terminal for `remove`, so headless callers (rollback, CI, agents)
+ * cannot remove anything. Pass `interactive: true` only from a human-driven
+ * CLI command with a TTY; Phantom then runs its own confirmation prompt.
+ * Returns true only when Phantom reports the secret removed.
+ */
+export async function removeSecret(
+  key: string,
+  cwd?: string,
+  opts: { interactive?: boolean } = {},
+): Promise<boolean> {
   await assertPhantomInstalled();
-  await exec(["remove", key], { cwd, allowFailure: true });
+  const result = await exec(["remove", key], {
+    cwd,
+    allowFailure: true,
+    interactive: opts.interactive === true,
+  });
+  const removed = result.code === 0 && result.completion === "exited";
+  return removed;
 }
 
+/**
+ * Secret names in the vault, from `phantom list --json` (never values). The
+ * human `phantom list` output is a decorated table and is not parsed.
+ */
 export async function listSecrets(cwd?: string): Promise<string[]> {
   await assertPhantomInstalled();
-  const { stdout } = await exec(["list"], { cwd, allowFailure: true });
-  return stdout
-    .split("\n")
-    .map((line) => line.trim())
-    .filter((line) => line.length > 0 && !line.startsWith("#"));
+  const { stdout, code } = await exec(["list", "--json"], { cwd, allowFailure: true });
+  if (code !== 0) {
+    throw new StackError(
+      "PHANTOM_METADATA_UNAVAILABLE",
+      "Phantom secret inventory is unavailable; stored names are unknown.",
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    throw new StackError(
+      "PHANTOM_OUTPUT_UNRECOGNIZED",
+      "phantom list --json did not return JSON; upgrade Phantom Secrets to 0.7.9 or newer.",
+    );
+  }
+  if (!Array.isArray(parsed)) {
+    throw new StackError(
+      "PHANTOM_OUTPUT_UNRECOGNIZED",
+      "phantom list --json did not return an array.",
+    );
+  }
+  const names: string[] = [];
+  for (const entry of parsed) {
+    if (
+      !entry ||
+      typeof entry !== "object" ||
+      Array.isArray(entry) ||
+      !("name" in entry) ||
+      typeof entry.name !== "string" ||
+      entry.name.length === 0
+    ) {
+      throw new StackError(
+        "PHANTOM_OUTPUT_UNRECOGNIZED",
+        "phantom list --json contains unrecognized secret-name metadata.",
+      );
+    }
+    names.push(entry.name);
+  }
+  return names;
+}
+
+/**
+ * Number of secrets in the vault, from `phantom list --json`. Null when the
+ * inventory cannot be read (Phantom missing, no .phantom.toml, unrecognized
+ * output), so callers never report an unreadable vault as empty.
+ */
+export async function countSecrets(cwd?: string): Promise<number | null> {
+  try {
+    if (!(await isPhantomInstalled())) return null;
+    return (await listSecrets(cwd)).length;
+  } catch {
+    return null;
+  }
 }
 
+/** Configuration observation only: no vault access, initialization or grants. */
+export async function assertProjectInitialized(cwd?: string): Promise<void> {
+  await assertPhantomInstalled();
+  const result = await exec(["status", "--json"], { cwd, allowFailure: true });
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch {
+    parsed = undefined;
+  }
+  if (
+    result.code !== 0 ||
+    !parsed ||
+    typeof parsed !== "object" ||
+    Array.isArray(parsed) ||
+    !("schema_version" in parsed) ||
+    parsed.schema_version !== 1 ||
+    !("inspection" in parsed) ||
+    parsed.inspection !== "metadata-only" ||
+    !("initialized" in parsed) ||
+    typeof parsed.initialized !== "boolean"
+  ) {
+    throw new StackError(
+      "PHANTOM_METADATA_UNAVAILABLE",
+      "Phantom project initialization is unknown. Use Phantom Secrets 0.7.9 or newer and check its metadata status before retrying.",
+    );
+  }
+  if (!parsed.initialized) {
+    throw new StackError(
+      "PHANTOM_PROJECT_NOT_INITIALIZED",
+      "Phantom project is not initialized or its configuration is unreadable. Review `phantom status --json`; for a new project run `phantom init --empty` in a trusted terminal, then retry.",
+    );
+  }
+}
+
+/**
+ * Read a secret value. Phantom Secrets >= 0.7.3 only reveals into an attached
+ * terminal after a typed confirmation, so from Stack (piped stdio) this fails
+ * with `PHANTOM_TRUSTED_TERMINAL_REQUIRED`. Callers must treat a stored value
+ * as unreadable and fall back to prompting.
+ */
 export async function revealSecret(key: string, cwd?: string): Promise<string> {
   await assertPhantomInstalled();
-  const { stdout } = await exec(["reveal", key], { cwd });
-  return stdout.trim();
+  const result = await exec(["reveal", key], { cwd, allowFailure: true });
+  if (result.code === 0) return result.stdout.trim();
+  const detail = result.stderr.trim();
+  if (/terminal/i.test(detail)) {
+    throw new StackError(
+      "PHANTOM_TRUSTED_TERMINAL_REQUIRED",
+      `Phantom only reveals ${key} in an attached terminal after typed confirmation; Stack cannot read it.`,
+    );
+  }
+  throw new StackError("PHANTOM_EXEC_FAILED", `phantom reveal ${key} failed (exit ${result.code})`);
 }
 
 export async function ensureInitialized(cwd?: string): Promise<void> {

package/src/pipeline.ts

@@ -1,14 +1,18 @@
-import {
-  type ServiceEntry,
-  type StackConfig,
-  readConfig,
-  writeConfig,
-} from "./config.ts";
+import { resolve } from "node:path";
+import { type ServiceEntry, type StackConfig, readConfig, writeConfig } from "./config.ts";
 import { StackError } from "./errors.ts";
-import { addSecret, assertPhantomInstalled } from "./phantom.ts";
-import { mergeMcpEntry } from "./mcp-writer.ts";
+import { mergeMcpEntry, removeMcpEntry } from "./mcp-writer.ts";
+import { assertPhantomInstalled, assertProjectInitialized, removeSecret } from "./phantom.ts";
+import type { LogEvent, PromptRequest, ProviderContext } from "./providers/_base.ts";
+import {
+  beginCredentialStage,
+  closeCredentialStage,
+  commitOrdinaryCredential,
+  commitResourceCredentials,
+  credentialPhase,
+  ordinaryCredentialPlan,
+} from "./providers/_credential-stage.ts";
 import { getProvider } from "./providers/index.ts";
-import type { LogEvent, ProviderContext } from "./providers/_base.ts";
 
 export interface AddServiceOpts {
   providerName: string;
@@ -17,6 +21,8 @@ export interface AddServiceOpts {
   existingResourceId?: string;
   hints?: Record<string, unknown>;
   log?: (event: LogEvent) => void;
+  /** Host-owned credential prompt. The CLI pauses its spinner around this. */
+  prompt?: (req: PromptRequest) => Promise<string>;
   /** If false, skip persisting to .stack.toml (used by dry-run / preview). */
   persist?: boolean;
 }
@@ -36,96 +42,199 @@ export interface AddServiceResult {
  * `stack templates apply` so behaviour stays in lockstep.
  */
 export async function addService(opts: AddServiceOpts): Promise<AddServiceResult> {
+  // Attachment never grants rollback authority to delete an upstream resource.
+  // Capture the request before awaits so a caller cannot change that custody.
+  const existingResourceId = opts.existingResourceId;
+  const cwd = resolve(opts.cwd ?? process.cwd());
   await assertPhantomInstalled();
   const provider = await getProvider(opts.providerName);
-  const cwd = opts.cwd ?? process.cwd();
   const config: StackConfig = await readConfig(cwd);
 
   // Attaching to an existing resource id is always allowed — that's the path
   // `stack doctor --fix` uses to re-run the pipeline for a degraded service.
-  if (config.services[provider.name] && !opts.existingResourceId) {
+  if (config.services[provider.name] && !existingResourceId) {
     throw new StackError(
       "SERVICE_ALREADY_ADDED",
       `${provider.displayName} is already in this stack. Pass existingResourceId to re-attach, or remove it first.`,
     );
   }
 
+  // Refuse unreadable/uninitialized project metadata before login, credential
+  // verification or provisioning. This observation does not authorize a vault.
+  await assertProjectInitialized(cwd);
+
   const ctx: ProviderContext = {
     cwd,
     interactive: opts.interactive ?? process.stdout.isTTY === true,
     log: opts.log ?? (() => {}),
+    prompt: opts.prompt,
   };
 
-  const auth = await provider.login(ctx);
-  const resource = await provider.provision(ctx, auth, {
-    existingResourceId: opts.existingResourceId,
-    hints: opts.hints,
-  });
-
-  // Provision succeeded: from here on, any failure leaves a dangling upstream
-  // resource. Wrap the rest of the pipeline so we can persist a minimal
-  // breadcrumb entry to .stack.toml before re-throwing. This is what lets
-  // `stack doctor --fix` (or `stack remove`) clean up later — without the
-  // breadcrumb, the user has a live resource on the provider side with no
-  // local record at all.
+  beginCredentialStage(ctx);
   try {
-    const materialized = await provider.materialize(ctx, resource, auth);
+    const auth = await provider.login(ctx).catch((err: unknown) => {
+      throw headlessAuthError(err, provider, ctx.interactive);
+    });
+    credentialPhase(ctx, "provision");
+    const resource = await provider.provision(ctx, auth, {
+      existingResourceId,
+      hints: opts.hints,
+    });
 
-    for (const [key, value] of Object.entries(materialized.secrets)) {
-      await addSecret(key, value, cwd);
-    }
-    if (materialized.mcp) await mergeMcpEntry(materialized.mcp, cwd);
+    // Provision returned: track local writes for best-effort failure cleanup.
+    // Track what has been written so the catch block can undo exactly that.
+    const writtenSecrets: string[] = [];
+    const criticalSecrets = new Set<string>();
+    let writtenMcp: string | undefined;
+    let failStep = "resource credential write";
 
-    const entry: ServiceEntry = {
-      provider: provider.name,
-      resource_id: resource.id,
-      region: resource.region,
-      secrets: Object.keys(materialized.secrets),
-      mcp: materialized.mcp?.name,
-      meta: resource.meta,
-      created_at: new Date().toISOString(),
-      created_by: "stack add",
-    };
+    try {
+      credentialPhase(ctx, "critical");
+      await commitResourceCredentials(ctx, resource, (key) => {
+        writtenSecrets.push(key);
+        criticalSecrets.add(key);
+      });
+      failStep = "materialize";
+      credentialPhase(ctx, "materialize");
+      const materialized = await provider.materialize(ctx, resource, auth);
+      const plan = ordinaryCredentialPlan(ctx, materialized.secrets);
+      credentialPhase(ctx, "commit");
+      failStep = "secret write";
 
-    if (opts.persist !== false) {
-      config.services[provider.name] = entry;
-      await writeConfig(config, cwd);
-    }
+      for (const [key, value] of plan) {
+        await commitOrdinaryCredential(ctx, key, value);
+        writtenSecrets.push(key);
+      }
+      failStep = "MCP write";
+      if (materialized.mcp) {
+        await mergeMcpEntry(materialized.mcp, cwd);
+        writtenMcp = materialized.mcp.name;
+      }
 
-    return {
-      providerName: provider.name,
-      resourceId: resource.id,
-      displayName: resource.displayName,
-      secretCount: Object.keys(materialized.secrets).length,
-      mcpWired: Boolean(materialized.mcp),
-      entry,
-    };
-  } catch (err) {
-    // Partial-failure breadcrumb: write just enough to .stack.toml that a
-    // later `stack doctor --fix` or `stack remove` can find the dangling
-    // upstream resource. We intentionally leave `secrets: []` — materialize
-    // didn't run to completion, so we don't know which vault keys (if any)
-    // were populated. Same goes for `mcp`: we don't know what the MCP entry
-    // would have been, so we don't claim to have wired one.
-    if (opts.persist !== false) {
-      const partial: ServiceEntry = {
+      const entry: ServiceEntry = {
         provider: provider.name,
         resource_id: resource.id,
         region: resource.region,
-        secrets: [],
+        secrets: Object.keys(materialized.secrets),
+        mcp: materialized.mcp?.name,
         meta: resource.meta,
         created_at: new Date().toISOString(),
-        created_by: "stack add (partial)",
+        created_by: "stack add",
       };
-      try {
-        config.services[provider.name] = partial;
+
+      failStep = "config write";
+      if (opts.persist !== false) {
+        config.services[provider.name] = entry;
         await writeConfig(config, cwd);
-      } catch {
-        // If even writing the breadcrumb fails, swallow — the original
-        // error below is the user-visible signal; we don't want to mask it
-        // with a disk-write failure.
       }
+
+      return {
+        providerName: provider.name,
+        resourceId: resource.id,
+        displayName: resource.displayName,
+        secretCount: Object.keys(materialized.secrets).length,
+        mcpWired: Boolean(materialized.mcp),
+        entry,
+      };
+    } catch (err) {
+      // --- Best-effort rollback ---
+      // 1. Remove any Phantom secrets already written. Phantom only removes in
+      //    an attached terminal, so headless rollback usually keeps them; name
+      //    them in the error so the next attempt does not collide unexplained.
+      const keptSecrets: string[] = [];
+      let keptCriticalCount = 0;
+      for (const key of writtenSecrets) {
+        let removed = false;
+        try {
+          removed = await removeSecret(key, cwd);
+        } catch {
+          /* best-effort */
+        }
+        if (!removed) {
+          if (criticalSecrets.has(key)) keptCriticalCount++;
+          else keptSecrets.push(key);
+        }
+      }
+      const keptNote =
+        (keptSecrets.length > 0
+          ? ` Phantom kept ${keptSecrets.join(", ")}; run \`phantom remove <NAME>\` in a terminal for each before retrying.`
+          : "") +
+        (keptCriticalCount > 0
+          ? ` Phantom kept ${keptCriticalCount} resource credential(s); manual vault reconciliation is required before retrying.`
+          : "");
+      // 2. Remove the MCP entry if it was written.
+      if (writtenMcp) {
+        try {
+          await removeMcpEntry(writtenMcp, cwd);
+        } catch {
+          /* best-effort */
+        }
+      }
+      // 3. Tear down the upstream resource (if provider supports it).
+      if (existingResourceId) {
+        throw new StackError(
+          "ADD_SERVICE_PARTIAL_FAILURE",
+          `Reattaching ${provider.displayName} failed at step "${failStep}". The requested existing upstream resource was preserved; no automatic upstream teardown was attempted. Original error: ${(err as Error).message}${keptNote}`,
+        );
+      }
+      if (provider.deprovision) {
+        // If deprovision itself throws, we still want to surface the original
+        // failure AND note that teardown was incomplete — otherwise the caller
+        // has no idea whether the upstream resource is still live.
+        let teardownErr: Error | undefined;
+        try {
+          await provider.deprovision(ctx, auth, resource.id);
+        } catch (derr) {
+          teardownErr = derr as Error;
+        }
+        const teardownNote = teardownErr
+          ? `Attempted automatic teardown but it FAILED (${teardownErr.message}) — resource ${resource.id} may still exist. Clean it up manually on the ${provider.displayName} dashboard.`
+          : `Upstream resource ${resource.id} has been torn down.`;
+        throw new StackError(
+          teardownErr ? "ADD_SERVICE_PARTIAL_FAILURE" : "ADD_SERVICE_ROLLED_BACK",
+          `${teardownErr ? "Adding" : "Rolled back"} ${provider.displayName} after failure at step "${failStep}". ` +
+            `${teardownNote} ` +
+            `Original error: ${(err as Error).message}${keptNote}`,
+        );
+      }
+      // No deprovision support — warn and direct to manual cleanup.
+      ctx.log({
+        level: "warn",
+        msg: `[stack] Partial failure adding ${provider.displayName}. Upstream resource ID: ${resource.id}. This provider does not support automatic teardown — please delete it manually, then run \`stack doctor --fix\` to resync local state.`,
+        data: { provider: provider.name, resourceId: resource.id },
+      });
+      throw new StackError(
+        "ADD_SERVICE_PARTIAL_FAILURE",
+        `Adding ${provider.displayName} failed at step "${failStep}" after the upstream resource was created. ` +
+          `Resource ID: ${resource.id}. ` +
+          `Clean it up manually on the ${provider.displayName} dashboard, then run \`stack doctor --fix\`.${keptNote}`,
+      );
+      // .stack.toml is intentionally NOT written — the add was not atomic.
     }
-    throw err;
+  } finally {
+    closeCredentialStage(ctx);
+  }
+}
+
+/**
+ * A provider that needs a pasted key or a browser sign-in cannot get one in
+ * a session without a terminal (an agent's MCP call, CI), and Phantom will
+ * not hand a stored key back to one either. Say so and name the command a
+ * person can run, instead of only "no valid key".
+ */
+export function headlessAuthError(
+  err: unknown,
+  provider: { name: string; displayName: string },
+  interactive: boolean,
+  command: "add" | "login" = "add",
+): unknown {
+  if (interactive || !(err instanceof StackError) || !err.code.endsWith("_AUTH_REQUIRED")) {
+    return err;
   }
+  const outcome = command === "add" ? "nothing was added" : "no credential was changed";
+  return new StackError(
+    err.code,
+    `${err.message} ${provider.displayName} needs a credential entered in an interactive terminal, and this session has none (agent or CI). Ask the user to run \`stack ${command} ${provider.name}\` in their own terminal, then retry; ${outcome}.`,
+    { cause: err },
+  );
 }

package/src/pm-detect.ts

@@ -0,0 +1,56 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export type PackageManager = "bun" | "pnpm" | "npm" | "yarn";
+
+/**
+ * Detect the PM used in a project by inspecting lockfiles. Walks up from
+ * `cwd` (default: process.cwd()) to find the nearest project root (dir
+ * containing package.json). Falls back to "npm" if nothing is found.
+ *
+ * Lockfile precedence:
+ *   bun.lock > bun.lockb > pnpm-lock.yaml > yarn.lock > package-lock.json
+ */
+export async function detectPackageManager(cwd?: string): Promise<PackageManager> {
+  const start = cwd ?? process.cwd();
+
+  // Walk up directory tree until we find a package.json or hit root.
+  let dir = start;
+  while (true) {
+    if (existsSync(join(dir, "bun.lock"))) return "bun";
+    if (existsSync(join(dir, "bun.lockb"))) return "bun";
+    if (existsSync(join(dir, "pnpm-lock.yaml"))) return "pnpm";
+    if (existsSync(join(dir, "yarn.lock"))) return "yarn";
+    if (existsSync(join(dir, "package-lock.json"))) return "npm";
+
+    // Stop walking if we found a package.json (this is the project root).
+    if (existsSync(join(dir, "package.json"))) break;
+
+    const parent = dirname(dir);
+    // Hit filesystem root — give up.
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return "npm";
+}
+
+/**
+ * The install command argv for a given PM + packages. Examples:
+ *   bun:  ["bun", "add", "@supabase/supabase-js"]
+ *   pnpm: ["pnpm", "add", "@supabase/supabase-js"]
+ *   npm:  ["npm", "install", "@supabase/supabase-js"]
+ *   yarn: ["yarn", "add", "@supabase/supabase-js"]
+ */
+export function installCommand(pm: PackageManager, packages: string[]): string[] {
+  switch (pm) {
+    case "bun":
+      return ["bun", "add", ...packages];
+    case "pnpm":
+      return ["pnpm", "add", ...packages];
+    case "yarn":
+      return ["yarn", "add", ...packages];
+    case "npm":
+      return ["npm", "install", ...packages];
+  }
+}