runchr 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# runchr
+
+Pull an agent stack into a folder. A stack is a combination of agent tools —
+MCP servers, skills, agents, frameworks — that do one job, plus the model, the
+harness, and the prompt to run it.
+
+```bash
+npx runchr pull runchr/docs-current-refactor-agent
+```
+
+It writes four files into `runchr-<slug>/`:
+
+| file | what |
+|---|---|
+| `runchr.json` | the manifest — the machine-readable stack |
+| `AGENTS.md` | the card: what the stack does, and the tools it uses |
+| `mcp.json` | the MCP servers, as a `mcpServers` config (best effort) |
+| `prompt.md` | the system prompt and the instructions |
+
+It fetches before it writes, so a failure leaves the folder untouched, and it
+only ever writes its own four files.
+
+## Usage
+
+```bash
+npx runchr pull <owner>/<slug>[@rev] [--dir <path>] [--json]
+npx runchr install [<owner>/<slug>[@rev]] [--dir <path>] [--yes] [--json]
+npx runchr check [<owner>/<slug>[@rev]] [--dir <path>] [--json]
+```
+
+- `owner` — a member's login, or `runchr` for a mined or drafted stack.
+- `@rev` — a specific revision (default: the current one).
+- `--dir` — where to write (default: `runchr-<slug>`; `install` and `check`
+  default to the current directory).
+- `--yes` — `install` only: run the tool installs. Without it, they are printed.
+- `--json` — print the result as JSON instead of a summary.
+
+### `pull` vs `install`
+
+`pull` writes the four files and stops.
+
+`install` writes them, merges the stack's MCP servers into a project
+`.mcp.json`, and — **only with `--yes`** — runs the tool installs. By default it
+prints what it would run, so nothing executes without consent. An MCP server is
+written as config (the harness runs it later); a `pip`/`npx`/`git` line is a
+command; a path or a harness command is a note.
+
+```bash
+npx runchr install runchr/docs-current-refactor-agent
+#   Applied runchr/docs-current-refactor-agent@1 into runchr-docs-current-refactor-agent
+#   MCP servers written to .mcp.json: context7, github-mcp-server
+#   Commands (not run — pass --yes to run):
+#     pip install aider-chat
+```
+
+Point it at another host with `RUNCHR_API_URL`.
+
+### `runchr.json` is a lockfile
+
+`install` writes `runchr.json` with the revision it applied. Commit it, and
+**`install` with no argument reproduces that exact revision** — not whatever is
+newest:
+
+```bash
+npx runchr install              # reads ./runchr.json, applies its revision
+```
+
+The lockfile is left untouched when it is the input, so a clean checkout stays
+clean on every CI run.
+
+### `check`
+
+`check` answers the question a builder actually has repeatedly: **is this stack
+still good?** It reports whether the pin is behind the current revision, and
+which tools have been archived or gone quiet — with what people reach for
+instead, ranked by the recipe graph (the tools used alongside the rest of *your*
+stack) rather than by stars alone.
+
+```bash
+npx runchr check
+#   runchr/docs-current-refactor-agent — pinned to revision 1; current is 2
+#     ok  context7 (mcp-server) — ok
+#     !!  dead-docs (mcp-server) — archived
+#           → gitmcp — used with 3 stacks like yours
+#   Something needs attention.
+```
+
+It **exits non-zero when something needs attention**, so a scheduled job can
+run it:
+
+```yaml
+- run: npx runchr install --yes
+- run: npx runchr check
+```
+
+Nothing is executed without `--yes`, so this is safe to put in CI.
+
+## Where the stacks come from
+
+[runchr.com](https://runchr.com) — a curated registry of agent artifacts. Browse
+by the job your agent does, read the stack, then pull it. The catalog is also
+open over HTTP (`https://api.runchr.com/api/tools`) and MCP
+(`https://api.runchr.com/mcp`).
+
+## License
+
+See the repository.

package/api.mjs

@@ -0,0 +1,85 @@
+/**
+ * The read side of the API, for the CLI. No token: reading is open.
+ */
+export const DEFAULT_API = "https://api.runchr.com";
+
+async function getJson(fetchImpl, url) {
+  const res = await fetchImpl(url);
+  if (!res.ok) {
+    throw new Error(`${res.status} ${res.statusText} for ${url}`);
+  }
+  return res.json();
+}
+
+function present(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+/**
+ * The card and the manifest for a stack. With a revision, the manifest is
+ * rebuilt from that revision's payload; its tool types come from the current
+ * manifest, and a ref the current stack no longer has is dropped.
+ *
+ * @param {{ owner: string, slug: string, revision?: number }} spec
+ * @param {{ apiBase?: string, fetchImpl?: (url: string) => Promise<Response> }} [options]
+ * @returns {Promise<{ manifest: any, card: any }>}
+ */
+export async function fetchStack(
+  { owner, slug, revision },
+  { apiBase = process.env.RUNCHR_API_URL ?? DEFAULT_API, fetchImpl = fetch } = {},
+) {
+  const base = String(apiBase).replace(/\/$/, "");
+  const cardUrl = `${base}/api/recipes/${encodeURIComponent(owner)}/${encodeURIComponent(slug)}`;
+
+  const [cardBody, manifestBody] = await Promise.all([
+    getJson(fetchImpl, cardUrl),
+    getJson(fetchImpl, `${cardUrl}/manifest`),
+  ]);
+  const card = cardBody.recipe;
+  let manifest = manifestBody.manifest;
+
+  if (revision) {
+    const revBody = await getJson(fetchImpl, `${cardUrl}/revisions/${revision}`);
+    const payload = revBody.revision?.payload ?? {};
+    const byRef = new Map((manifest.tools ?? []).map((tool) => [tool.ref, tool]));
+    const rebuilt = {
+      manifestVersion: manifest.manifestVersion ?? 1,
+      name: `${owner}/${slug}`,
+      revision,
+      version: manifest.version,
+      tier: manifest.tier,
+      tools: (payload.tools ?? [])
+        .map((ref) => byRef.get(ref))
+        .filter((tool) => Boolean(tool)),
+    };
+    for (const key of ["model", "harness", "systemPrompt", "instructions", "resultUrl", "repoUrl"]) {
+      const value = present(payload[key]);
+      if (value) rebuilt[key] = value;
+    }
+    manifest = rebuilt;
+  }
+
+  return { manifest, card };
+}
+
+/**
+ * Whether a stack is still good: behind the current revision, or carrying a
+ * tool that has been archived or gone quiet. With a revision, the answer is
+ * about that pin — which is what the loader has committed.
+ *
+ * @param {{ owner: string, slug: string, revision?: number }} spec
+ * @param {{ apiBase?: string, fetchImpl?: (url: string) => Promise<Response> }} [options]
+ * @returns {Promise<any>}
+ */
+export async function fetchCheck(
+  { owner, slug, revision },
+  { apiBase = process.env.RUNCHR_API_URL ?? DEFAULT_API, fetchImpl = fetch } = {},
+) {
+  const base = String(apiBase).replace(/\/$/, "");
+  const query = revision ? `?revision=${revision}` : "";
+  const body = await getJson(
+    fetchImpl,
+    `${base}/api/recipes/${encodeURIComponent(owner)}/${encodeURIComponent(slug)}/check${query}`,
+  );
+  return body.check;
+}

package/args.mjs

@@ -0,0 +1,70 @@
+const USAGE = [
+  "usage:",
+  "  runchr pull <owner>/<slug>[@rev] [--dir <path>] [--json]",
+  "  runchr install [<owner>/<slug>[@rev]] [--dir <path>] [--yes] [--json]",
+  "  runchr check [<owner>/<slug>[@rev]] [--dir <path>] [--json]",
+].join("\n");
+
+/**
+ * `owner/slug` or `owner/slug@3`. The owner is the namespace, so a bare slug is
+ * refused rather than guessed — the API accepts one for back-compat, but the
+ * CLI should not quietly pick an owner.
+ *
+ * @param {string} spec
+ * @returns {{ owner: string, slug: string, revision?: number }}
+ */
+export function parseSpec(spec) {
+  const raw = String(spec ?? "").trim();
+  const [path, rev] = raw.split("@");
+  const slash = path.indexOf("/");
+  if (slash < 1 || slash === path.length - 1) {
+    throw new Error("pull needs owner/slug, e.g. runchr pull runchr/context7-docs");
+  }
+  const owner = path.slice(0, slash);
+  const slug = path.slice(slash + 1);
+  if (rev === undefined || rev === "") {
+    return { owner, slug };
+  }
+  const revision = Number(rev);
+  if (!Number.isInteger(revision) || revision < 1) {
+    throw new Error(`@${rev} must be a revision number`);
+  }
+  return { owner, slug, revision };
+}
+
+/**
+ * `pull` writes the stack's files; `install` also applies them; `check` only
+ * asks whether they are still good.
+ *
+ * `install` and `check` may omit the spec: they then read the project's own
+ * `runchr.json`. That is the lockfile loop — the file is committed, and CI
+ * reproduces the pinned revision rather than whatever is newest.
+ *
+ * @param {string[]} argv
+ * @returns {{ command: "pull" | "install" | "check", spec?: string, dir?: string, yes: boolean, json: boolean }}
+ */
+export function parseArgs(argv) {
+  const [command, ...rest] = argv ?? [];
+  if (!["pull", "install", "check"].includes(command)) throw new Error(USAGE);
+
+  let spec;
+  let dir;
+  let yes = false;
+  let json = false;
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === "--json") {
+      json = true;
+    } else if (arg === "--yes") {
+      yes = true;
+    } else if (arg === "--dir") {
+      dir = rest[i + 1];
+      i += 1;
+    } else if (!arg.startsWith("-") && spec === undefined) {
+      spec = arg;
+    }
+  }
+  if (!spec && command === "pull") throw new Error(USAGE);
+
+  return { command, spec, dir, yes, json };
+}

