@event4u/agent-config 7.4.0 → 8.0.0

package/src/scripts/janitor.ts

@@ -0,0 +1,258 @@
+#!/usr/bin/env tsx
+/**
+ * Janitor — retention sweep for volatile/TTL directories.
+ *
+ * Supported TTL directories (per docs/contracts/agents-layout.md):
+ *   agents/tmp.old/     — processed inbox archive (TTL: 30 days)
+ *   agents/runtime/     — volatile runtime artefacts (TTL: 7 days for council/tmp)
+ *
+ * NEVER auto-sweeps agents/tmp/ (user inbox — user-owned, no TTL).
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/janitor          — dry-run report only
+ *   ./scripts-run src/scripts/janitor --apply  — delete expired files
+ *   ./scripts-run src/scripts/janitor --report — same as default (dry-run)
+ *
+ * Exit codes:
+ *   0 — report generated (dry-run) or sweep completed (--apply)
+ *   2 — invalid args
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.join(path.dirname(_HERE), '..', '..');
+
+// TTL configuration per directory (days)
+const TTL_CONFIG: ReadonlyArray<{ dir: string; ttlDays: number; description: string }> = [
+    {
+        dir: 'agents/tmp.old',
+        ttlDays: 30,
+        description: 'Processed inbox archive (consumed agents/tmp/ files)',
+    },
+    {
+        dir: 'agents/runtime/tmp',
+        ttlDays: 7,
+        description: 'Agent scratch / runtime tmp',
+    },
+    {
+        dir: 'agents/runtime/council/responses',
+        ttlDays: 7,
+        description: 'Council response cache',
+    },
+];
+
+// Directories that must NEVER be auto-swept
+const PROTECTED_DIRS: ReadonlySet<string> = new Set([
+    'agents/tmp',          // user inbox — user-owned, no TTL
+    'agents/knowledge',    // committed curated pages
+    'agents/memory',       // promotion pipeline (committed YAML)
+    'agents/decisions',    // permanent durable records
+    'agents/evidence',     // permanent durable evidence
+    'agents/roadmaps',     // tracked roadmaps
+]);
+
+interface FileStat {
+    relPath: string;
+    absPath: string;
+    ageDays: number;
+    size: number;
+}
+
+function _isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function _walkFiles(dir: string): string[] {
+    const results: string[] = [];
+    if (!_isDir(dir)) return results;
+    for (const entry of fs.readdirSync(dir)) {
+        const full = path.join(dir, entry);
+        const stat = fs.statSync(full);
+        if (stat.isFile()) {
+            results.push(full);
+        } else if (stat.isDirectory()) {
+            results.push(..._walkFiles(full));
+        }
+    }
+    return results;
+}
+
+function _ageDays(p: string): number {
+    try {
+        const stat = fs.statSync(p);
+        const ageMs = Date.now() - stat.mtimeMs;
+        return ageMs / (1000 * 60 * 60 * 24);
+    } catch {
+        return 0;
+    }
+}
+
+function _humanSize(bytes: number): string {
+    if (bytes < 1024) return `${bytes}B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}kB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+}
+
+function report(apply: boolean): void {
+    const now = new Date();
+    process.stdout.write(`\n🗂️  Janitor report — ${now.toISOString().slice(0, 10)}\n\n`);
+
+    // Inbox status (never swept, report only)
+    const inboxDir = path.join(REPO_ROOT, 'agents/tmp');
+    if (_isDir(inboxDir)) {
+        const files = _walkFiles(inboxDir);
+        if (files.length === 0) {
+            process.stdout.write(`✅  agents/tmp/ (user inbox) — empty\n`);
+        } else {
+            const oldest = files.map((f) => _ageDays(f)).reduce((a, b) => Math.max(a, b), 0);
+            const totalSize = files.reduce((s, f) => {
+                try { return s + fs.statSync(f).size; } catch { return s; }
+            }, 0);
+            process.stdout.write(
+                `📥  agents/tmp/ (user inbox) — ${files.length} file(s), ` +
+                    `oldest: ${oldest.toFixed(0)}d, size: ${_humanSize(totalSize)}\n` +
+                    `    (user-owned; never auto-swept)\n`,
+            );
+        }
+    }
+
+    process.stdout.write('\n');
+
+    // Harvest-local size note
+    const harvestDir = path.join(REPO_ROOT, 'agents/.harvest-local');
+    if (_isDir(harvestDir)) {
+        const files = _walkFiles(harvestDir);
+        const totalSize = files.reduce((s, f) => {
+            try { return s + fs.statSync(f).size; } catch { return s; }
+        }, 0);
+        process.stdout.write(
+            `📦  agents/.harvest-local/ — ${_humanSize(totalSize)} ` +
+                `(source-confidentiality evidence; retain, never auto-deleted)\n\n`,
+        );
+    }
+
+    let totalExpired = 0;
+    let totalSize = 0;
+
+    for (const { dir, ttlDays, description } of TTL_CONFIG) {
+        const absDir = path.join(REPO_ROOT, dir);
+        if (!_isDir(absDir)) continue;
+
+        // Safety: never sweep protected dirs
+        if (PROTECTED_DIRS.has(dir)) {
+            process.stdout.write(`🔒  ${dir} — protected, skipping\n`);
+            continue;
+        }
+
+        const files = _walkFiles(absDir);
+        const expired: FileStat[] = [];
+
+        for (const absPath of files) {
+            const ageDays = _ageDays(absPath);
+            if (ageDays >= ttlDays) {
+                let size = 0;
+                try { size = fs.statSync(absPath).size; } catch { /* */ }
+                expired.push({ relPath: path.relative(REPO_ROOT, absPath), absPath, ageDays, size });
+            }
+        }
+
+        if (files.length === 0) {
+            process.stdout.write(`✅  ${dir}/ — empty\n`);
+            continue;
+        }
+
+        const dirSize = files.reduce((s, f) => {
+            try { return s + fs.statSync(f).size; } catch { return s; }
+        }, 0);
+        process.stdout.write(
+            `📁  ${dir}/ — ${files.length} file(s), ${_humanSize(dirSize)} total, ` +
+                `TTL: ${ttlDays}d (${description})\n`,
+        );
+
+        if (expired.length === 0) {
+            process.stdout.write(`    ✅  No expired files.\n`);
+        } else {
+            const expiredSize = expired.reduce((s, f) => s + f.size, 0);
+            process.stdout.write(
+                `    ⚠️  ${expired.length} expired file(s), ${_humanSize(expiredSize)} reclaimable:\n`,
+            );
+            for (const f of expired.slice(0, 10)) {
+                process.stdout.write(
+                    `       ${f.relPath} (${f.ageDays.toFixed(0)}d old, ${_humanSize(f.size)})\n`,
+                );
+            }
+            if (expired.length > 10) {
+                process.stdout.write(`       … and ${expired.length - 10} more\n`);
+            }
+
+            if (apply) {
+                for (const f of expired) {
+                    try { fs.unlinkSync(f.absPath); } catch { /* ignore */ }
+                }
+                // Remove empty dirs
+                for (const f of expired) {
+                    let dir = path.dirname(f.absPath);
+                    while (dir.startsWith(absDir) && dir !== absDir) {
+                        try {
+                            if (fs.readdirSync(dir).length === 0) {
+                                fs.rmdirSync(dir);
+                            }
+                        } catch { /* */ }
+                        dir = path.dirname(dir);
+                    }
+                }
+                process.stdout.write(`    🗑️  Deleted ${expired.length} expired file(s).\n`);
+            } else {
+                process.stdout.write(
+                    `    → Run with --apply to delete. All files stay on disk in dry-run mode.\n`,
+                );
+            }
+
+            totalExpired += expired.length;
+            totalSize += expired.reduce((s, f) => s + f.size, 0);
+        }
+        process.stdout.write('\n');
+    }
+
+    if (!apply && totalExpired > 0) {
+        process.stdout.write(
+            `Total reclaimable: ${totalExpired} file(s), ${_humanSize(totalSize)}\n` +
+                `Run \`./scripts-run src/scripts/janitor --apply\` to delete.\n`,
+        );
+    } else if (apply && totalExpired > 0) {
+        process.stdout.write(`Total deleted: ${totalExpired} file(s), ${_humanSize(totalSize)} freed.\n`);
+    }
+}
+
+function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+
+    if (args.includes('--help') || args.includes('-h')) {
+        process.stdout.write(
+            'Usage: janitor [--apply] [--report]\n' +
+                '  (no flags)  — dry-run report\n' +
+                '  --report    — same as no flags\n' +
+                '  --apply     — delete expired files\n',
+        );
+        return 0;
+    }
+
+    const apply = args.includes('--apply');
+    report(apply);
+    return 0;
+}
+
+const _isCliEntry =
+    process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export { main, TTL_CONFIG, PROTECTED_DIRS };

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_agents_layout.ts

