@event4u/agent-config 9.35.0 → 10.0.0

package/src/scripts/hooks/ui_route_nudge_hook.ts

@@ -0,0 +1,250 @@
+#!/usr/bin/env tsx
+/**
+ * PreToolUse UI-route nudge — deterministic, warn-only, default-OFF.
+ *
+ * The two UI rules have `enforced_by: none` and say so honestly: nothing
+ * observes whether a UI write consulted the design surface first. This concern
+ * observes it — and it is a nudge, not a gate. It never blocks (dispatcher
+ * contract: 0 allow · 2 warn), because the obligation it points at is a
+ * judgement call and a block on a judgement call trades an ignore-problem for
+ * a friction-problem.
+ *
+ * IT DOES NOT READ THE RULES. Stated because the first draft of this header
+ * claimed it did. The UI-surface decision comes from `_lib/ui_surface.ts`; no
+ * code here parses `src/rules/*.md` frontmatter, so the rules' `keyword:`
+ * triggers still have no runtime consumer and this predicate is deliberately
+ * wider than their `file_pattern` list. The two are kept from drifting by
+ * `ui_rule_triggers.test.ts`, which asserts every declared pattern is accepted
+ * here — a test, not a dependency.
+ *
+ * WHAT IT OBSERVES, WHICH IS ALSO THE MEASUREMENT.
+ * Every PreToolUse event passes through here. A read or search touching a
+ * design surface (`fe-design`, `existing-ui-audit`, `design-review`,
+ * `design-intelligence`) latches "consulted" for the session. A Write or Edit
+ * to a UI path with no such latch is the case the nudge exists for. That latch
+ * is exactly the consultation signal the pre-registered consultation rate
+ * counts, so the nudge and the metric read the same event stream rather than
+ * two populations that could drift apart.
+ *
+ * ANTI-LOOP. At most `MAX_NUDGES` per session, then silent — the same
+ * degradation valve `design_slop_hook` carries, for the same reason: an agent
+ * that has decided to proceed must not be re-prompted into a loop.
+ *
+ * HOST BOUNDARY, STATED RATHER THAN IMPLIED. `pre_tool_use` exists on three
+ * hosts. Everywhere else this concern has nowhere to bind and the obligation
+ * stays model-carried, exactly as the two rules already declare. Run
+ * `agent-config hooks:status` for the host you are actually on.
+ *
+ * Default-OFF: no-ops unless `hooks.ui_route_nudge.enabled: true`.
+ * fail_closed: false — any error returns allow.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { hookSectionEnabled } from '../_lib/hook_settings.js';
+import { isUiPath, isUiTreePath } from '../_lib/ui_surface.js';
+import { readHookStdin } from './hook_stdin.js';
+
+const EXIT_ALLOW = 0;
+const EXIT_WARN = 2;
+/** Nudges per session before the valve goes silent. */
+export const MAX_NUDGES = 2;
+
+/** Reads or searches that count as consulting the design surface. */
+export const DESIGN_SURFACES = [
+    'fe-design',
+    'existing-ui-audit',
+    'design-review',
+    'design-intelligence',
+] as const;
+
+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);
+}
+
+function unwrap(envelope: JsonObject): JsonObject {
+    const inner = envelope['payload'];
+    return isObject(inner) ? inner : envelope;
+}
+
+export interface ToolEvent {
+    /** Path the tool touches; "" when the tool names none. */
+    file: string;
+    /** True when the tool proposes new content (Write / Edit). */
+    isWrite: boolean;
+}
+
+/** Best-effort extraction; mirrors the shape `design_slop_hook` reads. */
+export function extractEvent(outer: JsonObject): ToolEvent | null {
+    const envelope = unwrap(outer);
+    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 : '';
+
+    let isWrite = false;
+    for (const key of ['content', 'new_string', 'new_str', 'text', 'newText']) {
+        if (typeof ti[key] === 'string' && (ti[key] as string).length > 0) isWrite = true;
+    }
+
+    return { file, isWrite };
+}
+
+/**
+ * True when the event OPENS one of the design surfaces.
+ *
+ * Deliberately narrow, and the narrowness is the fix for a real defect: an
+ * earlier version matched the surface name anywhere in the path OR in any
+ * search text the tool carried, including `command`. That silenced the nudge
+ * for a whole session on a `git log -- src/skills/fe-design`, on a grep for
+ * `design-review` while writing a review artefact, and on a read of
+ * `src/rules/design-review-after-ui-write.md` — whose path contains the skill
+ * name without being the skill. Since the same latch is the consultation
+ * signal the pre-registered rate counts, one false positive corrupted both the
+ * gate and the metric.
+ *
+ * So consultation means: a non-write touching `skills/<surface>/`. A search is
+ * not a consultation — reading the skill is.
+ */
+export function isConsultation(event: ToolEvent): boolean {
+    if (event.isWrite || !event.file) return false;
+    const normalized = event.file.replace(/\\/g, '/').toLowerCase();
+    return DESIGN_SURFACES.some((surface) => normalized.includes(`skills/${surface}/`));
+}
+
+/** True when the event writes a UI surface. */
+export function isUiWrite(event: ToolEvent): boolean {
+    if (!event.isWrite || !event.file) return false;
+    return isUiPath(event.file) || isUiTreePath(event.file);
+}
+
+export interface SessionState {
+    consulted: boolean;
+    nudges: number;
+}
+
+function stateFile(root: string): string {
+    return path.join(root, 'agents', 'runtime', 'state', 'ui-route-nudge.json');
+}
+
+export function readState(root: string, session: string): SessionState {
+    try {
+        const all = JSON.parse(fs.readFileSync(stateFile(root), 'utf-8')) as Record<
+            string,
+            SessionState
+        >;
+        const entry = all[session];
+        if (entry && typeof entry.consulted === 'boolean' && typeof entry.nudges === 'number') {
+            return entry;
+        }
+    } catch {
+        /* fresh session */
+    }
+    return { consulted: false, nudges: 0 };
+}
+
+/** Sessions retained in the state file; oldest entries drop past this. */
+export const MAX_SESSIONS = 50;
+
+/** Drop the oldest entries so the file cannot grow without bound. */
+export function pruneSessions(
+    all: Record<string, SessionState>,
+    keep: number = MAX_SESSIONS,
+): Record<string, SessionState> {
+    const keys = Object.keys(all);
+    if (keys.length <= keep) return all;
+    const survivors = keys.slice(keys.length - keep);
+    const pruned: Record<string, SessionState> = {};
+    for (const key of survivors) pruned[key] = all[key]!;
+    return pruned;
+}
+
+export function writeState(root: string, session: string, state: SessionState): void {
+    try {
+        const file = stateFile(root);
+        let all: Record<string, SessionState> = {};
+        try {
+            all = JSON.parse(fs.readFileSync(file, 'utf-8')) as Record<string, SessionState>;
+        } catch {
+            // Fresh file, or one nothing can parse. There is no other session
+            // state to preserve in either case — a corrupt file has already
+            // lost it — so starting from empty is recovery, not discard. The
+            // cost is bounded: a lost latch means at most MAX_NUDGES extra
+            // reminders in the sessions that were in flight.
+        }
+        if (typeof all !== 'object' || all === null || Array.isArray(all)) all = {};
+        all[session] = state;
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(pruneSessions(all)));
+    } catch {
+        /* fail-open: a persistence failure must never break a tool call */
+    }
+}
+
+/**
+ * The decision, pure — so the test exercises the logic rather than the
+ * filesystem. Returns the next state and whether to warn.
+ */
+export function decide(
+    event: ToolEvent,
+    state: SessionState,
+): { state: SessionState; warn: boolean } {
+    if (isConsultation(event)) {
+        return { state: { ...state, consulted: true }, warn: false };
+    }
+    if (!isUiWrite(event)) return { state, warn: false };
+    if (state.consulted) return { state, warn: false };
+    if (state.nudges >= MAX_NUDGES) return { state, warn: false };
+    return { state: { ...state, nudges: state.nudges + 1 }, warn: true };
+}
+
+export function nudgeReason(file: string): string {
+    return `Non-trivial UI write to ${file} with no design consultation this session. Run \`existing-ui-audit\` first, then the fe-design loop (brief → build → review). Skip only if this is ui-trivial: <=1 file, <=5 lines, no new component, no new state, no new dependency.`;
+}
+
+export function main(): number {
+    let envelope: JsonValue;
+    try {
+        const raw = readHookStdin();
+        if (!raw.trim()) return EXIT_ALLOW;
+        envelope = JSON.parse(raw) as JsonValue;
+    } catch {
+        return EXIT_ALLOW;
+    }
+    if (!isObject(envelope)) return EXIT_ALLOW;
+
+    const rootVal = envelope['workspace_root'];
+    const root = typeof rootVal === 'string' && rootVal ? rootVal : process.cwd();
+    if (!hookSectionEnabled(root, 'ui_route_nudge')) return EXIT_ALLOW;
+
+    const sessionVal = envelope['session_id'];
+    const session = typeof sessionVal === 'string' && sessionVal ? sessionVal : 'unknown';
+
+    const event = extractEvent(envelope);
+    if (!event) return EXIT_ALLOW;
+
+    const before = readState(root, session);
+    const { state, warn } = decide(event, before);
+    if (state.consulted !== before.consulted || state.nudges !== before.nudges) {
+        writeState(root, session, state);
+    }
+    if (!warn) return EXIT_ALLOW;
+
+    process.stdout.write(`${JSON.stringify({ reason: nudgeReason(event.file) })}\n`);
+    return EXIT_WARN;
+}
+
+function isCliEntry(): boolean {
+    const entry = process.argv[1];
+    if (!entry) return false;
+    return pathToFileURL(path.resolve(entry)).href === import.meta.url;
+}
+
+if (isCliEntry()) process.exit(main());
+
+export const _HOOK_FILE = fileURLToPath(import.meta.url);

