@ashlr/stack 0.1.1 → 0.3.0

package/src/commands/recommend.ts

@@ -1,302 +0,0 @@
-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.");
-  },
-});

package/src/commands/remove.ts

@@ -1,124 +0,0 @@
-import { defineCommand } from "citty";
-import { readConfig, removeSecret, writeConfig } from "@ashlr/stack-core";
-import { removeMcpEntry } from "@ashlr/stack-core/mcp-writer";
-import { colors, intro, outro, outroError, prompts } from "../ui.ts";
-
-export const removeCommand = defineCommand({
-  meta: {
-    name: "remove",
-    description: "Remove a service from the stack (vault entries and MCP config).",
-  },
-  args: {
-    service: {
-      type: "positional",
-      required: false,
-      description: "Service name. Omit with --all to remove every service.",
-    },
-    all: {
-      type: "boolean",
-      default: false,
-      description: "Remove every service in this stack (with confirmation).",
-    },
-    keepRemote: {
-      type: "boolean",
-      default: false,
-      description: "Leave the provider-side resource untouched (don't deprovision).",
-    },
-  },
-  async run({ args }) {
-    if (args.all) return runRemoveAll(Boolean(args.keepRemote));
-    if (!args.service) {
-      intro("stack remove");
-      outroError("Missing service name. Pass --all to remove every service.");
-      return;
-    }
-    return runRemoveOne(String(args.service), Boolean(args.keepRemote));
-  },
-});
-
-async function runRemoveOne(serviceName: string, keepRemote: boolean): Promise<void> {
-  intro(`stack remove ${serviceName}`);
-  const config = await readConfig();
-  const entry = config.services[serviceName];
-  if (!entry) {
-    outroError(`${serviceName} is not in this stack.`);
-    return;
-  }
-
-  const confirmed = process.stdout.isTTY
-    ? await prompts.confirm({
-        message: `Remove ${serviceName} from .stack.toml, delete its ${entry.secrets.length} secret(s), and ${keepRemote ? "keep" : "deprovision"} the upstream resource?`,
-        initialValue: false,
-      })
-    : true;
-  if (!confirmed || prompts.isCancel(confirmed)) {
-    outroError("Cancelled.");
-    return;
-  }
-
-  for (const secret of entry.secrets) {
-    await removeSecret(secret);
-  }
-  if (entry.mcp) await removeMcpEntry(entry.mcp);
-  delete config.services[serviceName];
-  await writeConfig(config);
-
-  outro(colors.green(`Removed ${serviceName}.`));
-}
-
-async function runRemoveAll(keepRemote: boolean): Promise<void> {
-  intro("stack remove --all");
-  const config = await readConfig();
-  const serviceNames = Object.keys(config.services);
-  if (serviceNames.length === 0) {
-    outro(colors.dim("No services to remove."));
-    return;
-  }
-
-  const totalSecrets = Object.values(config.services).reduce(
-    (acc, e) => acc + e.secrets.length,
-    0,
-  );
-
-  console.log();
-  console.log(`  ${colors.bold("About to remove:")}`);
-  for (const name of serviceNames) {
-    const entry = config.services[name];
-    console.log(
-      `    ${colors.red("●")} ${name.padEnd(14)} ${colors.dim(`${entry.secrets.length} secret(s)`)}`,
-    );
-  }
-  console.log();
-
-  // Two-step confirmation — large blast radius.
-  if (process.stdout.isTTY) {
-    const confirmed = await prompts.confirm({
-      message: `Delete ${serviceNames.length} service(s), ${totalSecrets} secret(s), and strip MCP entries? ${keepRemote ? "(keeping upstream)" : "(deprovisioning upstream)"}`,
-      initialValue: false,
-    });
-    if (!confirmed || prompts.isCancel(confirmed)) {
-      outroError("Cancelled.");
-      return;
-    }
-    const typed = await prompts.text({
-      message: `Type ${colors.bold("remove all")} to confirm:`,
-      validate(val) {
-        return val === "remove all" ? undefined : "Type exactly: remove all";
-      },
-    });
-    if (prompts.isCancel(typed)) {
-      outroError("Cancelled.");
-      return;
-    }
-  }
-
-  for (const name of serviceNames) {
-    const entry = config.services[name];
-    for (const secret of entry.secrets) await removeSecret(secret);
-    if (entry.mcp) await removeMcpEntry(entry.mcp);
-    delete config.services[name];
-  }
-  await writeConfig(config);
-
-  outro(colors.green(`Removed ${serviceNames.length} service(s), ${totalSecrets} secret(s).`));
-}

