@thebattlearena/corner 0.9.1-beta.70 → 0.10.0

package/ring/scripts/format-gate.mjs

@@ -0,0 +1,723 @@
+#!/usr/bin/env node
+// The host's format, kept by ring while a bout is active: sort-imports (@getsupervisor/js-sort-imports,
+// with the repo's own tsconfig, so an alias sorts the same as with the repo's `sort` script) and then
+// prettier, using the binaries the repo installed. Never downloads anything: a repo without them is
+// left as it is, and `check` says so.
+//
+//   edit-hook    PostToolUse on Edit|Write|MultiEdit: formats the edited file.
+//   shell-hook   PostToolUse on Bash: formats what the shell wrote (cat >, sed -i, a script), which
+//                the edit hook never sees. Only the files that changed since its last pass, kept in
+//                `git rev-parse --git-path ring-format.json`, so it works in a worktree and costs
+//                nothing when the command wrote nothing. It looks at the toplevel of the session's
+//                cwd and at the worktree of an active bout of that repo the command names.
+//   fix [<dir>] [--range <a>..<b>]
+//                The wrestler's gate before each commit: formats the changed files (diff, staged and
+//                untracked); the repo's own `fix:changed` script wins when it has one. With --range,
+//                the files a range touched, to fix what is already committed.
+//   check [<dir>] [--range <a>..<b>]
+//                The cornerman's check, read-only: formats a copy of each changed file (of the range,
+//                as it is at <b>) and lists the ones that come out different. Not `sort-imports
+//                --check`: it reports a one-specifier import past printWidth that sort-imports wraps
+//                and prettier joins again, a false positive. Exit 0 clean, 1 unclean, 2 NOT VERIFIED
+//                (sort-imports or prettier missing: never read as clean), 64 an error.
+//
+// Both hooks act only on a repo with an active ring bout, never block (exit 0) and stand aside when
+// the repo's `.claude/settings.json` already runs its own format hook for that event.
+import { execFileSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import {
+  basename,
+  dirname,
+  extname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+} from 'node:path';
+import { activeBouts, HOST_CONFIG, isMain, repoSlug } from './config.mjs';
+
+export const FORMATTABLE = [
+  '.ts',
+  '.tsx',
+  '.js',
+  '.jsx',
+  '.mjs',
+  '.cjs',
+  '.json',
+  '.md',
+  '.css',
+  '.scss',
+  '.yml',
+  '.yaml',
+];
+export const SORTABLE = ['.ts', '.tsx'];
+const STATE = 'ring-format.json';
+
+const parse = (text) => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The tsconfig sort-imports reads the aliases from: `.claude/ring.json` `format.tsconfig`, else the
+ * one the repo's own sort-imports script passes, else `tsconfig.json` when the repo has it. PURE.
+ */
+export function formatTsconfig({ ringJson, packageJson, exists }) {
+  const configured = parse(ringJson ?? '')?.format?.tsconfig;
+  if (configured) return configured;
+  // `scripts.sort` first (what `yarn sort` does), then `sort:check`, then any other script: a
+  // build or test command that happens to call sort-imports must not win over the repo's sort.
+  const all = parse(packageJson ?? '')?.scripts ?? {};
+  const scripts = [
+    all.sort,
+    all['sort:check'],
+    ...Object.entries(all)
+      .filter(([name]) => !['sort', 'sort:check'].includes(name))
+      .map(([, script]) => script),
+  ].filter(Boolean);
+  const fromScript = scripts
+    .map(
+      (script) =>
+        /sort-imports\b.*?--tsconfig[ =](\S+)/.exec(String(script))?.[1],
+    )
+    .find(Boolean);
+  if (fromScript) return fromScript.replace(/^["']|["']$/g, '');
+  return exists('tsconfig.json') ? 'tsconfig.json' : null;
+}
+
+const FORMAT_COMMAND =
+  /format-changed|after-shell-write|prettier|sort-imports|fix-changed/;
+
+/**
+ * Does the repo already format on this event (`edit` or `shell`) with its own hook? PURE: `settings`
+ * are the texts of its `.claude/settings.json` and `.claude/settings.local.json`.
+ */
+export function ownFormatHook(settings, event) {
+  const wanted = event === 'shell' ? /\bBash\b/ : /\b(Edit|Write|MultiEdit)\b/;
+  return settings
+    .map(parse)
+    .filter(Boolean)
+    .flatMap((config) => config.hooks?.PostToolUse ?? [])
+    .some(
+      (entry) =>
+        wanted.test(entry.matcher ?? '') &&
+        (entry.hooks ?? []).some((hook) =>
+          FORMAT_COMMAND.test(hook.command ?? ''),
+        ),
+    );
+}
+
+/** The worktree paths of active bouts a shell command names (`cd <wt>`, `git -C <wt>`…). PURE. */
+export function namedWorktrees(command, worktrees) {
+  const text = String(command ?? '');
+  return worktrees.filter(
+    (worktree) =>
+      worktree &&
+      new RegExp(
+        `${worktree.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=$|[/\\s'";&|)])`,
+      ).test(text),
+  );
+}
+
+const git = (dir, args) =>
+  execFileSync('git', ['-C', dir, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+const gitOr = (dir, args, fallback = null) => {
+  try {
+    return git(dir, args);
+  } catch {
+    return fallback;
+  }
+};
+
+/** The git toplevel holding `path` (a file or a directory), or null outside a repo. */
+export function toplevel(path) {
+  const dir =
+    existsSync(path) && statSync(path).isDirectory() ? path : dirname(path);
+  return gitOr(dir, ['rev-parse', '--show-toplevel'])?.trim() || null;
+}
+
+/**
+ * The repo's binaries: its own node_modules/.bin, else the main checkout's (a fresh worktree of the
+ * wrestler may not have installed its dependencies). Null when absent: nothing is downloaded.
+ */
+export function binaries(root) {
+  const common = gitOr(root, [
+    'rev-parse',
+    '--path-format=absolute',
+    '--git-common-dir',
+  ])?.trim();
+  const homes = [root, common ? dirname(common) : null].filter(Boolean);
+  const find = (name) =>
+    homes
+      .map((home) => join(home, 'node_modules', '.bin', name))
+      .find((bin) => existsSync(bin)) ?? null;
+  return { sort: find('sort-imports'), prettier: find('prettier') };
+}
+
+const readOr = (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null);
+
+/** What formatting `root` takes: binaries, tsconfig (absolute) and whether it formats on its own. */
+export function toolchain(root) {
+  const tsconfig = formatTsconfig({
+    ringJson: readOr(join(root, HOST_CONFIG)),
+    packageJson: readOr(join(root, 'package.json')),
+    exists: (name) => existsSync(join(root, name)),
+  });
+  const settings = ['settings.json', 'settings.local.json'].map((name) =>
+    readOr(join(root, '.claude', name)),
+  );
+  return {
+    root,
+    ...binaries(root),
+    tsconfig: tsconfig
+      ? isAbsolute(tsconfig)
+        ? tsconfig
+        : join(root, tsconfig)
+      : null,
+    ownHook: {
+      edit: ownFormatHook(settings, 'edit'),
+      shell: ownFormatHook(settings, 'shell'),
+    },
+    ownFix: Boolean(
+      parse(readOr(join(root, 'package.json')) ?? '')?.scripts?.['fix:changed'],
+    ),
+  };
+}
+
+const formattable = (file) => FORMATTABLE.includes(extname(file).toLowerCase());
+const sortable = (file) => SORTABLE.includes(extname(file).toLowerCase());
+
+/** sort-imports, then prettier, on files of `tools.root` (absolute paths). Throws what fails. */
+export function formatFiles(tools, files) {
+  const run = (bin, args) =>
+    execFileSync(bin, args, { cwd: tools.root, stdio: 'pipe' });
+  const sorted = files.filter(sortable);
+  const tsconfig = tools.tsconfig ? ['--tsconfig', tools.tsconfig] : [];
+  if (tools.sort && sorted.length)
+    run(tools.sort, [...tsconfig, '--write', ...sorted]);
+  const pretty = files.filter(formattable);
+  if (tools.prettier && pretty.length)
+    run(tools.prettier, [
+      '--write',
+      '--ignore-unknown',
+      '--log-level',
+      'warn',
+      ...pretty,
+    ]);
+}
+
+/**
+ * `text` (the content of `file`) as the repo's format would leave it: sort-imports on a copy outside
+ * the repo, then prettier from stdin with the file's own path, so its config and ignore file apply.
+ */
+export function formattedText(tools, file, text) {
+  let out = text;
+  if (tools.sort && sortable(file)) {
+    const dir = mkdtempSync(join(tmpdir(), 'ring-format-'));
+    try {
+      const copy = join(dir, basename(file));
+      writeFileSync(copy, out);
+      const tsconfig = tools.tsconfig ? ['--tsconfig', tools.tsconfig] : [];
+      execFileSync(tools.sort, [...tsconfig, '--write', copy], {
+        cwd: tools.root,
+        stdio: 'pipe',
+      });
+      out = readFileSync(copy, 'utf8');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+  if (tools.prettier && formattable(file))
+    out = execFileSync(tools.prettier, ['--stdin-filepath', file], {
+      cwd: tools.root,
+      input: out,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      maxBuffer: 64 * 1024 * 1024,
+    });
+  return out;
+}
+
+const lines = (text) =>
+  String(text ?? '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+/** The changed files of `root` (diff, staged, untracked), relative, that still exist. */
+export function changedFiles(root) {
+  const listed = [
+    gitOr(root, ['diff', '--name-only', '--diff-filter=ACMR']),
+    gitOr(root, ['diff', '--cached', '--name-only', '--diff-filter=ACMR']),
+    gitOr(root, ['ls-files', '--others', '--exclude-standard']),
+  ];
+  if (listed.includes(null))
+    throw new Error(`git cannot list the changes of ${root}`);
+  return [...new Set(listed.flatMap(lines))].filter(
+    (file) => formattable(file) && existsSync(join(root, file)),
+  );
+}
+
+/** Is a bout of the repo at `root` active? A ring home that cannot be read counts as no. */
+function boutActive(root) {
+  try {
+    return activeBouts(repoSlug(root)).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+const readStdin = () => {
+  try {
+    return parse(readFileSync(0, 'utf8')) ?? {};
+  } catch {
+    return {};
+  }
+};
+
+/** edit-hook: the file an Edit/Write/MultiEdit just wrote. */
+export function editHook(input) {
+  const file = input?.tool_input?.file_path;
+  if (!file || !existsSync(file) || !formattable(file))
+    return 'skip: not a formattable file';
+  const root = toplevel(file);
+  if (!root) return 'skip: outside a repo';
+  if (!boutActive(root)) return 'skip: no active bout';
+  const tools = toolchain(root);
+  if (tools.ownHook.edit) return 'skip: the repo formats on its own';
+  if (!tools.sort && !tools.prettier)
+    return 'skip: no sort-imports nor prettier installed';
+  formatFiles(tools, [resolve(file)]);
+  return 'formatted';
+}
+
+const fingerprint = (path) => {
+  try {
+    const stats = statSync(path);
+    return `${stats.mtimeMs}:${stats.size}`;
+  } catch {
+    return null;
+  }
+};
+
+/** The roots a shell command may have written in: the cwd's repo and the bout worktrees it names. */
+function shellRoots(input) {
+  const cwdRoot = toplevel(input?.cwd || process.cwd());
+  const roots = new Set(cwdRoot ? [cwdRoot] : []);
+  let bouts = [];
+  try {
+    bouts = activeBouts(null);
+  } catch {
+    bouts = [];
+  }
+  namedWorktrees(
+    input?.tool_input?.command,
+    bouts
+      .map(({ state }) => state.worktree)
+      .filter((worktree) => worktree && existsSync(worktree)),
+  ).forEach((worktree) => roots.add(toplevel(worktree)));
+  return [...roots].filter(Boolean);
+}
+
+/** shell-hook: what changed since the last pass in each root the command may have written in. */
+export function shellHook(input) {
+  return shellRoots(input).map((root) => {
+    if (!boutActive(root)) return `${root}: no active bout`;
+    const tools = toolchain(root);
+    if (tools.ownHook.shell) return `${root}: the repo formats on its own`;
+    if (!tools.sort && !tools.prettier)
+      return `${root}: no sort-imports nor prettier`;
+    const statePath = gitOr(root, ['rev-parse', '--git-path', STATE])?.trim();
+    const stateFile = statePath ? resolve(root, statePath) : null;
+    const previous = (stateFile && parse(readOr(stateFile) ?? '')) || {};
+    const files = changedFiles(root);
+    const touched = files.filter(
+      (file) => fingerprint(join(root, file)) !== previous[file],
+    );
+    // One file at a time: a file prettier cannot parse must not stop the others, and it stays out
+    // of the state, so the next pass tries it again (the gate reports it if it never formats).
+    const failed = new Set(
+      touched.filter((file) => {
+        try {
+          formatFiles(tools, [join(root, file)]);
+          return false;
+        } catch {
+          return true;
+        }
+      }),
+    );
+    if (stateFile) {
+      const now = Object.fromEntries(
+        files
+          .filter((file) => !failed.has(file))
+          .map((file) => [file, fingerprint(join(root, file))]),
+      );
+      try {
+        mkdirSync(dirname(stateFile), { recursive: true });
+        writeFileSync(stateFile, JSON.stringify(now));
+      } catch {
+        // The state only saves work: without it the next pass looks at more, never at less.
+      }
+    }
+    return `${root}: ${touched.length} formatted`;
+  });
+}
+
+/** The formattable files a commit range `<a>..<b>` adds or changes, relative, that still exist. */
+const rangeFiles = (root, range) =>
+  lines(git(root, ['diff', '--name-only', '--diff-filter=ACMR', range])).filter(
+    formattable,
+  );
+
+/**
+ * fix: the changed files of `dir` formatted (the repo's own `fix:changed` when it has one), or,
+ * with `range`, the files the range touched as they are in the worktree now, by ring itself: the
+ * way to fix what is already committed (the wrestler commits the result).
+ */
+export function fix(dir, range = null) {
+  const root = toplevel(dir);
+  if (!root) throw new Error(`${dir} is not inside a git repo`);
+  const tools = toolchain(root);
+  // What was staged must be committed formatted: a fully staged file is staged again after
+  // formatting; one staged in part (with other edits unstaged) is left for the wrestler, who
+  // decides what goes in, and is reported.
+  const staged = lines(
+    gitOr(root, ['diff', '--cached', '--name-only', '--diff-filter=ACMR']),
+  );
+  const unstaged = new Set(
+    lines(gitOr(root, ['diff', '--name-only', '--diff-filter=ACMR'])),
+  );
+  const restage = () => {
+    const whole = staged.filter(
+      (file) => !unstaged.has(file) && existsSync(join(root, file)),
+    );
+    if (whole.length) git(root, ['add', '--', ...whole]);
+    return {
+      restaged: whole,
+      partial: staged.filter((file) => unstaged.has(file)),
+    };
+  };
+  if (tools.ownFix && !range) {
+    execFileSync(
+      existsSync(join(root, 'yarn.lock')) ? 'yarn' : 'npm',
+      ['run', 'fix:changed'],
+      {
+        cwd: root,
+        stdio: 'inherit',
+      },
+    );
+    return { root, files: null, by: 'the repo (fix:changed)', ...restage() };
+  }
+  if (!tools.sort && !tools.prettier)
+    throw new Error(
+      `${root} has neither sort-imports nor prettier in node_modules/.bin: install the dependencies (or report it to the referee)`,
+    );
+  const files = (range ? rangeFiles(root, range) : changedFiles(root)).filter(
+    (file) => existsSync(join(root, file)),
+  );
+  if (files.length)
+    formatFiles(
+      tools,
+      files.map((file) => join(root, file)),
+    );
+  return {
+    root,
+    files,
+    by: 'ring',
+    missing: missingTools(tools),
+    ...restage(),
+  };
+}
+
+const missingTools = (tools) =>
+  [!tools.sort && 'sort-imports', !tools.prettier && 'prettier'].filter(
+    Boolean,
+  );
+
+const WORKER = join(
+  dirname(fileURLToPath(import.meta.url)),
+  'format-worker.mjs',
+);
+
+/**
+ * The files (relative) whose `text` the repo's format would change, judged in one batch by
+ * format-worker.mjs; a file it could not judge counts as unclean.
+ */
+function batchUnclean(tools, entries) {
+  const byAbs = new Map(
+    entries.map(({ file }) => [join(tools.root, file), file]),
+  );
+  const output = execFileSync(process.execPath, [WORKER], {
+    cwd: tools.root,
+    input: JSON.stringify({
+      root: tools.root,
+      tsconfig: tools.tsconfig,
+      sort: tools.sort,
+      prettier: tools.prettier,
+      files: entries.map(({ file, text }) => ({
+        file: join(tools.root, file),
+        text,
+      })),
+    }),
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    maxBuffer: 256 * 1024 * 1024,
+  });
+  const { changed, failed } = JSON.parse(output);
+  return [...new Set([...changed, ...failed])].map((file) => byAbs.get(file));
+}
+
+/**
+ * check: the files that would change, read-only. `range` is `<a>..<b>` (files as they are at b).
+ * `verified` is false when sort-imports or prettier is not installed: then the files listed in
+ * `files` were not (fully) checked, and nothing may read that as clean.
+ */
+export function check(dir, range = null, only = null) {
+  const root = toplevel(dir);
+  if (!root) throw new Error(`${dir} is not inside a git repo`);
+  const tools = toolchain(root);
+  const missing = missingTools(tools);
+  const [, head] = range ? range.split('..') : [];
+  const files = only ?? (range ? rangeFiles(root, range) : changedFiles(root));
+  // Nothing to format is verified clean, whatever is installed.
+  if (missing.length === 2 && files.length)
+    return {
+      root,
+      verified: false,
+      checked: 0,
+      files,
+      unclean: [],
+      missing,
+      tsconfig: tools.tsconfig,
+    };
+  const unclean = files.length
+    ? batchUnclean(
+        tools,
+        files.map((file) => ({
+          file,
+          text: range
+            ? git(root, ['show', `${head || 'HEAD'}:${file}`])
+            : readFileSync(join(root, file), 'utf8'),
+        })),
+      )
+    : [];
+  return {
+    root,
+    verified: missing.length === 0 || files.length === 0,
+    checked: files.length,
+    files,
+    unclean,
+    missing,
+    tsconfig: tools.tsconfig,
+  };
+}
+
+// ---------------------------------------------------------------- the gate of a bout
+
+const CLEAN_BLOBS = 'format-clean.json';
+
+/**
+ * Why a bout's range is refused for its format, or null. PURE over the check's result:
+ * unclean files always refuse; a check that could not run (NOT VERIFIED) refuses unless the
+ * referee recorded `formatUnverified` for the bout (a repo without the tooling).
+ */
+export function formatRefusal(result, state) {
+  if (result.unclean.length)
+    return `files not as sort-imports + prettier leave them: ${result.unclean.join(', ')}. The wrestler runs format-gate.mjs fix <worktree> --range <base>..HEAD, commits, and it is checked again`;
+  if (!result.verified && !state.formatUnverified)
+    return `the format could NOT be verified (${result.missing.join(' and ')} not installed in the worktree nor in the main checkout): install the dependencies in the worktree, or, if the repo really has no such tooling, approve with --format-unverified "<why>" (it goes to decisions.md)`;
+  return null;
+}
+
+/**
+ * The format gate of a bout up to `sha`: the range from the merge base with origin/<base> to
+ * `sha`, checked as committed in the bout's worktree. Blobs that already came out clean (with the
+ * same tsconfig) are kept in `<bout dir>/format-clean.json` and not checked again, so approve,
+ * push, round-bell and close only pay for what changed. Returns { refusal, result }.
+ */
+export function boutFormatGate(dir, state, sha) {
+  const root = state.worktree;
+  if (!root || !existsSync(root))
+    throw new Error(
+      `the bout's worktree ${root} does not exist: its format cannot be checked`,
+    );
+  const baseRef = [`origin/${state.base}`, state.base].find(
+    (ref) =>
+      gitOr(root, ['rev-parse', '--verify', '-q', `${ref}^{commit}`]) !== null,
+  );
+  if (!baseRef)
+    throw new Error(
+      `neither origin/${state.base} nor ${state.base} exists in ${root}: fetch the base before checking the format`,
+    );
+  const base = git(root, ['merge-base', baseRef, sha]).trim();
+  const range = `${base}..${sha}`;
+  const tools = toolchain(root);
+  const cachePath = join(dir, CLEAN_BLOBS);
+  const cache = parse(readOr(cachePath) ?? '') ?? {};
+  const key = tools.tsconfig ?? '-';
+  const clean = new Set(cache[key] ?? []);
+  const blobOf = (file) => git(root, ['rev-parse', `${sha}:${file}`]).trim();
+  const files = rangeFiles(root, range);
+  const pending = files.filter((file) => !clean.has(blobOf(file)));
+  const result =
+    pending.length || !files.length
+      ? check(root, range, pending)
+      : {
+          root,
+          verified: true,
+          checked: 0,
+          files,
+          unclean: [],
+          missing: [],
+          tsconfig: tools.tsconfig,
+        };
+  if (result.verified) {
+    pending
+      .filter((file) => !result.unclean.includes(file))
+      .forEach((file) => clean.add(blobOf(file)));
+    try {
+      writeFileSync(cachePath, JSON.stringify({ ...cache, [key]: [...clean] }));
+    } catch {
+      // The cache only saves work.
+    }
+  }
+  return {
+    refusal: formatRefusal(result, state),
+    result: { ...result, range },
+  };
+}
+
+/**
+ * Records that the bout's repo really has no format tooling: the referee's decision, with its why,
+ * in decisions.md and in state.json (`formatUnverified`). From then on a NOT VERIFIED check does
+ * not refuse; unclean files still do.
+ */
+export function acceptUnverified(dir, reason, at = new Date().toISOString()) {
+  const why = String(reason ?? '').trim();
+  if (!why)
+    throw new Error(
+      'accepting an unverified format needs its why: --format-unverified "<why>"',
+    );
+  const statePath = join(dir, 'state.json');
+  const state = JSON.parse(readFileSync(statePath, 'utf8'));
+  writeFileSync(
+    statePath,
+    `${JSON.stringify({ ...state, formatUnverified: { reason: why, at } }, null, 2)}\n`,
+  );
+  writeFileSync(
+    join(dir, 'decisions.md'),
+    `${readOr(join(dir, 'decisions.md')) ?? ''}- ${at} · format · referee · FORMAT NOT VERIFIED accepted for the bout (no sort-imports/prettier in the repo): ${why}\n`,
+  );
+}
+
+/**
+ * Exit codes of `check`: 0 clean, 1 unclean files, 2 NOT VERIFIED (a binary is missing: never read
+ * it as clean), 64 a usage or setup error.
+ */
+export const CHECK_EXIT = { clean: 0, unclean: 1, unverified: 2, error: 64 };
+
+export const checkExit = (result) =>
+  result.unclean.length
+    ? CHECK_EXIT.unclean
+    : result.verified
+      ? CHECK_EXIT.clean
+      : CHECK_EXIT.unverified;
+
+function main(argv) {
+  const [command, ...rest] = argv;
+  const valueOf = (flag) => rest[rest.indexOf(flag) + 1];
+  const dir =
+    rest.find(
+      (arg, index) => !arg.startsWith('--') && rest[index - 1] !== '--range',
+    ) ?? process.cwd();
+  if (command === 'edit-hook') {
+    try {
+      editHook(readStdin());
+    } catch {
+      // A hook that formats never blocks the edit it follows.
+    }
+    return 0;
+  }
+  if (command === 'shell-hook') {
+    try {
+      shellHook(readStdin());
+    } catch {
+      // Same: formatting is a courtesy of the hook; the gate is `fix` and `check`.
+    }
+    return 0;
+  }
+  if (command === 'fix') {
+    const result = fix(
+      dir,
+      rest.includes('--range') ? valueOf('--range') : null,
+    );
+    const files =
+      result.files === null
+        ? 'its changed files'
+        : `${result.files.length} file(s)`;
+    console.log(
+      `[ring format] ${relative(process.cwd(), result.root) || '.'}: ${files} formatted by ${result.by}`,
+    );
+    if (result.restaged?.length)
+      console.log(
+        `[ring format] staged again, formatted: ${result.restaged.join(', ')}`,
+      );
+    if (result.partial?.length)
+      console.log(
+        `[ring format] staged in part, NOT staged again (stage what you mean to commit): ${result.partial.join(', ')}`,
+      );
+    if (result.missing?.length)
+      console.log(
+        `[ring format] not installed, skipped: ${result.missing.join(', ')}`,
+      );
+    return 0;
+  }
+  if (command === 'accept-unverified') {
+    acceptUnverified(rest[0], rest[1]);
+    console.log(
+      `[ring format] NOT VERIFIED accepted for ${rest[0]} (decisions.md)`,
+    );
+    return 0;
+  }
+  if (command === 'check') {
+    const result = check(
+      dir,
+      rest.includes('--range') ? valueOf('--range') : null,
+    );
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.verified)
+      console.error(
+        `[ring format] NOT VERIFIED: ${result.missing.join(' and ')} not installed in ${result.root} nor in its main checkout`,
+      );
+    return checkExit(result);
+  }
+  console.error(
+    'usage: format-gate.mjs edit-hook | shell-hook | fix [<dir>] [--range <a>..<b>] | check [<dir>] [--range <a>..<b>] | accept-unverified <bout dir> "<why>"',
+  );
+  return CHECK_EXIT.error;
+}
+
+if (isMain(import.meta.url)) {
+  try {
+    process.exitCode = main(process.argv.slice(2));
+  } catch (error) {
+    console.error(`[ring format] ${error.message}`);
+    process.exitCode = CHECK_EXIT.error;
+  }
+}