package/src/scripts/lint_roadmap_complexity.ts

@@ -216,6 +216,7 @@ function lint_roadmap(
         _check_human_gate_steps(text, warnings);
         _check_human_gate_phase_headings(text, warnings);
         _check_human_gate_exit_criteria(text, warnings);
+        _check_external_population_gates(text, warnings);
     }
     return problems;
 }
@@ -383,6 +384,65 @@ function _check_human_gate_exit_criteria(text: string, warnings: string[]): void
     }
 }
 
+// A gate whose opening condition depends on a quantity the project cannot
+// produce is not a gate — it is a permanent no in the shape of an answer. The
+// measured case: a single-user private tool carried a roadmap gate on "external
+// installations with write activity", which held 33 steps closed and would have
+// held them closed forever. Matched only inside gate-shaped context (exit
+// criteria, acceptance criteria, a blocker's `Resolved when:`), because these
+// nouns are ordinary vocabulary in a roadmap for an actual product.
+const EXTERNAL_POPULATION_PATS: Array<[RegExp, string]> = [
+    [/\bexternal (users?|installs?|installations?|adopters?|consumers?)\b/i, 'an external user population'],
+    // Bare `adopters` is deliberately absent: measured against the real roadmap
+    // corpus it matched four internal counts ("4 adopters" of a gate helper),
+    // and an external adopter count is already covered by the pattern above.
+    [/\b(installations?|sign-?ups?|subscribers?|active users?)\b/i, 'an external adoption count'],
+    [/\bmarket (demand|validation|traction|fit|signal)\b/i, 'a market signal'],
+    [/\bchurn(ing|ed)?\b/i, 'a metric only a real user population produces'],
+    [/\buser (population|base|segment)\b/i, 'a user population'],
+    [/\b(?:at least |≥\s?)\d+ (people|users|customers|installs|adopters)\b/i, 'a headcount threshold of external people'],
+];
+
+const RESOLVED_WHEN_PAT = /^\s*(?:[-*]\s+)?\*{0,2}resolved when\*{0,2}\s*:/i;
+
+const AUDIENCE_HINT =
+    'is this project meant to have that population at all? A gate whose ' +
+    'condition depends on a quantity the project cannot produce is a permanent ' +
+    'no, not a gate — see project.audience and § 8-pre of ' +
+    'docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md';
+
+function _check_external_population_gates(text: string, warnings: string[]): void {
+    let inHeadingBlock = false;
+    let inInlineBlock = false;
+    for (const rawLine of text.split('\n')) {
+        const heading = /^#{1,6}\s+(.*)$/.exec(rawLine);
+        if (heading) {
+            inHeadingBlock = /\b(acceptance|exit criteria)\b/i.test(heading[1]!);
+            inInlineBlock = false;
+            continue;
+        }
+        if (rawLine.trim() === '') {
+            inInlineBlock = false;
+            continue;
+        }
+        if (EXIT_CRITERIA_OPENER_PAT.test(rawLine)) {
+            inInlineBlock = true;
+        }
+        const isResolvedWhen = RESOLVED_WHEN_PAT.test(rawLine);
+        if (!inHeadingBlock && !inInlineBlock && !isResolvedWhen) {
+            continue;
+        }
+        for (const [re, label] of EXTERNAL_POPULATION_PATS) {
+            if (re.test(rawLine)) {
+                warnings.push(
+                    `gate rests on ${label}: "${rawLine.trim().slice(0, 80)}" — ` + AUDIENCE_HINT,
+                );
+                break;
+            }
+        }
+    }
+}
+
 function _check_execution_mode(fm: string, problems: string[]): void {
     if (!fm || !/^execution:/m.test(fm)) {
         return; // absent field = interactive default — valid

package/src/scripts/lint_rule_skill_pack_reach.ts

@@ -0,0 +1,263 @@
+#!/usr/bin/env tsx
+/**
+ * lint_rule_skill_pack_reach — a rule and the skills it routes to must be able
+ * to arrive in the same install.
+ *
+ * The defect that motivated this is real and was undocumented in the direction
+ * it actually runs. `ui-audit-gate` and `design-review-after-ui-write` are
+ * `packs: [frontend-design]`; `existing-ui-audit`, `design-review` and
+ * `fe-design` are `packs: [engineering-base]`. The direction the rule prose
+ * described — frontend-design without engineering-base — cannot happen, because
+ * `frontend-design` declares `requires: [engineering-base]`. The reverse can: a
+ * plain `laravel` or `react` install carries the skills and **no rule that ever
+ * routes to them**, since both packs only *suggest* frontend-design.
+ *
+ * TWO CHECKS, AND THEY ARE NOT THE SAME QUESTION.
+ *
+ *   unreachable-route (error) — a rule routes to a skill that a pack-legal
+ *   install of that rule cannot receive. The consumer gets the obligation
+ *   without the artefact that discharges it.
+ *
+ *   unrouted-skill (advisory) — a skill that IS routed somewhere reaches a pack
+ *   none of its routing rules reach. The consumer has the artefact and no path
+ *   to it. This is the measured case above.
+ *
+ *   Scope, stated because the obvious reading is wider than the scan: the
+ *   subject set is skills some rule already routes to. A skill NO rule routes
+ *   to anywhere is never examined, deliberately — most of the estate is in
+ *   that set by design (a skill invoked by name needs no rule), so reporting
+ *   it would bury the finding this check exists for. Advisory for the same
+ *   reason: reachability-only-by-invocation is a legitimate design, so a
+ *   finding here is a question, not a verdict.
+ *
+ * The install closure is `pack + requires*` — the transitive expansion the
+ * resolver performs. `suggests` is deliberately NOT followed: it is advisory,
+ * the wizard may offer it and the user may decline, so an invariant that
+ * counted it would pass on installs that do not exist.
+ *
+ * ADVISORY UNTIL ITS FINDING SET IS EMPTY, AND THE FIRST RUN SAYS WHY.
+ * Measured on introduction: 12 `unreachable-route` and 14 `unrouted-skill`
+ * findings across 116 rules. The UI pair is one instance of an estate-wide
+ * pattern — safety floors routing into packs their own pack does not pull, and
+ * skills delivered by a pack whose routing rule ships in a different one.
+ * Shipping this as a blocking gate on day one would have meant either 12
+ * unrelated fixes smuggled into a feature change or a suppression file created
+ * on day one, which is the ratchet-shaped failure this repo has recorded
+ * before. So `--strict` exists and the default does not use it: promotion to
+ * error is a one-flag change once the set is empty, and the count is printed
+ * on every run so "still 12" cannot quietly become "still 30".
+ *
+ * Exit codes: 0 advisory run (default) or clean · 1 `unreachable-route`
+ * findings under `--strict` · 2 usage or IO error. A scan that walked no rules
+ * exits 2 rather than green — a gate that scanned nothing must never read as a
+ * pass.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { parse as parseYaml } from 'yaml';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+const RULES_DIR = path.join(REPO, 'src', 'rules');
+const SKILLS_DIR = path.join(REPO, 'src', 'skills');
+const PACKS_FILE = path.join(REPO, 'src', 'config', 'discovery', 'packs.yml');
+
+export interface PackDef {
+    id: string;
+    requires: string[];
+}
+
+export interface Finding {
+    kind: 'unreachable-route' | 'unrouted-skill';
+    subject: string;
+    detail: string;
+}
+
+/** Frontmatter block between the leading fences, or "" when absent. */
+function frontmatterOf(content: string): string {
+    if (!content.startsWith('---')) return '';
+    const end = content.indexOf('\n---', 3);
+    return end === -1 ? '' : content.slice(3, end);
+}
+
+function frontmatterObject(file: string): Record<string, unknown> {
+    const raw = frontmatterOf(fs.readFileSync(file, 'utf-8'));
+    if (!raw.trim()) return {};
+    try {
+        const parsed = parseYaml(raw) as unknown;
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? (parsed as Record<string, unknown>)
+            : {};
+    } catch {
+        return {};
+    }
+}
+
+function stringList(value: unknown): string[] {
+    if (Array.isArray(value)) return value.filter((v): v is string => typeof v === 'string');
+    if (typeof value === 'string') return [value];
+    return [];
+}
+
+/** Parse the pack registry into id → hard requirements. */
+export function readPacks(file: string): Map<string, PackDef> {
+    const parsed = parseYaml(fs.readFileSync(file, 'utf-8')) as unknown;
+    const out = new Map<string, PackDef>();
+    if (!Array.isArray(parsed)) return out;
+    for (const entry of parsed) {
+        if (!entry || typeof entry !== 'object') continue;
+        const record = entry as Record<string, unknown>;
+        const id = record['id'];
+        if (typeof id !== 'string') continue;
+        out.set(id, { id, requires: stringList(record['requires']) });
+    }
+    return out;
+}
+
+/** `pack + requires*` — what an install selecting `pack` actually receives. */
+export function installClosure(pack: string, packs: Map<string, PackDef>): Set<string> {
+    const seen = new Set<string>();
+    const queue = [pack];
+    while (queue.length > 0) {
+        const current = queue.pop()!;
+        if (seen.has(current)) continue;
+        seen.add(current);
+        for (const required of packs.get(current)?.requires ?? []) queue.push(required);
+    }
+    return seen;
+}
+
+interface RuleInfo {
+    name: string;
+    packs: string[];
+    routesToSkills: string[];
+}
+
+export function readRules(dir: string): RuleInfo[] {
+    return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith('.md'))
+        .map((f) => {
+            const fm = frontmatterObject(path.join(dir, f));
+            return {
+                name: f.replace(/\.md$/, ''),
+                packs: stringList(fm['packs']),
+                routesToSkills: stringList(fm['routes_to'])
+                    .filter((r) => r.startsWith('skill:'))
+                    .map((r) => r.slice('skill:'.length)),
+            };
+        });
+}
+
+export function readSkillPacks(dir: string): Map<string, string[]> {
+    const out = new Map<string, string[]>();
+    for (const name of fs.readdirSync(dir)) {
+        const file = path.join(dir, name, 'SKILL.md');
+        if (!fs.existsSync(file)) continue;
+        out.set(name, stringList(frontmatterObject(file)['packs']));
+    }
+    return out;
+}
+
+export function analyze(
+    rules: RuleInfo[],
+    skillPacks: Map<string, string[]>,
+    packs: Map<string, PackDef>,
+): Finding[] {
+    const findings: Finding[] = [];
+
+    // 1. unreachable-route — the obligation without the artefact.
+    for (const rule of rules) {
+        if (rule.packs.length === 0) continue; // unscoped rule ships everywhere
+        for (const skill of rule.routesToSkills) {
+            const target = skillPacks.get(skill);
+            if (target === undefined) continue; // a missing skill is check_references' job
+            if (target.length === 0) continue; // unscoped skill ships everywhere
+            const unreachableFrom = rule.packs.filter((p) => {
+                const closure = installClosure(p, packs);
+                return !target.some((tp) => closure.has(tp));
+            });
+            if (unreachableFrom.length === 0) continue;
+            findings.push({
+                kind: 'unreachable-route',
+                subject: `${rule.name} → skill:${skill}`,
+                detail: `rule pack(s) [${unreachableFrom.join(', ')}] do not reach skill pack(s) [${target.join(', ')}]`,
+            });
+        }
+    }
+
+    // 2. unrouted-skill — the artefact without a path to it.
+    const routedSkills = new Set(rules.flatMap((r) => r.routesToSkills));
+    for (const skill of routedSkills) {
+        const target = skillPacks.get(skill);
+        if (target === undefined || target.length === 0) continue;
+        const routingRules = rules.filter((r) => r.routesToSkills.includes(skill));
+        for (const skillPack of target) {
+            const closure = installClosure(skillPack, packs);
+            const reached = routingRules.some(
+                (r) => r.packs.length === 0 || r.packs.some((p) => closure.has(p)),
+            );
+            if (reached) continue;
+            findings.push({
+                kind: 'unrouted-skill',
+                subject: `skill:${skill}`,
+                detail: `an install of pack [${skillPack}] receives this skill but none of its routing rule(s) [${routingRules.map((r) => r.name).join(', ')}]`,
+            });
+        }
+    }
+
+    return findings;
+}
+
+function main(): number {
+    const packs = readPacks(PACKS_FILE);
+    const rules = readRules(RULES_DIR);
+    const skillPacks = readSkillPacks(SKILLS_DIR);
+
+    if (rules.length === 0 || skillPacks.size === 0 || packs.size === 0) {
+        process.stderr.write(
+            `❌  lint_rule_skill_pack_reach scanned nothing (rules=${rules.length}, skills=${skillPacks.size}, packs=${packs.size}) — refusing to report a pass\n`,
+        );
+        return 2;
+    }
+
+    const findings = analyze(rules, skillPacks, packs);
+    const errors = findings.filter((f) => f.kind === 'unreachable-route');
+    const advisories = findings.filter((f) => f.kind === 'unrouted-skill');
+
+    // --quiet suppresses the per-finding lines but never the count line: this
+    // gate is expected to stay non-empty for a while, and a quiet run that
+    // printed nothing at all would read as clean.
+    const quiet = process.argv.includes('--quiet');
+    if (!quiet) {
+        for (const finding of errors) {
+            process.stdout.write(`❌  ${finding.subject} — ${finding.detail}\n`);
+        }
+        for (const finding of advisories) {
+            process.stdout.write(`⚠️  ${finding.subject} — ${finding.detail}\n`);
+        }
+    }
+
+    const strict = process.argv.includes('--strict');
+    process.stdout.write(
+        `scanned: ${rules.length} rule(s), ${skillPacks.size} skill(s), ${packs.size} pack(s) — ${errors.length} unreachable-route, ${advisories.length} unrouted-skill\n`,
+    );
+    if (errors.length > 0 && !strict) {
+        process.stdout.write(
+            `advisory run: ${errors.length} unreachable-route finding(s) reported, exit 0. Promote with --strict once the set is empty.\n`,
+        );
+    }
+    return strict && errors.length > 0 ? 1 : 0;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(_HERE)) {
+    try {
+        process.exit(main());
+    } catch (error) {
+        process.stderr.write(`❌  ${(error as Error).message}\n`);
+        process.exit(2);
+    }
+}