makersclaw 0.1.0

package/registry/blocks/board/demo.jsx

@@ -0,0 +1,50 @@
+"use client";
+
+// The Board with rows in memory — the gallery's and the smoke test's
+// surface. Not installed into apps: `makersclaw add board` lays index.js
+// and board.jsx only.
+import { useState } from "react";
+import { Badge } from "../components/ui";
+import { Board } from "../components/blocks/board";
+
+const STAGES = [
+  { key: "lead", label: "Lead" },
+  { key: "call", label: "Call booked" },
+  { key: "proposal", label: "Proposal" },
+  { key: "won", label: "Won" },
+];
+const START = [
+  { id: 1, name: "Northwind", stage: "lead", owner: "Maya", value: 4000 },
+  { id: 2, name: "Acme Ltd", stage: "call", owner: "Leon", value: 12000 },
+  { id: 3, name: "Globex", stage: "call", owner: "Priya", value: 7000 },
+  { id: 4, name: "Initech", stage: "proposal", owner: "Maya", value: 22000 },
+  { id: 5, name: "Umbrella", stage: "paused", owner: "Leon", value: 3000 },
+];
+
+export default function BoardDemo() {
+  const [rows, setRows] = useState(START);
+  return (
+    <Board
+      rows={rows}
+      groupBy="stage"
+      columns={STAGES}
+      titleOf={(d) => d.name}
+      onMove={async (row, to) => {
+        setRows((all) => all.map((r) => (r.id === row.id ? { ...r, stage: to } : r)));
+        return { ok: true };
+      }}
+      onCreate={async (name, stage) => {
+        setRows((all) => [...all, { id: Date.now(), name, stage, owner: null, value: 0 }]);
+        return { ok: true };
+      }}
+      renderDetails={(d) => (
+        <div className="flex items-center justify-between text-xs text-muted-foreground">
+          <span>{d.owner ?? "Unowned"}</span>
+          <Badge>{Number(d.value ?? 0).toLocaleString()}</Badge>
+        </div>
+      )}
+      limits={{ call: 1 }}
+      label="Demo deals by stage"
+    />
+  );
+}

package/registry/blocks/board/index.js

@@ -0,0 +1,4 @@
+// The Board block — `makersclaw add board`. Fixed: compose it through its
+// props (README.md beside this file); a board it cannot be is your own
+// component in components/.
+export { Board } from "./board";

package/registry/blocks/job-panel/README.md

@@ -0,0 +1,68 @@
+# JobPanel
+
+The panel that follows work the founder asked the app's agent for. It
+shows each step's label as the agent works, a Stop button while it runs,
+then "done" (closing itself a few seconds later) or the reason it
+stopped. When no job runs it renders nothing — a panel that is always
+there is a monitoring console, and apps do not have one.
+
+```jsx
+import { JobPanel } from "../components/blocks/job-panel";   // "./blocks/job-panel" from components/
+```
+
+A client component. It takes the object `useJob()` returns (lib/hooks.js,
+README §5 "Commissioning work") and draws it; starting the job stays with
+your surface.
+
+## Props
+
+- `job` — what `useJob()` returns. Required.
+- `title` — while it runs, what the agent is doing, in the founder's
+  words: `"Drafting the launch plan"`. Default `"Working on it"`.
+- `doneTitle` — after a clean finish: `"Launch plan drafted"`.
+- `failedTitle` — when it stopped with an error; the error follows it.
+- `onRetry` — shows "Try again" beside Close when the job failed: start
+  the same job again.
+- `autoClose` — milliseconds after a clean finish before the panel
+  closes itself (`job.reset()`); default 6000, `false` to keep it until
+  Close.
+- `maxSteps` — the newest steps shown, default 6; older ones become one
+  "N earlier steps" line.
+- `showText` — the agent's own account under the steps, default true. It
+  is what the agent says it did, never the result: the result is rows.
+- `className` — layout around it. Never colour.
+
+## Example
+
+```jsx
+"use client";
+import { useEffect } from "react";
+import { useJob } from "../lib/hooks";
+import { Button } from "./ui";
+import { JobPanel } from "./blocks/job-panel";
+
+const ASK = "Draft a launch plan for the next product in the list, with dates and owners.";
+
+export default function Launches({ launches, reload }) {
+  const job = useJob();
+  useEffect(() => { reload?.(); }, [job.progress]);   // rows appear as they land
+
+  return (
+    <div className="grid gap-4">
+      <div className="flex flex-wrap gap-2">
+        <Button variant="secondary" onClick={() => job.start(ASK)} disabled={job.running}>Generate a launch plan</Button>
+        <Button variant="primary" icon="plus" onClick={openNewLaunch}>New launch plan</Button>
+      </div>
+      <JobPanel job={job} title="Drafting the launch plan" doneTitle="Launch plan drafted" onRetry={() => job.start(ASK)} />
+      {/* the launches list — the job's result lands here */}
+    </div>
+  );
+}
+```
+
+The verb sits on the object list beside the manual "New" (README §5, rule
+1), and the panel sits where the result will appear.
+
+Its files are fixed: `npm run check` refuses a change, and `makersclaw add
+job-panel` restores them. A different panel is your own component in
+`components/`, built from the kit.

