canary-test-cli 7.0.0 → 7.2.0

package/dist/engine/analysis/reports.js

@@ -16,7 +16,7 @@ export { round1 };
 // ---------------------------------------------------------------------------
 // Flaky report
 // ---------------------------------------------------------------------------
-export function buildFlakyReport(rows, windowRuns, minRatePct, limit = 20) {
+export function buildFlakyTestsReport(rows, windowRuns, minRatePct, limit = 20) {
     if (rows.length === 0) {
         return `No tests above ${pyFloat(minRatePct)}% flake rate in the last ${windowRuns} runs.\n`;
     }
@@ -75,7 +75,7 @@ function detectSpikes(rows, deltaPp) {
     }
     return spikes;
 }
-export function buildSpikesReport(rows, deltaPp) {
+export function buildFailureSpikesReport(rows, deltaPp) {
     if (rows.length === 0) {
         return 'No run data available for spike detection.\n';
     }
@@ -210,8 +210,9 @@ function regressionRow(r) {
 export function buildDigest(args) {
     const sections = [
         '# Fleet Health Digest\n',
-        '## Flaky Tests\n\n' + buildFlakyReport(args.flaky, args.windowRuns, 10.0),
-        '## Spikes\n\n' + buildSpikesReport(args.spikes, args.deltaPp),
+        '## Flaky Tests\n\n' +
+            buildFlakyTestsReport(args.flaky, args.windowRuns, 10.0),
+        '## Spikes\n\n' + buildFailureSpikesReport(args.spikes, args.deltaPp),
         '## Area Health\n\n' + buildAreaHealthReport(args.areaHealth, args.weeks),
         '## Common Failures\n\n' +
             buildCommonFailuresReport(args.commonFailures, args.minSuites),

package/dist/engine/cli-commands.js

@@ -5,21 +5,25 @@
  * doctor, ticket-update). The commander wiring (options/args/defaults) lives in
  * `cli.ts`; these functions are the thin handlers it dispatches to.
  *
- * Conventions mirror `guardian/cli.ts`: `CliExit` for business exits,
+ * Conventions mirror `guardian/cli.ts`: `CliExitError` for business exits,
  * `jsonIndent2` for `json.dumps(indent=2)`, picocolors for rich markup (color
  * strips on a non-TTY sink so plain text is byte-exact), and output glyphs as
  * `\u{...}` escapes emitted verbatim.
  */
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync, } from 'node:fs';
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, extname, join, resolve } from 'node:path';
 import pc from 'picocolors';
-import { CliExit, jsonIndent2 } from './cli-common.js';
-import { gateOutcome } from './core/gate-result.js';
+import { CliExitError, jsonIndent2 } from './cli-common.js';
+import { gatherAdoptionReport } from './core/adoption.js';
+import { EXIT_ABSTAINED, errnoCode, gateOutcome, skippedSuffix, } from './core/gate-result.js';
+import { promotionVerdict } from './core/promotion-verdict.js';
+import { scanVacuity } from './core/vacuity-scanner.js';
 import { ckInitCmd } from './company-knowledge-cli.js';
 import { extractFrameworkHint } from './core/classifier.js';
 import { VALID_CATEGORIES, buildFeedback } from './core/feedback.js';
 import { OverlayNotFound, listOverlays, resolveOverlay, } from './core/overlays.js';
-import { JS_TEST_EXTENSIONS, frameworkForPath } from './core/static-linter.js';
+import { frameworkForPath } from './core/static-linter.js';
+import { SCANNABLE_DESC, collectTestFiles, isDir } from './core/test-files.js';
 import { RunSummary } from './core/ticket-updater.js';
 import { renderBanner } from './ui/banner.js';
 import { ARROW, CHECK, CHECK_MARK, CROSS, EM_DASH, HAMMER, NEXT, REDX, ROCKET, WARN, WRENCH, } from './main-deps.js';
@@ -39,68 +43,7 @@ function isFile(p) {
         return false;
     }
 }
-function isDir(p) {
-    try {
-        return statSync(p).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Directories never worth walking. A dependency's own test suite is not the
- * consumer's to fix: before #566, `node_modules` accounted for 254 of 256
- * findings in one downstream run, and the only `critical` sat inside vendored
- * code. `pattern-matcher.ts` has carried this set since the Python port; this
- * walk was the copy that never got it.
- */
-const IGNORED_DIRS = new Set([
-    'node_modules',
-    '.git',
-    '__pycache__',
-    '.venv',
-    'venv',
-    'dist',
-    'build',
-    '.next',
-    '.nuxt',
-]);
-function walkFiles(dir) {
-    const out = [];
-    let entries;
-    try {
-        entries = readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return out;
-    }
-    for (const e of entries) {
-        const full = join(dir, e.name);
-        if (e.isDirectory()) {
-            if (!IGNORED_DIRS.has(e.name))
-                out.push(...walkFiles(full));
-        }
-        else if (e.isFile())
-            out.push(full);
-    }
-    return out;
-}
-/**
- * `test_*.py` plus `*.test.*` / `*.spec.*` over every extension the scanners
- * can actually read -- `.mjs` and `.cjs` included, which is the half of #566
- * that made a directory of ESM tests collect zero files.
- */
-const JS_TEST_FILE_RE = new RegExp(`\\.(test|spec)\\.(${JS_TEST_EXTENSIONS.map((e) => e.slice(1)).join('|')})$`);
-/** Recursive test-file glob matching Python's `rglob` union, sorted by path. */
-function collectTestFiles(dir) {
-    return walkFiles(dir)
-        .filter((p) => {
-        const b = basename(p);
-        return ((b.startsWith('test_') && b.endsWith('.py')) || JS_TEST_FILE_RE.test(b));
-    })
-        .sort();
-}
-export function recommendCmd(promptText, opts, deps) {
+export function recommendFrameworkCmd(promptText, opts, deps) {
     const classifier = deps.makeClassifier();
     const recommender = deps.makeRecommender();
     const classification = classifier.classify(promptText);
@@ -149,7 +92,7 @@ const TIER_STYLE = {
     executable: pc.cyan,
     catalog: pc.yellow,
 };
-export function frameworksCmd(opts, deps) {
+export function listFrameworksCmd(opts, deps) {
     const summaries = deps.makeRegistry().summaries();
     if (opts.json) {
         deps.out(jsonIndent2({ frameworks: summaries }));
@@ -173,11 +116,11 @@ export function frameworksCmd(opts, deps) {
 export function feedbackCmd(message, opts, deps) {
     if (!VALID_CATEGORIES.includes(opts.category)) {
         deps.out(`${pc.bold(pc.red(CROSS))} Unknown --category '${opts.category}'. Choose one of: ${VALID_CATEGORIES.join(', ')}.`);
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
     if (!message || !message.trim()) {
         deps.out(`${pc.bold(pc.red(CROSS))} A feedback message is required.\nUsage: ${pc.bold('canary feedback "<message>" [--category bug|ux|docs|idea]')}`);
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
     const fb = buildFeedback(message.trim(), opts.category, resolveVersion(deps));
     if (opts.json) {
@@ -290,7 +233,7 @@ function resolveMigrateOverlay(fromOverlay, overlay, deps) {
         catch (e) {
             if (e instanceof OverlayNotFound) {
                 deps.out(`\n${pc.bold(pc.red(CROSS))} ${e.message}`);
-                throw new CliExit(1);
+                throw new CliExitError(1);
             }
             throw e;
         }
@@ -307,14 +250,33 @@ function resolveMigrateOverlay(fromOverlay, overlay, deps) {
     if (tracked.length > 1) {
         const names = tracked.join(', ');
         deps.out(`\n${pc.bold(pc.red(CROSS))} ${tracked.length} tracked overlays registered (${names}).\nChoose one with ${pc.bold('--from <name>')}.`);
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
     return null;
 }
+/**
+ * `--adoption-report`: which adoption pieces are in place here (#459).
+ *
+ * Read-only, and unlike `--check` it runs WITHOUT an overlay: "no overlay is
+ * tracked" is itself one of the answers a half-adopted repo needs, so refusing
+ * to report until one exists would hide the most common gap.
+ */
+function migrateAdoption(migrator, root, overlayPath, json, deps) {
+    let report;
+    try {
+        report = gatherAdoptionReport(migrator, root, overlayPath, deps.home());
+    }
+    catch (e) {
+        deps.out(`\n${pc.bold(pc.red(CROSS))} ${e instanceof Error ? e.message : String(e)}`);
+        throw new CliExitError(1);
+    }
+    deps.out(json ? jsonIndent2(report.to_dict()) : report.to_markdown());
+    throw new CliExitError(report.exit_code());
+}
 function migrateCheck(migrator, root, overlayPath, json, deps) {
     if (overlayPath === null) {
         deps.out(`\n${pc.yellow('No overlay to check against.')} Track one with ${pc.bold('canary overlay add')} or pass ${pc.bold('--from <overlay>')}.`);
-        throw new CliExit(0);
+        throw new CliExitError(0);
     }
     let report;
     try {
@@ -322,7 +284,7 @@ function migrateCheck(migrator, root, overlayPath, json, deps) {
     }
     catch (e) {
         deps.out(`\n${pc.bold(pc.red(CROSS))} ${e instanceof Error ? e.message : String(e)}`);
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
     if (json) {
         deps.out(jsonIndent2(report.to_dict()));
@@ -330,23 +292,37 @@ function migrateCheck(migrator, root, overlayPath, json, deps) {
     else {
         deps.out(report.to_markdown());
     }
-    throw new CliExit(report.exit_code());
+    throw new CliExitError(report.exit_code());
+}
+/**
+ * Dispatch the report-only modes, which each exit via `CliExitError`.
+ *
+ * One gate for both so `migrateCmd` carries a single "does this run write?"
+ * branch: a second report mode added inline is how the writing path acquires an
+ * accidental fall-through.
+ */
+function migrateReportOnly(opts, migrator, root, overlayPath, deps) {
+    const json = opts.json ?? false;
+    if (opts.adoptionReport) {
+        migrateAdoption(migrator, root, overlayPath, json, deps);
+    }
+    if (opts.check) {
+        migrateCheck(migrator, root, overlayPath, json, deps);
+    }
 }
 export function migrateCmd(opts, deps) {
     const root = resolve(opts.path);
     const overlayPath = resolveMigrateOverlay(opts.from, opts.overlay, deps);
     const migrator = deps.makeMigrator();
-    if (opts.check) {
-        migrateCheck(migrator, root, overlayPath, opts.json ?? false, deps);
-        return; // unreachable -- migrateCheck always throws CliExit
-    }
+    // Both report-only modes exit here; neither ever reaches the writing path.
+    migrateReportOnly(opts, migrator, root, overlayPath, deps);
     let ctx;
     try {
         ctx = migrator.detect(root);
     }
     catch (e) {
         deps.out(`\n${pc.bold(pc.red('Detection error:'))} ${e instanceof Error ? e.message : String(e)}`);
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
     if (!ctx.is_harness_project) {
         if (ctx.not_test_project_reason) {
@@ -355,7 +331,7 @@ export function migrateCmd(opts, deps) {
         else {
             deps.out(`\n${pc.bold(pc.red(CROSS))} No harness project detected at ${pc.bold(root)}.\nExpected ${pc.dim('harness.config.json')} and ${pc.dim('.harness/')} directory.`);
         }
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
     const dryRun = !opts.apply;
     const modeLabel = dryRun ? pc.dim('(dry run)') : pc.green('(apply)');
@@ -373,7 +349,7 @@ export function migrateCmd(opts, deps) {
     }
     catch (e) {
         deps.out(`\n${pc.bold(pc.red('Error:'))} ${e instanceof Error ? e.message : String(e)}`);
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
     if (opts.json) {
         deps.out(jsonIndent2({
@@ -417,11 +393,15 @@ function findingPayload(f) {
         suggestion: f.suggestion,
     };
 }
-/** Human-readable list of what the collectors look for, for remedy text. */
-const SCANNABLE_DESC = `test_*.py, *.test|spec.{${JS_TEST_EXTENSIONS.map((e) => e.slice(1)).join(',')}}`;
 /** Emit the abstention notice in the caller's output mode, then exit 3. */
-function abstain(remedy, deps, json) {
-    const outcome = gateOutcome({ checked: 0, findings: [] }, 'gate');
+function abstain(remedy, deps, json, skipped = []) {
+    const result = { checked: 0, findings: [] };
+    // Only attach a non-empty list: `skippedSuffix` renders nothing for an empty
+    // one, but leaving the key set would put `"skipped": []` in the shape other
+    // producers use to mean "nothing was dropped".
+    if (skipped.length > 0)
+        result.skipped = skipped;
+    const outcome = gateOutcome(result, 'gate');
     if (json) {
         deps.out(jsonIndent2([]));
         deps.err(`${outcome.summaryLine} ${remedy}`);
@@ -430,7 +410,7 @@ function abstain(remedy, deps, json) {
         deps.out(pc.bold(pc.yellow(outcome.summaryLine)));
         deps.out(`  ${remedy}`);
     }
-    throw new CliExit(outcome.exitCode);
+    throw new CliExitError(outcome.exitCode);
 }
 /**
  * The denominator guard shared by the file-scanning gates (#508 Wave 4a).
@@ -468,6 +448,59 @@ function abstainOnUnlintableFile(path, deps, json) {
     abstain(`Cannot lint ${ext} — no ruleset parses it, so a clean result would be ` +
         `meaningless (looked for ${SCANNABLE_DESC}).`, deps, json);
 }
+/**
+ * Run every collected file through `scan`, turning an unreadable one into a
+ * skip instead of an escaped exception (#704).
+ *
+ * The third zero these commands can hit. `abstainOnZeroFiles` guards the
+ * COLLECTOR and `abstainOnUnlintableFile` guards the RULESET; neither sees a
+ * path that collects fine and then cannot be opened, so `readFileSync` threw
+ * straight out of the handler and the CLI printed a raw Node stack. Not false
+ * green -- it exited 1 -- but exit 1 means "I found findings", and a run that
+ * opened nothing found nothing because it looked at nothing. Same shape
+ * `scanVacuity` and `promotionVerdict` already use: catch an errno-coded error,
+ * report a zero denominator plus a skip entry naming the cause.
+ *
+ * A fault with no errno code still throws. Swallowing an unknown one is how a
+ * scanner learns to go quiet.
+ */
+function sweepFiles(files, scan) {
+    const sweep = { findings: [], checked: 0, skipped: [] };
+    for (const f of files) {
+        try {
+            sweep.findings.push(...scan(f));
+            sweep.checked += 1;
+        }
+        catch (e) {
+            const code = errnoCode(e);
+            if (code === null)
+                throw e;
+            sweep.skipped.push({ name: f, reason: `could not be read (${code})` });
+        }
+    }
+    return sweep;
+}
+/** Every collected file was unreadable: nothing was inspected, so exit 3. */
+function abstainOnUnreadable(sweep, path, deps, json) {
+    if (sweep.checked > 0)
+        return;
+    abstain(`Nothing under ${path} could be opened, so this is an absent result and ` +
+        `not a clean one. Check the path exists and is readable.`, deps, json, sweep.skipped);
+}
+/**
+ * D7 for the partial read: a file dropped from a run that still had a
+ * denominator stays visible, or "clean" silently covers less than it claims.
+ * In `--json` the notice rides stderr so stdout stays a parseable array.
+ */
+function reportSkips(sweep, deps, json) {
+    if (sweep.skipped.length === 0)
+        return;
+    const line = `${WARN} Not every collected file was read${skippedSuffix(sweep.skipped)}`;
+    if (json)
+        deps.err(line);
+    else
+        deps.out(pc.yellow(line));
+}
 export function reviewTestCmd(path, opts, deps) {
     const json = opts.json === true;
     const files = isDir(path) ? collectTestFiles(path) : [path];
@@ -475,16 +508,17 @@ export function reviewTestCmd(path, opts, deps) {
     if (!isDir(path) && !opts.framework)
         abstainOnUnlintableFile(path, deps, json);
     const linter = deps.makeLinter();
-    const allFindings = [];
-    for (const f of files)
-        allFindings.push(...linter.lint(f, opts.framework));
+    const sweep = sweepFiles(files, (f) => linter.lint(f, opts.framework));
+    abstainOnUnreadable(sweep, path, deps, json);
+    reportSkips(sweep, deps, json);
+    const allFindings = sweep.findings;
     // `--json` renders the machine payload and then falls through to the same
     // exit-code decision as human mode. It used to `return` here, so a consumer
     // gating on `$?` saw every finding-bearing run as clean (#566).
     if (json) {
         deps.out(jsonIndent2(allFindings.map(findingPayload)));
         if (allFindings.some((f) => f.severity === 'critical')) {
-            throw new CliExit(1);
+            throw new CliExitError(1);
         }
         return;
     }
@@ -512,7 +546,7 @@ export function reviewTestCmd(path, opts, deps) {
         parts.push(pc.dim(`${counts['info']} info`));
     deps.out(`${pc.bold(`${allFindings.length} finding(s):`)} ${parts.join(', ')}`);
     if (counts['critical'])
-        throw new CliExit(1);
+        throw new CliExitError(1);
 }
 export function flakeCheckCmd(path, opts, deps) {
     const json = opts.json === true;
@@ -521,14 +555,15 @@ export function flakeCheckCmd(path, opts, deps) {
     if (!isDir(path))
         abstainOnUnlintableFile(path, deps, json);
     const linter = deps.makeLinter();
-    const allFindings = [];
-    for (const f of files)
-        allFindings.push(...linter.flakeCheck(f));
+    const sweep = sweepFiles(files, (f) => linter.flakeCheck(f));
+    abstainOnUnreadable(sweep, path, deps, json);
+    reportSkips(sweep, deps, json);
+    const allFindings = sweep.findings;
     // Exit-code parity with human mode, same reason as `review-test` above.
     if (json) {
         deps.out(jsonIndent2(allFindings.map(findingPayload)));
         if (allFindings.length > 0)
-            throw new CliExit(1);
+            throw new CliExitError(1);
         return;
     }
     if (allFindings.length === 0) {
@@ -542,12 +577,119 @@ export function flakeCheckCmd(path, opts, deps) {
         deps.out(`  ${pc.dim(`${ARROW} ${f.suggestion}`)}\n`);
     }
     deps.out(pc.bold(`${allFindings.length} flakiness pattern(s) found.`));
-    throw new CliExit(1);
+    throw new CliExitError(1);
+}
+// --- vacuity-check (canary-cassandra, #612) ----------------------------------
+/**
+ * The CLI surface of the vacuity scanner.
+ *
+ * Registered as an **advisory** command, not a gate: this repo's established
+ * shape for a brand-new detector is advisory first, ratchet to strict only after
+ * triage (the dogfooding jobs, #485). So findings exit 0.
+ *
+ * The abstention half is NOT advisory, and the asymmetry is the whole #508
+ * doctrine. "I found weak tests" is information a repo absorbs over time; "I
+ * verified nothing" is a broken instrument, and a vacuity detector that reported
+ * its own silence as success would be the exact false-green class it exists to
+ * find. Two distinct zeros are guarded: no file matched, and files matched but
+ * held no tests -- a scanner that only checked the first prints a clean tick on
+ * the second.
+ */
+export function vacuityCheckCmd(path, opts, deps) {
+    const json = opts.json === true;
+    const files = isDir(path) ? collectTestFiles(path) : [path];
+    const findings = [];
+    const skipped = [];
+    let checked = 0;
+    for (const f of files) {
+        const r = scanVacuity(f);
+        checked += r.checked;
+        findings.push(...r.findings);
+        if (r.skipped)
+            skipped.push(...r.skipped);
+    }
+    if (files.length === 0) {
+        skipped.push({
+            name: path,
+            reason: `no test file matched (looked for ${SCANNABLE_DESC})`,
+        });
+    }
+    const result = { checked, findings };
+    if (skipped.length > 0)
+        result.skipped = skipped;
+    const outcome = gateOutcome(result, 'advisory', { noun: 'test(s)' });
+    // `advisory` keeps findings at exit 0; the abstention still has to be loud, so
+    // the exit code for a zero denominator is taken from the gate contract.
+    const exitCode = outcome.abstained ? EXIT_ABSTAINED : 0;
+    if (json) {
+        deps.out(jsonIndent2({
+            checked,
+            abstained: outcome.abstained,
+            findings,
+            skipped,
+        }));
+        if (exitCode !== 0)
+            throw new CliExitError(exitCode);
+        return;
+    }
+    for (const f of findings) {
+        const color = f.severity === 'critical' ? pc.red : pc.yellow;
+        const tier = f.fidelity ? pc.dim(` [${f.fidelity}]`) : '';
+        deps.out(`${color(`[${f.severity.toUpperCase()}]`)} ${f.file}:${f.line} ${pc.dim(`(${f.rule})`)}${tier}`);
+        deps.out(`  ${f.test}: ${f.message}`);
+        deps.out(`  ${pc.dim(`${ARROW} ${f.suggestion}`)}\n`);
+    }
+    deps.out(outcome.abstained
+        ? pc.bold(pc.yellow(outcome.summaryLine))
+        : `${pc.bold(outcome.summaryLine)}`);
+    if (exitCode !== 0)
+        throw new CliExitError(exitCode);
+}
+// --- promote-check (#477) ----------------------------------------------------
+/**
+ * The gate `canary-promote-test` Phase 1 consumes.
+ *
+ * Unlike `vacuity-check` this IS a gate, and deliberately so: it does not scan a
+ * repository, it decides whether ONE generated draft may enter the committed
+ * suite. A blocking finding there is not a backlog item to triage, it is a
+ * reason not to import the draft. Nothing existing turns red -- the command is
+ * new and only ever pointed at `tests/generated/`.
+ */
+export function promoteCheckCmd(path, opts, deps) {
+    const verdict = promotionVerdict(path);
+    if (opts.json === true) {
+        deps.out(jsonIndent2(verdict));
+        if (verdict.exitCode !== 0)
+            throw new CliExitError(verdict.exitCode);
+        return;
+    }
+    for (const axis of verdict.axes) {
+        for (const f of axis.findings) {
+            const blocking = axis.gating && verdict.blocked.includes(f.rule);
+            const label = blocking ? pc.red('[BLOCK]') : pc.yellow('[ADVISORY]');
+            const tier = f.fidelity ? pc.dim(` [${f.fidelity}]`) : '';
+            deps.out(`${label} ${verdict.file}:${f.line} ${pc.dim(`(${f.rule}/${axis.axis})`)}${tier}`);
+            deps.out(`  ${f.message}`);
+            deps.out(`  ${pc.dim(`${ARROW} ${f.suggestion}`)}\n`);
+        }
+    }
+    // No glyph on `abstain`: `gateOutcome` already opens its summary line with the
+    // warning sign, and two in a row read as a rendering bug rather than emphasis.
+    const banner = {
+        promote: pc.green(`${CHECK_MARK} PROMOTE`),
+        block: pc.red(`${REDX} BLOCK`),
+        abstain: pc.yellow('ABSTAIN'),
+    };
+    deps.out(`${pc.bold(banner[verdict.decision])} ${EM_DASH} ${verdict.summaryLine}`);
+    if (verdict.remedy)
+        deps.out(`  ${verdict.remedy}`);
+    if (verdict.exitCode !== 0)
+        throw new CliExitError(verdict.exitCode);
 }
 export function healTestCmd(path, opts, deps) {
     if (!isFile(path)) {
         deps.out(pc.red(`Error: ${path} is not a file.`));
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
     const result = deps.makeHealer().heal(path);
     if (opts.json) {
@@ -631,17 +773,21 @@ export function upgradeCmd(opts, deps) {
     }
     else {
         deps.out(`${pc.red('Upgrade failed.')}\n${pip.stderr.trim()}`);
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
 }
-// --- overlay / doctor (npm-shim pointers) ------------------------------------
-export function overlayStub(deps) {
+// --- overlay / doctor / uninstall (npm-shim pointers) ------------------------
+export function overlayCmd(deps) {
     deps.out(`${pc.yellow('`canary overlay` is provided by the npm install of Canary.')}\nInstall it with:  ${pc.bold('npm install -g canary-test-cli')}\nThe pipx/Python entry point does not include the overlay commands.`);
-    throw new CliExit(1);
+    throw new CliExitError(1);
 }
-export function doctorStub(deps) {
+export function doctorCmd(deps) {
     deps.out(`${pc.yellow('`canary doctor` is provided by the npm install of Canary.')}\nInstall it with:  ${pc.bold('npm install -g canary-test-cli')}\nThe pipx/Python entry point does not include the doctor command.`);
-    throw new CliExit(1);
+    throw new CliExitError(1);
+}
+export function uninstallCmd(deps) {
+    deps.out(`${pc.yellow('`canary uninstall` is provided by the npm install of Canary.')}\nInstall it with:  ${pc.bold('npm install -g canary-test-cli')}\nThe pipx/Python entry point does not include the uninstall command.`);
+    throw new CliExitError(1);
 }
 export async function ticketUpdateCmd(opts, deps) {
     let reportData = {};
@@ -651,7 +797,7 @@ export async function ticketUpdateCmd(opts, deps) {
         }
         catch (exc) {
             deps.out(pc.red(`Could not read result file '${opts.result}': ${exc instanceof Error ? exc.message : String(exc)}`));
-            throw new CliExit(1);
+            throw new CliExitError(1);
         }
     }
     const testFile = opts.testFile;
@@ -702,7 +848,7 @@ export async function ticketUpdateCmd(opts, deps) {
         }
     }
     if (updateResult.transition.reason.startsWith(WARN)) {
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
 }
 /** Python string `<`/`>` comparison (stable code-unit order). */

package/dist/engine/cli-common.js

@@ -5,21 +5,26 @@
  *
  * The three concerns every command tree needs:
  *
- *   - {@link CliExit} -- the business-exit signal thrown from a handler (Python
- *     `typer.Exit(code)`). Re-exported from `guardian/cli.ts` so the ENTIRE
- *     command tree (main program, its sub-apps, AND the already-ported guardian
- *     sub-app it mounts) throws ONE class. `bin/canary.js` then catches a single
- *     `CliExit` regardless of which sub-app raised it.
+ *   - {@link CliExitError} -- the business-exit signal thrown from a handler
+ *     (Python `typer.Exit(code)`). Re-exported from `guardian/cli.ts` so the
+ *     ENTIRE command tree (main program, its sub-apps, AND the already-ported
+ *     guardian sub-app it mounts) throws ONE class. `bin/canary.js` catches one
+ *     `CliExitError` regardless of which sub-app raised it.
  *   - {@link normalizeUsageExit} -- the `.exitOverride()` callback that maps
  *     commander's usage-error exit code (1) to typer/click's 2, while leaving an
  *     explicit `--help`/`--version` at 0. Applied to the program AND every
  *     subcommand.
- *   - {@link ensureAscii} / {@link jsonIndent2} -- Python `json.dumps` fidelity:
- *     `ensure_ascii=True` (per-UTF-16-unit escaping, so astral chars emit a
- *     surrogate pair exactly like CPython) and the `indent=2` pretty form (whose
- *     separators match `JSON.stringify(x, null, 2)` byte-for-byte).
+ *   - {@link jsonIndent2} -- Python `json.dumps(x, indent=2)` fidelity: the
+ *     separators match `JSON.stringify(x, null, 2)` byte-for-byte, and the
+ *     `ensure_ascii=True` default is restored by `ensureAscii`.
+ *
+ * `ensureAscii` itself used to be declared and exported here, and was imported
+ * by nobody while eight modules carried private copies (#710). It now lives in
+ * `util/ensure-ascii.ts` -- the one layer `core`, `guardian`, and the entry
+ * modules are all permitted to depend on, which `cli` is not.
  */
-export { CliExit } from './guardian/cli.js';
+import { ensureAscii } from './util/ensure-ascii.js';
+export { CliExitError } from './guardian/cli.js';
 /**
  * Map commander's usage-error exit code to typer/click's `2`. Commander defaults
  * unknown/missing-option, bad-command and no-args-help errors to exit 1; typer
@@ -33,20 +38,6 @@ export function normalizeUsageExit(err) {
     }
     throw err;
 }
-/**
- * Escape every non-ASCII UTF-16 code UNIT to `\uXXXX`, matching Python
- * `json.dumps(ensure_ascii=True)`. Iterating by unit (not code point) means an
- * astral char's surrogate pair emits `\udXXX\udXXX`, exactly like CPython; a
- * code-point regex would stop at U+FFFF and leave astral chars raw.
- */
-export function ensureAscii(json) {
-    let out = '';
-    for (let i = 0; i < json.length; i++) {
-        const c = json.charCodeAt(i);
-        out += c >= 0x80 ? '\\u' + c.toString(16).padStart(4, '0') : json[i];
-    }
-    return out;
-}
 /**
  * `json.dumps(x, indent=2)` fidelity: `JSON.stringify(x, null, 2)` reproduces
  * Python's 2-space indent and `(',', ': ')` separators byte-for-byte (including