@ashlr/stack 0.1.1

package/src/commands/deps.ts

@@ -0,0 +1,79 @@
+import { defineCommand } from "citty";
+import { getProvider, readConfig } from "@ashlr/stack-core";
+import { colors, intro, outro } from "../ui.ts";
+
+/**
+ * `stack deps` — render an ASCII dependency graph of the services Stack has
+ * wired up for the current project, grouped by category and annotated with
+ * their secret slots. Good for onboarding a new developer ("here's what the
+ * stack looks like") and for sanity-checking templates.
+ */
+export const depsCommand = defineCommand({
+  meta: {
+    name: "deps",
+    description: "Show the service dependency graph for this stack.",
+  },
+  async run() {
+    intro("stack deps");
+    const config = await readConfig();
+    const services = Object.entries(config.services);
+    if (services.length === 0) {
+      outro(colors.dim("No services yet."));
+      return;
+    }
+
+    // Group by category.
+    const byCategory: Record<string, Array<{ name: string; displayName: string; secrets: string[]; mcp?: string }>> = {};
+    for (const [name, entry] of services) {
+      try {
+        const p = await getProvider(entry.provider);
+        (byCategory[p.category] ??= []).push({
+          name,
+          displayName: p.displayName,
+          secrets: entry.secrets,
+          mcp: entry.mcp,
+        });
+      } catch {
+        /* skip */
+      }
+    }
+
+    console.log();
+    console.log(`  ${colors.bold(config.stack.project_id)}`);
+    if (config.stack.template) {
+      console.log(`  ${colors.dim("template:")} ${config.stack.template}`);
+    }
+    console.log();
+
+    const categories = Object.keys(byCategory).sort();
+    for (let i = 0; i < categories.length; i += 1) {
+      const cat = categories[i];
+      const isLast = i === categories.length - 1;
+      const branch = isLast ? "└──" : "├──";
+      const cont = isLast ? "   " : "│  ";
+      console.log(`  ${branch} ${colors.bold(cat)}`);
+      const items = byCategory[cat];
+      for (let j = 0; j < items.length; j += 1) {
+        const item = items[j];
+        const subLast = j === items.length - 1;
+        const subBranch = subLast ? "└──" : "├──";
+        const subCont = subLast ? "   " : "│  ";
+        const mcpTag = item.mcp ? colors.cyan(` mcp:${item.mcp}`) : "";
+        console.log(`  ${cont} ${subBranch} ${colors.green("●")} ${item.displayName}${mcpTag}`);
+        for (const secret of item.secrets) {
+          console.log(`  ${cont} ${subCont} ${colors.dim("·")} ${colors.dim(secret)}`);
+        }
+      }
+      if (!isLast) console.log(`  │`);
+    }
+    console.log();
+
+    const totalSecrets = services.reduce((acc, [, e]) => acc + e.secrets.length, 0);
+    const totalMcps = services.filter(([, e]) => e.mcp).length;
+    outro(
+      colors.dim(
+        `${services.length} services · ${totalSecrets} secrets · ${totalMcps} MCP server(s)`,
+      ),
+    );
+  },
+});

package/src/commands/doctor.ts

