@ashlr/stack 0.1.1

package/src/commands/apply.ts

@@ -0,0 +1,244 @@
+import {
+  type Recipe,
+  hasConfig,
+  listRecipes,
+  readConfig,
+  readRecipe,
+  removeSecret,
+  wirePhantomForRecipe,
+  writeConfig,
+} from "@ashlr/stack-core";
+import { removeMcpEntry } from "@ashlr/stack-core/mcp-writer";
+import { defineCommand } from "citty";
+import { colors, intro, outro, outroError, prompts } from "../ui.ts";
+import { addCommand } from "./add.ts";
+import { doctorCommand } from "./doctor.ts";
+import { initCommand } from "./init.ts";
+
+/**
+ * `stack apply [recipe-id]` — replay a frozen Recipe through the add pipeline
+ * and pre-wire Phantom envelopes + webhook stubs so the provider-specific
+ * flows land real credentials into already-rotating slots.
+ *
+ * This is the moat: recommendation → TOML → `apply` → provisioned stack,
+ * with secret rotation wired from the first call.
+ */
+export const applyCommand = defineCommand({
+  meta: {
+    name: "apply",
+    description: "Apply a saved recipe: provision each provider + pre-wire Phantom rotation.",
+  },
+  args: {
+    recipeId: {
+      type: "positional",
+      required: false,
+      description: "Recipe id (filename stem in .stack/recipes). Omit for picker.",
+    },
+    noWire: {
+      type: "boolean",
+      default: false,
+      description: "Skip Phantom envelope + webhook pre-wiring (opts out of the moat).",
+    },
+    noRollback: {
+      type: "boolean",
+      default: false,
+      description:
+        "On partial failure, leave successfully-added services in .stack.toml instead of rolling them back.",
+    },
+  },
+  async run({ args }) {
+    intro(`stack apply${args.noWire ? colors.dim(" (no-wire)") : ""}`);
+
+    // The marketed golden path is `stack recommend --save && stack apply <id>`,
+    // which must work from a blank directory. Auto-init if no .stack.toml so
+    // the user isn't forced through a template picker they never asked for.
+    if (!hasConfig()) {
+      console.log(colors.dim("  ○ no .stack.toml — auto-running `stack init --noInteractive`"));
+      try {
+        await initCommand.run?.({
+          args: { noInteractive: true, force: false, _: [] },
+          cmd: initCommand,
+          rawArgs: ["--noInteractive"],
+          data: undefined,
+        } as unknown as Parameters<NonNullable<typeof initCommand.run>>[0]);
+      } catch (err) {
+        outroError(`Auto-init failed: ${(err as Error).message}`);
+        return;
+      }
+      if (!hasConfig()) {
+        outroError("Auto-init did not produce a .stack.toml. Run `stack init` manually.");
+        return;
+      }
+    }
+
+    const recipe = await pickRecipe(args.recipeId ? String(args.recipeId) : undefined);
+    if (!recipe) return; // pickRecipe already surfaced the error.
+
+    console.log();
+    console.log(`  ${colors.bold("recipe")}   ${recipe.id}`);
+    console.log(`  ${colors.dim("query")}    ${recipe.query}`);
+    console.log(`  ${colors.dim("providers")} ${recipe.providers.map((p) => p.name).join(", ")}`);
+    console.log();
+
+    // Re-run addCommand for each provider. We intentionally do NOT parallelize:
+    // some providers (e.g. Vercel) need cwd state written by earlier steps
+    // and interactive prompts don't interleave cleanly.
+    const succeeded: string[] = [];
+    const failures: Array<{ name: string; message: string }> = [];
+    for (const { name } of recipe.providers) {
+      try {
+        console.log(colors.dim(`  › stack add ${name}`));
+        // citty's CommandContext type requires every declared arg key; we
+        // only set the ones addCommand actually reads, so cast via unknown.
+        await addCommand.run?.({
+          args: { service: name, dryRun: false, _: [] },
+          cmd: addCommand,
+          rawArgs: [name],
+          data: undefined,
+        } as unknown as Parameters<NonNullable<typeof addCommand.run>>[0]);
+        succeeded.push(name);
+      } catch (err) {
+        failures.push({ name, message: (err as Error).message });
+      }
+    }
+
+    // On partial failure, offer to roll back the successful adds so re-running
+    // `stack apply` isn't blocked by SERVICE_ALREADY_ADDED errors. Default to
+    // rolling back in non-TTY mode (CI-friendly) unless --noRollback is set.
+    if (failures.length > 0 && succeeded.length > 0 && !args.noRollback) {
+      const shouldRollback = process.stdout.isTTY
+        ? await prompts.confirm({
+            message: `Recipe partially applied (${succeeded.length} succeeded, ${failures.length} failed). Roll back the successful adds so you can re-run cleanly?`,
+            initialValue: true,
+          })
+        : true;
+      if (shouldRollback && !prompts.isCancel(shouldRollback)) {
+        await rollbackServices(succeeded);
+      } else {
+        console.log(
+          colors.dim(
+            "  Keeping partial state. Run `stack doctor --fix` or `stack remove <name>` to clean up.",
+          ),
+        );
+      }
+    }
+
+    // Phantom-wire only runs when at least one provider made it through — no
+    // point creating rotation envelopes for services that aren't in the config.
+    if (succeeded.length > 0) {
+      try {
+        const wire = await wirePhantomForRecipe(recipe, { noWire: Boolean(args.noWire) });
+        if (!args.noWire) {
+          console.log();
+          console.log(
+            `  ${colors.dim("envelopes")} ${wire.envelopes.length} · ${colors.dim("webhooks")} ${wire.webhooks.length}${
+              wire.skipped.length > 0 ? ` · ${colors.yellow(`skipped ${wire.skipped.length}`)}` : ""
+            }`,
+          );
+          if (wire.skipped.length > 0) {
+            console.log(colors.dim(`  (phantom-wire skipped: ${wire.skipped.join(", ")})`));
+          }
+        }
+      } catch (err) {
+        console.log(colors.yellow(`  ⚠ phantom-wire failed: ${(err as Error).message}`));
+      }
+    }
+
+    // Verify with doctor — informational; a failing doctor doesn't fail apply.
+    try {
+      console.log();
+      console.log(colors.dim("  › stack doctor"));
+      await doctorCommand.run?.({
+        args: { fix: false, all: false, json: false, _: [] },
+        cmd: doctorCommand,
+        rawArgs: [],
+        data: undefined,
+      } as unknown as Parameters<NonNullable<typeof doctorCommand.run>>[0]);
+    } catch {
+      /* doctor surfaces its own errors */
+    }
+
+    if (failures.length > 0) {
+      outroError(
+        `Some providers failed: ${failures.map((f) => `${f.name}: ${f.message}`).join("; ")}`,
+      );
+      return;
+    }
+    outro(`${colors.green("✓")} ${recipe.id} applied.`);
+  },
+});
+
+/**
+ * Undo a partial apply. Reads the config, deletes each named service's secrets
+ * + MCP entry, and rewrites the config without them. Best-effort: a failure
+ * removing one service should not block the others.
+ */
+async function rollbackServices(names: string[]): Promise<void> {
+  if (names.length === 0) return;
+  console.log();
+  console.log(colors.dim(`  rolling back ${names.length} partial add(s)…`));
+  try {
+    const config = await readConfig();
+    for (const name of names) {
+      const entry = config.services[name];
+      if (!entry) continue;
+      for (const secret of entry.secrets) {
+        try {
+          await removeSecret(secret);
+        } catch {
+          /* secret may already be gone; keep going */
+        }
+      }
+      if (entry.mcp) {
+        try {
+          await removeMcpEntry(entry.mcp);
+        } catch {
+          /* keep going */
+        }
+      }
+      delete config.services[name];
+    }
+    await writeConfig(config);
+    console.log(colors.dim("  rollback complete — re-run `stack apply` to retry."));
+  } catch (err) {
+    console.log(colors.yellow(`  ⚠ rollback failed: ${(err as Error).message}`));
+  }
+}
+
+async function pickRecipe(id?: string): Promise<Recipe | null> {
+  if (id) {
+    try {
+      return await readRecipe(id);
+    } catch (err) {
+      outroError((err as Error).message);
+      return null;
+    }
+  }
+
+  const all = await listRecipes();
+  if (all.length === 0) {
+    outroError(
+      "No recipes in .stack/recipes. Run `stack recommend` first, or ask Claude to synthesize one.",
+    );
+    return null;
+  }
+
+  if (!process.stdout.isTTY) {
+    outroError(`No recipe id given. Available: ${all.map((r) => r.id).join(", ")}.`);
+    return null;
+  }
+
+  const picked = await prompts.select({
+    message: "Which recipe to apply?",
+    options: all.map((r) => ({
+      value: r.id,
+      label: `${colors.bold(r.id)} ${colors.dim(`· ${r.providers.length} providers`)}`,
+      hint: r.query.slice(0, 60),
+    })),
+  });
+  if (prompts.isCancel(picked)) {
+    outroError("Cancelled.");
+    return null;
+  }
+  return all.find((r) => r.id === String(picked)) ?? null;
+}

