canary-test-cli 5.15.0 → 6.0.0

package/dist/engine/skills-cli.js

@@ -0,0 +1,181 @@
+/**
+ * `canary skills` sub-app -- faithful port of the `skills_app` commands in
+ * `agent/cli.py` (`list`, `run`), wired to the already-ported `SkillRegistry`.
+ *
+ * INTENTIONAL DEVIATION (`skills run`, entry-target branch): Python's `entry:`
+ * skills load a Python `module:callable` via `importlib` and invoke it in-process
+ * -- there is no portable Node equivalent. The `cli:` branch (spawn a `.py`/`.js`
+ * target, the path skills actually use going forward) is ported faithfully; the
+ * `entry:` branch preserves the Python exit-code ladder (bad format -> 5,
+ * 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 { Command } from 'commander';
+import pc from 'picocolors';
+import { CliExit, normalizeUsageExit } from './cli-common.js';
+import { isExecutableSkillAllowed, resolveCliPath, } from './core/skill-registry.js';
+import { CROSS, EM_DASH } from './main-deps.js';
+function overlayName(skill) {
+    // Clone layout: ~/.canary/overlays/<overlay>/.canary/skills/<name>/SKILL.md
+    const parts = skill.path.split(/[\\/]/);
+    const i = parts.indexOf('overlays');
+    return i >= 0 && i + 1 < parts.length ? parts[i + 1] : '?';
+}
+function formatSkill(skill, verbose) {
+    // rich rendered `\[cli]` etc. as literal "[cli]" (the backslash escapes the
+    // markup); the equivalent picocolors output is the literal bracket text.
+    let marker = '';
+    if (skill.error)
+        marker = ' [error]';
+    else if (skill.cli)
+        marker = ' [cli]';
+    else if (skill.entry)
+        marker = ' [entry]';
+    const desc = skill.description ? `  ${skill.description}` : '';
+    let line = `  /${skill.name}${marker}${desc}`;
+    if (verbose)
+        line += `\n    ${pc.dim(skill.path)}`;
+    return line;
+}
+function listCmd(opts, deps) {
+    const verbose = opts.verbose ?? false;
+    const skills = deps.makeSkillRegistry().discover();
+    if (skills.length === 0) {
+        deps.out(pc.yellow('No skills found.'));
+        return;
+    }
+    const bundled = skills.filter((s) => s.source === 'bundled');
+    const overlay = skills.filter((s) => s.source === 'overlay');
+    const globalSkills = skills.filter((s) => s.source === 'global');
+    const local = skills.filter((s) => s.source === 'local');
+    if (bundled.length) {
+        deps.out(pc.bold('Bundled skills:'));
+        for (const skill of bundled)
+            deps.out(formatSkill(skill, verbose));
+    }
+    if (overlay.length) {
+        const sorted = [...overlay].sort((a, b) => overlayName(a).localeCompare(overlayName(b)));
+        let idx = 0;
+        let cur = null;
+        for (const skill of sorted) {
+            const oname = overlayName(skill);
+            if (oname !== cur) {
+                if (bundled.length || idx > 0)
+                    deps.out('');
+                deps.out(`${pc.bold('Overlay skills')} ${pc.dim(`(${oname} ${EM_DASH} override bundled):`)}`);
+                cur = oname;
+                idx += 1;
+            }
+            deps.out(formatSkill(skill, verbose));
+        }
+    }
+    if (globalSkills.length) {
+        if (bundled.length || overlay.length)
+            deps.out('');
+        deps.out(`${pc.bold('Global skills')} ${pc.dim(`(~/.canary/skills/ ${EM_DASH} override overlay):`)}`);
+        for (const skill of globalSkills)
+            deps.out(formatSkill(skill, verbose));
+    }
+    if (local.length) {
+        if (bundled.length || overlay.length || globalSkills.length)
+            deps.out('');
+        deps.out(`${pc.bold('Local overlay skills')} ${pc.dim('(override global):')}`);
+        for (const skill of local)
+            deps.out(formatSkill(skill, verbose));
+    }
+}
+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);
+    }
+    if (skill.error) {
+        deps.out(`${pc.red(CROSS)} Skill ${pc.bold(name)}: ${skill.error}`);
+        throw new CliExit(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);
+    }
+    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);
+    }
+    const forwarded = args;
+    if (skill.cli) {
+        let target;
+        try {
+            target = resolveCliPath(skill);
+        }
+        catch (exc) {
+            deps.out(`${pc.red(CROSS)} ${exc instanceof Error ? exc.message : String(exc)}`);
+            throw new CliExit(4);
+        }
+        const cmd = target.endsWith('.py') ? [deps.pythonExe(), target] : [target];
+        const res = deps.runSubprocess(cmd[0], [...cmd.slice(1), ...forwarded], {
+            cwd: skill.dir,
+            inherit: true,
+        });
+        // 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);
+    }
+    // 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);
+    }
+    try {
+        const mod = (await import(moduleName));
+        const target = mod[attr];
+        if (typeof target !== 'function')
+            throw new Error('not callable');
+        const rc = target();
+        throw new CliExit(typeof rc === 'number' ? rc : 0);
+    }
+    catch (exc) {
+        if (exc instanceof CliExit)
+            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);
+    }
+}
+/** Python `str.partition(sep)` -> `[before, sep, after]`. */
+function partition(s, sep) {
+    const i = s.indexOf(sep);
+    if (i < 0)
+        return [s, '', ''];
+    return [s.slice(0, i), sep, s.slice(i + sep.length)];
+}
+/** Build the `skills` sub-app wired to `deps`. */
+export function buildSkillsCommand(deps) {
+    const program = new Command('skills');
+    program
+        .description('List and invoke discoverable Canary skills.')
+        .exitOverride(normalizeUsageExit);
+    program
+        .command('list')
+        .description('List every skill discoverable from the current directory.')
+        .option('-v, --verbose', 'Also print the SKILL.md path for each skill.')
+        .action((opts) => {
+        listCmd(opts, deps);
+    });
+    program
+        .command('run')
+        .description("Invoke a code-bearing skill's declared cli or entry target.")
+        .argument('<name>', 'Name of the skill to invoke.')
+        .argument('[args...]', "Arguments forwarded to the skill's cli/entry.")
+        .option('--allow-executable-skills', 'Opt-in to invoking cli:/entry: skills in non-interactive (CI) contexts.')
+        .action(async (name, args, opts) => {
+        await runCmd(name, args ?? [], opts, deps);
+    });
+    for (const sub of program.commands) {
+        sub.exitOverride(normalizeUsageExit);
+    }
+    return program;
+}
+//# sourceMappingURL=skills-cli.js.map

