monkeyshape 0.0.0-stage → 0.2.0

package/src/adapters/workspace.ts

@@ -0,0 +1,281 @@
+/** Loads the repo into a `Snapshot`: git's file list, the texts checks read, and what bd, tsc and biome report. */
+import { realpath, stat } from "node:fs/promises";
+import { posix } from "node:path";
+import { Effect } from "effect";
+import { parseJsonc } from "../core/coverage.ts";
+import { type Integration, isTsSource, type Snapshot } from "../core/model.ts";
+import type { ResolvedConfig } from "../schemas/config.ts";
+import { WorkspaceError } from "../schemas/errors.ts";
+import { run, runTool } from "./process.ts";
+import { loadSkills } from "./skills.ts";
+
+export const readText = (root: string, path: string) =>
+  Effect.tryPromise({
+    try: () => Bun.file(`${root}/${path}`).text(),
+    catch: (cause) => new WorkspaceError({ operation: "read", path, reason: String(cause) }),
+  });
+
+/** Files and directories alike: git lists a submodule as one entry, and it is a directory. */
+const exists = (root: string, path: string) =>
+  Effect.promise(() =>
+    stat(`${root}/${path}`).then(
+      () => true,
+      () => false,
+    ),
+  );
+
+const listFiles = (root: string) =>
+  Effect.gen(function* () {
+    const result = yield* run(root, [
+      "git",
+      "ls-files",
+      "--cached",
+      "--others",
+      "--exclude-standard",
+      "-z",
+    ]);
+    if (result.code !== 0)
+      return yield* Effect.fail(
+        new WorkspaceError({ operation: "list", path: root, reason: "not a git repository" }),
+      );
+    // Nested repositories and worktrees show up as a directory entry; they are not ours.
+    return result.stdout.split("\0").filter((file) => file !== "" && !file.endsWith("/"));
+  });
+
+type Loaded<A> = { readonly integration: Integration; readonly value: A | undefined };
+
+const failed = <A>(reason: string): Loaded<A> => ({
+  integration: { state: "failed", reason },
+  value: undefined,
+});
+
+const jsonRows = (stdout: string): ReadonlyArray<unknown> | undefined => {
+  const parsed = parseJsonc(stdout);
+  // `bd list --limit 0 --json` wraps the rows as `{ issues: [...] }`; limited lists are bare.
+  const rows =
+    typeof parsed === "object" && parsed !== null && "issues" in parsed ? parsed.issues : parsed;
+  return Array.isArray(rows) ? rows : undefined;
+};
+
+/** Whether bd can be asked: absent without `.beads/config.yaml`, unavailable without bd. */
+const beadsUnreachable = (root: string) =>
+  Effect.gen(function* () {
+    if (!(yield* exists(root, ".beads/config.yaml")))
+      return { state: "absent" } satisfies Integration;
+    if (Bun.which("bd") === null)
+      return { state: "unavailable", reason: "bd is not on PATH" } satisfies Integration;
+    return undefined;
+  });
+
+/**
+ * Every bead `bd list --all <filters> --json` prints, with the integration state `check` and
+ * `track` both read: absent, unavailable, failed (bd ran and failed, its stderr kept) or ok.
+ */
+export const beadRows = (root: string, filters: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const unreachable = yield* beadsUnreachable(root);
+    if (unreachable !== undefined)
+      return { integration: unreachable, value: undefined } satisfies Loaded<
+        ReadonlyArray<unknown>
+      >;
+    const command = ["bd", "list", "--all", ...filters, "--limit", "0", "--json"];
+    // A spawn that throws is bd failing to run: reported as failed, never an abort.
+    const result = yield* Effect.try(() =>
+      Bun.spawnSync(command, { cwd: root, stdout: "pipe", stderr: "pipe" }),
+    ).pipe(Effect.orElseSucceed(() => undefined));
+    const rows = result?.exitCode === 0 ? jsonRows(result.stdout.toString()) : undefined;
+    if (rows === undefined) {
+      const stderr = result?.stderr.toString().trim() ?? "";
+      return failed<ReadonlyArray<unknown>>(
+        `\`${command.join(" ")}\` exited ${result?.exitCode ?? "without running"} or printed no rows${stderr === "" ? "" : `: ${stderr}`}`,
+      );
+    }
+    return { integration: { state: "ok" }, value: rows } satisfies Loaded<ReadonlyArray<unknown>>;
+  });
+
+/** bd memories and every bead id. A repo without `.beads` is absent; bd missing is unavailable. */
+const beads = (root: string) =>
+  Effect.gen(function* () {
+    type Value = { memories: ReadonlyMap<string, string>; ids: ReadonlySet<string> };
+    const unreachable = yield* beadsUnreachable(root);
+    if (unreachable !== undefined)
+      return { integration: unreachable, value: undefined } satisfies Loaded<Value>;
+    const memories = yield* runTool(root, ["bd", "memories", "--json"]);
+    const parsedMemories = memories.code === 0 ? parseJsonc(memories.stdout) : undefined;
+    if (typeof parsedMemories !== "object" || parsedMemories === null)
+      return failed<Value>(`\`bd memories --json\` exited ${memories.code} or printed no object`);
+    const list = yield* beadRows(root, ["--brief", "--skip-labels"]);
+    const rows = list.value;
+    if (rows === undefined)
+      return { integration: list.integration, value: undefined } satisfies Loaded<Value>;
+    const value: Value = {
+      memories: new Map(
+        Object.entries(parsedMemories).filter(
+          (entry): entry is [string, string] => typeof entry[1] === "string",
+        ),
+      ),
+      ids: new Set(
+        rows.flatMap((issue) =>
+          typeof issue === "object" &&
+          issue !== null &&
+          "id" in issue &&
+          typeof issue.id === "string"
+            ? [issue.id]
+            : [],
+        ),
+      ),
+    };
+    return { integration: { state: "ok" }, value } satisfies Loaded<Value>;
+  });
+
+/**
+ * A tool installed in the repo, as a command. Run through the current bun: the bin shims
+ * start with `#!/usr/bin/env node`, and a Bun-only machine has no node.
+ */
+const localBin = (root: string, name: string) =>
+  Effect.map(exists(root, `node_modules/.bin/${name}`), (found) =>
+    found ? [process.execPath, `${root}/node_modules/.bin/${name}`] : undefined,
+  );
+
+/**
+ * The tsconfigs a project's references point at. A reference names a tsconfig file or a
+ * directory holding `tsconfig.json`; references are not inherited through `extends`, so the
+ * file's own JSON is the whole answer. Unreadable files yield none; tsc reports them itself.
+ */
+const referencesOf = (root: string, tsconfig: string) =>
+  Effect.gen(function* () {
+    const text = yield* readText(root, tsconfig).pipe(Effect.orElseSucceed(() => "{}"));
+    const parsed = parseJsonc(text);
+    const references =
+      typeof parsed === "object" && parsed !== null && "references" in parsed
+        ? parsed.references
+        : undefined;
+    if (!Array.isArray(references)) return [];
+    const out: Array<string> = [];
+    for (const reference of references) {
+      if (typeof reference !== "object" || reference === null || !("path" in reference)) continue;
+      if (typeof reference.path !== "string") continue;
+      const target = posix.normalize(posix.join(posix.dirname(tsconfig), reference.path));
+      const isDirectory = yield* Effect.promise(() =>
+        stat(`${root}/${target}`).then(
+          (info) => info.isDirectory(),
+          () => false,
+        ),
+      );
+      out.push(isDirectory ? posix.join(target, "tsconfig.json") : target);
+    }
+    return out;
+  });
+
+/**
+ * The union of every configured tsconfig's program and, transitively, of every project it
+ * references, as tsc itself resolves each one. `tsc -p` checks one project and `--build`
+ * won't list files, so the reference graph is walked here, each project once.
+ */
+const typechecked = (root: string, realRoot: string, tsconfigs: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const tsc = yield* localBin(root, "tsc");
+    if (tsc === undefined)
+      return {
+        integration: { state: "unavailable", reason: "typescript is not installed" },
+        value: undefined,
+      } satisfies Loaded<ReadonlySet<string>>;
+    const files = new Set<string>();
+    const seen = new Set<string>();
+    const queue = tsconfigs.map((tsconfig) => posix.normalize(tsconfig));
+    for (let tsconfig = queue.shift(); tsconfig !== undefined; tsconfig = queue.shift()) {
+      if (seen.has(tsconfig)) continue;
+      seen.add(tsconfig);
+      const result = yield* runTool(root, [...tsc, "-p", tsconfig, "--listFilesOnly"]);
+      if (result.code !== 0)
+        return failed<ReadonlySet<string>>(
+          `\`tsc -p ${tsconfig} --listFilesOnly\` exited ${result.code}`,
+        );
+      for (const line of result.stdout.split("\n"))
+        if (line.startsWith(`${realRoot}/`)) files.add(line.slice(realRoot.length + 1));
+      queue.push(...(yield* referencesOf(root, tsconfig)));
+    }
+    return { integration: { state: "ok" }, value: files } satisfies Loaded<ReadonlySet<string>>;
+  });
+
+/** The files biome processes, from its verbose report, with `extends` and ignores resolved. */
+const linted = (root: string) =>
+  Effect.gen(function* () {
+    const biome = yield* localBin(root, "biome");
+    if (biome === undefined)
+      return {
+        integration: { state: "unavailable", reason: "@biomejs/biome is not installed" },
+        value: undefined,
+      } satisfies Loaded<ReadonlySet<string>>;
+    const result = yield* runTool(root, [
+      ...biome,
+      "lint",
+      "--verbose",
+      "--colors=off",
+      "--max-diagnostics=0",
+      ".",
+    ]);
+    const report = result.stdout.split("Files processed:")[1];
+    if (report === undefined)
+      return failed<ReadonlySet<string>>(
+        `\`biome lint --verbose\` printed no "Files processed:" list (exit ${result.code})`,
+      );
+    const files = new Set(
+      report.split("\n").flatMap((line) => {
+        const match = /^\s+- (.+)$/.exec(line);
+        return match?.[1] === undefined ? [] : [match[1].trim()];
+      }),
+    );
+    return { integration: { state: "ok" }, value: files } satisfies Loaded<ReadonlySet<string>>;
+  });
+
+/** `shippedSkills` is the running monkeyshape's `skills/`, to tell whether a sync is due. */
+export const loadSnapshot = (root: string, config: ResolvedConfig, shippedSkills: string) =>
+  Effect.gen(function* () {
+    const listed = yield* listFiles(root);
+    // A file deleted but not yet staged is still listed; it isn't part of the repo now.
+    const found = yield* Effect.forEach(listed, (file) => exists(root, file), { concurrency: 32 });
+    const present = listed.filter((_, i) => found[i] === true);
+    const configs = new Set([...config.coverage.tsconfigs, config.coverage.biome, "package.json"]);
+    const wanted = present.filter(
+      (file) => isTsSource(file) || file.endsWith(".md") || configs.has(file),
+    );
+    const texts = new Map(
+      yield* Effect.forEach(
+        wanted,
+        (file) => Effect.map(readText(root, file), (text) => [file, text] as const),
+        {
+          concurrency: 32,
+        },
+      ),
+    );
+    const manifest = parseJsonc(texts.get("package.json") ?? "{}");
+    const scripts =
+      typeof manifest === "object" &&
+      manifest !== null &&
+      "scripts" in manifest &&
+      typeof manifest.scripts === "object"
+        ? Object.keys(manifest.scripts ?? {})
+        : [];
+    const realRoot = yield* Effect.promise(() => realpath(root));
+    const loadedBeads = yield* beads(root);
+    const loadedTsc = yield* typechecked(root, realRoot, config.coverage.tsconfigs);
+    const loadedBiome = yield* linted(root);
+    const skills = yield* loadSkills(shippedSkills, root);
+    const snapshot: Snapshot = {
+      files: present,
+      texts,
+      packageScripts: new Set(scripts),
+      memories: loadedBeads.value?.memories,
+      beadIds: loadedBeads.value?.ids,
+      typechecked: loadedTsc.value,
+      linted: loadedBiome.value,
+      integrations: {
+        beads: loadedBeads.integration,
+        tsc: loadedTsc.integration,
+        biome: loadedBiome.integration,
+      },
+      skills,
+    };
+    return snapshot;
+  });

