@event4u/agent-config 7.3.0 → 7.5.0

package/src/scripts/hooks/design_slop_hook.ts

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse anti-slop nudge — surfaces high-severity aesthetic tells in
+ * proposed UI content BEFORE the write (road-to-anti-slop-detector Phase 3).
+ *
+ * OPTIONAL, host-limited (pre_tool_use fires on ~2–3 hosts). The universal
+ * source of truth is the `lint_design_slop` linter / CI gate; this hook is a
+ * convenience layer that runs the same registry against the about-to-be-written
+ * content. Default-OFF: no-ops unless `hooks.design_slop.enabled: true` in
+ * `.agent-settings.yml`. fail_closed: false (never break a write for a flag).
+ *
+ * FLAGS, NEVER A BLOCK. On a P0/P1 finding it WARNS (exit 2 + reason); it never
+ * returns block (exit 1). Mirrors the injection-scan "warn, don't block" shape.
+ *
+ * Anti-loop degradation (council-required safety valve): a `file::rule`
+ * signature surfaced ≥ DEGRADE_AFTER times is downgraded to silent, so a
+ * deliberate-but-undeclared pattern the agent keeps re-writing never traps it.
+ * State: <root>/agents/runtime/state/design-slop-hook.json.
+ *
+ * Exit codes (dispatcher contract): 0 allow · 2 warn (+ JSON reason on stdout).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { type DesignContext } from "../design_slop_rules.js";
+import { loadDesignContext, scanFile } from "../lint_design_slop.js";
+
+const SETTINGS_FILE = ".agent-settings.yml";
+const EXIT_ALLOW = 0;
+const EXIT_WARN = 2;
+const DEGRADE_AFTER = 3; // surfaces of the same file::rule signature before going silent
+const UI_EXT = /\.(html|htm|css|scss|sass|less|vue|svelte|astro|jsx|tsx)$/i;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function isObject(v: unknown): v is JsonObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Minimal `.agent-settings.yml` reader for hooks.design_slop.enabled (mirrors injection-scan). */
+function enabled(root: string): boolean {
+  const f = path.join(root, SETTINGS_FILE);
+  let text: string;
+  try {
+    if (!fs.statSync(f).isFile()) return false;
+    text = fs.readFileSync(f, "utf-8");
+  } catch {
+    return false;
+  }
+  let inHooks = false;
+  let inDs = false;
+  for (const raw of text.split(/\r\n|\r|\n/)) {
+    const line = raw.replace(/\s+$/, "");
+    if (!line || line.replace(/^\s+/, "").startsWith("#")) continue;
+    if (!(line.startsWith(" ") || line.startsWith("\t"))) {
+      inHooks = /^hooks\s*:\s*$/.test(line);
+      inDs = false;
+      continue;
+    }
+    if (inHooks) {
+      if (/^\s+design_slop\s*:\s*$/.test(line)) {
+        inDs = true;
+        continue;
+      }
+      if (inDs && /^\s{0,3}\S/.test(line)) inDs = false;
+    }
+    if (inDs && /^\s+enabled\s*:\s*true\b/.test(line)) return true;
+  }
+  return false;
+}
+
+/** Best-effort: pull (toolName, filePath, proposedContent) from the PreToolUse envelope. */
+function extract(envelope: JsonObject): { file: string; content: string } | null {
+  const ti = envelope["tool_input"] ?? envelope["toolInput"] ?? envelope["input"];
+  if (!isObject(ti)) return null;
+  const fileVal = ti["file_path"] ?? ti["path"] ?? ti["filePath"];
+  const file = typeof fileVal === "string" ? fileVal : "";
+  // Edit → new_string/new_str; Write → content; some hosts → text
+  for (const key of ["content", "new_string", "new_str", "text", "newText"]) {
+    const v = ti[key];
+    if (typeof v === "string" && v.length > 0) return { file, content: v };
+  }
+  return null;
+}
+
+function stateFile(root: string): string {
+  return path.join(root, "agents", "runtime", "state", "design-slop-hook.json");
+}
+
+function readState(root: string): Record<string, number> {
+  try {
+    const t = fs.readFileSync(stateFile(root), "utf-8");
+    const parsed = JSON.parse(t);
+    return isObject(parsed) ? (parsed as Record<string, number>) : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeState(root: string, state: Record<string, number>): void {
+  try {
+    const sf = stateFile(root);
+    fs.mkdirSync(path.dirname(sf), { recursive: true });
+    fs.writeFileSync(sf, JSON.stringify(state, null, 2) + "\n");
+  } catch {
+    /* fail-open: never break a write because state could not persist */
+  }
+}
+
+function readStdin(): string {
+  try {
+    return fs.readFileSync(0, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+export function main(): number {
+  let envelope: JsonValue;
+  try {
+    const raw = readStdin();
+    envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+  } catch {
+    return EXIT_ALLOW;
+  }
+  if (!isObject(envelope)) return EXIT_ALLOW;
+
+  const rootVal = envelope["cwd"] ?? envelope["project_root"] ?? ".";
+  const root = typeof rootVal === "string" && rootVal ? rootVal : ".";
+  if (!enabled(root)) return EXIT_ALLOW;
+
+  const ex = extract(envelope);
+  if (!ex || !ex.file || !UI_EXT.test(ex.file)) return EXIT_ALLOW;
+
+  let ctx: DesignContext;
+  try {
+    ctx = loadDesignContext(path.dirname(path.resolve(root, ex.file)));
+  } catch {
+    ctx = { raw: "", has: () => false };
+  }
+
+  let findings;
+  try {
+    findings = scanFile(ex.content, ex.file, ctx).filter(
+      (f) => f.severity === "P0" || f.severity === "P1",
+    );
+  } catch {
+    return EXIT_ALLOW;
+  }
+  if (findings.length === 0) return EXIT_ALLOW;
+
+  // Anti-loop degradation: drop any signature already surfaced DEGRADE_AFTER times.
+  const state = readState(root);
+  const surfaced = findings.filter((f) => {
+    const sig = `${ex.file}::${f.rule}`;
+    const seen = state[sig] ?? 0;
+    if (seen >= DEGRADE_AFTER) return false; // gone silent — never trap the agent
+    state[sig] = seen + 1;
+    return true;
+  });
+  writeState(root, state);
+
+  if (surfaced.length === 0) return EXIT_ALLOW;
+
+  const lines = surfaced
+    .map((f) => `${f.catalogId} (${f.rule}) ${f.file}:${f.line} — ${f.message}`)
+    .join("; ");
+  const reason =
+    "⚠️ Anti-slop: high-severity aesthetic tell(s) in the proposed UI — " +
+    lines +
+    ". Rebuttable: declare intent in DESIGN.md, add design-slop-disable-next-line, " +
+    "or proceed if deliberate (this is a flag, not a block).";
+  process.stdout.write(JSON.stringify({ decision: "warn", reason }) + "\n");
+  return EXIT_WARN;
+}
+
+const isCliEntry =
+  process.argv[1] !== undefined &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (isCliEntry) process.exit(main());

package/src/scripts/hooks/rtk_wrap_hook.ts

@@ -0,0 +1,228 @@
+#!/usr/bin/env tsx
+/**
+ * PreToolUse RTK-wrap nudge — deterministic, warn-in-context
+ * (token-saving Phase 3).
+ *
+ * Converts RTK from advisory to DETERMINISTIC: instead of trusting a
+ * self-reported flag, this hook keys off a live `which rtk` probe. When rtk is
+ * actually installed AND the agent is about to run a single verbose CLI command
+ * that is NOT completeness-critical, it surfaces (warn) "re-run wrapped with
+ * rtk" so the 60–90% output-token saving is captured. It NEVER blocks (the v1
+ * dispatcher contract is allow/block/warn — there is no transparent
+ * `updatedInput` rewrite — and, like `injection_scan_hook`, warn preserves
+ * agency). It NEVER fires when rtk is absent (silent plain-command fallback,
+ * no nag).
+ *
+ * Default-OFF. Fires only when `hooks.rtk_wrap.enabled: true` in
+ * `.agent-settings.yml`. Disabled / missing / rtk-absent → no-op exit 0.
+ * fail_closed: false — any parse/probe error returns allow (never break a
+ * command for a token optimization).
+ *
+ * Denylist (never nudged — completeness-critical or already-handled):
+ *   - `git diff` / `rtk read` (silent truncation risk — see the rtk skill)
+ *   - already `rtk …` wrapped, or piped / compound (`|`, `&&`, `||`, `;`)
+ *   - any program not in the verbose-CLI allowlist
+ *
+ * Exit codes (dispatcher contract): 0 allow · 2 warn (+ JSON reason on stdout).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  shlexSplit,
+  ShlexError,
+  _split_subcommands,
+  _is_env_assignment,
+} from "./block_no_verify.js";
+
+const SETTINGS_FILE = ".agent-settings.yml";
+const EXIT_ALLOW = 0;
+const EXIT_WARN = 2;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+// Verbose-CLI programs worth wrapping — mirrors the cli-output-handling rule
+// triggers + the rtk skill's "✅ Always" table. Kept in sync with
+// src/rules/cli-output-handling.md.
+const _RTK_PROGRAMS: ReadonlySet<string> = new Set([
+  "git", "phpstan", "rector", "phpunit", "composer",
+  "npm", "pnpm", "yarn", "eslint", "tsc", "vitest", "jest",
+  "pytest", "ruff", "mypy", "pyright", "cargo", "go",
+  "golangci-lint", "docker", "kubectl", "terraform",
+]);
+
+function _isObject(v: unknown): v is JsonObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** `hooks.rtk_wrap.enabled: true` mini-parser (mirrors injection_scan_hook). */
+function _enabled(root: string): boolean {
+  const f = path.join(root, SETTINGS_FILE);
+  try {
+    if (!fs.statSync(f).isFile()) return false;
+  } catch {
+    return false;
+  }
+  let text: string;
+  try {
+    text = fs.readFileSync(f, "utf-8");
+  } catch {
+    return false;
+  }
+  let in_hooks = false;
+  let in_rw = false;
+  const lines = text.split(/\r\n|\r|\n/);
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  for (const raw of lines) {
+    const line = raw.replace(/\s+$/, "");
+    if (!line || line.replace(/^\s+/, "").startsWith("#")) continue;
+    if (!(line.startsWith(" ") || line.startsWith("\t"))) {
+      in_hooks = /^hooks\s*:\s*$/.test(line);
+      in_rw = false;
+      continue;
+    }
+    if (in_hooks) {
+      if (/^\s+rtk_wrap\s*:\s*$/.test(line)) {
+        in_rw = true;
+        continue;
+      }
+      if (in_rw && /^\s{0,3}\S/.test(line)) in_rw = false;
+    }
+    if (in_rw && /^\s+enabled\s*:\s*true\b/.test(line)) return true;
+  }
+  return false;
+}
+
+/** Live `which rtk` — scan PATH for an executable `rtk` (cross-platform). */
+export function rtk_available(env: NodeJS.ProcessEnv = process.env): boolean {
+  const pathVar = env.PATH ?? env.Path ?? "";
+  if (!pathVar) return false;
+  const dirs = pathVar.split(path.delimiter).filter(Boolean);
+  // On Windows the launcher is rtk.exe / rtk.cmd / rtk.bat.
+  const exts = process.platform === "win32" ? ["", ".exe", ".cmd", ".bat"] : [""];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, `rtk${ext}`);
+      try {
+        const st = fs.statSync(candidate);
+        if (st.isFile()) {
+          // POSIX: require an executable bit; Windows: extension is enough.
+          if (process.platform === "win32" || (st.mode & 0o111) !== 0) return true;
+        }
+      } catch {
+        /* not here — keep scanning */
+      }
+    }
+  }
+  return false;
+}
+
+function _extract_command(envelope: JsonObject): string | null {
+  const payload = (_isObject(envelope["payload"]) ? envelope["payload"] : {}) as JsonObject;
+  const tool_input = (_isObject(payload["tool_input"]) ? payload["tool_input"] : {}) as JsonObject;
+  for (const src of [tool_input["command"], payload["command"], envelope["command"]]) {
+    if (typeof src === "string") return src;
+  }
+  return null;
+}
+
+export interface Eligibility {
+  eligible: boolean;
+  program?: string;
+  reason_skip?: string;
+}
+
+/**
+ * A command is eligible for an rtk-wrap nudge iff it is a SINGLE simple command
+ * (no pipe / compound separators), whose program is a known verbose CLI, and is
+ * not a completeness-critical / already-wrapped case.
+ */
+export function classify(command: string): Eligibility {
+  const cmd = command.trim();
+  if (!cmd) return { eligible: false, reason_skip: "empty" };
+
+  let tokens: string[];
+  try {
+    tokens = shlexSplit(cmd);
+  } catch (e) {
+    if (e instanceof ShlexError) return { eligible: false, reason_skip: "parse-error" };
+    throw e;
+  }
+
+  // Compound / piped → don't wrap (rtk wraps a single command). `_split_subcommands`
+  // splits on && || ; | — more than one group means a pipeline/chain.
+  const groups = _split_subcommands(tokens);
+  if (groups.length !== 1) return { eligible: false, reason_skip: "compound-or-piped" };
+
+  const sub = groups[0] as string[];
+  let i = 0;
+  while (i < sub.length && _is_env_assignment(sub[i] as string)) i += 1;
+  const program = sub[i];
+  if (!program) return { eligible: false, reason_skip: "no-program" };
+  if (program === "rtk") return { eligible: false, reason_skip: "already-rtk" };
+  if (!_RTK_PROGRAMS.has(program)) return { eligible: false, program, reason_skip: "not-verbose-cli" };
+  // `git diff` is completeness-critical (silent truncation) — never wrap.
+  if (program === "git" && sub[i + 1] === "diff") {
+    return { eligible: false, program, reason_skip: "git-diff-denylisted" };
+  }
+  return { eligible: true, program };
+}
+
+function _readStdin(): string {
+  try {
+    if (process.stdin.isTTY) return "";
+    return fs.readFileSync(0, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+function _jsonReason(reason: string): string {
+  return JSON.stringify({ decision: "warn", reason });
+}
+
+export function main(): number {
+  let envelope: JsonValue;
+  try {
+    const raw = _readStdin();
+    envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+  } catch {
+    return EXIT_ALLOW; // never break a command on a malformed envelope
+  }
+  if (!_isObject(envelope)) return EXIT_ALLOW;
+
+  const cwd = envelope["cwd"];
+  const projectRoot = envelope["workspace_root"] ?? envelope["project_root"];
+  const root =
+    typeof cwd === "string" && cwd
+      ? cwd
+      : typeof projectRoot === "string" && projectRoot
+        ? projectRoot
+        : ".";
+  if (!_enabled(root)) return EXIT_ALLOW;
+
+  // Deterministic gate: the live probe, NOT a self-reported flag.
+  if (!rtk_available()) return EXIT_ALLOW;
+
+  const command = _extract_command(envelope);
+  if (!command) return EXIT_ALLOW;
+
+  const verdict = classify(command);
+  if (!verdict.eligible) return EXIT_ALLOW;
+
+  const reason =
+    `rtk is installed and wraps verbose CLI output (60–90% fewer output tokens). ` +
+    `Re-run wrapped: \`rtk ${command.trim()}\`. ` +
+    `(Skip for completeness-critical output like \`git diff\`.)`;
+  process.stdout.write(`${_jsonReason(reason)}\n`);
+  return EXIT_WARN;
+}
+
+const _isCliEntry =
+  process.argv[1] !== undefined &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry) {
+  process.exit(main());
+}

package/src/scripts/lint_agent_security.ts

@@ -43,6 +43,7 @@ type Finding = Record<string, unknown>;
 
 const LINTERS: ReadonlyArray<[string, string]> = [
   ["hidden-unicode", "lint_hidden_unicode.ts"],
+  ["mixed-script-confusable", "lint_confusables.ts"],
   ["instruction-smuggling", "lint_instruction_smuggling.ts"],
   ["mcp-config-security", "lint_mcp_config_security.ts"],
   ["dangerous-frontmatter", "lint_skill_frontmatter_safety.ts"],

package/src/scripts/lint_confusables.ts

@@ -0,0 +1,197 @@
+// Visible mixed-script confusable / homoglyph linter
+// (road-to-injection-defense-pressure-corpus.md, Phase 1.2).
+//
+// Sibling of `lint_hidden_unicode.ts`. That linter catches the INVISIBLE
+// smuggling class (zero-width, bidi, tag-block). This one catches the VISIBLE
+// class it misses: a Latin word with one or more letters swapped for
+// visually-identical Cyrillic or Greek lookalikes (mixed-script token) — the
+// homoglyph version of the rules-file-backdoor attack. A reviewer sees
+// "ignore"; the model reads a token whose 'o' is U+043E CYRILLIC SMALL LETTER O.
+//
+// Detection signature (high-precision, low-false-positive):
+//   A whitespace-delimited token is flagged when ALL hold —
+//     1. it contains >= 1 Latin letter AND >= 1 Cyrillic-or-Greek letter that
+//        is in the TR39 confusable set (has a Latin lookalike). Math operators
+//        with NO Latin lookalike (Δ Σ Π Ω Φ Θ Λ Ξ Ψ Γ …) are NOT confusables,
+//        so legit notation like "ΔNWC" / "Σwᵢ" is never flagged,
+//     2. it has >= MIN_LETTERS total letters, and
+//     3. Latin is the MAJORITY script (the attack is a Latin word with foreign
+//        lookalike substitutions, not a foreign word with one Latin letter).
+//   Pure-Cyrillic / pure-Greek / CJK prose is single-script per token and is
+//   never flagged — legit non-Latin text passes.
+//
+// Scope + containment mirror lint_hidden_unicode: scans every .md under
+// src/{skills,rules,agent-src,domains} via sl.iter_corpus(); a
+// ```security-example fence or a `security-lint: allow mixed-script-confusable`
+// pragma exempts a region/file (a doc teaching confusables needs to show one).
+//
+// Exit 0 clean, 1 on any blocking finding.
+//
+// Usage: ./scripts-run src/scripts/lint_confusables [--json]
+
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import * as sl from './_lib/security_lint.js';
+
+export const CHECK = 'mixed-script-confusable';
+
+const MIN_LETTERS = 3;
+
+// Unicode-script classifiers via property escapes (requires the `u` flag).
+const _LATIN = /\p{Script=Latin}/u;
+const _CYRILLIC = /\p{Script=Cyrillic}/u;
+const _GREEK = /\p{Script=Greek}/u;
+const _LETTER = /\p{L}/u;
+// A "token" is a maximal run of letters / combining marks / decimal digits.
+const _TOKEN = /[\p{L}\p{M}\p{Nd}]+/gu;
+
+// Cyrillic + Greek codepoints that have a basic-Latin lookalike (Unicode TR39
+// confusables, common subset). A foreign letter only counts toward the
+// confusable signal when it is in this set — Greek math operators with no Latin
+// twin (Δ Σ Π Ω Φ Θ Λ Ξ Ψ Γ δ π ω …) are deliberately excluded so legit
+// notation does not false-positive.
+const _CONFUSABLE_FOREIGN: ReadonlySet<number> = new Set([
+    // Cyrillic lowercase ↔ Latin
+    0x0430 /*а→a*/, 0x0435 /*е→e*/, 0x043e /*о→o*/, 0x0440 /*р→p*/, 0x0441 /*с→c*/,
+    0x0443 /*у→y*/, 0x0445 /*х→x*/, 0x0455 /*ѕ→s*/, 0x0456 /*і→i*/, 0x0458 /*ј→j*/,
+    0x04bb /*һ→h*/, 0x0501 /*ԁ→d*/, 0x051b /*ԛ→q*/, 0x0577 /*no*/,
+    // Cyrillic uppercase ↔ Latin
+    0x0410 /*А→A*/, 0x0412 /*В→B*/, 0x0415 /*Е→E*/, 0x041a /*К→K*/, 0x041c /*М→M*/,
+    0x041d /*Н→H*/, 0x041e /*О→O*/, 0x0420 /*Р→P*/, 0x0421 /*С→C*/, 0x0422 /*Т→T*/,
+    0x0423 /*У→Y*/, 0x0425 /*Х→X*/, 0x0405 /*Ѕ→S*/, 0x0406 /*І→I*/, 0x0408 /*Ј→J*/,
+    // Greek lowercase ↔ Latin
+    0x03b1 /*α→a*/, 0x03b5 /*ε→e*/, 0x03bf /*ο→o*/, 0x03bd /*ν→v*/, 0x03c1 /*ρ→p*/,
+    0x03c5 /*υ→u*/, 0x03c7 /*χ→x*/, 0x03ba /*κ→k*/,
+    // Greek uppercase ↔ Latin (only those with a real Latin twin)
+    0x0391 /*Α→A*/, 0x0392 /*Β→B*/, 0x0395 /*Ε→E*/, 0x0396 /*Ζ→Z*/, 0x0397 /*Η→H*/,
+    0x0399 /*Ι→I*/, 0x039a /*Κ→K*/, 0x039c /*Μ→M*/, 0x039d /*Ν→N*/, 0x039f /*Ο→O*/,
+    0x03a1 /*Ρ→P*/, 0x03a4 /*Τ→T*/, 0x03a5 /*Υ→Y*/, 0x03a7 /*Χ→X*/, 0x0392 /*Β→B*/,
+]);
+
+type ScriptName = 'latin' | 'cyrillic' | 'greek' | 'other';
+
+function _script_of(ch: string): ScriptName {
+    if (_LATIN.test(ch)) return 'latin';
+    if (_CYRILLIC.test(ch)) return 'cyrillic';
+    if (_GREEK.test(ch)) return 'greek';
+    return 'other';
+}
+
+/**
+ * Classify a single token. Returns the offending mixed-script descriptor when
+ * the token matches the homoglyph signature, else null.
+ */
+export function _classify_token(token: string): string | null {
+    let latin = 0;
+    let cyrillic = 0;
+    let greek = 0;
+    let letters = 0;
+    for (const ch of token) {
+        if (!_LETTER.test(ch)) continue; // skip combining marks / digits for script vote
+        letters += 1;
+        const script = _script_of(ch);
+        if (script === 'latin') {
+            latin += 1;
+        } else if (script === 'cyrillic' || script === 'greek') {
+            // Only confusable foreign letters (TR39) count — math operators with
+            // no Latin twin are ignored, so legit notation never trips.
+            if (_CONFUSABLE_FOREIGN.has(ch.codePointAt(0) as number)) {
+                if (script === 'cyrillic') cyrillic += 1;
+                else greek += 1;
+            }
+        }
+    }
+    if (letters < MIN_LETTERS) return null;
+    const foreign = cyrillic + greek;
+    if (latin === 0 || foreign === 0) return null; // single-script (or no Latin) → legit
+    if (latin <= foreign) return null; // majority must be Latin (foreign word ≠ attack)
+    const which = cyrillic > 0 && greek > 0
+        ? 'cyrillic+greek'
+        : cyrillic > 0
+            ? 'cyrillic'
+            : 'greek';
+    return `latin+${which} (${latin} latin / ${foreign} foreign-confusable)`;
+}
+
+export function _scan(sf: sl.ScannedFile): sl.Finding[] {
+    if (sf.pragma_allows(CHECK)) {
+        return [];
+    }
+    const out: sl.Finding[] = [];
+    for (const [lineno, text] of sf.iter_lines({ skip_example_fence: true })) {
+        const tokens = text.match(_TOKEN);
+        if (tokens === null) continue;
+        for (const tok of tokens) {
+            const desc = _classify_token(tok);
+            if (desc !== null) {
+                out.push(
+                    new sl.Finding(
+                        sf.rel,
+                        lineno,
+                        CHECK,
+                        'HIGH',
+                        `mixed-script confusable token "${tok}" — ${desc}`,
+                        sf.weight,
+                    ),
+                );
+            }
+        }
+    }
+    return out;
+}
+
+interface Args {
+    json: boolean;
+}
+
+function _argError(msg: string): never {
+    process.stderr.write('usage: lint_confusables [-h] [--json]\n');
+    process.stderr.write(`lint_confusables: error: ${msg}\n`);
+    process.exit(2);
+}
+
+function parse_args(argv: readonly string[]): Args {
+    const out: Args = { json: false };
+    const extra: string[] = [];
+    for (const a of argv) {
+        if (a === '-h' || a === '--help') {
+            process.stdout.write('usage: lint_confusables [-h] [--json]\n');
+            process.exit(0);
+        } else if (a === '--json') {
+            out.json = true;
+        } else {
+            extra.push(a);
+        }
+    }
+    if (extra.length > 0) {
+        _argError(`unrecognized arguments: ${extra.join(' ')}`);
+    }
+    return out;
+}
+
+export function main(argv: readonly string[] | null = null): number {
+    const args = parse_args(argv ?? process.argv.slice(2));
+
+    const findings: sl.Finding[] = [];
+    for (const sf of sl.iter_corpus()) {
+        for (const h of _scan(sf)) {
+            findings.push(h);
+        }
+    }
+
+    if (args.json) {
+        const payload = sl.py_json_dumps_indent2(findings.map((f) => f.toDict()));
+        process.stdout.write(payload + '\n');
+        return findings.some((f) => f.is_fail) ? 1 : 0;
+    }
+
+    return sl.report(findings, { check_label: 'mixed-script-confusable' });
+}
+
+const _isCliEntry =
+    process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry) {
+    process.exitCode = main();
+}