@@ -0,0 +1,192 @@
+import { defineCommand } from "citty";
+import {
+  type ProviderContext,
+  addService,
+  getProvider,
+  isPhantomInstalled,
+  listProjects,
+  readConfig,
+} from "@ashlr/stack-core";
+import { colors, intro, logEvent, outro, outroError, prompts } from "../ui.ts";
+
+interface DoctorReport {
+  project: string;
+  path: string;
+  services: Array<{
+    name: string;
+    status: "ok" | "warn" | "error" | "unchecked";
+    detail?: string;
+    latencyMs?: number;
+  }>;
+}
+
+export const doctorCommand = defineCommand({
+  meta: {
+    name: "doctor",
+    description: "Verify every service is reachable and credentials are valid.",
+  },
+  args: {
+    fix: {
+      type: "boolean",
+      default: false,
+      description: "Attempt to auto-remediate by re-running `stack add` for failing services.",
+    },
+    all: {
+      type: "boolean",
+      default: false,
+      description: "Run doctor across every registered project on this machine.",
+    },
+    json: {
+      type: "boolean",
+      default: false,
+      description: "Emit machine-readable JSON (exit 0/1 on pass/fail). CI-friendly.",
+    },
+  },
+  async run({ args }) {
+    const json = Boolean(args.json);
+    if (!json) intro("stack doctor");
+
+    if (!(await isPhantomInstalled())) {
+      const msg = "Phantom is not installed. Stack cannot verify secrets without it.";
+      if (json) {
+        process.stdout.write(`${JSON.stringify({ error: msg })}\n`);
+        process.exitCode = 1;
+        return;
+      }
+      outroError(msg);
+      return;
+    }
+
+    const scope: Array<{ path: string; name: string }> = args.all
+      ? (await listProjects()).map((p) => ({ path: p.path, name: p.name }))
+      : [{ path: process.cwd(), name: "cwd" }];
+
+    if (scope.length === 0) {
+      if (json) {
+        process.stdout.write(`${JSON.stringify({ reports: [] })}\n`);
+        return;
+      }
+      outro(colors.dim("No registered projects yet."));
+      return;
+    }
+
+    const reports: DoctorReport[] = [];
+    let anyFailed = false;
+    for (const project of scope) {
+      if (!json && args.all) {
+        console.log(`\n${colors.bold(project.name)} ${colors.dim(project.path)}`);
+      }
+      const report = await runDoctor(project.path, project.name, Boolean(args.fix), json);
+      reports.push(report);
+      if (report.services.some((s) => s.status === "error")) anyFailed = true;
+    }
+
+    if (json) {
+      process.stdout.write(`${JSON.stringify({ reports }, null, 2)}\n`);
+      process.exitCode = anyFailed ? 1 : 0;
+      return;
+    }
+
+    if (anyFailed)
+      outroError("One or more services failed. Re-run with --fix to attempt remediation.");
+    else outro(colors.green("All services healthy."));
+  },
+});
+
+async function runDoctor(
+  cwd: string,
+  projectName: string,
+  fix: boolean,
+  json: boolean,
+): Promise<DoctorReport> {
+  const report: DoctorReport = { project: projectName, path: cwd, services: [] };
+  const config = await readConfig(cwd).catch(() => undefined);
+  if (!config) {
+    if (!json) console.log(colors.dim("  (no .stack.toml)"));
+    return report;
+  }
+  const services = Object.entries(config.services);
+  if (services.length === 0) {
+    if (!json) console.log(colors.dim("  (no services configured)"));
+    return report;
+  }
+
+  const ctx: ProviderContext = {
+    cwd,
+    interactive: !json && process.stdout.isTTY === true,
+    log: json ? () => {} : logEvent,
+  };
+
+  const failingNames: string[] = [];
+  for (const [name, entry] of services) {
+    const spinner = json ? undefined : prompts.spinner();
+    spinner?.start(`Checking ${name}…`);
+    try {
+      const provider = await getProvider(name);
+      if (!provider.healthcheck) {
+        report.services.push({ name, status: "unchecked" });
+        spinner?.stop(colors.dim(`  ${name}: no healthcheck implemented`));
+        continue;
+      }
+      const status = await provider.healthcheck(ctx, entry);
+      if (status.kind === "ok") {
+        report.services.push({ name, status: "ok", latencyMs: status.latencyMs });
+        spinner?.stop(
+          `  ${colors.green("●")} ${name}${status.latencyMs ? colors.dim(` (${status.latencyMs}ms)`) : ""}`,
+        );
+      } else if (status.kind === "warn") {
+        report.services.push({ name, status: "warn", detail: status.detail });
+        spinner?.stop(`  ${colors.yellow("●")} ${name}: ${status.detail}`);
+      } else {
+        failingNames.push(name);
+        report.services.push({ name, status: "error", detail: status.detail });
+        spinner?.stop(`  ${colors.red("●")} ${name}: ${status.detail}`);
+      }
+    } catch (err) {
+      failingNames.push(name);
+      report.services.push({ name, status: "error", detail: (err as Error).message });
+      spinner?.stop(`  ${colors.red("●")} ${name}: ${(err as Error).message}`);
+    }
+  }
+
+  if (fix && failingNames.length > 0 && !json) {
+    console.log();
+    prompts.log.info(colors.bold("  Attempting remediation…"));
+    for (const name of failingNames) {
+      const entry = config.services[name];
+      // Confirm before re-running, because `addService` may trigger a browser
+      // OAuth flow or provision new upstream resources. Doing that silently
+      // during a routine `doctor --fix` surprises users.
+      const confirmed = process.stdout.isTTY
+        ? await prompts.confirm({
+            message: `Re-run setup for ${name}? (may open browser / create new resource)`,
+            initialValue: true,
+          })
+        : true;
+      if (!confirmed || prompts.isCancel(confirmed)) {
+        console.log(`  ${colors.dim("·")} ${name}: skipped`);
+        continue;
+      }
+      const spinner = prompts.spinner();
+      spinner.start(`  Re-running ${name}…`);
+      try {
+        await addService({
+          providerName: name,
+          cwd,
+          existingResourceId: entry.resource_id,
+          interactive: process.stdout.isTTY === true,
+          log: (event) => {
+            spinner.stop();
+            logEvent(event);
+            spinner.start(`  Re-running ${name}…`);
+          },
+        });
+        spinner.stop(`  ${colors.green("●")} ${name} re-wired.`);
+      } catch (err) {
+        spinner.stop(`  ${colors.red("●")} ${name}: ${(err as Error).message}`);
+      }
+    }
+  }
+
+  return report;
+}