package/src/commands/scan.ts

@@ -1,123 +0,0 @@
-import { defineCommand } from "citty";
-import {
-  addService,
-  assertPhantomInstalled,
-  emptyConfig,
-  hasConfig,
-  listProviderNames,
-  readConfig,
-  scanSource,
-  writeConfig,
-} from "@ashlr/stack-core";
-import { colors, intro, logEvent, outro, outroError, prompts } from "../ui.ts";
-
-/**
- * `stack scan` — look at the current repo's source (package.json, config files,
- * etc.) and report which curated providers the code already uses. With
- * `--auto`, Stack will seed a .stack.toml (if missing) and offer to run
- * `stack add` for each detected provider.
- */
-export const scanCommand = defineCommand({
-  meta: {
-    name: "scan",
-    description: "Detect providers used by this repo (package.json, config files, .env.example).",
-  },
-  args: {
-    path: { type: "string", default: ".", description: "Directory to scan." },
-    auto: {
-      type: "boolean",
-      default: false,
-      description: "After scanning, offer to run `stack add` for each detected provider.",
-    },
-    confidence: {
-      type: "string",
-      default: "medium",
-      description: "Minimum confidence to surface: low | medium | high.",
-    },
-  },
-  async run({ args }) {
-    intro("stack scan");
-    const cwd = String(args.path);
-    const hits = await scanSource(cwd);
-    const minimum = String(args.confidence).toLowerCase() as "low" | "medium" | "high";
-    const order: Record<string, number> = { low: 0, medium: 1, high: 2 };
-    const filtered = hits.filter((h) => order[h.confidence] >= order[minimum]);
-
-    if (filtered.length === 0) {
-      outro(colors.dim("No providers detected. Run `stack scan --confidence low` to see weaker signals."));
-      return;
-    }
-
-    console.log();
-    console.log(
-      `  ${colors.bold(String(filtered.length))} provider(s) detected in ${colors.dim(cwd)}:`,
-    );
-    for (const h of filtered) {
-      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.slice(0, 3).join("  "))}`);
-    }
-    console.log();
-
-    if (!args.auto) {
-      const suggestion = filtered.map((h) => `stack add ${h.provider}`).join("\n  ");
-      console.log(colors.dim("  Next steps:"));
-      console.log(colors.dim(`    ${suggestion}\n`));
-      outro(colors.dim("scan complete — nothing written."));
-      return;
-    }
-
-    // --auto path: seed config if missing, offer each addition interactively.
-    try {
-      await assertPhantomInstalled();
-    } catch (err) {
-      outroError((err as Error).message);
-      return;
-    }
-
-    if (!hasConfig(cwd)) {
-      await writeConfig(emptyConfig("from-scan"), cwd);
-      prompts.log.info(colors.dim("Seeded a fresh .stack.toml."));
-    }
-
-    const config = await readConfig(cwd);
-    const registered = new Set(listProviderNames());
-
-    for (const h of filtered) {
-      if (!registered.has(h.provider)) continue;
-      if (config.services[h.provider]) {
-        prompts.log.info(colors.dim(`${h.provider}: already in stack, skipping`));
-        continue;
-      }
-      const shouldAdd = await prompts.confirm({
-        message: `Add ${h.provider}? (${h.signals.slice(0, 2).join(", ")})`,
-        initialValue: true,
-      });
-      if (prompts.isCancel(shouldAdd) || !shouldAdd) continue;
-
-      const spinner = prompts.spinner();
-      spinner.start(`Adding ${h.provider}…`);
-      try {
-        const result = await addService({
-          providerName: h.provider,
-          cwd,
-          interactive: process.stdout.isTTY === true,
-          log: (event) => {
-            spinner.stop();
-            logEvent(event);
-            spinner.start(`Adding ${h.provider}…`);
-          },
-        });
-        spinner.stop(`${colors.green("●")} ${h.provider} → ${result.displayName}`);
-      } catch (err) {
-        spinner.stop(colors.red(`✗ ${h.provider}: ${(err as Error).message}`));
-      }
-    }
-
-    outro(colors.green("scan complete."));
-  },
-});

package/src/commands/status.ts

@@ -1,39 +0,0 @@
-import { defineCommand } from "citty";
-import { hasConfig, isPhantomInstalled, listSecrets, readConfig } from "@ashlr/stack-core";
-import { colors } from "../ui.ts";
-
-export const statusCommand = defineCommand({
-  meta: { name: "status", description: "Show stack health at a glance." },
-  async run() {
-    const hasStack = hasConfig();
-    const phantomOk = await isPhantomInstalled();
-    const config = hasStack ? await readConfig() : undefined;
-    const vaultKeys = phantomOk ? await listSecrets().catch(() => []) : [];
-
-    console.log();
-    console.log(colors.bold("  Ashlr Stack"));
-    console.log();
-    console.log(
-      `  ${statusDot(hasStack)} .stack.toml       ${hasStack ? colors.dim(config?.stack.project_id) : colors.dim("missing — run `stack init`")}`,
-    );
-    console.log(
-      `  ${statusDot(phantomOk)} phantom           ${phantomOk ? colors.dim(`${vaultKeys.length} secrets in vault`) : colors.dim("not installed")}`,
-    );
-    console.log(
-      `  ${statusDot(hasStack && Object.keys(config?.services ?? {}).length > 0)} services          ${colors.dim(`${Object.keys(config?.services ?? {}).length} configured`)}`,
-    );
-    console.log();
-    if (config) {
-      for (const [name, entry] of Object.entries(config.services)) {
-        console.log(
-          `    ${colors.cyan("·")} ${name.padEnd(14)} ${colors.dim(entry.resource_id ?? "-")}`,
-        );
-      }
-      console.log();
-    }
-  },
-});
-
-function statusDot(ok: boolean): string {
-  return ok ? colors.green("●") : colors.red("●");
-}

package/src/commands/sync.ts

@@ -1,37 +0,0 @@
-import { defineCommand } from "citty";
-import { readConfig, syncToPlatform } from "@ashlr/stack-core";
-import { colors, intro, outro, outroError } from "../ui.ts";
-
-const SUPPORTED = ["vercel", "railway", "fly"] as const;
-type Platform = (typeof SUPPORTED)[number];
-
-export const syncCommand = defineCommand({
-  meta: {
-    name: "sync",
-    description: "Push secrets to a deployment platform (via phantom sync).",
-  },
-  args: {
-    platform: {
-      type: "string",
-      required: true,
-      description: `One of: ${SUPPORTED.join(", ")}`,
-    },
-  },
-  async run({ args }) {
-    intro(`stack sync ${args.platform}`);
-    if (!SUPPORTED.includes(args.platform as Platform)) {
-      outroError(`Unsupported platform. Use: ${SUPPORTED.join(", ")}`);
-      return;
-    }
-    const config = await readConfig();
-    const entry = config.services[args.platform];
-    if (!entry?.resource_id) {
-      outroError(
-        `No ${args.platform} project found in .stack.toml. Run \`stack add ${args.platform}\` first.`,
-      );
-      return;
-    }
-    await syncToPlatform(args.platform as Platform, entry.resource_id);
-    outro(colors.green(`Secrets synced to ${args.platform}.`));
-  },
-});