canary-test-cli 5.15.0 → 6.0.0

package/dist/engine/cli-commands.js

@@ -0,0 +1,618 @@
+/**
+ * Top-level `canary` command handlers -- faithful ports of the module-level
+ * commands in `agent/cli.py` (recommend, frameworks, feedback, run, init, setup,
+ * migrate, review-test, flake-check, heal-test, version, upgrade, overlay,
+ * 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,
+ * `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 { basename, join, resolve } from 'node:path';
+import pc from 'picocolors';
+import { CliExit, jsonIndent2 } from './cli-common.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 { 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';
+function resolveVersion(deps) {
+    try {
+        return deps.pkgVersion();
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function isFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+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())
+            out.push(...walkFiles(full));
+        else if (e.isFile())
+            out.push(full);
+    }
+    return out;
+}
+/** 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')) ||
+            b.endsWith('.spec.ts') ||
+            b.endsWith('.spec.js') ||
+            b.endsWith('.test.ts') ||
+            b.endsWith('.test.js'));
+    })
+        .sort();
+}
+export function recommendCmd(promptText, opts, deps) {
+    const classifier = deps.makeClassifier();
+    const recommender = deps.makeRecommender();
+    const classification = classifier.classify(promptText);
+    const results = recommender.recommend(classification, null, extractFrameworkHint(promptText));
+    const result = results[0] ??
+        {
+            framework: null,
+            file_extension: 'ts',
+            reason: ['No matching framework found'],
+        };
+    const alternatives = results.slice(1).map((r) => r.framework);
+    if (opts.json) {
+        const execInfo = deps.makeRegistry().executionInfo(result.framework) ?? {};
+        const payload = {
+            status: 'success',
+            test_type: classification.test_type,
+            framework: result.framework,
+            file_extension: result.file_extension,
+            execution_command: execInfo.execution_command ?? null,
+            ci_flags: execInfo.ci_flags ?? [],
+            reasoning: result.reason,
+            alternatives,
+        };
+        if (result.warning) {
+            payload['license'] = result.license;
+            payload['warning'] = result.warning;
+        }
+        deps.out(jsonIndent2(payload));
+        return;
+    }
+    deps.out(`${pc.bold(pc.green(`${CHECK_MARK} Canary Recommendation`))}\n`);
+    deps.out(`${pc.bold('Test Type:')} ${classification.test_type}`);
+    deps.out(`${pc.bold('Framework:')} ${result.framework === null ? 'None' : result.framework}`);
+    deps.out(`\n${pc.bold('Reasoning:')}`);
+    for (const r of result.reason)
+        deps.out(` - ${r}`);
+    if (result.warning) {
+        deps.out(`\n${pc.yellow(`${WARN} License: ${result.warning}`)}`);
+    }
+    if (alternatives.length) {
+        deps.out(`\n${pc.bold('Alternatives:')} ${alternatives.join(', ')}`);
+    }
+}
+const TIER_STYLE = {
+    full: pc.green,
+    executable: pc.cyan,
+    catalog: pc.yellow,
+};
+export function frameworksCmd(opts, deps) {
+    const summaries = deps.makeRegistry().summaries();
+    if (opts.json) {
+        deps.out(jsonIndent2({ frameworks: summaries }));
+        return;
+    }
+    deps.out(`${pc.bold(pc.green('Canary Frameworks'))}\n`);
+    for (const f of summaries) {
+        const status = f.status ? ` ${pc.dim(`(${f.status})`)}` : '';
+        const tier = f.tier || 'catalog';
+        const tierLabel = (TIER_STYLE[tier] ?? pc.white)(tier);
+        deps.out(`${pc.bold(f.name)} ${tierLabel}${status} ${EM_DASH} ${f.category || 'n/a'}`);
+        const cmd = f.execution_command || '(no run command)';
+        deps.out(`  run: ${cmd}`);
+        if (f.ci_flags.length) {
+            deps.out(`  ci:  ${f.ci_flags.join(' ')}`);
+        }
+    }
+    deps.out(`\n${pc.dim(`tier: full=scaffold+run \u{00b7} executable=run only \u{00b7} catalog=listed only.`)}`);
+    deps.out(pc.dim('`{file}` in a run command is the test-file path placeholder.'));
+}
+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);
+    }
+    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);
+    }
+    const fb = buildFeedback(message.trim(), opts.category);
+    if (opts.json) {
+        deps.out(jsonIndent2(fb));
+        return;
+    }
+    deps.out(`${pc.bold(pc.green('Canary Feedback'))}\n`);
+    deps.out(`${pc.bold('Category:')} ${fb.category}`);
+    deps.out(`${pc.bold('Message:')} ${fb.message}`);
+    deps.out(`\n${pc.bold('Attached context')} (no env vars, no file contents):`);
+    for (const [k, v] of Object.entries(fb.context)) {
+        deps.out(`  - ${k}: ${v}`);
+    }
+    deps.out(`\n${pc.bold('Open this pre-filled issue to submit:')}`);
+    deps.out(fb.issue_url);
+    if (opts.open) {
+        deps.openBrowser(fb.issue_url);
+        deps.out(`\n${pc.dim(`Opened in your browser ${EM_DASH} review and submit there.`)}`);
+    }
+}
+// --- run ---------------------------------------------------------------------
+export function runCmd(filePath, framework, deps) {
+    deps.out(`\n${pc.bold(pc.cyan(`${ROCKET} Canary Executing ${framework} Test...`))}\n`);
+    const [exitCode, stdout, stderr] = deps
+        .makeExecutor()
+        .execute(filePath, framework);
+    const colorize = exitCode === 0 ? pc.green : pc.red;
+    deps.out(colorize(`Result: ${exitCode === 0 ? 'Success' : 'Failure'} (Exit ${exitCode})`));
+    if (stderr)
+        deps.out(`\n${pc.red('Error:')}\n${stderr}`);
+    if (stdout)
+        deps.out(`\n${pc.dim('Output:')}\n${stdout}`);
+}
+// --- init / setup ------------------------------------------------------------
+function companyJsonPresent(deps) {
+    return existsSync(join(deps.cwd(), '.canary', 'company.json'));
+}
+function printInitSignpost(deps) {
+    deps.out(`\n${pc.bold(pc.cyan('canary init'))} ${EM_DASH} what would you like to do?\n`);
+    if (!companyJsonPresent(deps)) {
+        deps.out(`${pc.yellow(`This repo has no ${pc.bold('.canary/company.json')} yet ${EM_DASH} agents that rely on it run degraded.`)}\n`);
+    }
+    deps.out(`${pc.bold('Set up canary in this repo')} (recommended first step):`);
+    deps.out(`  ${pc.bold(pc.green('canary setup'))}  ${pc.dim('alias for `canary company-knowledge init`')}\n`);
+    deps.out(pc.bold('Scaffold a test suite:'));
+    deps.out(`  ${pc.bold(pc.green('canary init <framework>'))}  ${pc.dim('playwright | vitest | pytest | k6')}\n`);
+}
+export function initCmd(framework, deps) {
+    if (framework === undefined) {
+        printInitSignpost(deps);
+        return;
+    }
+    deps.out(`\n${pc.bold(pc.cyan(`${HAMMER} Canary Initializing ${framework} Scaffold...`))}\n`);
+    try {
+        const result = deps.makeScaffolder().scaffold(framework);
+        if (result.status === 'unsupported') {
+            deps.out(pc.bold(pc.yellow(`${WARN} ${result.guidance}`)));
+            return;
+        }
+        deps.out(`${pc.bold(pc.green(`${CHECK_MARK} Scaffolding Complete`))}\n`);
+        if (result.created_dirs && result.created_dirs.length) {
+            deps.out(pc.bold('Directories Created:'));
+            for (const d of result.created_dirs)
+                deps.out(`  + ${d}`);
+        }
+        if (result.created_files && result.created_files.length) {
+            deps.out(`\n${pc.bold('Files Created:')}`);
+            for (const f of result.created_files)
+                deps.out(`  + ${f}`);
+        }
+        if (result.skipped_files && result.skipped_files.length) {
+            deps.out(`\n${pc.bold(pc.yellow('Files Skipped (Already Exist):'))}`);
+            for (const f of result.skipped_files)
+                deps.out(`  - ${f}`);
+        }
+        deps.out(`\n${pc.bold(pc.cyan(`${NEXT} Next Steps:`))}`);
+        const fw = framework.toLowerCase();
+        if (fw === 'playwright') {
+            deps.out(`  1. Run: ${pc.bold(pc.green('npm install -D @playwright/test'))}`);
+            deps.out(`  2. Run: ${pc.bold(pc.green('npx playwright install'))}`);
+        }
+        else if (fw === 'vitest') {
+            deps.out(`  1. Run: ${pc.bold(pc.green('npm install -D vitest'))}`);
+        }
+        else if (fw === 'pytest') {
+            deps.out(`  1. Run: ${pc.bold(pc.green('pip install pytest'))}`);
+        }
+        else if (fw === 'k6') {
+            deps.out(`  1. Install k6: ${pc.bold(pc.green('https://k6.io/docs/getting-started/installation/'))}`);
+        }
+    }
+    catch (e) {
+        // Python catches ValueError (unknown framework); the TS scaffolder throws a
+        // plain Error for the same case.
+        deps.out(`\n${pc.bold(pc.red(`${REDX} Error: ${e instanceof Error ? e.message : String(e)}`))}`);
+        deps.out(pc.yellow('Supported frameworks: playwright, vitest, pytest, k6'));
+    }
+}
+export function setupCmd(opts, deps) {
+    ckInitCmd({ force: opts.force ?? false }, deps);
+}
+function resolveMigrateOverlay(fromOverlay, overlay, deps) {
+    if (fromOverlay) {
+        if (overlay) {
+            deps.out(pc.yellow('Both --from and --overlay given; using --from and ignoring --overlay.'));
+        }
+        try {
+            return resolveOverlay(fromOverlay, deps.home());
+        }
+        catch (e) {
+            if (e instanceof OverlayNotFound) {
+                deps.out(`\n${pc.bold(pc.red(CROSS))} ${e.message}`);
+                throw new CliExit(1);
+            }
+            throw e;
+        }
+    }
+    if (overlay) {
+        deps.out(pc.yellow(`--overlay is deprecated; use ${pc.bold('--from <overlay-name|path>')} instead.`));
+        return resolve(overlay);
+    }
+    const tracked = listOverlays(deps.home());
+    if (tracked.length === 1) {
+        deps.out(pc.dim(`Using tracked overlay '${tracked[0]}' (the only one registered).`));
+        return resolveOverlay(tracked[0], deps.home());
+    }
+    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);
+    }
+    return null;
+}
+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);
+    }
+    let report;
+    try {
+        report = migrator.checkFreshness(root, { overlayPath });
+    }
+    catch (e) {
+        deps.out(`\n${pc.bold(pc.red(CROSS))} ${e instanceof Error ? e.message : String(e)}`);
+        throw new CliExit(1);
+    }
+    if (json) {
+        deps.out(jsonIndent2(report.to_dict()));
+    }
+    else {
+        deps.out(report.to_markdown());
+    }
+    throw new CliExit(report.exit_code());
+}
+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
+    }
+    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);
+    }
+    if (!ctx.is_harness_project) {
+        if (ctx.not_test_project_reason) {
+            deps.out(`\n${pc.bold(pc.red(CROSS))} ${ctx.not_test_project_reason}`);
+        }
+        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);
+    }
+    const dryRun = !opts.apply;
+    const modeLabel = dryRun ? pc.dim('(dry run)') : pc.green('(apply)');
+    deps.out(`\n${pc.bold(pc.cyan('Canary Migrate'))} ${modeLabel}\n`);
+    if (!dryRun)
+        deps.out(`${pc.yellow('Writing files to disk...')}\n`);
+    let report;
+    try {
+        report = migrator.migrate(root, {
+            dryRun,
+            framework: opts.framework || null,
+            overlayPath,
+        });
+    }
+    catch (e) {
+        deps.out(`\n${pc.bold(pc.red('Error:'))} ${e instanceof Error ? e.message : String(e)}`);
+        throw new CliExit(1);
+    }
+    if (opts.json) {
+        deps.out(jsonIndent2({
+            framework: report.framework,
+            shape: report.shape,
+            dry_run: report.dry_run,
+            created_files: report.created_files,
+            created_dirs: report.created_dirs,
+            skipped_configs: report.skipped_configs,
+            preserved_files: report.preserved_files,
+            would_create: report.would_create,
+            manual_followups: report.manual_followups,
+            config_warnings: report.config_warnings,
+            deployed_skills: report.deployed_skills.map((r) => ({
+                skill_name: r.skill_name,
+                status: r.status,
+                note: r.note,
+            })),
+        }));
+        return;
+    }
+    deps.out(report.to_markdown());
+    if (dryRun && report.would_create.length) {
+        deps.out(`\n${pc.dim(`Re-run with ${pc.bold('--apply')} to write these files.`)}`);
+    }
+}
+const SEV_COLOR = {
+    critical: pc.red,
+    warning: pc.yellow,
+    info: pc.dim,
+};
+const SEV_ORDER = { critical: 0, warning: 1, info: 2 };
+function findingPayload(f) {
+    return {
+        file: f.file,
+        line: f.line,
+        rule: f.rule,
+        severity: f.severity,
+        message: f.message,
+        suggestion: f.suggestion,
+    };
+}
+export function reviewTestCmd(path, opts, deps) {
+    const files = isDir(path) ? collectTestFiles(path) : [path];
+    const linter = deps.makeLinter();
+    const allFindings = [];
+    for (const f of files)
+        allFindings.push(...linter.lint(f, opts.framework));
+    if (opts.json) {
+        deps.out(jsonIndent2(allFindings.map(findingPayload)));
+        return;
+    }
+    if (allFindings.length === 0) {
+        deps.out(pc.bold(pc.green(`${CHECK_MARK} No issues found.`)));
+        return;
+    }
+    allFindings.sort((a, b) => cmpStr(a.file, b.file) ||
+        a.line - b.line ||
+        (SEV_ORDER[a.severity] ?? 9) - (SEV_ORDER[b.severity] ?? 9));
+    const counts = { critical: 0, warning: 0, info: 0 };
+    for (const f of allFindings) {
+        counts[f.severity] = (counts[f.severity] ?? 0) + 1;
+        const color = SEV_COLOR[f.severity] ?? pc.white;
+        deps.out(`${color(`[${f.severity.toUpperCase()}]`)} ${f.file}:${f.line} ${pc.dim(`(${f.rule})`)}`);
+        deps.out(`  ${f.message}`);
+        deps.out(`  ${pc.dim(`${ARROW} ${f.suggestion}`)}\n`);
+    }
+    const parts = [];
+    if (counts['critical'])
+        parts.push(pc.red(`${counts['critical']} critical`));
+    if (counts['warning'])
+        parts.push(pc.yellow(`${counts['warning']} warning`));
+    if (counts['info'])
+        parts.push(pc.dim(`${counts['info']} info`));
+    deps.out(`${pc.bold(`${allFindings.length} finding(s):`)} ${parts.join(', ')}`);
+    if (counts['critical'])
+        throw new CliExit(1);
+}
+export function flakeCheckCmd(path, opts, deps) {
+    const files = isDir(path) ? collectTestFiles(path) : [path];
+    const linter = deps.makeLinter();
+    const allFindings = [];
+    for (const f of files)
+        allFindings.push(...linter.flakeCheck(f));
+    if (opts.json) {
+        deps.out(jsonIndent2(allFindings.map(findingPayload)));
+        return;
+    }
+    if (allFindings.length === 0) {
+        deps.out(pc.bold(pc.green(`${CHECK_MARK} No flakiness patterns detected.`)));
+        return;
+    }
+    for (const f of allFindings) {
+        const color = f.severity === 'critical' ? pc.red : pc.yellow;
+        deps.out(`${color(`[${f.severity.toUpperCase()}]`)} ${f.file}:${f.line} ${pc.dim(`(${f.rule})`)}`);
+        deps.out(`  ${f.message}`);
+        deps.out(`  ${pc.dim(`${ARROW} ${f.suggestion}`)}\n`);
+    }
+    deps.out(pc.bold(`${allFindings.length} flakiness pattern(s) found.`));
+    throw new CliExit(1);
+}
+export function healTestCmd(path, opts, deps) {
+    if (!isFile(path)) {
+        deps.out(pc.red(`Error: ${path} is not a file.`));
+        throw new CliExit(1);
+    }
+    const result = deps.makeHealer().heal(path);
+    if (opts.json) {
+        const payload = {
+            file: result.file,
+            changed: result.changed,
+            changes: result.changes.map((c) => ({
+                line: c.line,
+                rule: c.rule,
+                description: c.description,
+                before: c.before.trim(),
+                after: c.after.trim(),
+            })),
+            skipped: result.skipped,
+        };
+        deps.out(jsonIndent2(payload));
+        if (result.changed && !opts.dryRun) {
+            writeFileSync(path, result.patched_content, 'utf-8');
+        }
+        return;
+    }
+    if (!result.changed) {
+        deps.out(pc.bold(pc.green(`${CHECK_MARK} No auto-fixable patterns found.`)));
+        for (const s of result.skipped) {
+            deps.out(`${pc.yellow(`${WARN} Skipped:`)} ${s}`);
+        }
+        return;
+    }
+    deps.out(`${pc.bold(pc.cyan(`${WRENCH} Pattern fixes for ${path}`))}\n`);
+    for (const c of result.changes) {
+        deps.out(`${pc.green(`line ${c.line}`)} ${pc.dim(`(${c.rule})`)} ${c.description}`);
+        deps.out(`  ${pc.red(`- ${c.before.trim()}`)}`);
+        deps.out(`  ${pc.green(`+ ${c.after.trim()}`)}\n`);
+    }
+    for (const s of result.skipped) {
+        deps.out(`${pc.yellow(`${WARN} Skipped:`)} ${s}\n`);
+    }
+    if (opts.dryRun) {
+        deps.out(pc.dim(`${result.changes.length} fix(es) ready. Re-run without --dry-run to apply.`));
+    }
+    else {
+        writeFileSync(path, result.patched_content, 'utf-8');
+        deps.out(pc.bold(pc.green(`${CHECK_MARK} ${result.changes.length} fix(es) applied to ${path}`)));
+    }
+}
+// --- version / upgrade -------------------------------------------------------
+export function versionCmd(deps) {
+    deps.out(renderBanner(resolveVersion(deps)));
+}
+export function upgradeCmd(opts, deps) {
+    const current = resolveVersion(deps);
+    deps.out(pc.dim(`Current version: ${current}`));
+    if (opts.dryRun) {
+        deps.out(pc.dim(`Dry run ${EM_DASH} run without --dry-run to apply the upgrade.`));
+        return;
+    }
+    const report = () => {
+        const updated = resolveVersion(deps);
+        if (updated !== current) {
+            deps.out(pc.green(`${CHECK} ${current} ${ARROW} ${updated}`));
+        }
+        else {
+            deps.out(pc.dim(`Already up to date (${current})`));
+        }
+    };
+    const pipx = deps.runSubprocess('pipx', ['upgrade', 'canary-test-ai']);
+    if (pipx.status === 0) {
+        report();
+        return;
+    }
+    deps.out(pc.yellow(`pipx not found ${EM_DASH} trying pip...`));
+    const pip = deps.runSubprocess(deps.pythonExe(), [
+        '-m',
+        'pip',
+        'install',
+        '--upgrade',
+        'canary-test-ai',
+    ]);
+    if (pip.status === 0) {
+        report();
+    }
+    else {
+        deps.out(`${pc.red('Upgrade failed.')}\n${pip.stderr.trim()}`);
+        throw new CliExit(1);
+    }
+}
+// --- overlay / doctor (npm-shim pointers) ------------------------------------
+export function overlayStub(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);
+}
+export function doctorStub(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);
+}
+export async function ticketUpdateCmd(opts, deps) {
+    let reportData = {};
+    if (opts.result) {
+        try {
+            reportData = JSON.parse(readFileSync(opts.result, 'utf-8'));
+        }
+        catch (exc) {
+            deps.out(pc.red(`Could not read result file '${opts.result}': ${exc instanceof Error ? exc.message : String(exc)}`));
+            throw new CliExit(1);
+        }
+    }
+    const testFile = opts.testFile;
+    const suiteName = reportData['suite_name'] ?? (testFile || 'unknown');
+    const envName = reportData['env'] ?? deps.env['CANARY_ENV'] ?? 'unknown';
+    let rawResult = String(reportData['result'] ?? 'FAIL').toUpperCase();
+    if (!['PASS', 'FAIL', 'PARTIAL'].includes(rawResult))
+        rawResult = 'FAIL';
+    const passedNames = reportData['passed_names'] ?? [];
+    const failedPairs = reportData['failed_names'] ?? [];
+    const failedNames = failedPairs.map((item) => Array.isArray(item) && item.length >= 2
+        ? [String(item[0]), String(item[1])]
+        : [String(item), 'unknown']);
+    const summary = new RunSummary({
+        suite_name: suiteName,
+        env: envName,
+        result: rawResult,
+        passed: reportData['passed'] ?? passedNames.length,
+        total: reportData['total'] ??
+            passedNames.length + failedNames.length,
+        flaky_count: reportData['flaky_count'] ?? 0,
+        duration_s: Number(reportData['duration_s'] ?? 0.0),
+        test_file: testFile ?? reportData['test_file'] ?? '',
+        report_url: reportData['report_url'] ?? null,
+        passed_names: passedNames,
+        failed_names: failedNames,
+        ticket_key: opts.ticket ?? null,
+        project_key: opts.project ?? null,
+    });
+    const updater = deps.makeTicketUpdater();
+    const updateResult = await updater.update(summary, {
+        dryRun: opts.dryRun ?? false,
+        commentOnly: opts.commentOnly ?? false,
+        transitionOnly: opts.transitionOnly ?? false,
+    });
+    for (const msg of updateResult.messages)
+        deps.out(msg);
+    if (!opts.dryRun) {
+        if (updateResult.comment_posted) {
+            deps.out(`${pc.green(CHECK)} Comment posted to ${updateResult.ticket_key}`);
+        }
+        const tr = updateResult.transition;
+        if (tr.attempted && tr.succeeded) {
+            deps.out(`${pc.green(CHECK)} Transitioned ${updateResult.ticket_key}: "${tr.from_status}" ${ARROW} "${tr.to_status}"`);
+        }
+        else if (tr.attempted && !tr.succeeded) {
+            deps.out(`${pc.yellow(WARN)}  Transition failed: ${tr.reason}`);
+        }
+    }
+    if (updateResult.transition.reason.startsWith(WARN)) {
+        throw new CliExit(1);
+    }
+}
+/** Python string `<`/`>` comparison (stable code-unit order). */
+function cmpStr(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+//# sourceMappingURL=cli-commands.js.map

package/dist/engine/cli-common.js

@@ -0,0 +1,60 @@
+/**
+ * Shared plumbing for the Canary commander CLIs (main program + `history` and
+ * `analyze` sub-apps), factored out of the guardian CLI pattern established in
+ * `guardian/cli.ts`.
+ *
+ * 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 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).
+ */
+export { CliExit } 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
+ * uses 2. Explicit `--help`/`--version` exit 0 in BOTH, so leave those. Used as
+ * the `.exitOverride()` callback on the program and every subcommand.
+ */
+export function normalizeUsageExit(err) {
+    if (err.code !== 'commander.helpDisplayed' &&
+        err.code !== 'commander.version') {
+        err.exitCode = 2;
+    }
+    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
+ * `[]`/`{}` for empty containers), and {@link ensureAscii} restores the
+ * `ensure_ascii=True` default. A trailing newline is NOT added here -- callers
+ * that mirror `sys.stdout.write(... + "\n")` add it via their line sink.
+ */
+export function jsonIndent2(value) {
+    return ensureAscii(JSON.stringify(value, null, 2));
+}
+//# sourceMappingURL=cli-common.js.map