package/src/commands/env.ts

@@ -0,0 +1,87 @@
+import { defineCommand } from "citty";
+import {
+  isPhantomInstalled,
+  listSecrets,
+  readConfig,
+} from "@ashlr/stack-core";
+import { colors, intro, outro, outroError } from "../ui.ts";
+
+/**
+ * `stack env show [--env prod]` — pretty-print the effective env-var surface
+ * for this stack. For each secret the project declares, show whether it's
+ * present in the Phantom vault (masked) or missing. Designed for debugging
+ * "why does my app boot without Supabase?" kinds of questions.
+ */
+export const envCommand = defineCommand({
+  meta: {
+    name: "env",
+    description: "Inspect the effective env-var map for this stack.",
+  },
+  subCommands: {
+    show: defineCommand({
+      meta: { name: "show", description: "Show which secrets are present in Phantom." },
+      args: {
+        env: { type: "string", default: "dev", description: "Environment overlay to preview." },
+      },
+      async run({ args }) {
+        intro(`stack env show (${args.env})`);
+        const phantomOk = await isPhantomInstalled();
+        if (!phantomOk) {
+          outroError("Phantom not installed.");
+          return;
+        }
+        const config = await readConfig();
+        const vaultKeys = new Set(await listSecrets());
+        console.log();
+        for (const [name, entry] of Object.entries(config.services)) {
+          console.log(`  ${colors.bold(name)}`);
+          for (const slot of entry.secrets) {
+            const present = vaultKeys.has(slot);
+            const dot = present ? colors.green("●") : colors.red("○");
+            const value = present ? colors.dim("(phm_…)") : colors.red("missing");
+            console.log(`    ${dot} ${slot.padEnd(30)} ${value}`);
+          }
+        }
+        const declared = new Set(
+          Object.values(config.services).flatMap((e) => e.secrets),
+        );
+        const orphans = [...vaultKeys].filter((k) => !declared.has(k)).sort();
+        if (orphans.length > 0) {
+          console.log();
+          console.log(colors.dim(`  orphans in vault (not referenced by any service):`));
+          for (const k of orphans) console.log(`    ${colors.yellow("●")} ${k}`);
+        }
+        console.log();
+        outro(
+          colors.dim(
+            `${declared.size} declared · ${vaultKeys.size} in vault · ${orphans.length} orphan(s)`,
+          ),
+        );
+      },
+    }),
+    diff: defineCommand({
+      meta: { name: "diff", description: "Which declared secrets are missing from the vault?" },
+      async run() {
+        intro("stack env diff");
+        if (!(await isPhantomInstalled())) {
+          outroError("Phantom not installed.");
+          return;
+        }
+        const config = await readConfig();
+        const vaultKeys = new Set(await listSecrets());
+        const missing: string[] = [];
+        for (const entry of Object.values(config.services)) {
+          for (const slot of entry.secrets) {
+            if (!vaultKeys.has(slot)) missing.push(slot);
+          }
+        }
+        if (missing.length === 0) {
+          outro(colors.green("All declared secrets present."));
+          return;
+        }
+        for (const s of missing) console.log(`  ${colors.red("○")} ${s}`);
+        outroError(`${missing.length} secret(s) missing from the vault.`);
+      },
+    }),
+  },
+});

package/src/commands/exec.ts