@@ -14,7 +14,11 @@
  * uses the cwd-relative `agents/` root exactly as the Python does, so the
  * printed paths (`agents/<name>`) match byte-for-byte.
  *
- * No behaviour changes.
+ * Extended (road-to-agents-dir-and-gitignore-hygiene Phase 2.3):
+ * - In source-repo mode, unknown TOP-LEVEL DIRECTORIES also become errors.
+ *   Whitelist is ALLOWED_SOURCE_DIRS (see docs/contracts/agents-layout.md).
+ * - CONSUMER_EXPECTED_ENTRIES extended with the full consumer-scope subset
+ *   from the contract (knowledge/, memory/, roadmaps/, tmp/, tmp.old/).
  */
 
 import * as fs from 'node:fs';
@@ -33,12 +37,57 @@ const ALLOWED_FLAT_FILES: ReadonlySet<string> = new Set([
     '.event4u-bridge.yml',
     '.agent-tools.yml',
     '.maintainer-workspace.md',
+    // Gitignored local-only files (present in working tree, never committed).
+    // NOTE: if any of these are tracked (appear in `git ls-files`), that is a
+    // separate violation caught by check_tracked_but_ignored.ts.
+    '.ai-video.xml',       // operator AI-video config; gitignored per .gitignore § AI Video
+    'installed-tools.lock', // installer per-user inventory; gitignored per ADR-020
+    '.event4u-bridge.yml',  // consumer bridge marker; ADR-020 (should only be in consumers)
+]);
+
+// All directories allowed at the agents/ root in the SOURCE REPO.
+// Entries marked (* consumer) are also allowed in consumer projects.
+// Contract: docs/contracts/agents-layout.md § Directory table.
+const ALLOWED_SOURCE_DIRS: ReadonlySet<string> = new Set([
+    'decisions',
+    'evidence',
+    'features',
+    'knowledge',    // * consumer
+    'memory',       // * consumer
+    'notes',        // legacy; new files go to evidence/notes/
+    'reports',      // legacy; new files go to evidence/reports/ (see agents-layout.md)
+    'overrides',    // * consumer
+    'recruit-sessions',
+    'reference',
+    'roadmap-assets',
+    'roadmaps',     // * consumer
+    'roles',
+    'runtime',      // local-only, gitignored
+    'settings',
+    'state',        // local-only, gitignored
+    'templates',
+    'tickets',
+    'tmp',          // local-only, gitignored (* consumer)
+    'tmp.old',      // local-only, gitignored (* consumer)
+    '.harvest-local', // local-only, gitignored
 ]);
 
 const CONSUMER_EXPECTED_ENTRIES: ReadonlySet<string> = new Set([
+    // Required consumer entries
     'overrides',
     '.event4u-bridge.yml',
     '.gitkeep',
+    // Optional but legitimate consumer entries (will not trigger warnings)
+    'knowledge',
+    'memory',
+    'roadmaps',
+    'tmp',
+    'tmp.old',
+    // Flat files that are tracked in consumers
+    'index.md',
+    'roadmaps-progress.md',
+    '.agent-tools.yml',
+    '.maintainer-workspace.md',
 ]);
 
 const MIGRATE_HINT =