package/src/api/monkeyshape.ts

@@ -0,0 +1,8 @@
+/** The public surface: what an adopter imports from `monkeyshape`. */
+import type { ShapeConfig } from "../schemas/config.ts";
+
+export { decodeStrict } from "../helpers/decodeStrict.ts";
+export type { Allowance, ModuleRule, ShapeConfig } from "../schemas/config.ts";
+
+/** Identity, for type-checking `shape.config.ts`: `export default defineConfig({ ... })`. */
+export const defineConfig = (config: ShapeConfig): ShapeConfig => config;

package/src/cli/main.ts

@@ -0,0 +1,359 @@
+#!/usr/bin/env bun
+/** The `mshape` executable: the composition root, and the only place effects are run. */
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Effect } from "effect";
+import pkg from "../../package.json" with { type: "json" };
+import { BASELINE_FILE, readBaseline, writeBaseline } from "../adapters/baseline.ts";
+import { loadConfig } from "../adapters/config.ts";
+import { initRepo } from "../adapters/init.ts";
+import { reviewNew, reviewRm } from "../adapters/reviews.ts";
+import { installSkills } from "../adapters/skills.ts";
+import { trackCurrent, trackList, trackNew, trackRm } from "../adapters/tracks.ts";
+import { loadSnapshot } from "../adapters/workspace.ts";
+import { CHECKS, notices, prerequisites, runChecks, unevaluated } from "../core/check.ts";
+import { garden } from "../core/garden.ts";
+import { CLAUDE_SKILLS_LINK } from "../core/layout.ts";
+import type { CheckName } from "../core/model.ts";
+import { applyBaseline, count, tighten } from "../core/ratchet.ts";
+import { formatCheck, formatGarden, formatViolation } from "../core/report.ts";
+import { RULES } from "../core/rules/registry.ts";
+import { nextStep, REPO_NAME } from "../core/scaffold.ts";
+import { formatCollisions, formatSync } from "../core/skills.ts";
+import type { ConfigError, TrackError, WorkspaceError } from "../schemas/errors.ts";
+
+/** What a command returns: the text to print, and the exit code (0 prints to stdout). */
+interface Outcome {
+  readonly output: string;
+  readonly code: number;
+}
+
+/**
+ * One `mshape` command. A new command is one entry in `COMMANDS`, and the help is generated
+ * from the table, so a command can't ship without its usage and no two tracks edit one switch.
+ */
+interface Command {
+  readonly name: string;
+  /** Its lines in the help: each form indented two spaces, what it does six. */
+  readonly usage: string;
+  readonly run: (
+    root: string,
+    args: ReadonlyArray<string>,
+  ) => Effect.Effect<Outcome, ConfigError | WorkspaceError | TrackError>;
+}
+
+const FLAGS = `  --config <path>   For check, baseline and garden: use this config instead of ./shape.config.ts
+                    (trying a repo before adopting).`;
+
+/** Every command's usage, in table order. A function, since the table is declared below. */
+export const help = (): string =>
+  [`mshape ${pkg.version}`, "", ...COMMANDS.map((command) => command.usage), "", FLAGS].join("\n");
+
+const usage = (): Outcome => ({ output: help(), code: 2 });
+
+const parseOnly = (args: ReadonlyArray<string>): ReadonlyArray<CheckName> | string => {
+  const index = args.indexOf("--only");
+  if (index === -1) return CHECKS;
+  const names = (args[index + 1] ?? "").split(",").filter(Boolean);
+  const unknown = names.filter((name) => !(CHECKS as ReadonlyArray<string>).includes(name));
+  return unknown.length > 0 || names.length === 0
+    ? `unknown check(s): ${unknown.join(", ") || "(none given)"}`
+    : (names as ReadonlyArray<CheckName>);
+};
+
+/** The package's own directory: `template/` and `skills/` ship beside `src/`. */
+const PACKAGE_ROOT = fileURLToPath(new URL("../..", import.meta.url)).replace(/\/$/, "");
+
+const WORKFLOW_URL = `${pkg.homepage.replace(/#.*$/, "")}/blob/main/docs/workflow.md`;
+
+const init = (root: string, args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const fromFlag = args.indexOf("--from");
+    const from = fromFlag === -1 ? undefined : args[fromFlag + 1];
+    // A forgotten value would silently install from the registry, which --from exists to avoid.
+    if (fromFlag !== -1 && (from === undefined || from.startsWith("--")))
+      return {
+        output: "mshape init: --from needs a value: a tarball path or a spec bun install accepts",
+        code: 2,
+      };
+    const positional = args.filter(
+      (_, i) => fromFlag === -1 || (i !== fromFlag && i !== fromFlag + 1),
+    );
+    const [name, ...extra] = positional;
+    if (name === undefined || !REPO_NAME.test(name) || extra.length > 0)
+      return {
+        output: `mshape init: give the new repo's name in lowercase words joined by hyphens, e.g. \`mshape init my-app\` (got ${positional.length === 0 ? "nothing" : positional.map((arg) => `'${arg}'`).join(" ")})`,
+        code: 2,
+      };
+    // A bare path is a tarball; bun would resolve it from the new repo, not from here.
+    const spec = from === undefined || from.includes(":") ? from : `file:${resolve(root, from)}`;
+    const dev = pkg.devDependencies;
+    const result = yield* initRepo(`${root}/${name}`, name, PACKAGE_ROOT, {
+      bun: Bun.version,
+      monkeyshape: spec ?? pkg.version,
+      effect: dev.effect,
+      biome: dev["@biomejs/biome"],
+      typescript: dev.typescript,
+      typesBun: dev["@types/bun"],
+    });
+    return {
+      output: [
+        `Created ${name}/: ${result.done.join(", ")}.`,
+        ...result.notes.map((note) => `note: ${note}`),
+        "",
+        nextStep(name, WORKFLOW_URL),
+      ].join("\n"),
+      code: 0,
+    };
+  });
+
+/** Today in local time, `YYYY-MM-DD`: the date a new handoff's State carries. */
+const today = (): string => {
+  const now = new Date();
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+};
+
+const track = (root: string, args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const [sub, ...rest] = args;
+    const flags = rest.filter((arg) => arg.startsWith("--"));
+    const names = rest.filter((arg) => !arg.startsWith("--"));
+    const allowed = sub === "rm" ? ["--force", "--keep-handoff"] : [];
+    const takesName = sub === "new" || sub === "rm";
+    if (flags.some((flag) => !allowed.includes(flag))) return usage();
+    if (names.length !== (takesName ? 1 : 0)) return usage();
+    const name = names[0] ?? "";
+    if (sub === "new") return { output: yield* trackNew(root, name, today()), code: 0 };
+    if (sub === "list") return { output: yield* trackList(root), code: 0 };
+    if (sub === "current") return { output: yield* trackCurrent(root), code: 0 };
+    if (sub === "rm")
+      return {
+        output: yield* trackRm(
+          root,
+          name,
+          {
+            force: flags.includes("--force"),
+            keepHandoff: flags.includes("--keep-handoff"),
+            // rm fetches main's upstream; with no terminal to answer, a prompt would hang it.
+            fetchEnv: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+          },
+          (line) => Effect.sync(() => console.error(line)),
+        ),
+        code: 0,
+      };
+    return usage();
+  });
+
+const review = (root: string, args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    if (args.length === 1 && args[0] !== "rm")
+      return {
+        output: yield* reviewNew(root, args[0] ?? "", (line) =>
+          Effect.sync(() => console.error(line)),
+        ),
+        code: 0,
+      };
+    if (args.length === 2 && args[0] === "rm")
+      return {
+        output: yield* reviewRm(root, args[1] ?? "", (line) =>
+          Effect.sync(() => console.error(line)),
+        ),
+        code: 0,
+      };
+    return usage();
+  });
+
+const skills = (root: string, args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    if (args[0] !== "sync") return usage();
+    const { sync, linked } = yield* installSkills(`${PACKAGE_ROOT}/skills`, root);
+    return {
+      output: [
+        formatSync(sync),
+        ...(linked ? [`${CLAUDE_SKILLS_LINK}: linked`] : []),
+        ...formatCollisions(sync),
+      ].join("\n"),
+      code: sync.collisions.length > 0 ? 1 : 0,
+    };
+  });
+
+/** What `check`, `baseline` and `garden` all read: the config, the snapshot, the baseline. */
+const load = (root: string, args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const configFlag = args.indexOf("--config");
+    const configPath = configFlag === -1 ? undefined : args[configFlag + 1];
+    const config = yield* loadConfig(
+      root,
+      configPath === undefined
+        ? undefined
+        : configPath.startsWith("/")
+          ? configPath
+          : `${root}/${configPath}`,
+    );
+    const snapshot = yield* loadSnapshot(root, config, `${PACKAGE_ROOT}/skills`);
+    const baseline = yield* readBaseline(root);
+    return { config, snapshot, baseline };
+  });
+
+const check = (root: string, args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const { config, snapshot, baseline } = yield* load(root, args);
+    const blocked = prerequisites(config, snapshot);
+    const only = parseOnly(args);
+    if (typeof only === "string") return { output: only, code: 2 };
+    const ratcheted = applyBaseline(
+      runChecks(config, snapshot, only),
+      baseline,
+      unevaluated(snapshot, only, Object.keys(baseline)),
+    );
+    const result = { ...ratcheted, failing: [...blocked, ...ratcheted.failing] };
+    const said = notices(config, snapshot).map((notice) => `note: ${notice}`);
+    return {
+      output: [...said, formatCheck(result)].join("\n"),
+      code: result.failing.length + result.loose.length > 0 ? 1 : 0,
+    };
+  });
+
+const baseline = (root: string, args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const loaded = yield* load(root, args);
+    const { config, snapshot } = loaded;
+    const blocked = prerequisites(config, snapshot);
+    // A baseline written without a required integration would grandfather an incomplete count.
+    if (blocked.length > 0)
+      return {
+        output: [
+          ...blocked.map(formatViolation),
+          "mshape baseline: not written, because a prerequisite fails",
+        ].join("\n\n"),
+        code: 1,
+      };
+    const violations = runChecks(config, snapshot);
+    if (args.includes("--init")) {
+      yield* writeBaseline(root, count(violations));
+      return {
+        output: `${BASELINE_FILE}: grandfathered ${violations.length} violation(s)`,
+        code: 0,
+      };
+    }
+    if (args.includes("--tighten")) {
+      yield* writeBaseline(root, tighten(loaded.baseline, violations, unevaluated(snapshot)));
+      return { output: `${BASELINE_FILE}: tightened`, code: 0 };
+    }
+    return usage();
+  });
+
+const gardenCommand = (root: string, args: ReadonlyArray<string>) =>
+  Effect.map(load(root, args), ({ config, snapshot, baseline }) => ({
+    output: formatGarden(garden(config, snapshot, baseline)),
+    code: 0,
+  }));
+
+const rules = () =>
+  Effect.succeed({
+    output: RULES.map((r) => `${r.id.padEnd(22)}${r.layer.padEnd(9)}${r.bugClass}`).join("\n"),
+    code: 0,
+  });
+
+/** Every command, in the order the help lists them. */
+export const COMMANDS: ReadonlyArray<Command> = [
+  {
+    name: "init",
+    usage: `  mshape init <name> [--from <spec>]
+      Create ./<name>: a new repo whose gate passes, with one starter test. --from installs
+      monkeyshape from <spec> (a tarball path) instead of the registry, to try a release first.`,
+    run: init,
+  },
+  {
+    name: "skills",
+    usage: `  mshape skills sync
+      Refresh the shared skills in .agents/skills from the installed package, after a bump.
+      Skills the package doesn't ship are the repo's own and are left alone.`,
+    run: skills,
+  },
+  {
+    name: "check",
+    usage: `  mshape check [--only arch,refs,budgets,coverage,rules,skills]
+      Run the checks; violations above .shape/baseline.json fail.`,
+    run: check,
+  },
+  {
+    name: "baseline",
+    usage: `  mshape baseline --tighten
+      Lower baseline counts to what is found now. Never raises one.
+  mshape baseline --init
+      Grandfather every current violation. For adopting a repo; review the diff.`,
+    run: baseline,
+  },
+  {
+    name: "garden",
+    usage: `  mshape garden
+      Print budgets and escape hatches for the milestone-boundary sweep.`,
+    run: gardenCommand,
+  },
+  {
+    name: "rules",
+    usage: `  mshape rules
+      List the custom rules and the bug class each one removes.`,
+    run: rules,
+  },
+  {
+    name: "track",
+    usage: `  mshape track new <name>
+      Start a track: worktree .agents/worktrees/<repo>@<name> on track/<name> from main,
+      the shared handoffs and tracks.sharedPaths linked in, and a stub handoff. Shared paths
+      come from the main checkout's shape.config.ts, from whichever checkout this runs.
+  mshape track list
+      Every track: handoff status, open beads, commits in neither main nor origin/main,
+      worktree. Restores missing handoff links; a track label with open beads and no track
+      left is listed too. Offline: run git fetch to see merges done on the remote.
+  mshape track current
+      The track of this directory, name only; exit 1, saying why, outside a track.
+  mshape track rm <name> [--force] [--keep-handoff]
+      Remove a finished track: worktree, branch, handoff. Fetches main's upstream first, then
+      refuses on uncommitted changes or work in neither main nor origin/main (by merge,
+      rebase or squash); --force discards them. Also refuses while beads labelled
+      track:<name> aren't closed, which --force doesn't override. Never touches main or other tracks.`,
+    run: track,
+  },
+  {
+    name: "review",
+    usage: `  mshape review <n>
+      Pull request <n>'s head from origin in a detached worktree .agents/worktrees/<repo>.pr-<n>,
+      tracks.sharedPaths linked in. Again later: put it exactly at the new head, printing the
+      old one; edits to tracked files there are listed, then discarded.
+  mshape review rm <n>
+      Remove that worktree, listing what it discards, and its fetched ref. Never the shared data.`,
+    run: review,
+  },
+];
+
+const HELP: ReadonlyArray<string | undefined> = [undefined, "help", "--help"];
+
+export const program = (root: string, args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const [name, ...rest] = args;
+    if (name === "--version") return { output: pkg.version, code: 0 };
+    if (HELP.includes(name)) return { output: help(), code: 0 };
+    const command = COMMANDS.find((entry) => entry.name === name);
+    if (command === undefined)
+      return { output: `mshape: unknown command '${name}'\n\n${help()}`, code: 2 };
+    return yield* command.run(root, rest);
+  });
+
+// Only as the executable: tests import the table and the help without running a command.
+if (import.meta.main) {
+  const outcome = await Effect.runPromise(
+    program(process.cwd(), process.argv.slice(2)).pipe(
+      Effect.catchTags({
+        ConfigError: (error) => Effect.succeed({ output: `mshape: ${error.message}`, code: 2 }),
+        WorkspaceError: (error) => Effect.succeed({ output: `mshape: ${error.message}`, code: 2 }),
+        TrackError: (error) => Effect.succeed({ output: `mshape: ${error.message}`, code: 1 }),
+      }),
+    ),
+  );
+  if (outcome.code === 0) console.log(outcome.output);
+  else console.error(outcome.output);
+  process.exitCode = outcome.code;
+}