package/src/commands/ci.ts

@@ -0,0 +1,110 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { defineCommand } from "citty";
+import { hasConfig } from "@ashlr/stack-core";
+import { colors, intro, outro, outroError } from "../ui.ts";
+
+const DEFAULT_WORKFLOW = `name: Stack doctor
+
+# Runs \`stack doctor --json --all\` in CI. Requires two repository secrets:
+#
+#   PHANTOM_VAULT_PASSPHRASE  — passphrase for the encrypted-file vault fallback
+#                                (Phantom uses this in CI where keychain isn't available).
+#   PHANTOM_CLOUD_TOKEN       — GitHub OAuth device token for \`phantom cloud pull\`.
+#
+# Both are created once with \`phantom login\` + \`phantom cloud push\` locally, then
+# copied into GitHub \`Settings → Secrets and variables → Actions\`.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    # Nightly drift check — catches when an upstream key gets revoked out of band.
+    - cron: "0 7 * * *"
+  workflow_dispatch:
+
+jobs:
+  doctor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Phantom Secrets
+        run: npm install -g phantom-secrets
+
+      - name: Install Stack CLI
+        run: npm install -g @ashlr/stack
+
+      - name: Pull vault from Phantom Cloud
+        env:
+          PHANTOM_CLOUD_TOKEN: \${{ secrets.PHANTOM_CLOUD_TOKEN }}
+          PHANTOM_VAULT_PASSPHRASE: \${{ secrets.PHANTOM_VAULT_PASSPHRASE }}
+        run: phantom cloud pull --force
+
+      - name: Run stack doctor
+        run: stack doctor --json > stack-doctor.json
+
+      - name: Upload doctor report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: stack-doctor-report
+          path: stack-doctor.json
+`;
+
+/**
+ * `stack ci init` — scaffold a ready-to-commit GitHub Actions workflow that
+ * runs `stack doctor --json` on every push + nightly, backed by Phantom Cloud
+ * for secret pull. The YAML is opinionated but gives a correct-by-default
+ * starting point; users tweak from there.
+ */
+export const ciCommand = defineCommand({
+  meta: {
+    name: "ci",
+    description: "Scaffold CI integrations that run `stack doctor` on pushes + nightly.",
+  },
+  subCommands: {
+    init: defineCommand({
+      meta: {
+        name: "init",
+        description: "Write .github/workflows/stack-ci.yml for GitHub Actions.",
+      },
+      args: {
+        force: {
+          type: "boolean",
+          default: false,
+          description: "Overwrite an existing stack-ci.yml.",
+        },
+      },
+      async run({ args }) {
+        intro("stack ci init");
+        if (!hasConfig()) {
+          outroError("No .stack.toml found. Run `stack init` first.");
+          return;
+        }
+        const cwd = process.cwd();
+        const dir = resolve(join(cwd, ".github", "workflows"));
+        if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+        const path = join(dir, "stack-ci.yml");
+        if (existsSync(path) && !args.force) {
+          outroError(`${path} already exists. Pass --force to overwrite.`);
+          return;
+        }
+        await writeFile(path, DEFAULT_WORKFLOW, "utf-8");
+        console.log();
+        console.log(`  ${colors.green("●")} wrote ${colors.bold(".github/workflows/stack-ci.yml")}`);
+        console.log();
+        console.log(colors.dim("  Next steps:"));
+        console.log(colors.dim("    1. Add PHANTOM_VAULT_PASSPHRASE + PHANTOM_CLOUD_TOKEN to repo secrets."));
+        console.log(colors.dim("    2. Commit the workflow."));
+        console.log(
+          colors.dim("    3. Watch the first run in Actions — downloads the doctor report as an artifact."),
+        );
+        console.log();
+        outro(colors.green("CI workflow scaffolded."));
+      },
+    }),
+  },
+});