package/registry/blocks/job-panel/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "job-panel",
+  "title": "JobPanel",
+  "description": "The panel that follows work the founder asked the app's agent for (useJob): each step's label as it runs, Stop, then done or the reason it stopped — and nothing on screen when no job runs.",
+  "useWhen": "A surface has a verb that asks the agent to make or find something (\"Generate a launch plan\", \"Find 20 leads\", \"Plan next sprint\") and the founder should watch it happen where the result will land.",
+  "tags": ["job", "agent", "generate", "progress", "steps", "running", "working", "commission", "ai", "stop", "status"],
+  "exports": ["JobPanel"],
+  "files": ["index.js", "job-panel.jsx"],
+  "requires": []
+}

package/registry/blocks/job-panel/demo.jsx

@@ -0,0 +1,75 @@
+"use client";
+
+// JobPanel driven by a pretend job — the gallery's and the smoke test's
+// surface. Not installed into apps.
+import { useEffect, useRef, useState } from "react";
+import { Button } from "../components/ui";
+import { JobPanel } from "../components/blocks/job-panel";
+
+const STEPS = ["Reading the product list", "Searching the web", "Drafting the plan", "Saving 6 tasks"];
+const IDLE = { running: false, steps: [], text: "", error: null, finishedAt: null, progress: 0 };
+
+function usePretendJob() {
+  const [state, setState] = useState(IDLE);
+  const timers = useRef([]);
+  const clear = () => {
+    timers.current.forEach(clearTimeout);
+    timers.current = [];
+  };
+  useEffect(() => clear, []);
+  const later = (ms, fn) => timers.current.push(setTimeout(fn, ms));
+  function start(fail) {
+    clear();
+    setState({ ...IDLE, running: true });
+    STEPS.forEach((label, i) =>
+      later(700 * i + 200, () =>
+        setState((s) => ({
+          ...s,
+          steps: [...s.steps.map((x) => ({ ...x, status: "done" })), { name: `step_${i}`, label, status: "running" }],
+          text: `${s.text}${label}…\n`,
+        })),
+      ),
+    );
+    later(700 * STEPS.length + 400, () =>
+      setState((s) =>
+        fail
+          ? {
+              ...s,
+              running: false,
+              steps: s.steps.map((x, i) => ({ ...x, status: i === s.steps.length - 1 ? "failed" : "done" })),
+              error: "The search service did not answer.",
+            }
+          : { ...s, running: false, steps: s.steps.map((x) => ({ ...x, status: "done" })), finishedAt: new Date().toISOString(), progress: s.progress + 1 },
+      ),
+    );
+  }
+  return {
+    ...state,
+    start,
+    cancel: () => {
+      clear();
+      setState((s) => ({ ...s, running: false, finishedAt: new Date().toISOString() }));
+    },
+    reset: () => {
+      clear();
+      setState(IDLE);
+    },
+  };
+}
+
+export default function JobPanelDemo() {
+  const job = usePretendJob();
+  return (
+    <div className="grid max-w-xl gap-4">
+      <div className="flex flex-wrap gap-2">
+        <Button variant="secondary" onClick={() => job.start(false)} disabled={job.running}>
+          Generate a launch plan
+        </Button>
+        <Button variant="quiet" onClick={() => job.start(true)} disabled={job.running}>
+          Run one that fails
+        </Button>
+      </div>
+      <JobPanel job={job} title="Drafting the launch plan" doneTitle="Launch plan drafted" onRetry={() => job.start(false)} />
+    </div>
+  );
+}

