canary-test-cli 6.3.0 → 6.5.0

package/dist/gate-result.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared gate-abstention helper (issue #508, no-silent-abstention spec).
+ *
+ * Doctrine: a check that verified zero items has ABSTAINED, not passed.
+ * Every gate reports its denominator (`checked`); zero is a distinct loud
+ * outcome. "Skipped" renders in every summary line and never aggregates
+ * into "passed" (D7).
+ *
+ * `gateOutcome` is the only path to a summary line for swept commands, so
+ * the refusal to print bare success on a zero denominator is structural.
+ * Surfaces append their own remediation text (why the denominator
+ * collapsed, first fix step) after the summary line.
+ *
+ * Output glyphs are written as `\u{...}` escapes so this source stays
+ * ASCII while the emitted bytes match the rest of the CLI (warning sign
+ * U+26A0, em dash U+2014).
+ */
+/** A check that was not run, and why. Always visible, never "passed". */
+export interface SkipEntry {
+    name: string;
+    reason: string;
+}
+/** What a gate actually verified: its denominator and what it found. */
+export interface GateResult<F> {
+    /** How many items were actually verified. Skipped items do NOT count. */
+    checked: number;
+    findings: F[];
+    skipped?: SkipEntry[];
+}
+/**
+ * Reserved CLI-wide (D4): exit 3 always means "abstained -- verified zero
+ * items", distinct from 0 (clean), 1 (findings), 2 (surface-specific).
+ */
+export declare const EXIT_ABSTAINED = 3;
+/**
+ * D3: a "gate" has an exit-code contract and fails loud (exit 3) on a zero
+ * denominator; an "advisory" command warns unmissably but exits 0 -- an
+ * empty answer honestly labeled is not an error.
+ */
+export type GateKind = 'gate' | 'advisory';
+export interface GateOutcome {
+    exitCode: number;
+    abstained: boolean;
+    summaryLine: string;
+}
+/** Copy hooks: surfaces adapt wording without re-owning the decision. */
+export interface GateOutcomeOptions {
+    /** Unit noun for the clean-pass line. Default: `'check(s)'`. */
+    noun?: string;
+}
+/**
+ * D7: skipped entries render in EVERY summary line.
+ *
+ * Exported so a surface with its own failure vocabulary (doctor says
+ * "check(s) failed", not "finding(s)") can render the identical skip suffix
+ * instead of re-deriving the format -- the decision still comes from
+ * {@link gateOutcome}, only the noun differs.
+ */
+export declare function skippedSuffix(skipped?: SkipEntry[]): string;
+/**
+ * The single summary-line/exit-code path for swept commands.
+ *
+ * Non-abstained exit codes are helper defaults (findings -> 1 for gates);
+ * surfaces with richer contracts (e.g. freshness 2 = local edits) apply
+ * their own mapping AFTER checking `abstained`.
+ */
+export declare function gateOutcome<F>(result: GateResult<F>, kind: GateKind, opts?: GateOutcomeOptions): GateOutcome;

package/dist/gate-result.js

@@ -0,0 +1,73 @@
+"use strict";
+// GENERATED FILE — DO NOT EDIT.
+// Verbatim copy of ts/src/core/gate-result.ts, mirrored into this CommonJS
+// package by scripts/sync-gate-result.mjs because the staged engine bundle is
+// ESM and unavailable at test time. Edit the engine source and re-run:
+//   node scripts/sync-gate-result.mjs
+// `npm test` verifies this copy has not drifted (--check runs as pretest).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXIT_ABSTAINED = void 0;
+exports.skippedSuffix = skippedSuffix;
+exports.gateOutcome = gateOutcome;
+/**
+ * Reserved CLI-wide (D4): exit 3 always means "abstained -- verified zero
+ * items", distinct from 0 (clean), 1 (findings), 2 (surface-specific).
+ */
+exports.EXIT_ABSTAINED = 3;
+const WARN = '\u{26A0}'; // warning sign
+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;
+/**
+ * D7: skipped entries render in EVERY summary line.
+ *
+ * Exported so a surface with its own failure vocabulary (doctor says
+ * "check(s) failed", not "finding(s)") can render the identical skip suffix
+ * instead of re-deriving the format -- the decision still comes from
+ * {@link gateOutcome}, only the noun differs.
+ */
+function skippedSuffix(skipped) {
+    if (!skipped || skipped.length === 0)
+        return '';
+    const names = skipped
+        .map((s) => s.name.replace(CONTROL_CHARS, ''))
+        .join(', ');
+    return ` (${skipped.length} skipped: ${names})`;
+}
+/**
+ * The single summary-line/exit-code path for swept commands.
+ *
+ * Non-abstained exit codes are helper defaults (findings -> 1 for gates);
+ * surfaces with richer contracts (e.g. freshness 2 = local edits) apply
+ * their own mapping AFTER checking `abstained`.
+ */
+function gateOutcome(result, kind, opts = {}) {
+    const noun = opts.noun ?? 'check(s)';
+    const suffix = skippedSuffix(result.skipped);
+    // Findings outrank abstention: a finding proves something was checked,
+    // so it must never be masked by a collapsed/invalid denominator.
+    if (result.findings.length > 0) {
+        return {
+            exitCode: kind === 'gate' ? 1 : 0,
+            abstained: false,
+            summaryLine: `${result.findings.length} finding(s) across ` +
+                `${result.checked} checked${suffix}`,
+        };
+    }
+    // Negated comparison so 0, negatives, and NaN all abstain: an invalid
+    // denominator must never render as success.
+    if (!(result.checked > 0)) {
+        return {
+            exitCode: kind === 'gate' ? exports.EXIT_ABSTAINED : 0,
+            abstained: true,
+            summaryLine: `${WARN} Abstained ${EMDASH} verified zero items; ` +
+                `this is not a pass.${suffix}`,
+        };
+    }
+    return {
+        exitCode: 0,
+        abstained: false,
+        summaryLine: `All ${result.checked} run ${noun} passed${suffix}`,
+    };
+}

package/dist/overlay-commands.js

@@ -51,6 +51,7 @@ const registry = __importStar(require("./overlays-registry.js"));
 const doctor_manifest_js_1 = require("./doctor-manifest.js");
 const overlay_conflicts_js_1 = require("./overlay-conflicts.js");
 const overlay_lint_js_1 = require("./overlay-lint.js");
+const gate_result_js_1 = require("./gate-result.js");
 const defaultGit = (args, opts = {}) => {
     const r = (0, node_child_process_1.spawnSync)('git', args, { cwd: opts.cwd, encoding: 'utf8' });
     if (r.error) {
@@ -373,12 +374,27 @@ function lint(nameOrPath, deps = {}, opts = {}) {
     }
     const result = (0, overlay_lint_js_1.lintOverlay)(dir);
     const errors = result.findings.filter((f) => f.level === 'error');
+    // #508: linting zero skills is an ABSENT verdict, not a clean bill of health.
+    // Advisory (D3) -- a workflows-only overlay is legitimate, so the exit stays
+    // 0 -- but the line is unmissable and `--json` says so. Findings outrank
+    // abstention inside `gateOutcome`, so a missing skills dir still exits 1.
+    const outcome = (0, gate_result_js_1.gateOutcome)({ checked: result.skillsChecked, findings: result.findings }, 'advisory');
     if (opts.json) {
-        out.write(`${JSON.stringify(result, null, 2)}\n`);
+        out.write(`${JSON.stringify({
+            ...result,
+            checked: result.skillsChecked,
+            abstained: outcome.abstained,
+        }, null, 2)}\n`);
         return errors.length === 0 ? 0 : 1;
     }
     const symbol = (f) => (f.level === 'error' ? '✗' : '⚠');
     out.write(`canary overlay lint: ${nameOrPath}\n`);
+    if (outcome.abstained) {
+        out.write(`\n${outcome.summaryLine}\n`);
+        out.write(`  No skill directories under ${dir}/.canary/skills, so nothing was ` +
+            `linted. Add a skill, or lint the overlay that actually ships them.\n`);
+        return 0;
+    }
     if (result.findings.length === 0) {
         out.write(`\n✓ ${result.skillsChecked} skill(s) — no issues.\n`);
         return 0;

package/dist/overlay-lint.d.ts

@@ -1,4 +1,9 @@
-/** Migration target shapes a `deploy_to` entry may name, plus the `all` sentinel. */
+/**
+ * The BUNDLED migration target shapes, plus the `all` sentinel. Not a closed
+ * set: `migrate` matches `deploy_to` against the consuming repo's resolved
+ * `canary_shape` by plain string comparison, so downstream overlays may use
+ * custom shapes. Lint warns (never errors) on a value outside this set (#501).
+ */
 export declare const VALID_DEPLOY_TARGETS: ReadonlySet<string>;
 export interface LintFinding {
     /** Skill name, or `(overlay)` for an overlay-level finding. */

package/dist/overlay-lint.js

@@ -43,8 +43,13 @@ exports.lintOverlay = lintOverlay;
  *
  * Checks (per skill under `<overlay>/.canary/skills/<name>/SKILL.md`):
  *   1. frontmatter floor — `name` and `description` present and non-empty
- *      (modeled on harness's `skill validate`);
- *   2. `deploy_to` values resolve to known migration targets;
+ *      (modeled on harness's `skill validate`), plus any frontmatter parse
+ *      diagnostic (e.g. an unterminated flow list) reported as an error —
+ *      a declared list must never silently read as empty (#501);
+ *   2. `deploy_to` values that are not bundled migration targets are a
+ *      WARNING, not an error — shapes are extensible and `migrate` matches
+ *      `deploy_to` against the consuming repo's resolved `canary_shape` by
+ *      plain string comparison, so a custom shape is legitimate (#501);
  *   3. `cli:` script paths exist inside the skill dir (no escape);
  * plus one overlay-level check:
  *   4. `.canary/doctor.json` (if present) passes manifest validation — reuses
@@ -53,7 +58,13 @@ exports.lintOverlay = lintOverlay;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const doctor_manifest_js_1 = require("./doctor-manifest.js");
-/** Migration target shapes a `deploy_to` entry may name, plus the `all` sentinel. */
+const skill_frontmatter_js_1 = require("./skill-frontmatter.js");
+/**
+ * The BUNDLED migration target shapes, plus the `all` sentinel. Not a closed
+ * set: `migrate` matches `deploy_to` against the consuming repo's resolved
+ * `canary_shape` by plain string comparison, so downstream overlays may use
+ * custom shapes. Lint warns (never errors) on a value outside this set (#501).
+ */
 exports.VALID_DEPLOY_TARGETS = new Set([
     'api',
     'e2e_ui',
@@ -62,40 +73,6 @@ exports.VALID_DEPLOY_TARGETS = new Set([
     'performance',
     'all',
 ]);
-/** Parse the tiny-YAML subset canary uses (mirrors the Python loader). */
-function parseFrontmatter(md) {
-    const fm = {};
-    if (!md.startsWith('---'))
-        return fm;
-    for (const line of md.split('\n').slice(1)) {
-        if (line.trim() === '---')
-            break;
-        const idx = line.indexOf(':');
-        if (idx === -1)
-            continue;
-        const key = line.slice(0, idx).trim();
-        const value = line.slice(idx + 1).trim();
-        if (key === 'deploy_to') {
-            fm.deploy_to =
-                value.startsWith('[') && value.endsWith(']')
-                    ? value
-                        .slice(1, -1)
-                        .split(',')
-                        .map((s) => s.trim())
-                        .filter(Boolean)
-                    : value
-                        ? [value]
-                        : [];
-        }
-        else if (key === 'name' ||
-            key === 'description' ||
-            key === 'cli' ||
-            key === 'entry') {
-            fm[key] = value;
-        }
-    }
-    return fm;
-}
 /** True when `cli` resolves to a real file inside `skillDir` (no escape). */
 function cliFinding(skill, skillDir, cli) {
     const resolvedDir = path.resolve(skillDir);
@@ -116,45 +93,53 @@ function cliFinding(skill, skillDir, cli) {
     }
     return null;
 }
+/**
+ * Checks 0–2: parse diagnostics (a declared-but-unreadable list is a loud
+ * error, never a silent empty), the name/description floor, and deploy_to
+ * values — unknown targets warn, since shapes are extensible (#501).
+ */
+function frontmatterFindings(skill, fm, parseErrors) {
+    const findings = parseErrors.map((m) => ({
+        skill,
+        level: 'error',
+        message: `frontmatter parse error: ${m}`,
+    }));
+    for (const field of ['name', 'description']) {
+        if (!(0, skill_frontmatter_js_1.scalarField)(fm, field)) {
+            findings.push({
+                skill,
+                level: 'error',
+                message: field === 'name'
+                    ? 'frontmatter is missing `name`'
+                    : 'frontmatter is missing a non-empty `description`',
+            });
+        }
+    }
+    for (const target of (0, skill_frontmatter_js_1.listField)(fm, 'deploy_to')) {
+        if (!exports.VALID_DEPLOY_TARGETS.has(target)) {
+            findings.push({
+                skill,
+                level: 'warning',
+                message: `deploy_to value "${target}" is not a bundled target (${[...exports.VALID_DEPLOY_TARGETS].join(', ')}); fine if it matches a consuming repo's custom canary_shape, otherwise a typo`,
+            });
+        }
+    }
+    return findings;
+}
 function lintSkill(name, skillDir) {
-    const findings = [];
-    const mdPath = path.join(skillDir, 'SKILL.md');
     let text;
     try {
-        text = fs.readFileSync(mdPath, 'utf8');
+        text = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8');
     }
     catch {
         return [{ skill: name, level: 'error', message: 'SKILL.md is unreadable' }];
     }
-    const fm = parseFrontmatter(text);
-    // 1. Frontmatter floor.
-    if (!fm.name) {
-        findings.push({
-            skill: name,
-            level: 'error',
-            message: 'frontmatter is missing `name`',
-        });
-    }
-    if (!fm.description) {
-        findings.push({
-            skill: name,
-            level: 'error',
-            message: 'frontmatter is missing a non-empty `description`',
-        });
-    }
-    // 2. deploy_to targets.
-    for (const target of fm.deploy_to ?? []) {
-        if (!exports.VALID_DEPLOY_TARGETS.has(target)) {
-            findings.push({
-                skill: name,
-                level: 'error',
-                message: `deploy_to value "${target}" is not a known target (${[...exports.VALID_DEPLOY_TARGETS].join(', ')})`,
-            });
-        }
-    }
+    const { frontmatter: fm, errors } = (0, skill_frontmatter_js_1.parseFrontmatter)(text);
+    const findings = frontmatterFindings(name, fm, errors);
     // 3. cli path (entry is a module ref, not a filesystem path — not checked here).
-    if (fm.cli) {
-        const f = cliFinding(name, skillDir, fm.cli);
+    const cli = (0, skill_frontmatter_js_1.scalarField)(fm, 'cli');
+    if (cli) {
+        const f = cliFinding(name, skillDir, cli);
         if (f)
             findings.push(f);
     }

package/dist/skill-frontmatter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * SKILL.md frontmatter parsing for `canary overlay lint` (#501). Mirror of
+ * the engine's `SkillRegistry.parseFrontmatterWithDiagnostics`
+ * (ts/src/core/skill-registry.ts) — keep in sync — so lint and `canary
+ * migrate` never disagree on what a SKILL.md declares. The packages compile
+ * separately (CJS here, ESM engine), so the rules are mirrored, not imported;
+ * parity is pinned by equivalent fixtures in both test suites. Rules: flow
+ * lists may wrap across indented lines, block sequences (`- item`) are read,
+ * indented continuations fold into the scalar above, and a list-shaped value
+ * that cannot be read (an unterminated `[`) is a recorded error — never a
+ * silent empty list.
+ */
+/** Parsed frontmatter entries: scalar strings or list values. */
+export type Frontmatter = Record<string, string | string[]>;
+export interface ParsedFrontmatter {
+    frontmatter: Frontmatter;
+    errors: string[];
+}
+/** Parse a SKILL.md's frontmatter, collecting diagnostics (never throws). */
+export declare function parseFrontmatter(md: string): ParsedFrontmatter;
+/** A scalar entry as `string | undefined` (list-valued entries are not scalars). */
+export declare function scalarField(fm: Frontmatter, key: string): string | undefined;
+/** An entry normalized to `string[]` (a bare scalar becomes a one-item list). */
+export declare function listField(fm: Frontmatter, key: string): string[];

package/dist/skill-frontmatter.js

@@ -0,0 +1,89 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFrontmatter = parseFrontmatter;
+exports.scalarField = scalarField;
+exports.listField = listField;
+/** Frontmatter body: comment-free lines between the `---` fences. */
+function frontmatterBody(md) {
+    const rest = md.split('\n').slice(1);
+    const end = rest.findIndex((l) => l.trim() === '---');
+    return (end === -1 ? rest : rest.slice(0, end)).filter((l) => !l.trim().startsWith('#'));
+}
+/** Block-sequence items; a dash-less line folds into the item above it. */
+function blockListItems(cont) {
+    const items = [];
+    for (const c of cont) {
+        if (c.startsWith('- '))
+            items.push(c.slice(2).trim());
+        else if (c !== '-' && items.length > 0)
+            items[items.length - 1] = `${items[items.length - 1]} ${c}`.trim();
+    }
+    return items.filter(Boolean);
+}
+/** Assign one entry from its inline value plus indented continuation lines. */
+function assignValue(fm, errors, key, inline, cont) {
+    const flow = inline.startsWith('[')
+        ? [inline, ...cont]
+        : inline === '' && cont[0]?.startsWith('[')
+            ? cont
+            : null;
+    if (flow !== null) {
+        const joined = flow.join(' ').trim();
+        if (!joined.endsWith(']')) {
+            errors.push(`\`${key}\`: unterminated flow list (no closing \`]\`): ${joined}`);
+            fm[key] = [];
+            return;
+        }
+        fm[key] = joined
+            .slice(1, -1)
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+    }
+    else if (inline === '' && /^-( |$)/.test(cont[0] ?? '')) {
+        const items = blockListItems(cont);
+        if (items.length === 0)
+            errors.push(`\`${key}\`: block list has no parseable items`);
+        fm[key] = items;
+    }
+    else {
+        // Scalar; indented continuation lines fold in (plain multiline YAML).
+        fm[key] = [inline, ...cont].join(' ').trim();
+    }
+}
+/** Parse a SKILL.md's frontmatter, collecting diagnostics (never throws). */
+function parseFrontmatter(md) {
+    const frontmatter = {};
+    const errors = [];
+    if (!md.startsWith('---'))
+        return { frontmatter, errors };
+    const body = frontmatterBody(md);
+    let i = 0;
+    while (i < body.length) {
+        const line = body[i];
+        const idx = line.indexOf(':'); // first colon, like the engine
+        i++;
+        // A line is a key only when top-level, non-blank, and colon-bearing.
+        if (!line.trim() || /^\s/.test(line) || idx === -1)
+            continue;
+        const cont = []; // indented continuation lines for this key
+        while (i < body.length && /^\s+\S/.test(body[i])) {
+            cont.push(body[i].trim());
+            i++;
+        }
+        assignValue(frontmatter, errors, line.slice(0, idx).trim(), line.slice(idx + 1).trim(), cont);
+    }
+    return { frontmatter, errors };
+}
+/** A scalar entry as `string | undefined` (list-valued entries are not scalars). */
+function scalarField(fm, key) {
+    const v = fm[key];
+    return typeof v === 'string' && v ? v : undefined;
+}
+/** An entry normalized to `string[]` (a bare scalar becomes a one-item list). */
+function listField(fm, key) {
+    const v = fm[key];
+    if (Array.isArray(v))
+        return v;
+    return typeof v === 'string' && v ? [v.trim()] : [];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canary-test-cli",
-  "version": "6.3.0",
+  "version": "6.5.0",
   "description": "Canary — AI-powered test automation agent",
   "license": "MIT",
   "repository": {
@@ -8,7 +8,8 @@
     "url": "https://github.com/bop-clocktower/canary.git"
   },
   "bin": {
-    "canary": "./bin/canary.js"
+    "canary": "./bin/canary.js",
+    "canary-mcp": "./bin/canary-mcp.js"
   },
   "exports": {
     "./reporter": {
@@ -29,6 +30,7 @@
   "scripts": {
     "build": "tsc && node scripts/build-engine.mjs",
     "prepare": "npm run build",
+    "pretest": "node scripts/sync-gate-result.mjs --check",
     "test": "tsc && node --test \"scripts/__tests__/*.test.js\""
   },
   "engines": {
@@ -36,6 +38,7 @@
   },
   "files": [
     "bin/canary.js",
+    "bin/canary-mcp.js",
     "dist/"
   ],
   "dependencies": {