canary-test-cli 7.0.0 → 7.1.0

package/dist/engine/mcp-server.js

@@ -34,7 +34,7 @@
  *     default for `_WORKING_DIR` uses `??` to mirror `os.environ.get(k, cwd)`
  *     (an explicitly-empty env var stays `""`).
  *   - **ensure_ascii.** Hand-built JSON returned to the MCP host is escaped via
- *     {@link ensureAscii} (the reporter.ts pattern) so non-ASCII code points
+ *     the shared {@link ensureAscii} (`util/ensure-ascii.ts`) so non-ASCII units
  *     emit `\uXXXX`, matching Python's default `json.dumps`.
  *   - **splitlines.** `context_snippets` uses {@link pySplitlines}, which drops
  *     a single trailing-newline empty tail exactly as `str.splitlines()` does.
@@ -46,12 +46,14 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import * as z from 'zod';
 import { DomainScanner } from './core/domain-scanner.js';
-import { detectEnvironment } from './core/environment-detect.js';
+import { detectEnvironment, detectUserLevel, } from './core/environment-detect.js';
+import { effectivePersonaRegistry, personaToDict, resolvePersona, } from './core/persona.js';
 import { CanaryTestExecutor } from './core/executor.js';
 import { FrameworkRegistry } from './core/framework-registry.js';
 import { HarnessMigrator } from './core/migrator.js';
 import { findTestFiles, PatternMatcher } from './core/pattern-matcher.js';
 import { Scaffolder } from './core/scaffolder.js';
+import { ensureAscii } from './util/ensure-ascii.js';
 // ---------------------------------------------------------------------------
 // Module constants (mirror agent/mcp_server.py)
 // ---------------------------------------------------------------------------
@@ -99,15 +101,6 @@ const MAX_FILE_FUNCTIONS = 20;
 // ---------------------------------------------------------------------------
 // Python-compatibility helpers
 // ---------------------------------------------------------------------------
-/**
- * Reproduce Python's `json.dumps(..., ensure_ascii=True)` (the library default):
- * escape every code point >= 0x80 as `\uXXXX`. Copied per-module, matching the
- * reporter.ts / guardian pattern (the regex range is written with `\u....`
- * escapes so this source stays ASCII).
- */
-function ensureAscii(json) {
-    return json.replace(/[\u0080-\uffff]/g, (ch) => '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0'));
-}
 /**
  * Split like Python's `str.splitlines()` for the common line endings: splits on
  * `\r\n` / `\r` / `\n` and drops the single empty tail a trailing separator
@@ -436,9 +429,37 @@ export function analyzeFileImpl(filePath) {
     // Context-aware persona & environment detection (#341): attach the detected
     // BASE_URL, suite type, and SDET-vs-manual user level. The file under
     // analysis is itself an "open file" signal for the user-level heuristic.
-    const environment = detectEnvironment(projectRoot, {
+    const detected = detectEnvironment(projectRoot, {
         openFiles: [filePath],
-    }).toDict();
+    });
+    // Personas (#462) — and the consumer #341 never had. Detection shipped and
+    // was read by nobody: the level was computed, attached here, and dropped.
+    // Resolving it into a persona is what turns the signal into something a
+    // skill can consult instead of re-inventing its own audience rules.
+    //
+    // The persona re-derives the user level WITHOUT the analyzed file, and that
+    // is the whole point of the second call. `filePath` is this tool's argument,
+    // not an observation of what the caller is working on, so counting it as
+    // evidence about the person would let any `.ts` file in any project with a
+    // package.json clear the two-independent-signal floor and declare the reader
+    // a senior SDET. `environment` above keeps reporting it — that contract is
+    // unchanged — and only the persona declines to count it.
+    const [personaLevel, personaSignals, personaConfidence] = detectUserLevel(projectRoot, []);
+    // Both I/O decisions are made *here* rather than inside the resolver, which
+    // is pure by design: reading the environment variable, and loading the
+    // registry (shipped personas folded with every overlay's). `CANARY_PERSONA`
+    // is the audience-depth axis and is unrelated to `canary doctor --audience`,
+    // which tags which overlay checks run.
+    const persona = personaToDict(resolvePersona({
+        explicit: process.env['CANARY_PERSONA'] ?? null,
+        detected: {
+            level: personaLevel,
+            confidence: personaConfidence,
+            signals: personaSignals,
+        },
+        registry: effectivePersonaRegistry(),
+    }));
+    const environment = detected.toDict();
     return {
         framework,
         framework_source: frameworkSource,
@@ -452,6 +473,7 @@ export function analyzeFileImpl(filePath) {
         existing_tests: findExistingTests(projectRoot, framework),
         context_snippets: contextSnippets,
         environment,
+        persona,
     };
 }
 /** Python: `_write_test_file_impl`. */

