@ashlr/stack 0.1.1

package/src/commands/init.ts

@@ -0,0 +1,93 @@
+import { defineCommand } from "citty";
+import {
+  type StackConfig,
+  emptyConfig,
+  hasConfig,
+  isPhantomInstalled,
+  listTemplates,
+  loadTemplate,
+  resolveConfigPath,
+  writeConfig,
+} from "@ashlr/stack-core";
+import { colors, intro, outro, outroError, prompts } from "../ui.ts";
+
+export const initCommand = defineCommand({
+  meta: {
+    name: "init",
+    description: "Scaffold a .stack.toml in the current directory.",
+  },
+  args: {
+    template: {
+      type: "string",
+      description: "Name of a starter template to apply (e.g. nextjs-supabase-posthog).",
+    },
+    force: {
+      type: "boolean",
+      default: false,
+      description: "Overwrite an existing .stack.toml.",
+    },
+    noInteractive: {
+      type: "boolean",
+      default: false,
+      description: "Skip template picker — always creates a blank .stack.toml.",
+    },
+  },
+  async run({ args }) {
+    intro("stack init");
+
+    const cwd = process.cwd();
+    if (hasConfig(cwd) && !args.force) {
+      outroError(
+        `${colors.bold(".stack.toml")} already exists at ${resolveConfigPath(cwd)}. Pass --force to overwrite.`,
+      );
+      return;
+    }
+
+    if (!(await isPhantomInstalled())) {
+      prompts.log.warn(
+        colors.yellow(
+          "Phantom Secrets isn't on your PATH. Stack will create .stack.toml anyway, but `stack add` needs Phantom.",
+        ),
+      );
+      prompts.log.info("  Install: brew install ashlrai/phantom/phantom");
+    }
+
+    let templateName = args.template ? String(args.template) : undefined;
+
+    if (!templateName && !args.noInteractive && process.stdout.isTTY) {
+      const available = listTemplates();
+      if (available.length > 0) {
+        const picked = await prompts.select({
+          message: "Pick a starter template (or blank):",
+          options: [
+            { value: "", label: "Blank — add services later with `stack add`" },
+            ...available.map((name) => ({ value: name, label: name })),
+          ],
+        });
+        if (prompts.isCancel(picked)) {
+          outroError("Cancelled.");
+          return;
+        }
+        if (picked) templateName = String(picked);
+      }
+    }
+
+    let config: StackConfig;
+    if (templateName) {
+      const loaded = await loadTemplate(templateName);
+      if (!loaded) {
+        outroError(`Unknown template: ${templateName}`);
+        return;
+      }
+      config = loaded;
+      config.stack.template = templateName;
+    } else {
+      config = emptyConfig();
+    }
+
+    await writeConfig(config, cwd);
+    outro(
+      `Wrote ${colors.bold(".stack.toml")} (${config.stack.project_id})${templateName ? ` from template ${colors.bold(templateName)}` : ""}.`,
+    );
+  },
+});

package/src/commands/list.ts

@@ -0,0 +1,27 @@
+import { defineCommand } from "citty";
+import { readConfig } from "@ashlr/stack-core";
+import { colors } from "../ui.ts";
+
+export const listCommand = defineCommand({
+  meta: { name: "list", description: "List services configured in this stack." },
+  async run() {
+    const config = await readConfig();
+    const entries = Object.entries(config.services);
+    if (entries.length === 0) {
+      console.log(colors.dim("No services yet. Try `stack add supabase`."));
+      return;
+    }
+    console.log();
+    console.log(colors.bold(`  ${config.stack.project_id}  `) + colors.dim(`(${entries.length} services)`));
+    console.log();
+    for (const [name, entry] of entries) {
+      const mcp = entry.mcp ? colors.cyan(` mcp:${entry.mcp}`) : "";
+      const region = entry.region ? colors.dim(` @${entry.region}`) : "";
+      console.log(`  ${colors.green("●")} ${colors.bold(name)}${region}${mcp}`);
+      console.log(
+        `    ${colors.dim("resource:")} ${entry.resource_id ?? "-"}   ${colors.dim("secrets:")} ${entry.secrets.join(", ") || "-"}`,
+      );
+    }
+    console.log();
+  },
+});

package/src/commands/login.ts