package/dist/engine/ui/banner.js

@@ -0,0 +1,50 @@
+/**
+ * CLI startup banner -- faithful TypeScript port of `agent/ui/banner.py`.
+ *
+ * The Python banner writes raw ANSI escape codes with `print()` (NOT rich), so
+ * it never strips color for a non-TTY sink -- the bytes are identical whether
+ * stdout is a terminal or a captured test buffer. This port reproduces those
+ * exact bytes: the ESC byte (Python `\033`) as `\u{1b}`, the SGR sequences
+ * verbatim, and the box-drawing glyphs as `\u{...}` escapes (ASCII-source rule).
+ *
+ * Only `renderBanner` is ported -- it is all the CLI's `version` command and
+ * `--version` option need. `print_result_line` / `print_section` are unused by
+ * the CLI and intentionally omitted.
+ */
+const ESC = '\u{1b}';
+const RESET = `${ESC}[0m`;
+const BOLD = `${ESC}[1m`;
+// Canary gold (#F0C040) and the supporting palette (true-color SGR).
+const GOLD = `${ESC}[38;2;240;192;64m`;
+const AMBER = `${ESC}[38;2;192;144;24m`;
+const WHITE = `${ESC}[38;2;245;245;245m`;
+const MUTED = `${ESC}[38;2;85;85;85m`;
+const DARK = `${ESC}[38;2;46;46;46m`;
+// Bird mark (3-line ASCII-art): U+25B2 up-triangle, U+2588 full block,
+// U+2580 upper-half block.
+const BIRD = [
+    `${GOLD}  \u{25b2}${RESET}`,
+    `${GOLD} \u{25b2}\u{2588}\u{25b2}${RESET}`,
+    `${AMBER}  \u{2580}${RESET}`,
+];
+const TAGLINE = 'test automation agent';
+// U+00B7 middle dot separator.
+const NETWORK = 'birds of prey network \u{00b7} clocktower voice system';
+const RULE = '\u{2500}'.repeat(44); // U+2500 box drawings light horizontal
+/**
+ * Render the Canary startup banner as a single string (no trailing newline;
+ * the caller's line sink adds one, matching Python `print(banner)`).
+ */
+export function renderBanner(version) {
+    const divider = `${DARK}${RULE}${RESET}`;
+    const lines = [
+        '',
+        `  ${BIRD[0]}   ${BOLD}${WHITE}canary${RESET}  ${GOLD}v${version}${RESET}`,
+        `  ${BIRD[1]}   ${MUTED}${TAGLINE}${RESET}`,
+        `  ${BIRD[2]}   ${DARK}${NETWORK}${RESET}`,
+        `       ${divider}`,
+        '',
+    ];
+    return lines.join('\n');
+}
+//# sourceMappingURL=banner.js.map