package/src/commands/clone.ts

@@ -0,0 +1,113 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { defineCommand } from "citty";
+import { hasConfig, scanSource } from "@ashlr/stack-core";
+import { colors, intro, outro, outroError } from "../ui.ts";
+
+/**
+ * `stack clone <git-url> [dir]` — git clone the repo, then run `stack scan` in
+ * the new checkout and surface next-step guidance. Treats committed
+ * .stack.toml as authoritative when it exists.
+ */
+export const cloneCommand = defineCommand({
+  meta: {
+    name: "clone",
+    description: "Clone a GitHub repo and auto-detect its Stack services.",
+  },
+  args: {
+    url: { type: "positional", required: true, description: "GitHub / git URL to clone." },
+    dir: { type: "positional", required: false, description: "Optional target directory." },
+  },
+  async run({ args }) {
+    intro(`stack clone ${args.url}`);
+    const url = String(args.url);
+
+    if (!isAllowedGitUrl(url)) {
+      outroError(
+        "Only https:// and git@ URLs are allowed (no file://, no --option prefixes, no local paths).",
+      );
+      return;
+    }
+
+    const target = args.dir ? String(args.dir) : inferDirFromUrl(url);
+    if (target.startsWith("-") || target.includes("..")) {
+      outroError(`Refusing to clone into suspicious target path "${target}".`);
+      return;
+    }
+
+    if (existsSync(target)) {
+      outroError(`Target directory "${target}" already exists.`);
+      return;
+    }
+
+    // `--` separates options from positional args so a crafted URL can't be
+    // parsed as a git flag (e.g. --upload-pack=<cmd>).
+    const result = spawnSync("git", ["clone", "--", url, target], { stdio: "inherit" });
+    if (result.status !== 0) {
+      outroError("git clone failed.");
+      return;
+    }
+
+    const resolved = resolve(target);
+    console.log();
+
+    const committed = hasConfig(resolved);
+    if (committed) {
+      console.log(
+        `  ${colors.green("●")} committed ${colors.bold(".stack.toml")} found — this repo is Stack-aware.`,
+      );
+      console.log(colors.dim("  Next steps:"));
+      console.log(colors.dim(`    cd ${target}`));
+      console.log(colors.dim(`    stack doctor --fix     # verify, re-login for anything missing`));
+      console.log(colors.dim(`    stack exec -- bun dev  # run with Phantom's proxy active`));
+    } else {
+      const hits = await scanSource(resolved);
+      const highConfidence = hits.filter((h) => h.confidence === "high");
+      if (hits.length === 0) {
+        console.log(colors.dim("  No providers detected. You can still `cd in` and run `stack init`."));
+      } else {
+        console.log(
+          `  ${colors.bold(String(hits.length))} provider(s) detected in source (${highConfidence.length} high-confidence):`,
+        );
+        for (const h of hits) {
+          const dot =
+            h.confidence === "high"
+              ? colors.green("●")
+              : h.confidence === "medium"
+                ? colors.yellow("●")
+                : colors.dim("●");
+          console.log(`    ${dot} ${h.provider.padEnd(12)} ${colors.dim(h.signals[0] ?? "")}`);
+        }
+        console.log(colors.dim("\n  Next steps:"));
+        console.log(colors.dim(`    cd ${target}`));
+        console.log(colors.dim(`    stack scan --auto     # offer to wire up each provider`));
+      }
+    }
+
+    outro(colors.green(`Cloned to ${target}.`));
+  },
+});
+
+function inferDirFromUrl(url: string): string {
+  // Handle https://github.com/org/repo(.git), git@github.com:org/repo.git, etc.
+  const trimmed = url.replace(/\.git$/i, "").replace(/\/$/, "");
+  return basename(trimmed);
+}
+
+/**
+ * Accept https://, http:// (for self-hosted), and git@host:org/repo SSH URLs
+ * only. Reject file://, ext::, --option-prefixed strings, empty strings, and
+ * anything else that could cause git to do something other than clone a
+ * remote repo.
+ */
+function isAllowedGitUrl(url: string): boolean {
+  if (!url || url.length > 2048) return false;
+  if (url.startsWith("-")) return false;
+  if (/^file:/i.test(url)) return false;
+  if (/^ext::/i.test(url)) return false;
+  if (/^(https?:\/\/)/i.test(url)) return true;
+  if (/^git@[\w.-]+:[\w./~-]+$/i.test(url)) return true;
+  if (/^ssh:\/\//i.test(url)) return true;
+  return false;
+}

package/src/commands/completion.ts

@@ -0,0 +1,187 @@
+import { defineCommand } from "citty";
+import { listProviderNames, listTemplates } from "@ashlr/stack-core";
+
+/**
+ * `stack completion <shell>` — emit a shell completion script. Runtime-static
+ * (we bake the command list + the currently-installed provider / template
+ * names when it runs). Users re-run this after adding a new shell.
+ *
+ *   stack completion bash > /etc/bash_completion.d/stack
+ *   stack completion zsh > ~/.local/share/zsh/site-functions/_stack
+ *   stack completion fish > ~/.config/fish/completions/stack.fish
+ */
+export const completionCommand = defineCommand({
+  meta: {
+    name: "completion",
+    description: "Emit shell completion for bash, zsh, or fish.",
+  },
+  args: {
+    shell: {
+      type: "positional",
+      required: true,
+      description: "One of: bash, zsh, fish.",
+    },
+  },
+  async run({ args }) {
+    const shell = String(args.shell).toLowerCase();
+    const commands = [
+      "init",
+      "import",
+      "scan",
+      "clone",
+      "add",
+      "remove",
+      "list",
+      "info",
+      "status",
+      "env",
+      "deps",
+      "doctor",
+      "exec",
+      "sync",
+      "open",
+      "login",
+      "templates",
+      "providers",
+      "projects",
+      "upgrade",
+      "completion",
+      "ci",
+    ];
+    const providers = listProviderNames();
+    const templates = listTemplates();
+
+    if (shell === "bash") process.stdout.write(emitBash(commands, providers, templates));
+    else if (shell === "zsh") process.stdout.write(emitZsh(commands, providers, templates));
+    else if (shell === "fish") process.stdout.write(emitFish(commands, providers, templates));
+    else {
+      process.stderr.write(`Unsupported shell: ${shell}. Use bash, zsh, or fish.\n`);
+      process.exit(1);
+    }
+  },
+});
+
+function emitBash(commands: string[], providers: string[], templates: string[]): string {
+  return `# stack completion — bash
+_stack_completion() {
+  local cur prev words cword
+  _init_completion || return
+
+  if [[ \${cword} -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "${commands.join(" ")}" -- "\${cur}") )
+    return
+  fi
+
+  case "\${words[1]}" in
+    add|remove|info|login|open)
+      COMPREPLY=( $(compgen -W "${providers.join(" ")}" -- "\${cur}") )
+      ;;
+    templates)
+      if [[ \${cword} -eq 2 ]]; then
+        COMPREPLY=( $(compgen -W "list apply" -- "\${cur}") )
+      elif [[ "\${words[2]}" == "apply" ]]; then
+        COMPREPLY=( $(compgen -W "${templates.join(" ")}" -- "\${cur}") )
+      fi
+      ;;
+    sync)
+      COMPREPLY=( $(compgen -W "--platform vercel railway fly" -- "\${cur}") )
+      ;;
+    env)
+      COMPREPLY=( $(compgen -W "show diff set unset" -- "\${cur}") )
+      ;;
+    projects)
+      COMPREPLY=( $(compgen -W "list register remove where" -- "\${cur}") )
+      ;;
+    completion)
+      COMPREPLY=( $(compgen -W "bash zsh fish" -- "\${cur}") )
+      ;;
+  esac
+}
+complete -F _stack_completion stack
+`;
+}
+
+function emitZsh(commands: string[], providers: string[], templates: string[]): string {
+  return `#compdef stack
+# stack completion — zsh
+
+_stack() {
+  local state
+  _arguments -C \\
+    '1: :->command' \\
+    '*:: :->args'
+
+  case \$state in
+    command)
+      _values 'stack command' ${commands.map((c) => `"${c}"`).join(" ")}
+      ;;
+    args)
+      case \$words[1] in
+        add|remove|info|login|open)
+          _values 'provider' ${providers.map((p) => `"${p}"`).join(" ")}
+          ;;
+        templates)
+          if [[ $CURRENT -eq 2 ]]; then
+            _values 'subcommand' 'list' 'apply'
+          elif [[ $words[2] == "apply" ]]; then
+            _values 'template' ${templates.map((t) => `"${t}"`).join(" ")}
+          fi
+          ;;
+        env)
+          _values 'subcommand' 'show' 'diff' 'set' 'unset'
+          ;;
+        projects)
+          _values 'subcommand' 'list' 'register' 'remove' 'where'
+          ;;
+        completion)
+          _values 'shell' 'bash' 'zsh' 'fish'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_stack
+`;
+}
+
+function emitFish(commands: string[], providers: string[], templates: string[]): string {
+  const lines: string[] = [
+    "# stack completion — fish",
+    "complete -c stack -f",
+    "",
+  ];
+  for (const c of commands) {
+    lines.push(
+      `complete -c stack -n "__fish_use_subcommand" -a "${c}" -d "stack subcommand"`,
+    );
+  }
+  for (const verb of ["add", "remove", "info", "login", "open"]) {
+    for (const p of providers) {
+      lines.push(
+        `complete -c stack -n "__fish_seen_subcommand_from ${verb}" -a "${p}" -d "provider"`,
+      );
+    }
+  }
+  for (const sub of ["list", "apply"]) {
+    lines.push(
+      `complete -c stack -n "__fish_seen_subcommand_from templates" -a "${sub}" -d "template action"`,
+    );
+  }
+  for (const t of templates) {
+    lines.push(
+      `complete -c stack -n "__fish_seen_subcommand_from apply" -a "${t}" -d "starter template"`,
+    );
+  }
+  for (const sub of ["show", "diff", "set", "unset"]) {
+    lines.push(
+      `complete -c stack -n "__fish_seen_subcommand_from env" -a "${sub}" -d "env subcommand"`,
+    );
+  }
+  for (const sh of ["bash", "zsh", "fish"]) {
+    lines.push(
+      `complete -c stack -n "__fish_seen_subcommand_from completion" -a "${sh}" -d "shell"`,
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}