@@ -0,0 +1,28 @@
+import { defineCommand } from "citty";
+import { type ProviderContext, getProvider } from "@ashlr/stack-core";
+import { colors, intro, logEvent, outro, outroError } from "../ui.ts";
+
+export const loginCommand = defineCommand({
+  meta: {
+    name: "login",
+    description: "Refresh OAuth / PAT credentials for a specific provider.",
+  },
+  args: {
+    service: { type: "positional", required: true, description: "Provider name." },
+  },
+  async run({ args }) {
+    intro(`stack login ${args.service}`);
+    try {
+      const provider = await getProvider(args.service);
+      const ctx: ProviderContext = {
+        cwd: process.cwd(),
+        interactive: process.stdout.isTTY === true,
+        log: logEvent,
+      };
+      await provider.login(ctx);
+      outro(colors.green(`${provider.displayName}: signed in.`));
+    } catch (err) {
+      outroError((err as Error).message);
+    }
+  },
+});

package/src/commands/open.ts

@@ -0,0 +1,32 @@
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+import { defineCommand } from "citty";
+import { getProvider, readConfig } from "@ashlr/stack-core";
+import { colors, intro, outro, outroError } from "../ui.ts";
+
+export const openCommand = defineCommand({
+  meta: { name: "open", description: "Open a service's dashboard in your browser." },
+  args: {
+    service: { type: "positional", required: true, description: "Service name." },
+  },
+  async run({ args }) {
+    intro(`stack open ${args.service}`);
+    const config = await readConfig();
+    const entry = config.services[args.service];
+    if (!entry) {
+      outroError(`${args.service} is not in this stack.`);
+      return;
+    }
+    const provider = await getProvider(args.service);
+    const url = provider.dashboardUrl?.(entry);
+    if (!url) {
+      outroError(`${provider.displayName} has no dashboard URL configured.`);
+      return;
+    }
+
+    const opener =
+      platform() === "darwin" ? "open" : platform() === "win32" ? "start" : "xdg-open";
+    spawn(opener, [url], { stdio: "ignore", detached: true }).unref();
+    outro(colors.green(`Opening ${url}`));
+  },
+});

package/src/commands/projects.ts

@@ -0,0 +1,92 @@
+import { defineCommand } from "citty";
+import {
+  findProjectByName,
+  listProjects,
+  registerProject,
+  unregisterProject,
+} from "@ashlr/stack-core";
+import { colors, intro, outro, outroError } from "../ui.ts";
+
+/**
+ * `stack projects` — work across every Stack-enabled project on this machine.
+ *
+ *   stack projects list
+ *   stack projects register   (register the current cwd)
+ *   stack projects remove <name|path>
+ *   stack projects where <name>
+ */
+export const projectsCommand = defineCommand({
+  meta: {
+    name: "projects",
+    description: "Manage the cross-project registry at ~/.stack/projects.json.",
+  },
+  subCommands: {
+    list: defineCommand({
+      meta: { name: "list", description: "List every Stack-enabled project on this machine." },
+      async run() {
+        intro("stack projects");
+        const projects = await listProjects();
+        if (projects.length === 0) {
+          outro(colors.dim("No projects registered yet. Run `stack init` in one to start."));
+          return;
+        }
+        console.log();
+        for (const p of projects) {
+          const template = p.template ? colors.dim(` [${p.template}]`) : "";
+          const services = p.services.length
+            ? colors.dim(` · ${p.services.join(", ")}`)
+            : colors.dim(" · no services");
+          console.log(
+            `  ${colors.green("●")} ${colors.bold(p.name)}${template}  ${colors.dim(p.project_id)}`,
+          );
+          console.log(`    ${colors.dim(p.path)}${services}`);
+        }
+        console.log();
+      },
+    }),
+    register: defineCommand({
+      meta: { name: "register", description: "Register the current directory in the registry." },
+      async run() {
+        intro("stack projects register");
+        const entry = await registerProject(process.cwd());
+        if (!entry) {
+          outroError("No .stack.toml in the current directory — run `stack init` first.");
+          return;
+        }
+        outro(colors.green(`Registered ${entry.name} (${entry.project_id}).`));
+      },
+    }),
+    remove: defineCommand({
+      meta: { name: "remove", description: "Remove a project from the registry (does not delete files)." },
+      args: {
+        target: { type: "positional", required: true, description: "Project name or absolute path." },
+      },
+      async run({ args }) {
+        intro("stack projects remove");
+        const target = String(args.target);
+        const match = target.startsWith("/") ? target : (await findProjectByName(target))?.path;
+        if (!match) {
+          outroError(`No registered project matches "${target}".`);
+          return;
+        }
+        await unregisterProject(match);
+        outro(colors.green(`Removed ${target} from registry.`));
+      },
+    }),
+    where: defineCommand({
+      meta: { name: "where", description: "Print the path of a registered project." },
+      args: {
+        name: { type: "positional", required: true, description: "Project name." },
+      },
+      async run({ args }) {
+        const project = await findProjectByName(String(args.name));
+        if (!project) {
+          process.exitCode = 1;
+          console.error(`No registered project named "${args.name}".`);
+          return;
+        }
+        console.log(project.path);
+      },
+    }),
+  },
+});

