@ashlr/stack-core 0.1.1 → 0.3.0

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];
+  }
+}

package/src/providers/_api-key.ts

@@ -1,7 +1,5 @@
 import type { ServiceEntry } from "../config.ts";
 import { StackError } from "../errors.ts";
-import { addSecret } from "../phantom.ts";
-import { readLine, tryRevealSecret } from "./_helpers.ts";
 import type {
   AuthHandle,
   HealthStatus,
@@ -12,6 +10,8 @@ import type {
   ProviderContext,
   Resource,
 } from "./_base.ts";
+import { acceptVerifiedExisting, storeProviderSecret } from "./_credential-stage.ts";
+import { promptSecret, tryRevealSecret } from "./_helpers.ts";
 
 /**
  * Factory for API-key-paste providers (OpenAI, Anthropic, xAI, DeepSeek, Resend,
@@ -54,10 +54,13 @@ export function makeApiKeyProvider(spec: ApiKeyProviderSpec): Provider {
     docs: spec.docs,
 
     async login(ctx: ProviderContext): Promise<AuthHandle> {
-      const cached = await tryRevealSecret(spec.secretName);
+      const cached = await tryRevealSecret(spec.secretName, ctx);
       if (cached) {
         const identity = await spec.verify(cached);
-        if (identity) return { token: cached, identity };
+        if (identity) {
+          acceptVerifiedExisting(ctx, spec.secretName, cached);
+          return { token: cached, identity };
+        }
         ctx.log({ level: "warn", msg: `Cached ${spec.displayName} key invalid; re-entering.` });
       }
       if (!ctx.interactive) {
@@ -66,20 +69,20 @@ export function makeApiKeyProvider(spec: ApiKeyProviderSpec): Provider {
           `${spec.displayName}: no valid key in vault and session is non-interactive.`,
         );
       }
-      process.stderr.write(`\n  ${spec.howTo}\n  Paste your ${spec.displayName} API key: `);
-      const key = (await readLine()).trim();
-      if (!key) throw new StackError(`${spec.name.toUpperCase()}_AUTH_REQUIRED`, "No key provided.");
+      const key = await promptSecret(ctx, {
+        message: `Paste your ${spec.displayName} API key`,
+        howTo: spec.howTo,
+      });
+      if (!key)
+        throw new StackError(`${spec.name.toUpperCase()}_AUTH_REQUIRED`, "No key provided.");
       const identity = await spec.verify(key);
       if (!identity)
         throw new StackError(
           `${spec.name.toUpperCase()}_AUTH_INVALID`,
           `${spec.displayName} rejected that key.`,
         );
-      // Persist the verified key immediately. Previously we deferred to
-      // `materialize()`, so if any step after `login()` threw (e.g. a
-      // provision-side API error) the user would have to re-paste their key.
-      // Matches the hand-written providers (supabase, neon, vercel, github, sentry).
-      await addSecret(spec.secretName, key);
+      // Explicit login writes now; addService owns deferred credential inputs.
+      await storeProviderSecret(ctx, spec.secretName, key);
       return { token: key, identity };
     },
 
@@ -95,8 +98,8 @@ export function makeApiKeyProvider(spec: ApiKeyProviderSpec): Provider {
       };
     },
 
-    async materialize(_ctx, _resource, auth): Promise<Materialized> {
-      await addSecret(spec.secretName, auth.token);
+    async materialize(ctx, _resource, auth): Promise<Materialized> {
+      await storeProviderSecret(ctx, spec.secretName, auth.token);
       return {
         secrets: { [spec.secretName]: auth.token },
         ...(spec.mcp ? { mcp: spec.mcp } : {}),
@@ -105,7 +108,7 @@ export function makeApiKeyProvider(spec: ApiKeyProviderSpec): Provider {
 
     async healthcheck(ctx, entry) {
       if (spec.healthcheck) return spec.healthcheck(ctx, entry);
-      const key = await tryRevealSecret(spec.secretName);
+      const key = await tryRevealSecret(spec.secretName, ctx);
       if (!key) return { kind: "error", detail: `${spec.secretName} missing from vault` };
       const start = Date.now();
       const identity = await spec.verify(key);
@@ -118,5 +121,3 @@ export function makeApiKeyProvider(spec: ApiKeyProviderSpec): Provider {
     },
   };
 }
-
-

package/src/providers/_base.ts

@@ -5,6 +5,7 @@ export type ProviderCategory =
   | "deploy"
   | "cloud"
   | "analytics"
+  | "observability"
   | "errors"
   | "ai"
   | "payments"
@@ -12,6 +13,7 @@ export type ProviderCategory =
   | "tickets"
   | "email"
   | "auth"
+  | "featureflags"
   | "comms";
 
 export type AuthKind = "oauth_pkce" | "oauth_device" | "pat" | "api_key" | "cli_shell";
@@ -22,6 +24,24 @@ export interface ProviderContext {
   interactive: boolean;
   /** Structured logger — callers wire this to the CLI's @clack spinner. */
   log: (event: LogEvent) => void;
+  /**
+   * Host-owned interactive prompt for credential entry. The CLI wires this to
+   * its @clack prompt and pauses any active spinner around it (mirrors `log`).
+   * Providers MUST route PAT/key paste through this rather than writing to
+   * stderr directly — a stderr prompt is clobbered by a running spinner, which
+   * makes `stack add` appear to hang. When absent (tests, non-CLI hosts),
+   * `promptSecret` falls back to a bare stdin read.
+   */
+  prompt?: (req: PromptRequest) => Promise<string>;
+}
+
+export interface PromptRequest {
+  /** One-line ask, e.g. "Paste your Supabase access token". */
+  message: string;
+  /** Optional guidance shown above the input (a URL, required scopes). */
+  howTo?: string;
+  /** Mask the input. Defaults to true — these are always secrets. */
+  secret?: boolean;
 }
 
 export interface LogEvent {
@@ -92,5 +112,12 @@ export interface Provider {
 
   healthcheck?(ctx: ProviderContext, entry: ServiceEntry): Promise<HealthStatus>;
   dashboardUrl?(entry: ServiceEntry): string;
-  deprovision?(ctx: ProviderContext, entry: ServiceEntry, auth: AuthHandle): Promise<void>;
+
+  /**
+   * Tear down an upstream resource created by `provision`. Used by `addService`
+   * to roll back on partial failure. Optional — if the provider doesn't
+   * implement it, the dangling resource is logged and the user is directed to
+   * `stack doctor --fix`.
+   */
+  deprovision?(ctx: ProviderContext, auth: AuthHandle, resourceId: string): Promise<void>;
 }