package/dist/engine/skills-cli.js

@@ -10,9 +10,14 @@
  * load/attr failure -> 6) over a dynamic `import()`, which will not resolve a
  * Python module. No Python test exercises the cli/entry execution branches.
  */
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { Command } from 'commander';
 import pc from 'picocolors';
-import { CliExit, normalizeUsageExit } from './cli-common.js';
+import { CliExitError, jsonIndent2, normalizeUsageExit } from './cli-common.js';
+import { gateOutcome } from './core/gate-result.js';
+import { checkExamples, spawnRunner, } from './core/skill-examples.js';
+import { SurfaceFindingKind, checkSurfaces, collectSurfaces, } from './core/skill-surfaces.js';
 import { isExecutableSkillAllowed, resolveCliPath, } from './core/skill-registry.js';
 import { CROSS, EM_DASH } from './main-deps.js';
 function overlayName(skill) {
@@ -88,19 +93,19 @@ async function runCmd(name, args, opts, deps) {
     const skill = deps.makeSkillRegistry().find(name);
     if (skill === null) {
         deps.out(`${pc.red(CROSS)} No skill named ${pc.bold(name)} found.`);
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
     if (skill.error) {
         deps.out(`${pc.red(CROSS)} Skill ${pc.bold(name)}: ${skill.error}`);
-        throw new CliExit(2);
+        throw new CliExitError(2);
     }
     if (!skill.isExecutable) {
         deps.out(pc.yellow(`Skill ${pc.bold(name)} is markdown-only ${EM_DASH} no cli: or entry: field to run.`));
-        throw new CliExit(2);
+        throw new CliExitError(2);
     }
     if (!isExecutableSkillAllowed(opts.allowExecutableSkills ?? false)) {
         deps.out(`${pc.red(CROSS)} Refusing to invoke executable skill in non-interactive context. Pass ${pc.bold('--allow-executable-skills')} to opt in (e.g. in trusted CI configurations).`);
-        throw new CliExit(3);
+        throw new CliExitError(3);
     }
     const forwarded = args;
     if (skill.cli) {
@@ -110,7 +115,7 @@ async function runCmd(name, args, opts, deps) {
         }
         catch (exc) {
             deps.out(`${pc.red(CROSS)} ${exc instanceof Error ? exc.message : String(exc)}`);
-            throw new CliExit(4);
+            throw new CliExitError(4);
         }
         const cmd = target.endsWith('.py') ? [deps.pythonExe(), target] : [target];
         const res = deps.runSubprocess(cmd[0], [...cmd.slice(1), ...forwarded], {
@@ -120,14 +125,14 @@ async function runCmd(name, args, opts, deps) {
         // A spawn failure (missing interpreter/binary) yields status=null; Python's
         // subprocess.run raises FileNotFoundError -> nonzero exit. Map null -> 1, not
         // a silent 0. A normal run passes its real exit code through.
-        throw new CliExit(res.status ?? 1);
+        throw new CliExitError(res.status ?? 1);
     }
     // entry: branch -- see module docstring (Python-module semantics are not
     // portable; the exit-code ladder is preserved).
     const [moduleName, sep, attr] = partition(skill.entry, ':');
     if (!moduleName || !attr || !sep) {
         deps.out(`${pc.red(CROSS)} Skill ${pc.bold(name)} entry must be 'module:callable', got '${skill.entry}'`);
-        throw new CliExit(5);
+        throw new CliExitError(5);
     }
     try {
         const mod = (await import(moduleName));
@@ -135,15 +140,122 @@ async function runCmd(name, args, opts, deps) {
         if (typeof target !== 'function')
             throw new Error('not callable');
         const rc = target();
-        throw new CliExit(typeof rc === 'number' ? rc : 0);
+        throw new CliExitError(typeof rc === 'number' ? rc : 0);
     }
     catch (exc) {
-        if (exc instanceof CliExit)
+        if (exc instanceof CliExitError)
             throw exc;
         deps.out(`${pc.red(CROSS)} Skill ${pc.bold(name)} entry '${skill.entry}': ${exc instanceof Error ? exc.message : String(exc)}`);
-        throw new CliExit(6);
+        throw new CliExitError(6);
     }
 }
+/**
+ * `skills verify` -- cross-surface consistency (#452) plus execution of the
+ * commands the docs promise (#487).
+ *
+ * **Two checks, two summary lines, deliberately.** Folding them into one
+ * denominator is the trap: 80 surfaces checked and 0 examples executed would
+ * render as a single healthy number while the half that actually executes
+ * something had abstained. Each check therefore reports its own denominator
+ * through `gateOutcome`, and the reader sees both.
+ *
+ * Classified **advisory** (exit 0): both checks are landing on a corpus nothing
+ * has ever swept, so their precision is unknown and ADR 0010 says promotion
+ * waits for the triage. Abstention is still printed loudly -- that is what the
+ * classification does *not* soften.
+ */
+/**
+ * Run the examples half, or explain why it could not run.
+ *
+ * The examples half spawns a CLI. When there is no built one, the honest result
+ * is a zero denominator carrying the reason -- an unrunnable runner must never
+ * look like a clean corpus.
+ */
+function exampleHalf(opts, surfaces, root) {
+    const bin = opts.canaryBin ?? join(root, 'ts', 'bin', 'canary.js');
+    if ((opts.runExamples ?? true) && existsSync(bin)) {
+        return checkExamples(surfaces, spawnRunner(bin), root);
+    }
+    return {
+        checked: 0,
+        findings: [],
+        skipped: [
+            {
+                name: 'every documented example',
+                reason: opts.runExamples === false
+                    ? '--no-run-examples was passed'
+                    : `no built CLI at ${bin} (run \`npm --prefix ts run build\`)`,
+            },
+        ],
+    };
+}
+/**
+ * Per-kind tally over the FULL enum, including kinds that scored zero.
+ *
+ * A triage backlog is read by category, and `cli-not-executable=0` is the line
+ * that says the rule ran. An absent line is indistinguishable from a rule that
+ * was never evaluated -- the reading trap this whole check exists to close.
+ */
+function tallyByKind(findings) {
+    return Object.values(SurfaceFindingKind)
+        .map((kind) => `${kind}=${findings.filter((f) => f.kind === kind).length}`)
+        .join(' ');
+}
+/** Both halves as JSON, each carrying its own `checked` and `abstained`. */
+function verifyJson(root, surfaceResult, exampleResult) {
+    return jsonIndent2({
+        root,
+        surfaces: {
+            checked: surfaceResult.checked,
+            abstained: !(surfaceResult.checked > 0),
+            findings: surfaceResult.findings,
+        },
+        examples: {
+            checked: exampleResult.checked,
+            abstained: !(exampleResult.checked > 0),
+            findings: exampleResult.findings,
+            skipped: exampleResult.skipped ?? [],
+        },
+    });
+}
+/** One summary line per half, plus the remediation text on an abstention. */
+function verifyReport(root, surfaceResult, exampleResult, deps) {
+    for (const f of surfaceResult.findings) {
+        deps.err(`${pc.yellow(CROSS)} [${f.kind}] ${f.name}: ${f.detail}`);
+    }
+    for (const f of exampleResult.findings) {
+        deps.err(`${pc.yellow(CROSS)} [${f.kind}] ${f.skill}: ${f.detail}`);
+    }
+    const surfaceOutcome = gateOutcome(surfaceResult, 'advisory', {
+        noun: 'surface declaration(s)',
+    });
+    deps.out(`surfaces: ${surfaceOutcome.summaryLine}`);
+    deps.out(`  by kind: ${tallyByKind(surfaceResult.findings)}`);
+    if (surfaceOutcome.abstained) {
+        deps.out(`  no skill surface was found under ${root} ${EM_DASH} check the path, ` +
+            'or that `agents/skills/` has not been renamed.');
+    }
+    const exampleOutcome = gateOutcome(exampleResult, 'advisory', {
+        noun: 'documented example(s)',
+    });
+    deps.out(`examples: ${exampleOutcome.summaryLine}`);
+    if (exampleOutcome.abstained) {
+        deps.out(`  zero documented commands were executed ${EM_DASH} nothing here is ` +
+            'proven. Add a help-shaped example in a shell fence to a SKILL.md, or ' +
+            'build the engine so the runner has a CLI to spawn.');
+    }
+}
+function verifyCmd(opts, deps) {
+    const root = resolve(opts.root ?? deps.cwd());
+    const surfaces = collectSurfaces(root);
+    const surfaceResult = checkSurfaces(root);
+    const exampleResult = exampleHalf(opts, surfaces, root);
+    if (opts.json) {
+        deps.out(verifyJson(root, surfaceResult, exampleResult));
+        return;
+    }
+    verifyReport(root, surfaceResult, exampleResult, deps);
+}
 /** Python `str.partition(sep)` -> `[before, sep, after]`. */
 function partition(s, sep) {
     const i = s.indexOf(sep);
@@ -173,6 +285,16 @@ export function buildSkillsCommand(deps) {
         .action(async (name, args, opts) => {
         await runCmd(name, args ?? [], opts, deps);
     });
+    program
+        .command('verify')
+        .description('Check that skill surfaces agree and that documented examples still run.')
+        .option('--root <path>', 'Repository root to inspect (default: cwd).')
+        .option('--json', 'Emit both denominators and every finding as JSON.')
+        .option('--no-run-examples', 'Inspect declarations only; do not execute documented examples.')
+        .option('--canary-bin <path>', 'CLI to spawn for documented examples.')
+        .action((opts) => {
+        verifyCmd(opts, deps);
+    });
     for (const sub of program.commands) {
         sub.exitOverride(normalizeUsageExit);
     }

package/dist/engine/util/ensure-ascii.js

@@ -0,0 +1,37 @@
+/**
+ * The one `ensure_ascii=True` implementation (#710).
+ *
+ * Python's `json.dumps` escapes every non-ASCII character to `\uXXXX` by
+ * default; `JSON.stringify` emits raw UTF-8. Every module that reproduces a
+ * Python payload byte-for-byte therefore has to post-process its stringify
+ * output, and eight of them used to do it with a private copy of this function.
+ *
+ * It lives under `util/` rather than in `cli-common.ts` (which documented it
+ * first) because the copies were spread across the `core`, `guardian`, and
+ * entry layers, and the layer model in `harness.config.json` lets nothing
+ * depend on `cli`. `util` is the one leaf every layer is allowed to reach.
+ *
+ * `ts/test/shared-helper-single-source.test.ts` fails if a ninth copy appears.
+ */
+/**
+ * Escape every non-ASCII UTF-16 code UNIT to `\uXXXX`, matching Python
+ * `json.dumps(ensure_ascii=True)`.
+ *
+ * Iterating by code unit rather than code point is the load-bearing detail: an
+ * astral character's surrogate pair emits `\udXXX\udXXX`, exactly as CPython
+ * writes it. A code-point walk (`for (const ch of json)`) would instead reach
+ * a value above `0xffff`, which does not fit a four-hex-digit `\uXXXX` escape
+ * at all -- so it would either truncate or leave the character raw.
+ *
+ * Only the `>= 0x80` range is touched, so the ASCII escapes `JSON.stringify`
+ * already produced (`\"`, `\\`, control characters) pass through intact.
+ */
+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;
+}
+//# sourceMappingURL=ensure-ascii.js.map

package/dist/engine/workflow-cli.js

@@ -12,7 +12,7 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { Command } from 'commander';
 import pc from 'picocolors';
-import { CliExit, jsonIndent2, normalizeUsageExit } from './cli-common.js';
+import { CliExitError, jsonIndent2, normalizeUsageExit } from './cli-common.js';
 import { SemanticRole, WorkflowDiscoveryError, WorkflowMapping, } from './core/workflow-discovery.js';
 import { CHECK, CROSS, MAGNIFIER, WARN, ELLIPSIS, } from './main-deps.js';
 /** ISO-8601 UTC timestamp truncated to seconds (Python `isoformat(timespec)`). */
@@ -38,7 +38,7 @@ async function discoverCmd(opts, deps) {
         }
         if (keys.length === 0) {
             deps.out(`${pc.yellow('No project keys found.')} Pass ${pc.bold('--project <key>')} or add keys to ${pc.bold('.canary/company.json')} ${'\u{2192}'} ${pc.bold('jira_projects')}.`);
-            throw new CliExit(1);
+            throw new CliExitError(1);
         }
     }
     const errors = [];
@@ -76,7 +76,7 @@ async function discoverCmd(opts, deps) {
     }
     if (errors.length) {
         deps.out(`\n${pc.red(`Discovery failed for: ${errors.join(', ')}`)}`);
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
 }
 function showCmd(opts, deps) {
@@ -99,7 +99,7 @@ function showCmd(opts, deps) {
         }
         if (keys.length === 0) {
             deps.out(pc.yellow('No cached workflow mappings found.'));
-            throw new CliExit(0);
+            throw new CliExitError(0);
         }
     }
     let anyFound = false;
@@ -162,7 +162,7 @@ function showCmd(opts, deps) {
         }
     }
     if (!anyFound) {
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
 }
 function initCmd(opts, deps) {
@@ -170,7 +170,7 @@ function initCmd(opts, deps) {
     const mappingPath = wd.mappingPath(opts.project);
     if (existsSync(mappingPath) && !opts.force) {
         deps.out(`${pc.yellow(WARN)}  Mapping already exists at ${mappingPath}.\nUse ${pc.bold('--force')} to overwrite.`);
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
     const resolvedUrl = (opts.atlassianUrl || deps.env['ATLASSIAN_URL'] || '').replace(/\/+$/, '') || null;
     const semanticRoles = {

package/dist/gate-result.d.ts

@@ -48,6 +48,17 @@ export interface GateOutcomeOptions {
     /** Unit noun for the clean-pass line. Default: `'check(s)'`. */
     noun?: string;
 }
+/**
+ * The errno code `e` carries, or `null` when it carries none.
+ *
+ * Load-bearing wherever a read failure is absorbed into a {@link SkipEntry}:
+ * only "the filesystem said no" may become a skip. Node PROGRAMMER errors carry
+ * a string `code` too, so keying off `typeof code === 'string'` reports a
+ * genuine defect inside the scanner as a tidy abstention with a misleading
+ * reason -- which is how a scanner learns to go quiet. Anything this returns
+ * `null` for must still throw.
+ */
+export declare function errnoCode(e: unknown): string | null;
 /**
  * D7: skipped entries render in EVERY summary line.
  *

package/dist/gate-result.js

@@ -7,6 +7,7 @@
 // `npm test` verifies this copy has not drifted (--check runs as pretest).
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EXIT_ABSTAINED = void 0;
+exports.errnoCode = errnoCode;
 exports.skippedSuffix = skippedSuffix;
 exports.gateOutcome = gateOutcome;
 /**
@@ -19,6 +20,23 @@ const EMDASH = '\u{2014}'; // em dash
 // C0 controls (incl. \n, ESC) and DEL: a skip name must never be able to
 // forge output lines or smuggle ANSI sequences into the summary.
 const CONTROL_CHARS = /[\u0000-\u001F\u007F]/g;
+// A libuv/POSIX errno code (`ENOENT`, `EACCES`, `EISDIR`), as opposed to a Node
+// programmer-error code (`ERR_INVALID_ARG_TYPE`).
+const ERRNO = /^E[A-Z0-9]+$/;
+/**
+ * The errno code `e` carries, or `null` when it carries none.
+ *
+ * Load-bearing wherever a read failure is absorbed into a {@link SkipEntry}:
+ * only "the filesystem said no" may become a skip. Node PROGRAMMER errors carry
+ * a string `code` too, so keying off `typeof code === 'string'` reports a
+ * genuine defect inside the scanner as a tidy abstention with a misleading
+ * reason -- which is how a scanner learns to go quiet. Anything this returns
+ * `null` for must still throw.
+ */
+function errnoCode(e) {
+    const code = e?.code;
+    return typeof code === 'string' && ERRNO.test(code) ? code : null;
+}
 /**
  * D7: skipped entries render in EVERY summary line.
  *

package/dist/uninstall.js

@@ -128,9 +128,20 @@ const KNOWN_FLAGS = new Set([
     '--apply',
     '--include-generated',
 ]);
+/** The scope menu, shared by `--help` and the no-scope refusal. */
+const SCOPE_HELP = '  --global   overlays and orphaned Claude Code plugin caches\n' +
+    '  --project  .canary/, generated reports, and the .mcp.json entry\n' +
+    '  --all      both\n' +
+    'Nothing is removed without --apply.\n';
 function run(argv, deps = {}) {
     const out = deps.out ?? process.stdout;
     const err = deps.err ?? process.stderr;
+    // Routed before the engine's commander sees argv (#730), so `--help` lands
+    // here as a plain token. Asking how a command works is not a usage error.
+    if (argv.includes('--help') || argv.includes('-h')) {
+        out.write(`usage: canary uninstall <scope> [--apply]\n${SCOPE_HELP}`);
+        return 0;
+    }
     for (const a of argv) {
         if (!KNOWN_FLAGS.has(a)) {
             err.write(`canary uninstall: unknown option "${a}".\n`);
@@ -145,11 +156,7 @@ function run(argv, deps = {}) {
     if (argv.includes('--all'))
         scopes.push('all');
     if (scopes.length === 0) {
-        err.write('canary uninstall: choose a scope.\n' +
-            '  --global   overlays and orphaned Claude Code plugin caches\n' +
-            '  --project  .canary/, generated reports, and the .mcp.json entry\n' +
-            '  --all      both\n' +
-            'Nothing is removed without --apply.\n');
+        err.write(`canary uninstall: choose a scope.\n${SCOPE_HELP}`);
         return 1;
     }
     if (scopes.length > 1) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canary-test-cli",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "description": "Canary — AI-powered test automation agent",
   "license": "MIT",
   "repository": {