package/dist/engine/util/coalesce.js

@@ -0,0 +1,12 @@
+/**
+ * Nullish-default helper.
+ *
+ * `def(x, fallback)` is exactly `x ?? fallback`, but as a function call it is not
+ * a decision point — so replacing dense `??` fallback chains in field-mapper
+ * functions with `def(...)` keeps behaviour identical while lowering the
+ * cyclomatic complexity the arch ratchet measures.
+ */
+export function def(value, fallback) {
+    return value ?? fallback;
+}
+//# sourceMappingURL=coalesce.js.map

package/dist/engine/util/round.js

@@ -0,0 +1,43 @@
+/**
+ * Python-compatible numeric rounding, shared by the history store (rate
+ * computation) and the report builders (display formatting).
+ */
+/** Python-compatible round-half-to-even at 1 decimal place. */
+export function round1(x) {
+    const scaled = x * 10;
+    const floor = Math.floor(scaled);
+    const diff = scaled - floor;
+    const eps = 1e-9;
+    let rounded;
+    if (Math.abs(diff - 0.5) < eps) {
+        // Exact .5 tie → round to even.
+        rounded = floor % 2 === 0 ? floor : floor + 1;
+    }
+    else {
+        rounded = Math.round(scaled);
+    }
+    return rounded / 10;
+}
+/** Render a 1-decimal-rounded number the way Python's `str(float)` would. */
+export function num1(x) {
+    return round1(x).toFixed(1);
+}
+/** Python-compatible `round(x)` to the nearest integer, half-to-even. */
+export function roundHalfEvenInt(x) {
+    const floor = Math.floor(x);
+    const diff = x - floor;
+    const eps = 1e-9;
+    if (Math.abs(diff - 0.5) < eps) {
+        return floor % 2 === 0 ? floor : floor + 1;
+    }
+    return Math.round(x);
+}
+/**
+ * Render a float the way Python's `str(float)` would: an integer-valued float
+ * keeps a trailing ".0" (Python `str(10.0)` → "10.0", whereas JS `${10.0}`
+ * yields "10"). Used for threshold parameters interpolated raw into headers.
+ */
+export function pyFloat(x) {
+    return Number.isInteger(x) ? `${x}.0` : `${x}`;
+}
+//# sourceMappingURL=round.js.map

package/dist/engine/workflow-cli.js