@@ -99,26 +148,35 @@ function is_source_repo(projectRoot: string): boolean {
     return false;
 }
 
-function find_violations(root: string): string[] {
+function find_violations(root: string, sourceRepo = false): string[] {
     const unknown: string[] = [];
     if (!_isDir(root)) {
         return unknown;
     }
     for (const p of _iterdirSorted(root)) {
-        if (!_isFile(p)) {
-            continue;
-        }
         const name = path.basename(p);
-        if (ALLOWED_FLAT_FILES.has(name)) {
-            continue;
+        if (_isFile(p)) {
+            if (ALLOWED_FLAT_FILES.has(name)) {
+                continue;
+            }
+            unknown.push(
+                `${p}: flat file not in agents/ whitelist — move to a typed ` +
+                    'subdirectory (runtime/, evidence/, decisions/, settings/, ' +
+                    'audits/, roadmaps/, policies/, contexts/, …) or add to ' +
+                    'ALLOWED_FLAT_FILES in scripts/lint_agents_layout.ts with ' +
+                    'rationale.',
+            );
+        } else if (_isDir(p) && sourceRepo) {
+            // In source-repo mode, unknown top-level directories are also errors.
+            // See docs/contracts/agents-layout.md § Directory table.
+            if (!ALLOWED_SOURCE_DIRS.has(name)) {
+                unknown.push(
+                    `${p}: unknown top-level directory in agents/ — ` +
+                        'add to ALLOWED_SOURCE_DIRS in lint_agents_layout.ts ' +
+                        '(with rationale) AND to docs/contracts/agents-layout.md.',
+                );
+            }
         }
-        unknown.push(
-            `${p}: flat file not in agents/ whitelist — move to a typed ` +
-                'subdirectory (runtime/, evidence/, decisions/, settings/, ' +
-                'audits/, roadmaps/, policies/, contexts/, …) or add to ' +
-                'ALLOWED_FLAT_FILES in scripts/lint_agents_layout.py with ' +
-                'rationale.',
-        );
     }
     return unknown;
 }
@@ -149,8 +207,8 @@ function main(argv?: readonly string[]): number {
     const quiet = args.includes('--quiet');
 
     const projectRoot = process.cwd();
-    const unknown = find_violations(AGENTS_ROOT);
     const consumerMode = !is_source_repo(projectRoot);
+    const unknown = find_violations(AGENTS_ROOT, !consumerMode);
     const warnings = consumerMode ? find_consumer_warnings(AGENTS_ROOT) : [];
 
     if (unknown.length > 0) {
@@ -196,6 +254,7 @@ if (_isCliEntry || process.argv[1] === _HERE) {
 export {
     AGENTS_ROOT,
     ALLOWED_FLAT_FILES,
+    ALLOWED_SOURCE_DIRS,
     CONSUMER_EXPECTED_ENTRIES,
     MIGRATE_HINT,
     is_source_repo,

package/src/scripts/lint_bench_ab.ts

@@ -32,7 +32,10 @@ const REQUIRED_SECTIONS = [
     // bench_ab_v2_stats.py --markdown). The v1 Headline/Track-A/Track-B/History
     // structure was retired with the v1 binary-capability frame.
     '## Honesty labels',
-    '## Gate verdict',
+    // Since the 2026-07 per-host split the verdict lives inside per-host h2
+    // headings ("## Weak host (…) — Gate verdict: **PASS**"), so match the
+    // verdict label rather than a standalone "## Gate verdict" section.
+    'Gate verdict:',
     '## Methodology',
 ] as const;
 

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();
+}