package/registry/blocks/job-panel/index.js

@@ -0,0 +1,3 @@
+// The JobPanel block — `makersclaw add job-panel`. Fixed: compose it
+// through its props (README.md beside this file).
+export { JobPanel } from "./job-panel";

package/registry/blocks/job-panel/job-panel.jsx

@@ -0,0 +1,110 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { Button, Icon, cx } from "../../ui";
+
+// JobPanel — the panel that follows work the founder asked the app's
+// agent for (useJob in lib/hooks.js, README §5 "Commissioning work"). It
+// keeps the four rules a hand-drawn panel breaks: it is not there when
+// nothing runs, it shows each step's label (the founder's phrase, never
+// the tool's name), the agent's text is its account and not the
+// deliverable (the rows are), and Stop / Close are always one press away.
+//
+//   const job = useJob();
+//   <Button onClick={() => job.start("Draft a launch plan for Rowhouse")}>Generate a launch plan</Button>
+//   <JobPanel job={job} title="Drafting the launch plan" doneTitle="Launch plan drafted" />
+
+function StepMark({ status }) {
+  if (status === "done") return <Icon name="check" size={14} className="shrink-0 text-success" />;
+  if (status === "failed") return <Icon name="warning" size={14} className="shrink-0 text-destructive" />;
+  return <span aria-hidden="true" className="mx-[3px] size-2 shrink-0 animate-pulse rounded-full bg-primary" />;
+}
+
+export function JobPanel({
+  job,
+  title = "Working on it",
+  doneTitle = "Done",
+  failedTitle = "It stopped",
+  onRetry,
+  autoClose = 6000,
+  maxSteps = 6,
+  showText = true,
+  className,
+}) {
+  const textRef = useRef(null);
+  const running = Boolean(job?.running);
+  const failed = !running && Boolean(job?.error);
+  const done = !running && !failed && Boolean(job?.finishedAt);
+
+  // The agent's account grows at the bottom; keep the newest line in view.
+  useEffect(() => {
+    const el = textRef.current;
+    if (el) el.scrollTop = el.scrollHeight;
+  }, [job?.text]);
+
+  // A clean finish closes itself: the rows it made are the answer.
+  useEffect(() => {
+    if (!done || !autoClose || !job?.reset) return undefined;
+    const t = setTimeout(() => job.reset(), autoClose);
+    return () => clearTimeout(t);
+  }, [done, autoClose, job?.finishedAt]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  if (!job || !(running || failed || done)) return null;
+
+  const steps = job.steps ?? [];
+  const hidden = Math.max(0, steps.length - maxSteps);
+  const visible = steps.slice(hidden);
+  const heading = running ? title : failed ? failedTitle : doneTitle;
+
+  return (
+    <section
+      aria-label={heading}
+      className={cx("rounded-lg border bg-card p-4 text-card-foreground", failed ? "border-destructive/50" : "border-border", className)}
+    >
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0">
+          <p aria-live="polite" className="flex items-center gap-2 text-sm font-semibold">
+            {running ? <StepMark status="running" /> : <StepMark status={failed ? "failed" : "done"} />}
+            <span className="min-w-0">{heading}</span>
+          </p>
+          {failed ? <p className="mt-1 text-sm text-muted-foreground">{job.error}</p> : null}
+        </div>
+        <div className="flex shrink-0 gap-2">
+          {failed && onRetry ? (
+            <Button size="sm" variant="secondary" onClick={onRetry}>
+              Try again
+            </Button>
+          ) : null}
+          {running ? (
+            <Button size="sm" variant="quiet" onClick={() => job.cancel?.()}>
+              Stop
+            </Button>
+          ) : (
+            <Button size="sm" variant="quiet" onClick={() => job.reset?.()}>
+              Close
+            </Button>
+          )}
+        </div>
+      </div>
+      {visible.length ? (
+        <ol className="mt-3 grid gap-1.5 text-sm">
+          {hidden > 0 ? <li className="text-xs text-muted-foreground">{hidden} earlier {hidden === 1 ? "step" : "steps"}</li> : null}
+          {visible.map((step, i) => (
+            <li key={`${hidden + i}-${step.name}`} className="flex items-center gap-2">
+              <StepMark status={step.status} />
+              <span className={step.status === "running" ? "text-foreground" : "text-muted-foreground"}>{step.label ?? "Working"}</span>
+            </li>
+          ))}
+        </ol>
+      ) : null}
+      {showText && job.text ? (
+        <div
+          ref={textRef}
+          className="mt-3 max-h-32 overflow-y-auto whitespace-pre-wrap border-t border-border pt-3 text-xs leading-relaxed text-muted-foreground"
+        >
+          {job.text}
+        </div>
+      ) : null}
+    </section>
+  );
+}

package/src/cli.mjs

@@ -0,0 +1,301 @@
+// `npx makersclaw <command>` — parse the arguments, run the command in
+// src/install.mjs, say what happened. Text is written for a person or an
+// agent reading a terminal: short lines, what changed, what to run next.
+// --json is the same result as one object, for the platform.
+
+import { resolve } from "node:path";
+import { CliError, add, diff, init, remove, update } from "./install.mjs";
+import { loadItems, loadTemplate, packageInfo, readmeOf, searchItems, suggest, templateNames } from "./registry.mjs";
+
+const COMMANDS = {
+  init: "init",
+  add: "add",
+  remove: "remove",
+  rm: "remove",
+  search: "search",
+  find: "search",
+  view: "view",
+  show: "view",
+  list: "list",
+  ls: "list",
+  diff: "diff",
+  update: "update",
+  upgrade: "update",
+  help: "help",
+};
+
+const VALUE_FLAGS = new Map([
+  ["--cwd", "cwd"],
+  ["-t", "template"],
+  ["--template", "template"],
+  ["--type", "type"],
+  ["--limit", "limit"],
+]);
+const BOOL_FLAGS = new Map([
+  ["--json", "json"],
+  ["--force", "force"],
+  ["-f", "force"],
+  ["--major", "major"],
+  ["--adopt", "adopt"],
+  ["--yes", "yes"],
+  ["-y", "yes"],
+  ["--help", "help"],
+  ["-h", "help"],
+  ["--version", "version"],
+  ["-v", "version"],
+]);
+
+export function parseArgs(argv) {
+  const opts = { positionals: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const eq = arg.indexOf("=");
+    const flag = arg.startsWith("--") && eq > 0 ? arg.slice(0, eq) : arg;
+    if (VALUE_FLAGS.has(flag)) {
+      const value = eq > 0 && arg.startsWith("--") ? arg.slice(eq + 1) : argv[++i];
+      if (value === undefined) throw new CliError(`${flag} needs a value`);
+      opts[VALUE_FLAGS.get(flag)] = value;
+    } else if (BOOL_FLAGS.has(arg)) {
+      opts[BOOL_FLAGS.get(arg)] = true;
+    } else if (arg.startsWith("-") && arg !== "-") {
+      throw new CliError(`unknown option ${arg}`, "makersclaw help lists them");
+    } else {
+      opts.positionals.push(arg);
+    }
+  }
+  const [word, ...rest] = opts.positionals;
+  opts.command = word === undefined ? (opts.version ? "version" : "help") : COMMANDS[word] ?? word;
+  opts.args = rest;
+  return opts;
+}
+
+function helpText() {
+  const { version } = packageInfo();
+  return `makersclaw ${version} — the Makersclaw app template, its kit and its blocks
+
+  npx makersclaw init [dir] [-t next]     lay the template: base files, the kit, the check
+  npx makersclaw add <name...>            install blocks, or restore a kit component
+  npx makersclaw search <words...>        find blocks and components by what they do
+  npx makersclaw view <name>              one item: props, data, an example
+  npx makersclaw list [--type block]      everything in this version
+  npx makersclaw remove <block...>        uninstall blocks no file imports
+  npx makersclaw diff                     what update would change in this app
+  npx makersclaw update [--major]         lay this version's fixed files and blocks
+                     [--adopt]             …or take on an app laid before makersclaw (kit era)
+
+  --cwd <dir>   the app (default: this folder)       --json   one JSON object
+  --force       init over an app that exists (your own files stay)
+  templates: ${templateNames().join(", ")}`;
+}
+
+const clip = (text, n = 88) => {
+  const one = String(text ?? "").replace(/\s+/g, " ").trim();
+  return one.length > n ? `${one.slice(0, n - 1)}…` : one;
+};
+const plural = (n, word, many = `${word}s`) => `${n} ${n === 1 ? word : many}`;
+const listLine = (paths, n = 6) => (paths.length > n ? `${paths.slice(0, n).join(", ")} … +${paths.length - n}` : paths.join(", "));
+
+function packageLines(changes) {
+  if (!changes.length) return [];
+  return [`  package.json: ${changes.map((c) => `${c.name} ${c.from ?? "(new)"} → ${c.to}`).join(" · ")}`];
+}
+
+function layText(r, verb) {
+  const head =
+    verb === "update"
+      ? `makersclaw ${r.from ?? "?"} → ${r.version} · template ${r.template}`
+      : `makersclaw ${r.version} · template ${r.template}${r.from ? ` (was ${r.from})` : ""}`;
+  const lines = [head];
+  lines.push(
+    r.written.length
+      ? `  wrote ${plural(r.written.length, "file")}${verb === "init" && r.written.length > 8 ? "" : `: ${listLine(r.written)}`}`
+      : "  nothing to write — every file already matches this version",
+  );
+  if (r.kept.length) lines.push(`  kept yours: ${r.kept.join(", ")}`);
+  if (r.removed.length) lines.push(`  removed (no longer shipped): ${listLine(r.removed)}`);
+  if (r.blocks.length) lines.push(`  blocks: ${r.blocks.join(", ")}`);
+  lines.push(...packageLines(r.package));
+  lines.push(`  ${plural(r.pinned, "fixed file")} pinned in check/pins.json · makersclaw.json records ${r.version}`);
+  for (const n of r.notes) lines.push(`  note: ${n}`);
+  const next = [];
+  if (r.install) next.push("npm install");
+  if (verb === "init" && !r.from) next.push("design app/shell.jsx and the surfaces", "find blocks: npx makersclaw search <what the surface needs>");
+  else next.push("npm run check");
+  lines.push(`next: ${next.join(" · ")}`);
+  return lines.join("\n");
+}
+
+function addText(r) {
+  const lines = [];
+  for (const a of r.added) {
+    const where = a.type === "block" ? `components/blocks/${a.name}/` : a.files.join(", ");
+    const state = a.changed === 0 ? "already installed, unchanged" : `${plural(a.files.length, "file")} pinned`;
+    lines.push(`${a.requested ? "added" : "added (required)"} ${a.name} (${a.type}) → ${where} · ${state}`);
+    lines.push(`  ${a.import}`);
+  }
+  lines.push(...packageLines(r.package));
+  if (r.install) lines.push("next: npm install");
+  for (const u of r.usage) if (u.readme) lines.push("", u.readme.trimEnd());
+  return lines.join("\n");
+}
+
+function itemLine(item) {
+  return `  ${item.name.padEnd(18)} ${item.type.padEnd(10)} ${clip(item.description, 72)}`;
+}
+
+function searchText(query, matches) {
+  if (!matches.length) return `nothing matches "${query}" — npx makersclaw list shows everything`;
+  const lines = [`${plural(matches.length, "match", "matches")} for "${query}"`];
+  for (const { item } of matches) {
+    lines.push(itemLine(item));
+    lines.push(`  ${"".padEnd(29)} ${item.type === "block" ? `npx makersclaw add ${item.name}` : "in every app — import it"}`);
+  }
+  return lines.join("\n");
+}
+
+function viewText(item, readme) {
+  const { version } = packageInfo();
+  const head = `${item.name} · ${item.type} · makersclaw ${version}`;
+  if (readme) return `${head}\n\n${readme.trimEnd()}`;
+  const folder = item.type === "part" ? "parts" : "ui";
+  return [
+    head,
+    "",
+    `${item.title} — ${item.description}`,
+    `  file: ${item.files.map((f) => f.to).join(", ")} (every app has it; add ${item.name} restores it)`,
+    `  import { ${item.title.split(",")[0].trim()} } from "../components/${folder}";`,
+  ].join("\n");
+}
+
+function listText(items) {
+  const { version } = packageInfo();
+  const groups = [
+    ["component", "components — in every app (components/ui)"],
+    ["part", "parts — in every app, bound to the data layer (components/parts)"],
+    ["block", "blocks — add the one a surface needs (components/blocks/<name>)"],
+  ];
+  const lines = [`makersclaw ${version}`];
+  for (const [type, label] of groups) {
+    const of = items.filter((i) => i.type === type);
+    if (!of.length) continue;
+    lines.push("", label);
+    for (const i of of) lines.push(`  ${i.name.padEnd(18)} ${clip(i.description, 80)}`);
+  }
+  return lines.join("\n");
+}
+
+function diffText(r) {
+  const lines = [`makersclaw ${r.from} → ${r.to} · ${r.compatible ? "compatible" : "changes the contract — update --major"}`];
+  if (!r.entries.length && !r.package.length) {
+    lines.push(`  nothing to update — the app matches makersclaw ${r.to}`);
+    return lines.join("\n");
+  }
+  for (const e of r.entries) lines.push(`  ${e.item.padEnd(14)} ${e.status.padEnd(8)} ${e.path}${e.detail ? ` — ${e.detail}` : ""}`);
+  for (const c of r.package) lines.push(`  ${"package.json".padEnd(14)} ${c.key}.${c.name}: ${c.from ?? "(new)"} → ${c.to}`);
+  lines.push(`next: npx makersclaw update${r.compatible ? "" : " --major"}`);
+  return lines.join("\n");
+}
+
+function templateFor(opts, fallback = "next") {
+  const name = opts.template ?? fallback;
+  const tpl = loadTemplate(name);
+  if (!tpl) throw new CliError(`no template "${name}"`, `templates: ${templateNames().join(", ")}`);
+  return tpl;
+}
+
+/** Run one command. Returns { result, text } or throws a CliError. */
+export function run(opts) {
+  const cwd = resolve(opts.cwd ?? process.cwd());
+  switch (opts.command) {
+    case "help":
+      return { result: { help: helpText() }, text: helpText() };
+    case "version":
+      return { result: packageInfo(), text: packageInfo().version };
+    case "init": {
+      const dir = opts.args[0] ? resolve(cwd, opts.args[0]) : cwd;
+      const result = init(dir, { template: opts.template ?? "next", force: Boolean(opts.force) });
+      return { result: { dir, ...result }, text: layText(result, "init") };
+    }
+    case "update": {
+      const result = update(cwd, { major: Boolean(opts.major), adopt: Boolean(opts.adopt) });
+      return { result: { dir: cwd, ...result }, text: layText(result, "update") };
+    }
+    case "add": {
+      const result = add(cwd, opts.args);
+      return { result: { dir: cwd, ...result }, text: addText(result) };
+    }
+    case "remove": {
+      const result = remove(cwd, opts.args);
+      return {
+        result: { dir: cwd, ...result },
+        text: `removed ${opts.args.join(", ")} — ${plural(result.removed.length, "file")}; installed now: ${result.blocks.join(", ") || "no blocks"}`,
+      };
+    }
+    case "diff": {
+      const result = diff(cwd);
+      return { result: { dir: cwd, ...result }, text: diffText(result) };
+    }
+    case "search": {
+      const query = opts.args.join(" ").trim();
+      if (!query) throw new CliError("search needs words: what the surface has to do", 'npx makersclaw search "drag cards between stages"');
+      const items = loadItems(templateFor(opts));
+      const limit = opts.limit ? Math.max(1, Number(opts.limit) || 8) : 8;
+      const matches = searchItems(items, query, { type: opts.type, limit });
+      return {
+        result: { query, matches: matches.map(({ item, score }) => ({ ...summary(item), score })) },
+        text: searchText(query, matches),
+      };
+    }
+    case "view": {
+      const name = opts.args[0];
+      if (!name) throw new CliError("view needs a name", "npx makersclaw list shows every name");
+      const items = loadItems(templateFor(opts));
+      const item = items.find((i) => i.name === name);
+      if (!item) {
+        const close = suggest(items, name);
+        throw new CliError(`no block or component named "${name}"`, close.length ? `did you mean ${close.join(", ")}?` : "npx makersclaw search <words>");
+      }
+      const readme = readmeOf(item);
+      return { result: { item: summary(item), readme }, text: viewText(item, readme) };
+    }
+    case "list": {
+      const items = loadItems(templateFor(opts)).filter((i) => !opts.type || i.type === opts.type);
+      return { result: { version: packageInfo().version, items: items.map(summary) }, text: listText(items) };
+    }
+    default:
+      throw new CliError(`unknown command "${opts.command}"`, "makersclaw help lists them");
+  }
+}
+
+function summary(item) {
+  return {
+    name: item.name,
+    type: item.type,
+    title: item.title,
+    description: item.description,
+    useWhen: item.useWhen || undefined,
+    tags: item.tags,
+    requires: item.requires.length ? item.requires : undefined,
+    exports: item.exports?.length ? item.exports : undefined,
+    files: item.files.map((f) => f.to),
+  };
+}
+
+export function main(argv, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  let opts = { json: argv.includes("--json") };
+  try {
+    opts = parseArgs(argv);
+    if (opts.help && opts.command !== "help") opts = { ...opts, command: "help" };
+    const { result, text } = run(opts);
+    stdout.write(opts.json ? `${JSON.stringify({ ok: true, command: opts.command, ...result }, null, 2)}\n` : `${text}\n`);
+    return 0;
+  } catch (error) {
+    if (!(error instanceof CliError)) throw error;
+    if (opts.json) {
+      stdout.write(`${JSON.stringify({ ok: false, command: opts.command ?? null, error: error.message, next: error.next }, null, 2)}\n`);
+    } else {
+      stderr.write(`error: ${error.message}\n${error.next ? `next: ${error.next}\n` : ""}`);
+    }
+    return 1;
+  }
+}