@@ -0,0 +1,242 @@
+/**
+ * `canary workflow` sub-app -- faithful port of the `workflow_app` commands in
+ * `agent/cli.py` (`discover`, `show`, `init`), wired to the already-ported
+ * `WorkflowDiscovery` / `WorkflowMapping` / `SemanticRole`.
+ *
+ * `discover` is async (the discovery HTTP path returns Promises), so its handler
+ * is awaited. `show` / `init` are synchronous. Ticket keys, mapping paths, and
+ * the `.canary` dir all resolve from `process.cwd()` inside the injected
+ * `makeWorkflowDiscovery()` factory, so a test drives them by chdir-ing.
+ */
+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 { 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)`). */
+function nowIsoCli() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, '+00:00');
+}
+async function discoverCmd(opts, deps) {
+    const wd = deps.makeWorkflowDiscovery();
+    let keys = [];
+    if (opts.project) {
+        keys = [opts.project];
+    }
+    else {
+        const companyPath = join(deps.cwd(), '.canary', 'company.json');
+        if (existsSync(companyPath)) {
+            try {
+                const data = JSON.parse(readFileSync(companyPath, 'utf-8'));
+                keys = data.jira_projects ?? [];
+            }
+            catch {
+                // JSONDecodeError / OSError -> leave keys empty.
+            }
+        }
+        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);
+        }
+    }
+    const errors = [];
+    for (const key of keys) {
+        deps.out(`\n${pc.bold(pc.cyan(`${MAGNIFIER} Discovering workflow for ${key}${ELLIPSIS}`))}`);
+        let mapping;
+        try {
+            mapping = await wd.discover(key, {
+                refresh: opts.refresh ?? false,
+                dryRun: opts.dryRun ?? false,
+            });
+        }
+        catch (exc) {
+            if (exc instanceof WorkflowDiscoveryError) {
+                deps.out(`${pc.red(CROSS)} ${exc.message}`);
+                errors.push(key);
+                continue;
+            }
+            throw exc;
+        }
+        const nTypes = mapping.issue_types.length;
+        const nRoles = Object.keys(mapping.semantic_roles).length;
+        const confirmed = mapping.role_annotations_confirmed
+            ? `${CHECK} confirmed`
+            : `${WARN} unconfirmed`;
+        if (opts.dryRun) {
+            deps.out(`${pc.dim('(dry-run)')} ${mapping.toJson()}`);
+        }
+        else {
+            deps.out(`${pc.green(CHECK)} ${key}: ${nTypes} issue type(s), ${nRoles} semantic role(s) [${confirmed}]`);
+            if (!mapping.role_annotations_confirmed) {
+                deps.out(pc.dim(`  Tip: verify role assignments with ${pc.bold(`canary workflow show --project ${key} --roles-only`)}`));
+            }
+        }
+    }
+    if (errors.length) {
+        deps.out(`\n${pc.red(`Discovery failed for: ${errors.join(', ')}`)}`);
+        throw new CliExit(1);
+    }
+}
+function showCmd(opts, deps) {
+    const wd = deps.makeWorkflowDiscovery();
+    let keys = [];
+    if (opts.project) {
+        keys = [opts.project];
+    }
+    else {
+        const canaryDir = join(deps.cwd(), '.canary');
+        if (existsSync(canaryDir)) {
+            try {
+                keys = readdirSync(canaryDir)
+                    .filter((f) => f.startsWith('workflow-') && f.endsWith('.json'))
+                    .map((f) => f.slice('workflow-'.length, -'.json'.length));
+            }
+            catch {
+                keys = [];
+            }
+        }
+        if (keys.length === 0) {
+            deps.out(pc.yellow('No cached workflow mappings found.'));
+            throw new CliExit(0);
+        }
+    }
+    let anyFound = false;
+    for (const key of keys) {
+        const mapping = wd.show(key);
+        if (mapping === null) {
+            deps.out(`${pc.yellow(`No cached mapping for ${key}.`)}  Run ${pc.bold(`canary workflow discover --project ${key}`)} first.`);
+            continue;
+        }
+        anyFound = true;
+        if (opts.json) {
+            if (opts.rolesOnly) {
+                const rolesDict = {};
+                for (const [r, sr] of Object.entries(mapping.semantic_roles)) {
+                    rolesDict[r] = {
+                        status_name: sr.status_name,
+                        issue_type: sr.issue_type,
+                    };
+                }
+                deps.out(jsonIndent2(rolesDict));
+            }
+            else {
+                deps.out(mapping.toJson());
+            }
+            continue;
+        }
+        const confirmedTag = mapping.role_annotations_confirmed
+            ? pc.green('confirmed')
+            : pc.yellow('unconfirmed');
+        deps.out(`\n${pc.bold(key)}  ${pc.dim(`source=${mapping.source}  discovered=${mapping.discovered_at}  roles=${confirmedTag}`)}`);
+        if (opts.rolesOnly) {
+            if (Object.keys(mapping.semantic_roles).length) {
+                deps.out(`  ${pc.bold('Semantic roles:')}`);
+                for (const [role, sr] of Object.entries(mapping.semantic_roles)) {
+                    deps.out(`    ${role.padEnd(20)} ${'\u{2192}'} '${sr.status_name}'  ${pc.dim(`(${sr.issue_type})`)}`);
+                }
+            }
+            else {
+                deps.out(`  ${pc.yellow('No semantic roles resolved yet.')}`);
+            }
+            continue;
+        }
+        for (const it of mapping.issue_types) {
+            deps.out(`\n  ${pc.bold(it.name)}`);
+            for (const s of it.statuses) {
+                deps.out(`    [${s.category}] ${s.name}`);
+            }
+            if (it.transitions.length) {
+                deps.out('    Transitions:');
+                for (const t of it.transitions) {
+                    deps.out(`      ${t.from_status} ${'\u{2192}'} ${t.to_status}  ${pc.dim(`(${t.name})`)}`);
+                }
+            }
+        }
+        if (Object.keys(mapping.semantic_roles).length) {
+            deps.out(`\n  ${pc.bold('Semantic roles:')}`);
+            for (const [role, sr] of Object.entries(mapping.semantic_roles)) {
+                deps.out(`    ${role.padEnd(20)} ${'\u{2192}'} '${sr.status_name}'  ${pc.dim(`(${sr.issue_type})`)}`);
+            }
+        }
+    }
+    if (!anyFound) {
+        throw new CliExit(1);
+    }
+}
+function initCmd(opts, deps) {
+    const wd = deps.makeWorkflowDiscovery();
+    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);
+    }
+    const resolvedUrl = (opts.atlassianUrl || deps.env['ATLASSIAN_URL'] || '').replace(/\/+$/, '') || null;
+    const semanticRoles = {
+        qa_passed: new SemanticRole(opts.qaPassed, 'Story'),
+    };
+    if (opts.inQa) {
+        semanticRoles['in_qa'] = new SemanticRole(opts.inQa, 'Story');
+    }
+    const mapping = new WorkflowMapping({
+        project_key: opts.project,
+        source: 'jira',
+        discovered_at: nowIsoCli(),
+        issue_types: [],
+        semantic_roles: semanticRoles,
+        role_annotations_confirmed: true,
+        atlassian_url: resolvedUrl,
+    });
+    wd.write(mapping);
+    deps.out(`${pc.green(CHECK)} Created ${mappingPath}`);
+    deps.out(`  qa_passed  ${'\u{2192}'} '${opts.qaPassed}'`);
+    if (opts.inQa) {
+        deps.out(`  in_qa      ${'\u{2192}'} '${opts.inQa}'`);
+    }
+    if (resolvedUrl) {
+        deps.out(`  atlassian_url ${'\u{2192}'} ${resolvedUrl}`);
+    }
+    deps.out(`\n${pc.dim(`Verify with: ${pc.bold(`canary workflow show --project ${opts.project} --roles-only`)}`)}`);
+}
+/** Build the `workflow` sub-app wired to `deps`. */
+export function buildWorkflowCommand(deps) {
+    const program = new Command('workflow');
+    program
+        .description('Discover and inspect per-project issue-workflow mappings.')
+        .exitOverride(normalizeUsageExit);
+    program
+        .command('discover')
+        .description('Discover the Jira or GitHub workflow for one or more projects and persist the mapping.')
+        .option('-p, --project <project>', 'Jira project key or GitHub repo slug. Defaults to company.json jira_projects.')
+        .option('--refresh', 'Re-discover even if a cached mapping already exists.')
+        .option('--dry-run', 'Print the mapping that would be written without writing it.')
+        .action(async (opts) => {
+        await discoverCmd(opts, deps);
+    });
+    program
+        .command('show')
+        .description('Print the persisted workflow mapping for a project.')
+        .option('-p, --project <project>', 'Jira project key or GitHub repo slug. Shows all cached mappings if omitted.')
+        .option('--roles-only', 'Print only the semantic_roles block.')
+        .option('--json', 'Emit raw JSON instead of styled output.')
+        .action((opts) => {
+        showCmd(opts, deps);
+    });
+    program
+        .command('init')
+        .description('Create a minimal workflow mapping for a project without running discovery.')
+        .requiredOption('-p, --project <project>', 'Jira project key (e.g. ACME).')
+        .requiredOption('--qa-passed <status>', 'Exact Jira status name that means QA passed.')
+        .option('--in-qa <status>', "Exact Jira status name for 'in QA'. Optional.")
+        .option('--atlassian-url <url>', 'Jira base URL for this project.')
+        .option('--force', 'Overwrite an existing mapping file.')
+        .action((opts) => {
+        initCmd(opts, deps);
+    });
+    for (const sub of program.commands) {
+        sub.exitOverride(normalizeUsageExit);
+    }
+    return program;
+}
+//# sourceMappingURL=workflow-cli.js.map

package/dist/engine-checks.d.ts

@@ -0,0 +1,49 @@
+import type { CheckResult } from './doctor.js';
+import { type GitRunner } from './overlay-commands.js';
+import { type CommandProbe } from './skill-requirements.js';
+export interface EngineCheckDeps {
+    git?: GitRunner;
+    homeDir?: string;
+    /** Project directory scanned for `.canary/` config and `.mcp.json`. */
+    cwd?: string;
+    /** Current CLI version; defaults to reading the package's own package.json. */
+    currentVersion?: string;
+    /** Latest published version, or null when unknown/offline. Injectable. */
+    getLatestVersion?: () => Promise<string | null>;
+    timeoutMs?: number;
+    /** Probe a command's presence + version (#336). Injectable for tests. */
+    skillProbe?: CommandProbe;
+}
+/** String `version` from a registry body; null on parse error or non-string shape (SEC-DES-001: registry JSON is untrusted). */
+export declare function parseRegistryVersion(rawBody: string): string | null;
+/** True when semver `a` is strictly older than `b` (numeric compare, no prerelease). */
+export declare function isOlder(a: string, b: string): boolean;
+/** CLI version vs latest release. Offline degrades to info, never a failure. */
+export declare function checkVersion(deps?: EngineCheckDeps): Promise<CheckResult>;
+/** git present on PATH. */
+export declare function checkGit(deps?: EngineCheckDeps): CheckResult;
+/** Registered overlays present, fresh, and free of local modifications. */
+export declare function checkOverlays(deps?: EngineCheckDeps): CheckResult[];
+/** Project `.canary/` config files parse as JSON. */
+export declare function checkProjectConfig(deps?: EngineCheckDeps): CheckResult;
+/** MCP config references resolvable — read project and home `.mcp.json` directly. */
+export declare function checkMcpConfig(deps?: EngineCheckDeps): CheckResult;
+/**
+ * Skill-name collisions across registered overlays are resolved by a declared
+ * precedence (#333). A collision with no precedence winner is a `fail` — which
+ * definition wins is otherwise accidental (directory-name order). No overlays
+ * or no collisions → an informational/passing line, never a false alarm.
+ */
+export declare function checkOverlayConflicts(deps?: EngineCheckDeps): CheckResult;
+/**
+ * Verify the runtime requirements declared by installed skills (#336). Reads
+ * `requires:` from each overlay/global/local skill's SKILL.md and checks every
+ * declared command (and optional version) against the environment. A missing
+ * or too-old requirement is a `fail` naming the skill and command; a bare
+ * presence check that passes, or a token whose version cannot be read, never
+ * fails. No declarations at all → an informational line (not a false "all
+ * good"). Bundled skills ship inside the engine and are out of scope here.
+ */
+export declare function checkSkillRequirements(deps?: EngineCheckDeps): CheckResult;
+/** Run every engine check, in display order. */
+export declare function runEngineChecks(deps?: EngineCheckDeps): Promise<CheckResult[]>;

package/dist/overlay-commands.d.ts

@@ -0,0 +1,81 @@
+import * as registry from './overlays-registry.js';
+/** Result of running a git subcommand. */
+export interface GitResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+}
+/** Runs a git subcommand and captures status/stdout/stderr (never throws). */
+export type GitRunner = (args: string[], opts?: {
+    cwd?: string;
+}) => GitResult;
+/** Sink for command output — matches the write() slice of a WritableStream. */
+export interface Writer {
+    write(chunk: string): void;
+}
+export interface CommandDeps {
+    git?: GitRunner;
+    homeDir?: string;
+    out?: Writer;
+    err?: Writer;
+    /** ISO date stamp for new registry entries (injectable for tests). */
+    now?: () => string;
+    /** Interactive yes/no prompt for the `overlay add` consent gate (injectable). */
+    confirm?: (question: string) => boolean;
+}
+/** Best-effort classification of a failed `git clone`, for a useful remedy. */
+export declare function classifyCloneFailure(res: GitResult): string;
+/**
+ * `canary overlay add <source> [--ref <tag>]` — clone a tracked overlay into
+ * `~/.canary/overlays/<name>/` and register it. Returns a process exit code.
+ * Nothing is registered unless the clone succeeds.
+ */
+export declare function add(source: string, options?: {
+    ref?: string | null;
+}, deps?: CommandDeps): number;
+/** Count `.canary/skills/<name>/SKILL.md` entries in a clone. */
+export declare function skillCount(dest: string): number;
+/** Working-tree cleanliness of a clone. */
+export type CleanStatus = 'clean' | 'dirty' | 'unreadable';
+/**
+ * Whether a clone's working tree is clean, dirty (local modifications), or its
+ * git status is unreadable. Shared by `overlay update` (refuses on dirty) and
+ * the `doctor` engine check ("no local overlay modifications").
+ */
+export declare function workingTreeStatus(dest: string, git: GitRunner): CleanStatus;
+/**
+ * Freshness of a clone against its LOCAL knowledge of the upstream — no fetch
+ * is performed (that is `overlay update`'s job). Returns a human-readable
+ * status string.
+ */
+export declare function freshness(dest: string, entry: registry.OverlayEntry, git: GitRunner): string;
+/**
+ * `canary overlay list` — one block per registered overlay: name, source, ref,
+ * freshness, and skill count.
+ */
+/** Options for {@link list}. */
+export interface ListOptions {
+    /** `--conflicts`: report skill-name collisions across overlays (#333). */
+    conflicts?: boolean;
+}
+export declare function list(deps?: CommandDeps, opts?: ListOptions): number;
+/** Options for {@link lint}. */
+export interface LintOptions {
+    json?: boolean;
+}
+/**
+ * `canary overlay lint <name|path>` (#332) — validate an overlay against the
+ * authoring contract. Exits 0 when there are no errors (warnings are advisory),
+ * 1 on any error or an unresolvable target.
+ */
+export declare function lint(nameOrPath: string | undefined, deps?: CommandDeps, opts?: LintOptions): number;
+/**
+ * `canary overlay update [name]` — fast-forward tracked overlays. With no name,
+ * updates all; refuses on local modifications or a non-fast-forward.
+ */
+export declare function update(name: string | null, deps?: CommandDeps): number;
+/**
+ * `canary overlay remove <name>` — deregister an overlay and delete its clone.
+ * Unknown name is an error; the registry is left unchanged in that case.
+ */
+export declare function remove(name: string, deps?: CommandDeps): number;