package/check.mjs

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parseSpec } from "./args.mjs";
+import { fetchCheck } from "./api.mjs";
+
+/**
+ * The project's lockfile, if it has one.
+ *
+ * `runchr.json` is what `install` writes and what `install`/`check` with no
+ * argument read. It is a lockfile in the npm sense: the committed revision is
+ * what a teammate and CI reproduce, not whatever is newest.
+ */
+export function readLock(dir) {
+  const file = path.join(dir, "runchr.json");
+  if (!existsSync(file)) return undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** `owner/slug@revision` from a manifest, or undefined when it is not one. */
+export function lockSpec(lock) {
+  const name = String(lock?.name ?? "").trim();
+  if (!name.includes("/")) return undefined;
+  const revision = Number(lock?.revision);
+  return Number.isInteger(revision) && revision > 0 ? `${name}@${revision}` : name;
+}
+
+/**
+ * Ask whether the stack this project pins is still good: behind the current
+ * revision, or carrying a tool that has been archived or gone quiet.
+ *
+ * @param {{ spec?: string, dir?: string }} args
+ * @param {{ apiBase?: string, fetchImpl?: (url: string) => Promise<Response>, cwd?: string }} [options]
+ * @returns {Promise<{ dir: string, report: any }>}
+ */
+export async function check({ spec, dir }, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const target = path.resolve(cwd, dir ?? ".");
+  const lock = readLock(target);
+  const resolved = spec ?? lockSpec(lock);
+  if (!resolved) {
+    throw new Error(
+      "check needs owner/slug, or a runchr.json in this directory (run runchr install first)",
+    );
+  }
+
+  const report = await fetchCheck(parseSpec(resolved), options);
+  return { dir: target, report };
+}

package/files.mjs

@@ -0,0 +1,114 @@
+/**
+ * The files a pulled stack becomes. Pure: given a manifest and the card, it
+ * returns the file contents; the caller writes them.
+ */
+
+/**
+ * The install line as a runnable config. Many MCP servers publish the whole
+ * `claude_desktop_config.json` block as their snippet, so a JSON object is
+ * unwrapped to the first server; `npx …` becomes a command; a URL stays a URL.
+ */
+export function parseInstall(line) {
+  const value = String(line).trim();
+
+  if (value.startsWith("{")) {
+    try {
+      const parsed = JSON.parse(value);
+      const servers = parsed.mcpServers ?? parsed.mcp_servers;
+      const first = servers && typeof servers === "object" ? Object.values(servers)[0] : undefined;
+      if (first && typeof first === "object") return first;
+    } catch {
+      /* not JSON — fall through */
+    }
+  }
+
+  if (value.startsWith("npx ")) {
+    return { command: "npx", args: value.split(/\s+/).slice(1) };
+  }
+  if (/^https?:\/\//.test(value)) {
+    return { url: value };
+  }
+  return { install: value };
+}
+
+/**
+ * The MCP servers in a stack, as a `mcpServers` config. Other tools are skipped.
+ *
+ * @param {{ tools?: Array<{ type: string, ref: string, install?: string }> }} manifest
+ * @returns {{ mcpServers: Record<string, unknown> }}
+ */
+export function mcpConfigFor(manifest) {
+  const mcpServers = {};
+  for (const tool of manifest.tools ?? []) {
+    if (tool.type !== "mcp-server") continue;
+    if (!tool.install) continue;
+    mcpServers[tool.ref] = parseInstall(tool.install);
+  }
+  return { mcpServers };
+}
+
+function section(title, body) {
+  const text = String(body ?? "").trim();
+  return text ? `## ${title}\n\n${text}\n` : "";
+}
+
+function agentsMd(manifest, card) {
+  const lines = [`# ${card.name ?? manifest.name}`, ""];
+  if (card.summary) lines.push(card.summary, "");
+  if (card.description) lines.push(card.description, "");
+
+  for (const [title, body] of [
+    ["What they did", card.whatTheyDid],
+    ["Outcome", card.outcome],
+    ["Caveats", card.caveats],
+    ["Wiring", card.wiring],
+  ]) {
+    const block = section(title, body);
+    if (block) lines.push(block);
+  }
+
+  lines.push("## Tools", "");
+  for (const tool of manifest.tools ?? []) {
+    const install = tool.install ? ` — \`${tool.install}\`` : "";
+    lines.push(`- \`${tool.ref}\` (${tool.type})${install}`);
+  }
+  lines.push("");
+
+  if (card.sourceUrl) lines.push(`Source: ${card.sourceUrl}`, "");
+  // The slug names the stack; the URL is how a reader who finds this file
+  // reaches runchr. A committed AGENTS.md is a small, honest ad.
+  const slug = String(manifest.name).split("/").pop();
+  lines.push(
+    `Pulled from runchr: https://runchr.com/recipes/${slug} (${manifest.tier}, revision ${manifest.revision}).`,
+    "",
+  );
+
+  return lines.join("\n");
+}
+
+function promptMd(manifest) {
+  const system = String(manifest.systemPrompt ?? "").trim();
+  const instructions = String(manifest.instructions ?? "").trim();
+  if (!system && !instructions) {
+    return "No prompt in this stack.\n";
+  }
+  const lines = [];
+  if (system) lines.push("# System prompt", "", system, "");
+  if (instructions) lines.push("# Instructions", "", instructions, "");
+  return lines.join("\n");
+}
+
+/**
+ * The four files a pull writes, keyed by file name.
+ *
+ * @param {{ manifest: any, card: any }} input
+ * @returns {Record<string, string>}
+ */
+export function renderFiles({ manifest, card }) {
+  return {
+    "runchr.json": `${JSON.stringify(manifest, null, 2)}\n`,
+    "mcp.json": `${JSON.stringify(mcpConfigFor(manifest), null, 2)}\n`,
+    "AGENTS.md": agentsMd(manifest, card),
+    "prompt.md": promptMd(manifest),
+  };
+}

package/index.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * `runchr pull owner/slug[@rev] [--dir <path>] [--json]`
+ * `runchr install [owner/slug[@rev]] [--dir <path>] [--yes] [--json]`
+ * `runchr check [owner/slug[@rev]] [--dir <path>] [--json]`
+ *
+ * A zero-dependency loader. `pull` writes runchr.json, AGENTS.md, mcp.json, and
+ * prompt.md into a folder. `install` does that, merges the MCP servers into a
+ * project `.mcp.json`, and — only with `--yes` — runs the tool installs. With no
+ * spec, `install` reproduces the revision the project's own `runchr.json` pins,
+ * which is what makes that file a lockfile. `check` asks whether that pin is
+ * still good and exits non-zero when it is not, so CI can run it.
+ */
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "./args.mjs";
+import { pull } from "./pull.mjs";
+import { install } from "./install.mjs";
+import { check } from "./check.mjs";
+
+const HEALTH = { ok: "ok", stale: "stale", archived: "archived", unknown: "unmeasured" };
+
+function printCheck(result) {
+  const { report } = result;
+  const state = report.outdated
+    ? `pinned to revision ${report.installedRevision}; current is ${report.currentRevision}`
+    : `revision ${report.installedRevision} is current`;
+  process.stdout.write(`${report.name} — ${state}\n`);
+
+  for (const tool of report.tools) {
+    const label = HEALTH[tool.health] ?? tool.health;
+    process.stdout.write(`  ${tool.health === "ok" ? "ok" : "!!"}  ${tool.slug} (${tool.type}) — ${label}\n`);
+    for (const replacement of tool.replacements ?? []) {
+      process.stdout.write(`        → ${replacement.slug} — ${replacement.reason}\n`);
+    }
+  }
+
+  process.stdout.write(report.ok ? "Nothing to do.\n" : "Something needs attention.\n");
+}
+
+function printPull(result) {
+  process.stdout.write(`Pulled ${result.manifest.name}@${result.manifest.revision} into ${result.dir}\n`);
+  for (const file of result.files) process.stdout.write(`  ${file}\n`);
+}
+
+function printInstall(result, ran) {
+  process.stdout.write(`Applied ${result.manifest.name}@${result.manifest.revision} into ${result.dir}\n`);
+  if (result.fromLock) {
+    process.stdout.write("  (from runchr.json — the lockfile was left as it is)\n");
+  }
+  for (const file of result.files) process.stdout.write(`  ${file}\n`);
+
+  const servers = Object.keys(result.plan.mcpServers);
+  if (servers.length > 0) {
+    process.stdout.write(`MCP servers written to .mcp.json: ${servers.join(", ")}\n`);
+  }
+
+  if (result.plan.commands.length > 0) {
+    process.stdout.write(ran ? "Ran:\n" : "Commands (not run — pass --yes to run):\n");
+    for (const step of result.plan.commands) process.stdout.write(`  ${step.command}\n`);
+  }
+  for (const note of result.plan.notes) {
+    process.stdout.write(`Note — ${note.ref}: ${note.note}\n`);
+  }
+}
+
+export async function main(argv) {
+  const args = parseArgs(argv);
+
+  if (args.command === "check") {
+    const result = await check(args);
+    if (args.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    else printCheck(result);
+    // The exit code is the point when CI runs this: a stack that is behind or
+    // carrying a dead tool fails the build rather than scrolling past.
+    return result.report.ok ? 0 : 1;
+  }
+
+  if (args.command === "install") {
+    const result = await install(args);
+    if (args.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    else printInstall(result, args.yes);
+    return 0;
+  }
+
+  const result = await pull(args);
+  if (args.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else printPull(result);
+  return 0;
+}
+
+// `process.argv[1]` is the path used to invoke the script. npm installs a bin as
+// a symlink, so the path and the module's own url differ unless the real path is
+// resolved first — without that, the CLI installed from npm would do nothing.
+const invokedDirectly =
+  Boolean(process.argv[1]) &&
+  import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+
+if (invokedDirectly) {
+  main(process.argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((error) => {
+      process.stderr.write(`${error.message}\n`);
+      process.exit(1);
+    });
+}

package/install-plan.mjs

@@ -0,0 +1,61 @@
+/**
+ * Turn a stack's manifest into an install plan. Pure: it decides what would be
+ * done; `install.mjs` decides whether to do it.
+ *
+ * An MCP server is config (the harness runs it later). A line that is a shell
+ * command is a command — including `git clone` and `curl`, which is why the
+ * caller runs commands only with explicit consent. Everything else is a note:
+ * a path, a harness command, or nothing.
+ */
+import { parseInstall } from "./files.mjs";
+
+const SHELL_COMMAND =
+  /^(?:npx|npm|pnpm|yarn|bun|pip|pip3|pipx|uv|python|python3|brew|cargo|go|git|curl|wget|docker|make|bash|sh|node|deno)\b/;
+
+/** One tool's install line as an action.
+ *
+ * @param {{ ref?: string, type?: string, install?: string }} tool
+ * @returns {{ ref: string, type: string, kind: "config" | "command" | "note", value: string }}
+ */
+export function classifyTool(tool) {
+  const ref = tool?.ref ?? "";
+  const type = tool?.type ?? "";
+  const line = String(tool?.install ?? "").trim();
+
+  if (type === "mcp-server") {
+    return line
+      ? { ref, type, kind: "config", value: line }
+      : { ref, type, kind: "note", value: "no install line" };
+  }
+  if (SHELL_COMMAND.test(line)) return { ref, type, kind: "command", value: line };
+  if (line) return { ref, type, kind: "note", value: line };
+  return { ref, type, kind: "note", value: "no install line" };
+}
+
+/** The whole stack as a plan.
+ *
+ * @param {{ tools?: Array<{ ref?: string, type?: string, install?: string }> }} manifest
+ * @returns {{
+ *   mcpServers: Record<string, unknown>,
+ *   commands: { ref: string, command: string }[],
+ *   notes: { ref: string, note: string }[],
+ * }}
+ */
+export function installPlan(manifest) {
+  const mcpServers = {};
+  const commands = [];
+  const notes = [];
+
+  for (const tool of manifest?.tools ?? []) {
+    const classified = classifyTool(tool);
+    if (classified.kind === "config") {
+      mcpServers[classified.ref] = parseInstall(classified.value);
+    } else if (classified.kind === "command") {
+      commands.push({ ref: classified.ref, command: classified.value });
+    } else {
+      notes.push({ ref: classified.ref, note: classified.value });
+    }
+  }
+
+  return { mcpServers, commands, notes };
+}

package/install.mjs

@@ -0,0 +1,95 @@
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parseSpec } from "./args.mjs";
+import { fetchStack } from "./api.mjs";
+import { lockSpec, readLock } from "./check.mjs";
+import { renderFiles } from "./files.mjs";
+import { installPlan } from "./install-plan.mjs";
+
+function defaultRunCommand(command, cwd) {
+  execSync(command, { stdio: "inherit", cwd });
+}
+
+/**
+ * Merge the stack's MCP servers into an existing `.mcp.json`, keeping every
+ * other key and every server already there. A stack's servers win on a name
+ * clash — the stack is the thing the user asked for.
+ */
+export function mergeMcpConfig(existing, mcpServers) {
+  const base = existing && typeof existing === "object" ? existing : {};
+  return {
+    ...base,
+    mcpServers: { ...(base.mcpServers ?? {}), ...mcpServers },
+  };
+}
+
+/**
+ * Apply a stack: write the four files, merge its MCP servers into the project
+ * `.mcp.json`, and — only with `yes` — run the tool installs. Fetch first,
+ * write second, run third, so a failure leaves the earlier steps.
+ *
+ * With no spec it reads the project's own `runchr.json` and reproduces that
+ * revision. The lockfile is then left untouched: it is the input, so rewriting
+ * it from a rebuilt manifest would dirty a clean checkout on every CI run.
+ *
+ * @param {{ spec?: string, dir?: string, yes?: boolean }} args
+ * @param {{ apiBase?: string, fetchImpl?: (url: string) => Promise<Response>, cwd?: string, runCommand?: (command: string, cwd: string) => void }} [options]
+ * @returns {Promise<{ dir: string, files: string[], manifest: any, plan: any, ran: string[], fromLock: boolean }>}
+ */
+export async function install(
+  { spec, dir, yes },
+  { apiBase, fetchImpl = fetch, cwd = process.cwd(), runCommand = defaultRunCommand } = {},
+) {
+  const target = path.resolve(cwd, dir ?? ".");
+  const fromLock = !spec;
+  const resolved = spec ?? lockSpec(readLock(target));
+  if (!resolved) {
+    throw new Error(
+      "install needs owner/slug, or a runchr.json in this directory (try runchr install runchr/docs-agent)",
+    );
+  }
+
+  const parsed = parseSpec(resolved);
+  const { manifest, card } = await fetchStack(parsed, { apiBase, fetchImpl });
+  const rendered = renderFiles({ manifest, card });
+  // The lockfile is the source when it is what we installed from.
+  const files = fromLock
+    ? Object.fromEntries(Object.entries(rendered).filter(([name]) => name !== "runchr.json"))
+    : rendered;
+
+  // `install` applies the stack to the project, so it lands in the current
+  // directory by default — `.mcp.json` and `AGENTS.md` are read from the project
+  // root, not from a subfolder. (`pull` keeps the `runchr-<slug>` folder.)
+  mkdirSync(target, { recursive: true });
+  for (const [name, content] of Object.entries(files)) {
+    writeFileSync(path.join(target, name), content, "utf8");
+  }
+
+  const plan = installPlan(manifest);
+
+  const mcpPath = path.join(target, ".mcp.json");
+  let existing = {};
+  if (existsSync(mcpPath)) {
+    try {
+      existing = JSON.parse(readFileSync(mcpPath, "utf8"));
+    } catch {
+      existing = {};
+    }
+  }
+  writeFileSync(
+    mcpPath,
+    `${JSON.stringify(mergeMcpConfig(existing, plan.mcpServers), null, 2)}\n`,
+    "utf8",
+  );
+
+  const ran = [];
+  if (yes) {
+    for (const step of plan.commands) {
+      runCommand(step.command, target);
+      ran.push(step.ref);
+    }
+  }
+
+  return { dir: target, files: Object.keys(files), manifest, plan, ran, fromLock };
+}

package/package.json

@@ -1,6 +1,35 @@
-{
-  "name": "runchr",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+{
+"name": "runchr",
+"version": "0.1.0",
+"description": "Pull a runchr agent stack into a folder: runchr.json, AGENTS.md, mcp.json, prompt.md.",
+"type": "module",
+"bin": {
+"runchr": "./index.mjs"
+},
+"files": [
+"index.mjs",
+"args.mjs",
+"api.mjs",
+"check.mjs",
+"files.mjs",
+"pull.mjs",
+"install.mjs",
+"install-plan.mjs",
+"README.md"
+],
+"engines": {
+"node": ">=18"
+},
+"keywords": [
+"agent",
+"agents",
+"mcp",
+"stack",
+"cli",
+"runchr"
+],
+"homepage": "https://runchr.com",
+"bugs": {
+"url": "mailto:hello@runchr.com"
+}
 }

package/pull.mjs

@@ -0,0 +1,31 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parseSpec } from "./args.mjs";
+import { fetchStack } from "./api.mjs";
+import { renderFiles } from "./files.mjs";
+
+/**
+ * Pull a stack into a directory. Fetch first, render second, write third — so a
+ * failed fetch leaves the directory untouched. It only ever writes its own four
+ * files; it never deletes.
+ *
+ * @param {{ spec: string, dir?: string }} args
+ * @param {{ apiBase?: string, fetchImpl?: (url: string) => Promise<Response>, cwd?: string }} [options]
+ * @returns {Promise<{ dir: string, files: string[], manifest: any }>}
+ */
+export async function pull(
+  { spec, dir },
+  { apiBase, fetchImpl = fetch, cwd = process.cwd() } = {},
+) {
+  const parsed = parseSpec(spec);
+  const { manifest, card } = await fetchStack(parsed, { apiBase, fetchImpl });
+  const files = renderFiles({ manifest, card });
+
+  const target = path.resolve(cwd, dir ?? `runchr-${parsed.slug}`);
+  mkdirSync(target, { recursive: true });
+  for (const [name, content] of Object.entries(files)) {
+    writeFileSync(path.join(target, name), content, "utf8");
+  }
+
+  return { dir: target, files: Object.keys(files), manifest };
+}