package/src/commands/providers.ts

@@ -0,0 +1,38 @@
+import { defineCommand } from "citty";
+import { getProvider, listProviderNames } from "@ashlr/stack-core";
+import { colors, intro } from "../ui.ts";
+
+export const providersCommand = defineCommand({
+  meta: { name: "providers", description: "List every curated provider Stack can wire up." },
+  async run() {
+    intro("stack providers");
+    const names = listProviderNames();
+    const byCategory: Record<string, Array<{ name: string; displayName: string; auth: string }>> = {};
+    for (const name of names) {
+      try {
+        const p = await getProvider(name);
+        (byCategory[p.category] ??= []).push({
+          name: p.name,
+          displayName: p.displayName,
+          auth: p.authKind,
+        });
+      } catch {
+        /* ignore load failures — the registry is authoritative */
+      }
+    }
+
+    const categories = Object.keys(byCategory).sort();
+    console.log();
+    for (const cat of categories) {
+      console.log(`  ${colors.bold(cat)}`);
+      for (const p of byCategory[cat]) {
+        console.log(
+          `    ${colors.cyan("·")} ${p.name.padEnd(12)} ${colors.dim(`(${p.auth})`)}  ${p.displayName}`,
+        );
+      }
+      console.log();
+    }
+    console.log(colors.dim(`  ${names.length} providers total. Add one with: stack add <name>`));
+    console.log();
+  },
+});

package/src/commands/recommend.ts