@@ -0,0 +1,54 @@
+import { spawn } from "node:child_process";
+import { defineCommand } from "citty";
+import { assertPhantomInstalled, hasConfig } from "@ashlr/stack-core";
+import { colors, intro, outroError } from "../ui.ts";
+
+/**
+ * `stack exec -- <cmd>` — run a command with Phantom's proxy active so env
+ * vars with `phm_` tokens get swapped for real secrets at the network layer.
+ * Thin wrapper over `phantom exec` so users don't have to context-switch
+ * between Stack and Phantom for day-to-day work.
+ */
+export const execCommand = defineCommand({
+  meta: {
+    name: "exec",
+    description: "Run a command with Phantom's secret proxy active.",
+  },
+  args: {
+    _: { type: "positional", required: false, description: "Command to run after --" },
+  },
+  async run({ rawArgs }) {
+    intro("stack exec");
+
+    if (!hasConfig()) {
+      outroError("No .stack.toml found. Run `stack init` first.");
+      return;
+    }
+
+    try {
+      await assertPhantomInstalled();
+    } catch (err) {
+      outroError((err as Error).message);
+      return;
+    }
+
+    // Forward everything after `--` (or everything after `exec`) to `phantom exec`.
+    const sep = rawArgs.indexOf("--");
+    const forwarded = sep >= 0 ? rawArgs.slice(sep + 1) : rawArgs;
+    if (forwarded.length === 0) {
+      outroError("Nothing to run. Usage: stack exec -- <command>");
+      return;
+    }
+
+    const child = spawn("phantom", ["exec", "--", ...forwarded], { stdio: "inherit" });
+    child.on("close", (code) => {
+      if (code !== 0) {
+        process.stderr.write(colors.dim(`\n[stack exec] phantom exec exited ${code}\n`));
+      }
+      process.exitCode = code ?? 0;
+    });
+    child.on("error", (err) => {
+      outroError((err as Error).message);
+    });
+  },
+});

package/src/commands/import.ts

@@ -0,0 +1,120 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { defineCommand } from "citty";
+import {
+  addSecret,
+  assertPhantomInstalled,
+  emptyConfig,
+  groupByProvider,
+  hasConfig,
+  listProviderNames,
+  parseEnv,
+  readConfig,
+  toServiceEntry,
+  writeConfig,
+} from "@ashlr/stack-core";
+import { colors, intro, outro, outroError, prompts } from "../ui.ts";
+
+/**
+ * `stack import [--from .env]` — inhale an existing .env, route each secret
+ * into Phantom, and populate .stack.toml with a best-guess service map.
+ *
+ * This is the most important migration command: most users arrive at Stack
+ * with projects that already have filled-in .env files. They shouldn't have
+ * to re-paste 20 keys to try the product.
+ */
+export const importCommand = defineCommand({
+  meta: {
+    name: "import",
+    description: "Import an existing .env into Phantom + .stack.toml.",
+  },
+  args: {
+    from: { type: "string", default: ".env", description: "Path to the .env file to import." },
+    dryRun: {
+      type: "boolean",
+      default: false,
+      description: "Print what would happen without writing anything.",
+    },
+  },
+  async run({ args }) {
+    intro("stack import");
+
+    const envPath = join(process.cwd(), String(args.from));
+    if (!existsSync(envPath)) {
+      outroError(`${envPath} not found.`);
+      return;
+    }
+
+    try {
+      await assertPhantomInstalled();
+    } catch (err) {
+      if (!args.dryRun) {
+        outroError((err as Error).message);
+        return;
+      }
+      prompts.log.warn(colors.yellow("Phantom not installed — dry-run mode will still preview."));
+    }
+
+    const raw = await readFile(envPath, "utf-8");
+    const entries = parseEnv(raw);
+    if (entries.length === 0) {
+      outro(colors.dim(`${args.from}: nothing to import.`));
+      return;
+    }
+
+    const grouped = groupByProvider(entries.map((e) => e.key));
+    const registered = new Set(listProviderNames());
+    const detectedProviders = Object.keys(grouped).filter((p) => registered.has(p));
+    const detectedSecretCount = detectedProviders.reduce(
+      (acc, p) => acc + grouped[p].length,
+      0,
+    );
+    const orphanSecrets = entries
+      .map((e) => e.key)
+      .filter((name) => !detectedProviders.some((p) => grouped[p].includes(name)));
+
+    console.log();
+    console.log(
+      `  ${colors.bold(String(entries.length))} env vars · ${colors.bold(String(detectedProviders.length))} providers detected · ${colors.bold(String(orphanSecrets.length))} unattributed`,
+    );
+    for (const provider of detectedProviders) {
+      console.log(
+        `  ${colors.green("●")} ${provider.padEnd(14)} ${colors.dim(grouped[provider].join(", "))}`,
+      );
+    }
+    if (orphanSecrets.length > 0) {
+      console.log(
+        `  ${colors.dim("·")} ${"(orphans)".padEnd(14)} ${colors.dim(orphanSecrets.join(", "))}`,
+      );
+    }
+    console.log();
+
+    if (args.dryRun) {
+      outro(colors.dim("dry-run: nothing written."));
+      return;
+    }
+
+    // 1. Store every secret in Phantom (provider-matched + orphans alike).
+    let stored = 0;
+    for (const { key, value } of entries) {
+      if (value.length === 0) continue;
+      await addSecret(key, value);
+      stored += 1;
+    }
+
+    // 2. Update .stack.toml — create one if missing, then populate service entries.
+    const config = hasConfig() ? await readConfig() : emptyConfig();
+    for (const provider of detectedProviders) {
+      if (config.services[provider]) continue; // don't clobber pre-existing entries
+      config.services[provider] = toServiceEntry(provider, grouped[provider]);
+    }
+    await writeConfig(config);
+
+    outro(
+      colors.green(
+        `Imported ${stored} secret(s); wired ${detectedProviders.length} service(s) in .stack.toml. Run \`stack doctor\` to verify.`,
+      ),
+    );
+  },
+});

