canary-test-cli 7.0.0 → 7.1.0

package/dist/engine/cli-commands.js

@@ -5,7 +5,7 @@
  * 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.
@@ -13,8 +13,11 @@
 import { existsSync, readdirSync, 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';
@@ -100,7 +103,7 @@ function collectTestFiles(dir) {
     })
         .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 +152,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 +176,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 +293,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 +310,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 +344,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 +352,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 +391,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 +409,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({
@@ -420,8 +456,14 @@ function findingPayload(f) {
 /** 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 +472,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 +510,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 +570,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 +608,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 +617,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 +639,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 +835,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 +859,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 +910,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

package/dist/engine/cli.core.js

@@ -7,8 +7,8 @@
  *
  * Conventions follow `guardian/cli.ts` (see `cli-common.ts`): a
  * {@link createCanaryCommand} factory wired to an injectable {@link MainDeps},
- * `CliExit` for business exits, `normalizeUsageExit` on the program AND every
- * subcommand so usage errors exit 2 (typer/click) not commander's default 1, and
+ * `CliExitError` for business exits, `normalizeUsageExit` on the program AND
+ * every subcommand so usage errors exit 2 (typer/click) not commander's 1, and
  * an eager `-V/--version` global option + `_main` callback analog.
  *
  * Sub-app mounting note: `guardian`/`history`/`analyze` are mounted as FRESH
@@ -17,9 +17,9 @@
  * mount into multiple `createCanaryCommand()` calls, e.g. across tests).
  */
 import { Command, Option } from 'commander';
-import { CliExit, normalizeUsageExit } from './cli-common.js';
+import { CliExitError, normalizeUsageExit } from './cli-common.js';
 import { createAnalyzeCommand } from './analysis/cli.js';
-import { doctorStub, feedbackCmd, flakeCheckCmd, frameworksCmd, healTestCmd, initCmd, migrateCmd, overlayStub, recommendCmd, reviewTestCmd, runCmd, setupCmd, ticketUpdateCmd, upgradeCmd, versionCmd, } from './cli-commands.js';
+import { doctorCmd, feedbackCmd, flakeCheckCmd, listFrameworksCmd, healTestCmd, initCmd, migrateCmd, overlayCmd, promoteCheckCmd, recommendFrameworkCmd, reviewTestCmd, runCmd, setupCmd, ticketUpdateCmd, uninstallCmd, upgradeCmd, vacuityCheckCmd, versionCmd, } from './cli-commands.js';
 import { buildCompanyKnowledgeCommand } from './company-knowledge-cli.js';
 import { createGuardianCommand } from './guardian/cli.js';
 import { createHistoryCommand } from './history/cli.js';
@@ -38,18 +38,18 @@ export function createCanaryCommand(depsInit = {}) {
         .hook('preAction', () => {
         if (program.opts()['version']) {
             versionCmd(deps);
-            throw new CliExit(0);
+            throw new CliExitError(0);
         }
     })
         .action(() => {
         if (program.opts()['version']) {
             versionCmd(deps);
-            throw new CliExit(0);
+            throw new CliExitError(0);
         }
         // Python `typer.Typer(no_args_is_help=True)` prints help and exits 2 on a
         // bare `canary` invocation (a usage exit), NOT 0.
         program.outputHelp();
-        throw new CliExit(2);
+        throw new CliExitError(2);
     });
     program
         .command('recommend')
@@ -57,14 +57,14 @@ export function createCanaryCommand(depsInit = {}) {
         .argument('<prompt>')
         .option('--json', 'Output as JSON for tool integration.')
         .action((prompt, opts) => {
-        recommendCmd(prompt, opts, deps);
+        recommendFrameworkCmd(prompt, opts, deps);
     });
     program
         .command('frameworks')
         .description('List the supported testing frameworks and how to run each.')
         .option('--json', 'Dump the registry as JSON for tool integration.')
         .action((opts) => {
-        frameworksCmd(opts, deps);
+        listFrameworksCmd(opts, deps);
     });
     program
         .command('feedback')
@@ -107,6 +107,7 @@ export function createCanaryCommand(depsInit = {}) {
         .option('-o, --overlay <path>', '[deprecated: use --from] Path to an overlay repo whose .canary/skills/ are deployed.')
         .option('--apply', 'Write files. Without this flag the command is a dry run.')
         .option('--check', 'Freshness gate: report drift without writing.')
+        .option('--adoption-report', 'Report which adoption pieces (company.json, shape, overlay, skills, manifest, workflows) are present or missing in this repo. Writes nothing. Exits 0 fully adopted, 1 pieces missing, 3 nothing verifiable.')
         .option('--force', 'Overwrite a .github/workflows/ file that differs from the overlay template. Without this flag a difference is only reported -- your CI is never rewritten behind your back.')
         .option('--json', 'Emit the report as JSON.')
         .action((opts) => {
@@ -131,6 +132,22 @@ export function createCanaryCommand(depsInit = {}) {
         .action((path, opts) => {
         flakeCheckCmd(path, opts, deps);
     });
+    program
+        .command('promote-check')
+        .description('Decide whether a generated test may be promoted into the committed suite.')
+        .argument('<path>', 'The generated test file to judge.')
+        .option('--json', 'Emit the structured verdict as JSON.')
+        .action((path, opts) => {
+        promoteCheckCmd(path, opts, deps);
+    });
+    program
+        .command('vacuity-check')
+        .description('Find tests that pass without proving anything -- advisory, no LLM required.')
+        .argument('<path>', 'Test file or directory to scan.')
+        .option('--json', 'Output the verdict and its denominator as JSON.')
+        .action((path, opts) => {
+        vacuityCheckCmd(path, opts, deps);
+    });
     program
         .command('heal-test')
         .description('Apply deterministic pattern fixes to a test file -- no LLM required.')
@@ -162,7 +179,7 @@ export function createCanaryCommand(depsInit = {}) {
         .allowExcessArguments(true)
         .argument('[args...]')
         .action(() => {
-        overlayStub(deps);
+        overlayCmd(deps);
     });
     program
         .command('doctor')
@@ -171,7 +188,16 @@ export function createCanaryCommand(depsInit = {}) {
         .allowExcessArguments(true)
         .argument('[args...]')
         .action(() => {
-        doctorStub(deps);
+        doctorCmd(deps);
+    });
+    program
+        .command('uninstall')
+        .description('Remove installed Canary artifacts (requires the npm install of Canary).')
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .argument('[args...]')
+        .action(() => {
+        uninstallCmd(deps);
     });
     program
         .command('ticket-update')

package/dist/engine/cli.js

@@ -7,7 +7,7 @@ import { createRequire } from 'node:module';
 import { CommanderError } from 'commander';
 
 import { createCanaryCommand } from './cli.core.js';
-import { CliExit } from './cli-common.js';
+import { CliExitError } from './cli-common.js';
 
 const require = createRequire(import.meta.url);
 
@@ -24,7 +24,7 @@ const program = createCanaryCommand({ pkgVersion: () => readVersion() });
 try {
   await program.parseAsync(process.argv.slice(2), { from: 'user' });
 } catch (err) {
-  if (err instanceof CliExit) process.exit(err.code);
+  if (err instanceof CliExitError) process.exit(err.code);
   if (err instanceof CommanderError) process.exit(err.exitCode);
   console.error(err);
   process.exit(1);