@@ -0,0 +1,302 @@
+import { defineCommand } from "citty";
+import {
+  PROVIDER_CATEGORIES,
+  getInferenceBackend,
+  NoInferenceBackendError,
+  recipeFromRetrieval,
+  retrieve,
+  retrieveByCategory,
+  writeRecipe,
+  type Recipe,
+  type RetrievalHit,
+} from "@ashlr/stack-core";
+import { colors, intro, outro } from "../ui.ts";
+
+/**
+ * `stack recommend` — free-text → curated providers.
+ *
+ * Three execution paths:
+ *   1. Default  — pure BM25 retrieval. Instant, zero-IO, no LLM. The shape
+ *      Claude consumes via the `stack_recommend` MCP tool.
+ *   2. `--save` — also freezes the result to `.stack/recipes/<id>.toml` so
+ *      the user can follow up with `stack apply <id>`.
+ *   3. `--synth` — pipes the retrieval candidates into the local SLM backend
+ *      (LM Studio / Ollama via OpenAI-compatible HTTP) and swaps the
+ *      retrieval-only rationales for model-authored ones. No-ops gracefully
+ *      when neither endpoint is reachable.
+ *
+ * Output modes:
+ *   - default: human-readable list, grouped by category
+ *   - --json: machine-readable blob (used by the MCP server + site /api)
+ */
+
+interface RecommendOutputHit {
+  name: string;
+  displayName: string;
+  category: string;
+  authKind: string;
+  secrets: string[];
+  blurb: string;
+  score: number;
+  matched: string[];
+  rationale?: string;
+}
+
+interface RecommendOutput {
+  query: string;
+  hits: RecommendOutputHit[];
+  byCategory: Record<string, Array<{ name: string; score: number }>>;
+  guidance: string;
+  recipe?: { id: string; path: string };
+  inference?: { mode: "synth" | "mcp-delegated"; backend: string; note?: string };
+}
+
+function toOutputHit(
+  hit: RetrievalHit,
+  rationale?: string,
+): RecommendOutputHit {
+  return {
+    name: hit.provider.name,
+    displayName: hit.provider.displayName,
+    category: hit.provider.category,
+    authKind: hit.provider.authKind,
+    secrets: hit.provider.secrets,
+    blurb: hit.provider.blurb,
+    score: Number(hit.score.toFixed(3)),
+    matched: hit.matched,
+    rationale,
+  };
+}
+
+function buildGuidance(hits: RetrievalHit[], categories: string[]): string {
+  if (hits.length === 0) {
+    return "No strong matches. Try describing the concrete capability you need (e.g. 'postgres database', 'stripe subscriptions', 'deploy frontend').";
+  }
+  const covered = new Set(hits.map((h) => h.provider.category));
+  const missing = categories.filter(
+    (c) => !covered.has(c as (typeof PROVIDER_CATEGORIES)[number]),
+  );
+  const topByCat = Object.entries(
+    hits.reduce<Record<string, RetrievalHit>>((acc, h) => {
+      if (!acc[h.provider.category] || acc[h.provider.category].score < h.score) {
+        acc[h.provider.category] = h;
+      }
+      return acc;
+    }, {}),
+  )
+    .sort((a, b) => b[1].score - a[1].score)
+    .map(([cat, h]) => `${cat}→${h.provider.name}`);
+  const parts = [`Top pick per category: ${topByCat.join(", ")}.`];
+  if (missing.length > 0) {
+    parts.push(
+      `No matches surfaced for: ${missing.join(", ")}. Add terms for those categories if the user needs them.`,
+    );
+  }
+  parts.push(
+    `Apply a chosen set with: stack add ${hits.slice(0, 3).map((h) => h.provider.name).join(" ")} (or supply your own list).`,
+  );
+  return parts.join(" ");
+}
+
+function buildCatalogContext(hits: RetrievalHit[]): string {
+  return hits
+    .map(
+      (h) =>
+        `- ${h.provider.name} (${h.provider.category}): ${h.provider.blurb} [secrets: ${h.provider.secrets.join(", ")}]`,
+    )
+    .join("\n");
+}
+
+async function trySynth(
+  query: string,
+  hits: RetrievalHit[],
+): Promise<{ rationales: Map<string, string>; note?: string; backend: string; mode: "synth" | "mcp-delegated" } | null> {
+  try {
+    const backend = await getInferenceBackend({ preferLocal: true });
+    const result = await backend.infer({
+      query,
+      catalogContext: buildCatalogContext(hits),
+    });
+    const rationales = new Map<string, string>();
+    for (const p of result.recipe?.providers ?? []) {
+      if (p.rationale) rationales.set(p.name, p.rationale);
+    }
+    return {
+      rationales,
+      note: result.recipe?.notes,
+      backend: backend.name,
+      mode: result.mode,
+    };
+  } catch (err) {
+    if (err instanceof NoInferenceBackendError) return null;
+    throw err;
+  }
+}
+
+export const recommendCommand = defineCommand({
+  meta: {
+    name: "recommend",
+    description: "Pick the right providers for what you're building (AI-assisted).",
+  },
+  args: {
+    query: {
+      type: "positional",
+      description: "Free-text description of the project (in quotes).",
+      required: false,
+    },
+    k: {
+      type: "string",
+      description: "Max results to return (default 6).",
+      required: false,
+    },
+    category: {
+      type: "string",
+      description: "Restrict to a single category (e.g. Database, Auth).",
+      required: false,
+    },
+    json: {
+      type: "boolean",
+      description: "Machine-readable JSON output.",
+      required: false,
+    },
+    save: {
+      type: "boolean",
+      description:
+        "Persist the result as .stack/recipes/<id>.toml so you can run `stack apply <id>`.",
+      required: false,
+    },
+    synth: {
+      type: "boolean",
+      description:
+        "Call the local SLM (LM Studio / Ollama) to synthesize rationales. Silently falls back to retrieval-only when no endpoint is reachable.",
+      required: false,
+    },
+  },
+  async run({ args }) {
+    const query = typeof args.query === "string" ? args.query.trim() : "";
+    if (!query) {
+      if (args.json) {
+        console.log(
+          JSON.stringify(
+            {
+              query: "",
+              hits: [],
+              byCategory: {},
+              guidance: "Provide a query: stack recommend \"what you're building\".",
+            } satisfies RecommendOutput,
+            null,
+            2,
+          ),
+        );
+        return;
+      }
+      intro("stack recommend");
+      console.log(
+        colors.dim(
+          "  Usage: stack recommend \"B2B SaaS with auth, AI, and payments\"\n",
+        ),
+      );
+      outro("No query — nothing to recommend.");
+      return;
+    }
+
+    const k = Number.parseInt(String(args.k ?? "6"), 10);
+    const categories = args.category ? [String(args.category)] : undefined;
+    const hits = retrieve(query, {
+      k: Number.isFinite(k) && k > 0 ? k : 6,
+      categories: categories as RetrievalHit["provider"]["category"][] | undefined,
+    });
+
+    let synthOutcome: Awaited<ReturnType<typeof trySynth>> = null;
+    if (args.synth && hits.length > 0) {
+      synthOutcome = await trySynth(query, hits);
+    }
+
+    const outputHits: RecommendOutputHit[] = hits.map((h) =>
+      toOutputHit(h, synthOutcome?.rationales.get(h.provider.name)),
+    );
+
+    let recipeInfo: RecommendOutput["recipe"];
+    if (args.save && hits.length > 0) {
+      const guidance = buildGuidance(hits, [...PROVIDER_CATEGORIES]);
+      const recipe: Recipe = recipeFromRetrieval(query, hits, guidance);
+      // Prefer synth-authored rationales over raw matched-term strings.
+      if (synthOutcome) {
+        recipe.providers = recipe.providers.map((p) => ({
+          ...p,
+          rationale: synthOutcome!.rationales.get(p.name) ?? p.rationale,
+        }));
+      }
+      const path = await writeRecipe(recipe);
+      recipeInfo = { id: recipe.id, path };
+    }
+
+    const payload: RecommendOutput = {
+      query,
+      hits: outputHits,
+      byCategory: Object.fromEntries(
+        Object.entries(retrieveByCategory(query, { k: 20 })).map(([cat, catHits]) => [
+          cat,
+          catHits.map((h) => ({
+            name: h.provider.name,
+            score: Number(h.score.toFixed(3)),
+          })),
+        ]),
+      ),
+      guidance: buildGuidance(hits, [...PROVIDER_CATEGORIES]),
+      recipe: recipeInfo,
+      inference: synthOutcome
+        ? { mode: synthOutcome.mode, backend: synthOutcome.backend, note: synthOutcome.note }
+        : undefined,
+    };
+
+    if (args.json) {
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    intro("stack recommend");
+    console.log(colors.dim(`  query: ${query}\n`));
+    if (hits.length === 0) {
+      console.log(colors.yellow("  No strong matches.") + "\n");
+      console.log(colors.dim(`  ${payload.guidance}\n`));
+      outro("Try a more specific query.");
+      return;
+    }
+    for (const hit of outputHits) {
+      const scoreTag = colors.dim(`(${hit.score.toFixed(2)})`);
+      console.log(
+        `  ${colors.green("●")} ${colors.bold(hit.displayName)}  ${colors.cyan(hit.category)}  ${scoreTag}`,
+      );
+      console.log(`    ${colors.dim(hit.blurb)}`);
+      if (hit.rationale) {
+        console.log(`    ${colors.dim("why:")} ${hit.rationale}`);
+      }
+      console.log(
+        `    ${colors.dim("add with:")} ${colors.reset("stack add ")}${hit.name}`,
+      );
+      console.log();
+    }
+    if (synthOutcome?.note) {
+      console.log(colors.dim(`  notes: ${synthOutcome.note}\n`));
+    }
+    console.log(colors.dim(`  ${payload.guidance}`));
+    if (recipeInfo) {
+      console.log();
+      console.log(
+        colors.dim("  Saved recipe:") +
+          ` ${colors.bold(recipeInfo.id)}   ` +
+          colors.dim(`(${recipeInfo.path})`),
+      );
+      console.log(
+        colors.dim("  Apply with:  ") + colors.reset(`stack apply ${recipeInfo.id}`),
+      );
+    } else if (!args.json) {
+      console.log();
+      console.log(
+        colors.dim("  Tip: rerun with `--save` to freeze as a recipe for `stack apply`."),
+      );
+    }
+    outro("Tell Claude or run `stack add <name>` to continue.");
+  },
+});