package/src/commands/info.ts

@@ -0,0 +1,85 @@
+import { defineCommand } from "citty";
+import {
+  type ProviderContext,
+  getProvider,
+  isPhantomInstalled,
+  listSecrets,
+  readConfig,
+} from "@ashlr/stack-core";
+import { colors, intro, logEvent, outro, outroError, prompts } from "../ui.ts";
+
+/**
+ * `stack info <service>` — deep-dive on a configured service. Prints its
+ * provider, resource id, region, secret slots (with vault presence), MCP
+ * wiring, dashboard URL, and runs a fresh healthcheck.
+ */
+export const infoCommand = defineCommand({
+  meta: {
+    name: "info",
+    description: "Show everything Stack knows about a configured service.",
+  },
+  args: {
+    service: { type: "positional", required: true, description: "Service name." },
+  },
+  async run({ args }) {
+    intro(`stack info ${args.service}`);
+    const config = await readConfig();
+    const entry = config.services[String(args.service)];
+    if (!entry) {
+      outroError(`${args.service} is not in this stack. Run \`stack list\`.`);
+      return;
+    }
+
+    const provider = await getProvider(entry.provider);
+    const vaultKeys = (await isPhantomInstalled()) ? new Set(await listSecrets()) : new Set();
+
+    console.log();
+    console.log(`  ${colors.bold(provider.displayName)}  ${colors.dim(provider.category)}`);
+    console.log(`    ${colors.dim("resource:")} ${entry.resource_id ?? "(not provisioned)"}`);
+    if (entry.region) console.log(`    ${colors.dim("region:")}   ${entry.region}`);
+    console.log(`    ${colors.dim("auth:")}     ${provider.authKind}`);
+    console.log(`    ${colors.dim("created:")}  ${entry.created_at}${entry.created_by ? colors.dim(` by ${entry.created_by}`) : ""}`);
+    if (provider.docs) console.log(`    ${colors.dim("docs:")}     ${provider.docs}`);
+    const dashboard = provider.dashboardUrl?.(entry);
+    if (dashboard) console.log(`    ${colors.dim("dash:")}     ${dashboard}`);
+    if (entry.mcp) console.log(`    ${colors.dim("mcp:")}      ${entry.mcp}`);
+    if (entry.meta && Object.keys(entry.meta).length > 0) {
+      console.log(`    ${colors.dim("meta:")}     ${JSON.stringify(entry.meta)}`);
+    }
+    console.log();
+
+    console.log(`  ${colors.bold("secrets")}`);
+    for (const slot of entry.secrets) {
+      const present = vaultKeys.has(slot);
+      const dot = present ? colors.green("●") : colors.red("○");
+      const tag = present ? colors.dim("in vault") : colors.red("missing");
+      console.log(`    ${dot} ${slot.padEnd(30)} ${tag}`);
+    }
+    console.log();
+
+    if (provider.healthcheck) {
+      const ctx: ProviderContext = {
+        cwd: process.cwd(),
+        interactive: false,
+        log: logEvent,
+      };
+      const spinner = prompts.spinner();
+      spinner.start("Running healthcheck…");
+      try {
+        const status = await provider.healthcheck(ctx, entry);
+        if (status.kind === "ok") {
+          spinner.stop(
+            `${colors.green("●")} healthy${status.latencyMs ? colors.dim(` (${status.latencyMs}ms)`) : ""}`,
+          );
+        } else if (status.kind === "warn") {
+          spinner.stop(`${colors.yellow("●")} warning: ${status.detail}`);
+        } else {
+          spinner.stop(`${colors.red("●")} error: ${status.detail}`);
+        }
+      } catch (err) {
+        spinner.stop(`${colors.red("●")} healthcheck threw: ${(err as Error).message}`);
+      }
+    }
+    outro("");
+  },
+});