archstrict 0.0.0 → 0.1.0

package/README.md

@@ -1,3 +1,64 @@
-# archstrict
+# 🧱 archstrict
 
-Reserved. Nothing is published here yet.
+[![npm version](https://img.shields.io/npm/v/archstrict?logo=npm)](https://www.npmjs.com/package/archstrict)
+
+arch is architecture, not tsc, not eslint, not a type checker: module boundary checking.
+Not archetype.
+
+TypeScript module boundary checking, in the sense of ArchUnit (Java) and archspec (Ruby): a module is one directory declared explicitly in config, it shows the rest of the codebase one public-surface file, and everything else inside it is private.
+
+See [AGENTS.md](AGENTS.md) for the shape, the rules, and the commands, and [skills/archstrict/SKILL.md](skills/archstrict/SKILL.md) for the workflow.
+
+## Install
+
+```sh
+npm install --save-dev archstrict
+```
+
+This puts a real `archstrict` binary at `node_modules/.bin/archstrict` in your project - the exact path the PreToolUse and PostToolUse hooks (see [hook.md](skills/archstrict/references/hook.md)) check for before previewing and confirming a change on your behalf around an edit. The install also carries the agent skill (`skills/archstrict/SKILL.md` and `skills/archstrict/references/`), `llms.txt`, and `.agents/` (the plugin manifest, the two hooks, and the MCP server) into `node_modules/archstrict/`. npm omits the checkout's symlinks (`.claude-plugin/plugin.json`, `hooks/`, `mcp/`), so the installed hooks are `node_modules/archstrict/.agents/hooks/pre-tool-use.mjs` and `post-tool-use.mjs`, and the installed MCP server is `node_modules/archstrict/.agents/mcp/server.mjs`. A git checkout still loads as a Claude Code plugin through those symlinks.
+
+### Installing from a local checkout
+
+Use one of these instead when working against an unpublished checkout of this repository.
+
+1. **`npm link`, from a local checkout on the same machine.**
+
+   ```sh
+   # in this checkout
+   npm run build   # if dist/ is missing or stale
+   npm link
+
+   # in the project you want to check
+   npm link archstrict
+   ```
+
+   `npm unlink archstrict` in the target project removes it again.
+
+2. **A `file:` dependency on a local checkout**, when you want the dependency recorded in the target's own `package.json` instead of a global link:
+
+   ```json
+   "archstrict": "file:../archstrict"
+   ```
+
+   `npm install` turns this into a symlink to the checkout, the same way `npm link` does, and runs no build step. Run `npm run build` in the checkout before running `npm install` in the target project - a symlinked `file:` dependency does not run the checkout's lifecycle scripts, so its `prepare` script never builds it. If you already installed before building, rerun `npm install` in the target project afterward, so it links the binary now that `dist/` exists.
+
+3. **A git dependency** (`"archstrict": "github:<owner>/archstrict#<ref>"`), for a machine that cannot reach this checkout but can read the repository over git. `dist/` is not committed; npm installs the package's devDependencies and runs its `prepare` script (`npm run build`) after cloning, which builds `dist/`. Two conditions apply:
+   - The installing machine must be able to read the repository. An agent whose access covers only the repository it runs in gets a 404 here; use mode 4 instead.
+   - Lifecycle scripts must be enabled. With `ignore-scripts=true` in the npm config, `prepare` never runs and the install has no `dist/`, so `node_modules/.bin/archstrict` points at a missing file. Pass `--ignore-scripts=false` for this install, or use mode 4.
+
+4. **A tarball from `npm pack`**, copied to the target machine - the mode that works where the target has no access to this repository at all (for example, an agent whose access covers only the repository it runs in):
+
+   ```sh
+   # in this checkout
+   npm run build
+   npm pack   # writes archstrict-<version>.tgz
+
+   # copy the tarball to the target machine, then in the target project
+   npm install ./archstrict-<version>.tgz
+   ```
+
+   `npm pack` packs the checkout's working tree, not its git history, so it needs `dist/` already built. Confirmed by running it: the tarball contains `dist/`, `skills/`, `llms.txt`, `.agents/`, `README.md`, `README.ja.md`, `CHANGELOG.md`, `docs/`, `AGENTS.md`, `LICENSE`, and `package.json` - the same set `npm link` and the `file:` mode expose, plus the packaging itself.
+
+---
+
+[Japanese](README.ja.md)

package/dist/augmentation-cache.js

@@ -0,0 +1,65 @@
+// Responsibility: store the lazy module-augmentation scan for TypeScript
+// files outside analysis. Each absolute file path owns one validated entry.
+// Boundary: this module does not list, read, parse, or resolve project files.
+// The caller supplies scan results and treats every cache failure as a miss.
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+// An unknown shape is a silent miss. Trying to decode an older shape is
+// refused because a stale negative answer can suppress a required fallback.
+export const AUGMENTATION_CACHE_SCHEMA = 1;
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isMode(value) {
+    return value === undefined || (typeof value === "number" && Number.isInteger(value));
+}
+function isSpecifier(value) {
+    return record(value) && typeof value.specifier === "string" && isMode(value.mode);
+}
+function isEntry(value) {
+    return record(value) && typeof value.mtimeMs === "number" && Number.isFinite(value.mtimeMs) &&
+        typeof value.size === "number" && Number.isFinite(value.size) &&
+        typeof value.optionsHash === "string" && isMode(value.impliedNodeFormat) &&
+        Array.isArray(value.specifiers) && value.specifiers.every(isSpecifier);
+}
+// Invalid content is a cache miss. Reporting cache damage is refused because
+// the scan result remains available from the project files themselves.
+export function readAugmentationCache(path, archstrictVersion) {
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (!record(value) || value.schema !== AUGMENTATION_CACHE_SCHEMA ||
+        value.archstrictVersion !== archstrictVersion || !record(value.files) ||
+        !Object.values(value.files).every(isEntry))
+        return undefined;
+    const entries = value.files;
+    const files = Object.fromEntries(Object.entries(entries).map(([file, entry]) => [file, {
+            ...entry,
+            // JSON omits an undefined mode. Restoring the field is required because
+            // callers use the same exact shape that the syntax scanner returns.
+            specifiers: entry.specifiers.map((item) => ({ specifier: item.specifier, mode: item.mode })),
+        }]));
+    return { schema: AUGMENTATION_CACHE_SCHEMA, archstrictVersion, files };
+}
+// A temporary file keeps a killed writer from leaving partial JSON. Direct
+// writes are refused because a later scoped check must treat the cache atomically.
+export function writeAugmentationCache(path, archstrictVersion, files) {
+    const dir = dirname(path);
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(temp, JSON.stringify({ schema: AUGMENTATION_CACHE_SCHEMA, archstrictVersion, files }));
+        renameSync(temp, path);
+    }
+    finally {
+        try {
+            rmSync(temp);
+        }
+        catch { /* A successful rename already removes it. */ }
+    }
+}

package/dist/check-options.js

@@ -0,0 +1,40 @@
+// Responsibility: parse the check verb's command-line options.
+// Boundary: rule and module existence depend on the loaded project and are validated by check().
+import { ReportError } from "./report-error.js";
+export function parseCheckArgv(argv) {
+    const positional = [];
+    const rules = [];
+    const modules = [];
+    let asJson = false;
+    let prove = false;
+    let frozen = false;
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg === "--json") {
+            asJson = true;
+        }
+        else if (arg === "--prove") {
+            prove = true;
+        }
+        else if (arg === "--frozen") {
+            frozen = true;
+        }
+        else if (arg === "--rule" || arg === "--module") {
+            const value = argv[++index];
+            if (value === undefined || value.startsWith("--")) {
+                throw new ReportError(`${arg} requires a value`, "archstrict check [file] [--rule <id>] [--module <name>]");
+            }
+            (arg === "--rule" ? rules : modules).push(value);
+        }
+        else if (arg.startsWith("-")) {
+            throw new ReportError(`unknown option '${arg}'`, "archstrict check [file] [--rule <id>] [--module <name>]");
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    if (positional.length > 1) {
+        throw new ReportError("check takes at most one file", "archstrict check [file] [--rule <id>] [--module <name>]");
+    }
+    return { asJson, prove, frozen, focusFile: positional[0], rules, modules };
+}

package/dist/classify.js

@@ -0,0 +1,148 @@
+// Responsibility: turn a config's `classify` (glob -> tags) and
+// `classifyByDirectoryName` (ambient, name-based) entries into the tag set a
+// given file carries. Boundary: no edge-constraint logic here (that's
+// tickets 4+); this module only answers "what tags does this file have."
+//
+// Precedence for two `classify` entries that both match the same file:
+// most-specific wins, where specificity is (a) the glob's literal prefix
+// length (the text before its first wildcard character), then (b) fewest
+// wildcard characters. This makes config order irrelevant - the property a
+// coding agent depends on when it can't see how a config it's editing was
+// originally ordered. A tie (identical specificity, different tags) is a
+// config error: two equally-specific entries disagreeing about the same
+// file is not something precedence can resolve for you.
+//
+// `classify` and `classifyByDirectoryName` are independent mechanisms whose
+// results union: a file can get tags from an explicit glob AND an ambient
+// directory-name match at once (VS Code's own env:* tags are pure ambient;
+// Prisma's are pure explicit; nothing requires a project pick only one).
+import { sep } from "node:path";
+import { ReportError } from "./report-error.js";
+// Converts one glob into a matcher plus its specificity. Supports `**`
+// (any number of path segments, including zero) and `*` (any characters
+// within one path segment - no `/`). Anything else in the pattern is a
+// literal character, escaped for use in a RegExp. Exported: declared-module
+// membership (module-graph.ts) uses the same precedence rule as tag
+// classification does, and shouldn't reimplement it.
+// Every per-file caller (mostSpecificMatch, for declared-module membership
+// and tag classification; the exclude-glob check and the .d.ts surface
+// check in isEligibleSourceFileWithDtsGlobs) recompiles the same fixed,
+// small set of config globs once per candidate file - O(files * globs)
+// RegExp construction on a large codebase. A glob's own compiled form
+// depends only on its literal text, so caching by that text is exact, not
+// approximate: the same string always compiles to the same matcher.
+const compiledGlobCache = new Map();
+export function compileGlob(glob) {
+    const cached = compiledGlobCache.get(glob);
+    if (cached !== undefined)
+        return cached;
+    const compiled = compileGlobUncached(glob);
+    compiledGlobCache.set(glob, compiled);
+    return compiled;
+}
+function compileGlobUncached(glob) {
+    const firstWildcard = glob.search(/\*/);
+    const literalPrefixLength = firstWildcard === -1 ? glob.length : firstWildcard;
+    const wildcardCount = (glob.match(/\*/g) ?? []).length;
+    let pattern = "";
+    let i = 0;
+    while (i < glob.length) {
+        if (glob.startsWith("/**/", i)) {
+            // `a/**/b.ts` must match `a/b.ts` too (zero segments between the two
+            // literal slashes), not just `a/x/b.ts` - translating `**` to `.*` in
+            // isolation while keeping both surrounding slashes as literals would
+            // require at least one segment. Fold the trailing slash into an
+            // optional group instead: one literal slash, then an optional
+            // "anything, ending in a slash" group.
+            pattern += "/(?:.*/)?";
+            i += 4;
+        }
+        else if (glob.startsWith("**", i)) {
+            pattern += ".*";
+            i += 2;
+        }
+        else if (glob[i] === "*") {
+            pattern += "[^/]*";
+            i += 1;
+        }
+        else {
+            pattern += glob[i].replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+            i += 1;
+        }
+    }
+    const re = new RegExp(`^${pattern}$`);
+    return { test: (path) => re.test(path), literalPrefixLength, wildcardCount };
+}
+// A path is more specific than another when its literal prefix is longer,
+// or (tied) it has fewer wildcards. Returns 0 for a genuine tie: same
+// literal-prefix length AND same wildcard count - the config-error case.
+function compareSpecificity(a, b) {
+    if (a.literalPrefixLength !== b.literalPrefixLength) {
+        return a.literalPrefixLength - b.literalPrefixLength;
+    }
+    return b.wildcardCount - a.wildcardCount; // fewer wildcards = more specific
+}
+export class AmbiguousClassifyError extends ReportError {
+    constructor(path, glob1, glob2) {
+        super(`'${path}' matches two equally-specific entries ('${glob1}' and '${glob2}') with no way to prefer one - narrow one of the globs`, `narrow '${glob1}' or '${glob2}' in archstrict.config.ts, then run archstrict check`);
+        this.name = "AmbiguousClassifyError";
+    }
+}
+// Shared precedence engine: the most-specific of several glob-keyed entries
+// matching `path` wins, config order is irrelevant, and a genuine tie
+// (equal specificity, different `value`s per `sameValue`) throws. Used both
+// for tag classification (`value` is a tag array) and declared-module
+// membership (`value` is a module name) - two different callers, one
+// precedence rule, so they can't quietly drift apart.
+export function mostSpecificMatch(path, entries, sameValue) {
+    let best;
+    for (const entry of entries) {
+        const compiled = compileGlob(entry.glob);
+        if (!compiled.test(path))
+            continue;
+        if (best === undefined) {
+            best = { value: entry.value, glob: entry.glob, ...compiled };
+            continue;
+        }
+        const cmp = compareSpecificity(compiled, best);
+        if (cmp > 0) {
+            best = { value: entry.value, glob: entry.glob, ...compiled };
+        }
+        else if (cmp === 0 && !sameValue(entry.value, best.value)) {
+            throw new AmbiguousClassifyError(path, best.glob, entry.glob);
+        }
+    }
+    return best?.value;
+}
+function sameTags(a, b) {
+    return a.length === b.length && a.every((tag, i) => tag === b[i]);
+}
+// Relative path (project-root-relative, forward-slash-separated) -> the
+// tags its most-specific matching `classify` entry names, or undefined if
+// no entry matches at all.
+export function classifyByGlob(path, entries) {
+    return mostSpecificMatch(path, entries.map((e) => ({ glob: e.glob, value: e.tags })), sameTags);
+}
+// The nearest directory-name segment (innermost first) matching one of
+// `names` becomes `${tagNamespace}:${name}` - VS Code's own code-layering.ts
+// algorithm: walk the path's directory segments from the file outward, stop
+// at the first recognized name.
+export function classifyByDirectoryName(path, config) {
+    if (config === undefined)
+        return [];
+    const segments = path.split(sep === "\\" ? /\\|\// : "/");
+    for (let i = segments.length - 1; i >= 0; i--) {
+        if (config.names.includes(segments[i])) {
+            return [`${config.tagNamespace}:${segments[i]}`];
+        }
+    }
+    return [];
+}
+export function classifyFile(path, config) {
+    const tags = new Set();
+    for (const tag of classifyByGlob(path, config.classify ?? []) ?? [])
+        tags.add(tag);
+    for (const tag of classifyByDirectoryName(path, config.classifyByDirectoryName))
+        tags.add(tag);
+    return tags;
+}

package/dist/cli.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+// Responsibility: parse argv and dispatch to a verb (init, check, todo, rules, agents, recommend, fix, simulate, search, hotspots).
+// Boundary: no rule logic here; verbs live in their own modules.
+import { startArchstrictMcpServer } from "./mcp-server.js";
+import { search, formatSearchText } from "./verbs/search.js";
+import { simulate, formatSimulateText } from "./verbs/simulate.js";
+import { agents, formatAgentsText } from "./verbs/agents.js";
+import { recommend, formatRecommendText } from "./verbs/recommend.js";
+import { fix, formatFixText } from "./verbs/fix.js";
+import { init } from "./verbs/init.js";
+import { check, formatText, hasBlockingViolations } from "./verbs/check.js";
+import { todo } from "./verbs/todo.js";
+import { rules, formatRulesText } from "./verbs/rules.js";
+import { hotspots, formatHotspotsText } from "./verbs/hotspots.js";
+import { ReportError } from "./report-error.js";
+import { parseCheckArgv } from "./check-options.js";
+// Text and JSON share one shape: the message, then the one command to run.
+// A violation already carries `do`; a thrown config or missing-file
+// failure goes through here so it does too.
+function reportFailure(error, verb, asJson) {
+    const message = error instanceof Error ? error.message : String(error);
+    const doText = error instanceof ReportError ? error.do : `archstrict ${verb}`;
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify({ error: message, do: doText })}\n`);
+    }
+    else {
+        process.stderr.write(`archstrict: ${message}\ndo: ${doText}\n`);
+    }
+}
+// `--json` is a flag, never read as a directory, so it's stripped before
+// the positional rules apply. Every other argument is a directory, so any
+// other flag-looking argument ("-" prefix) is rejected outright rather
+// than silently accepted as a directory name. More than one positional
+// means the shell expanded an unquoted glob (`src/*` with more than one
+// match) - archstrict cannot tell that apart from a person genuinely
+// typing two directory names, so both read the same way: init takes
+// exactly one.
+function parseInitArgv(argv) {
+    const positional = argv.filter((arg) => arg !== "--json");
+    for (const arg of positional) {
+        if (arg.startsWith("-"))
+            throw new ReportError(`unknown option '${arg}'`, "archstrict init");
+    }
+    if (positional.length > 1) {
+        throw new ReportError(`init takes one directory; got ${positional.length} arguments (the shell expands an unquoted * or src/*)`, "archstrict init");
+    }
+    return positional[0];
+}
+async function runInit(args) {
+    const asJson = args.includes("--json");
+    const result = await init(process.cwd(), parseInitArgv(args));
+    if (asJson) {
+        // Field names and shapes follow check's and todo's own --json
+        // convention: one object, keys in the same order this prints them.
+        // `typesPath` (not `generatedPath`, InitResult's own internal name)
+        // matches archstrict.types.ts's own file name, which is what an agent
+        // reading this JSON actually needs to find.
+        process.stdout.write(`${JSON.stringify({
+            configPath: result.configPath,
+            typesPath: result.generatedPath,
+            configWritten: result.configWritten,
+            opened: result.opened === "" ? null : result.opened,
+            moduleNames: result.moduleNames,
+            hiddenDirs: result.hiddenDirs,
+            noiseDirs: result.noiseDirs,
+            testFileExcludes: result.testFileExcludes.map((t) => ({ pattern: t.label, exclude: t.exclude, files: t.fileCount })),
+            uncovered: result.uncovered.map((g) => ({
+                path: g.rel,
+                kind: g.kind,
+                files: g.fileCount,
+                declare: g.entry,
+                exclude: g.excludeGlob,
+            })),
+            notes: result.notes,
+            do: result.doText,
+        })}\n`);
+        return 0;
+    }
+    for (const line of result.messageLines)
+        process.stdout.write(`${line}\n`);
+    process.stdout.write(`do: ${result.doText}\n`);
+    return 0;
+}
+async function runCheck(args) {
+    const parsed = parseCheckArgv(args);
+    const result = await check(process.cwd(), parsed.focusFile, {
+        prove: parsed.prove,
+        rules: parsed.rules,
+        modules: parsed.modules,
+        frozen: parsed.frozen,
+    });
+    if (parsed.asJson) {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write(formatText(result));
+    }
+    return hasBlockingViolations(result) ? 1 : 0;
+}
+async function runTodo(args) {
+    const asJson = args.includes("--json");
+    const result = await todo(process.cwd());
+    if (asJson) {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        return 0;
+    }
+    if (result.firstRun) {
+        process.stdout.write(`froze ${result.added} violation(s)\n`);
+    }
+    else {
+        process.stdout.write(`pruned ${result.pruned} stale entrie(s)\n`);
+    }
+    process.stdout.write(`do: archstrict check\n`);
+    return 0;
+}
+async function runRules(args) {
+    const asJson = args.includes("--json");
+    const paths = args.filter((arg) => arg !== "--json");
+    if (paths.length !== 1)
+        throw new Error("usage: archstrict rules <path> [--json]");
+    const result = await rules(process.cwd(), paths[0]);
+    process.stdout.write(asJson ? JSON.stringify(result, null, 2) + "\n" : formatRulesText(result));
+    return 0;
+}
+function runAgents(args) {
+    if (args.some((arg) => arg !== "--json" && arg !== "--remove")) {
+        throw new Error("usage: archstrict agents [--remove] [--json]");
+    }
+    const result = agents(process.cwd(), args.includes("--remove"));
+    process.stdout.write(args.includes("--json") ? JSON.stringify(result, null, 2) + "\n" : formatAgentsText(result));
+    return 0;
+}
+async function runRecommend(args) {
+    const paths = args.filter(arg => arg !== "--json");
+    if (paths.length > 1 || paths.some(arg => arg.startsWith("-"))) {
+        throw new Error("usage: archstrict recommend [dir] [--json]");
+    }
+    // Without a config, the directory controls init's own in-memory walk; a
+    // declared config supplies its own scope regardless.
+    const result = await recommend(process.cwd(), paths[0]);
+    process.stdout.write(args.includes("--json") ? JSON.stringify(result, null, 2) + "\n" : formatRecommendText(result));
+    return 0;
+}
+async function runFix(args) {
+    const paths = args.filter(arg => arg !== "--json" && arg !== "--dry-run");
+    if (paths.length > 1 || paths.some(arg => arg.startsWith("-"))) {
+        throw new Error("usage: archstrict fix [file] [--dry-run] [--json]");
+    }
+    const dryRun = args.includes("--dry-run");
+    const result = await fix(process.cwd(), paths[0], dryRun);
+    process.stdout.write(args.includes("--json") ? JSON.stringify(result, null, 2) + "\n" : formatFixText(result));
+    return dryRun || (result.unfixable.length === 0 && result.reverted.length === 0) ? 0 : 1;
+}
+async function runSimulate(args) {
+    if (args.some(arg => arg !== "--json" && arg !== "--whole-project")) {
+        throw new Error("usage: archstrict simulate [--json] [--whole-project]");
+    }
+    let input = "";
+    process.stdin.setEncoding("utf8");
+    for await (const chunk of process.stdin)
+        input += chunk;
+    const body = JSON.parse(input);
+    if (typeof body !== "object" || body === null || !("changes" in body) || !Array.isArray(body.changes)) {
+        throw new Error("stdin must contain a JSON object with a changes array");
+    }
+    const result = await simulate(process.cwd(), body.changes, { wholeProject: args.includes("--whole-project") });
+    process.stdout.write(args.includes("--json") ? JSON.stringify(result, null, 2) + "\n" : formatSimulateText(result));
+    return result.added.length === 0 ? 0 : 1;
+}
+async function runSearch(args) {
+    const query = args.filter(arg => arg !== "--json").join(" ");
+    const result = await search(process.cwd(), query);
+    process.stdout.write(args.includes("--json") ? JSON.stringify(result, null, 2) + "\n" : formatSearchText(result));
+    return 0;
+}
+async function runHotspots(args) {
+    let since;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            continue;
+        if (arg === "--since" && since === undefined && args[i + 1] !== undefined && !args[i + 1].startsWith("--")) {
+            since = args[++i];
+            continue;
+        }
+        throw new Error("usage: archstrict hotspots [--since <git ref or date>] [--json]");
+    }
+    const result = await hotspots(process.cwd(), since);
+    process.stdout.write(args.includes("--json") ? JSON.stringify(result, null, 2) + "\n" : formatHotspotsText(result));
+    return 0;
+}
+// The connected transport's stdin listener keeps Node alive after this function returns.
+// A real subprocess stayed alive with stdin open and exited when stdin closed;
+// the host can also terminate it. A separate server-closed promise is unnecessary.
+async function runMcp() {
+    await startArchstrictMcpServer(process.cwd());
+    return 0;
+}
+async function main(argv) {
+    const [verb, ...rest] = argv;
+    if (verb === undefined) {
+        process.stderr.write("usage: archstrict <init|check|todo|rules|agents|recommend|fix|simulate|search|hotspots|mcp> [args]\n");
+        return 1;
+    }
+    try {
+        if (verb === "mcp")
+            return await runMcp();
+        if (verb === "search")
+            return await runSearch(rest);
+        if (verb === "hotspots")
+            return await runHotspots(rest);
+        if (verb === "simulate")
+            return await runSimulate(rest);
+        if (verb === "fix")
+            return await runFix(rest);
+        if (verb === "recommend")
+            return await runRecommend(rest);
+        if (verb === "init")
+            return await runInit(rest);
+        if (verb === "check")
+            return await runCheck(rest);
+        if (verb === "todo")
+            return await runTodo(rest);
+        if (verb === "rules")
+            return await runRules(rest);
+        if (verb === "agents")
+            return runAgents(rest);
+        process.stderr.write(`archstrict: '${verb}' is not implemented yet\ndo: archstrict init\n`);
+        return 1;
+    }
+    catch (error) {
+        // A config or missing-file error throws before any real output.
+        // reportFailure prints the message and a do: line — the same pair
+        // a violation carries — instead of a bare message or stack trace.
+        reportFailure(error, verb, rest.includes("--json"));
+        return 1;
+    }
+}
+process.exitCode = await main(process.argv.slice(2));