canary-test-cli 6.3.0 → 6.4.0

package/bin/canary-mcp.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+'use strict';
+
+// Console-script entry for `canary-mcp` (#507): starts the Canary MCP server
+// over stdio from the bundled TypeScript engine (dist/engine/mcp-server.js,
+// staged by scripts/build-engine.mjs). The engine bundle is ESM while this
+// package is CommonJS, so the server module is loaded via dynamic import().
+// stdout carries the JSON-RPC stream and must never be polluted -- every
+// failure path writes to stderr only.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { pathToFileURL } = require('node:url');
+
+/** Absolute path to the bundled engine's MCP server module. */
+function getServerPath() {
+  return path.join(__dirname, '..', 'dist', 'engine', 'mcp-server.js');
+}
+
+/**
+ * Start the server. Returns the exit code (0 when runStdio resolves, 1 when
+ * the bundle is missing). Dependencies are injectable for testing.
+ */
+async function main({
+  serverPath = getServerPath(),
+  existsSync = fs.existsSync,
+  stderr = process.stderr,
+} = {}) {
+  if (!existsSync(serverPath)) {
+    stderr.write(
+      `canary MCP server not found at ${serverPath}.\n` +
+        `The package looks incomplete; try reinstalling: npm install -g canary-test-cli\n`,
+    );
+    return 1;
+  }
+  const { runStdio } = await import(pathToFileURL(serverPath).href);
+  await runStdio();
+  return 0;
+}
+
+if (require.main === module) {
+  main()
+    .then((code) => {
+      if (code !== 0) process.exit(code);
+    })
+    .catch((err) => {
+      console.error(err);
+      process.exit(1);
+    });
+}
+
+module.exports = { getServerPath, main };

package/dist/engine/cli-commands.js

@@ -155,7 +155,7 @@ export function feedbackCmd(message, opts, deps) {
         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);
+    const fb = buildFeedback(message.trim(), opts.category, resolveVersion(deps));
     if (opts.json) {
         deps.out(jsonIndent2(fb));
         return;

package/dist/engine/core/feedback.js

@@ -12,10 +12,10 @@
  * never reads environment variables or file contents.
  *
  * Python→TS nuances:
- *   - **Context shape is a contract**: the four keys `{version, os, python,
- *     install}` (and their order) are preserved. The `python` value is the JS
- *     *runtime* version (`process.version`) — the Node analog of Python's
- *     `platform.python_version()`; the field name is kept for shape fidelity.
+ *   - The context keys are `{version, os, runtime, install}` (insertion order
+ *     preserved). `runtime` carries `process.version`; the key was named
+ *     `python` for golden-parity shape fidelity until #506 — in filed issues
+ *     it misled triage ("user on python v22?") once the Python engine retired.
  *   - `urlencode(...)` (which uses `quote_plus`, space -> `+`) maps to
  *     `URLSearchParams`, which also form-encodes with space -> `+` and preserves
  *     insertion order. Exotic-character percent-encoding can differ byte-for-byte
@@ -26,12 +26,6 @@ import { release, type } from 'node:os';
 /** The public issue tracker (from npm/package.json `repository`). */
 export const TRACKER_URL = 'https://github.com/bop-clocktower/canary';
 export const VALID_CATEGORIES = ['bug', 'ux', 'docs', 'idea'];
-function canaryVersion() {
-    // Python reads `importlib.metadata.version("canary-test-ai")`, falling back to
-    // "unknown". The TS pilot has no equivalent package-metadata lookup wired in,
-    // so we return the same best-effort "unknown" sentinel.
-    return 'unknown';
-}
 /** Best-effort install-method label — never fails, never inspects secrets. */
 function installMethod() {
     const exe = (process.execPath || '').toLowerCase();
@@ -45,23 +39,43 @@ function installMethod() {
  *
  * Deliberately excludes environment variables and file contents — only the
  * coarse runtime facts a maintainer needs to triage a CLI report.
+ *
+ * `version` comes from the caller (#506): this module is pure and cannot know
+ * which package it shipped in, but the CLI layer does (`deps.pkgVersion()`),
+ * and the version is the single most useful triage field.
  */
-export function collectContext() {
+export function collectContext(version = 'unknown') {
     return {
-        version: canaryVersion(),
+        version,
         os: `${type()} ${release()}`.trim(),
-        python: process.version,
+        runtime: process.version,
         install: installMethod(),
     };
 }
+// Horizontal ellipsis, kept as an escape so this source stays ASCII.
+const ELLIPSIS = '\u{2026}';
+/**
+ * Cap the title at 60 code points (`Array.from` slices by code point, not
+ * UTF-16 unit, so astral chars do not truncate early). When the cap bites,
+ * break on the last word boundary inside the budget (falling back to a hard
+ * cut for an unbreakable token) and append an ellipsis so the truncation is
+ * visible instead of ending mid-word (#506).
+ */
+function truncateTitle(message) {
+    const points = Array.from(message);
+    if (points.length <= 60)
+        return message;
+    const hard = points.slice(0, 60).join('');
+    const lastBreak = hard.search(/\s+\S*$/);
+    const cut = lastBreak > 0 ? hard.slice(0, lastBreak) : hard;
+    return `${cut}${ELLIPSIS}`;
+}
 /**
  * A pre-filled GitHub 'new issue' URL: category in the title, message + context
  * in the body, category as a label. All parts are URL-encoded.
  */
 export function buildIssueUrl(category, message, context) {
-    // Python `message[:60]` slices by code point; JS `slice` slices by UTF-16
-    // unit, so an astral char would truncate the title early. Match the oracle.
-    const title = `[${category}] ${Array.from(message).slice(0, 60).join('')}`.trim();
+    const title = `[${category}] ${truncateTitle(message)}`.trim();
     const bodyLines = [
         message,
         '',
@@ -81,8 +95,8 @@ export function buildIssueUrl(category, message, context) {
     return `${TRACKER_URL}/issues/new?${query.toString()}`;
 }
 /** Bundle a report: message, category, context, and the pre-filled URL. */
-export function buildFeedback(message, category) {
-    const context = collectContext();
+export function buildFeedback(message, category, version = 'unknown') {
+    const context = collectContext(version);
     return {
         message,
         category,

package/dist/engine/core/gate-result.js

@@ -0,0 +1,73 @@
+/**
+ * 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).
+ */
+/**
+ * Reserved CLI-wide (D4): exit 3 always means "abstained -- verified zero
+ * items", distinct from 0 (clean), 1 (findings), 2 (surface-specific).
+ */
+export const 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. */
+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`.
+ */
+export 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' ? 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}`,
+    };
+}
+//# sourceMappingURL=gate-result.js.map

package/dist/engine/core/migrator.js

@@ -43,6 +43,7 @@ import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { readJsonWithWarning } from './config-validation.js';
 import { uncertainDetectionMessage } from './detection.js';
 import { FrameworkRegistry } from './framework-registry.js';
+import { EXIT_ABSTAINED, gateOutcome } from './gate-result.js';
 import { Scaffolder, scaffoldableFrameworks, TEMPLATES } from './scaffolder.js';
 import { SkillRegistry } from './skill-registry.js';
 // ---------------------------------------------------------------------------
@@ -594,8 +595,34 @@ export class FreshnessReport {
     get in_sync() {
         return !this.has_drift && !this.has_local_edits;
     }
-    /** 0 in sync, 1 drift, 2 local edits (safety refusal wins). */
+    /**
+     * The freshness gate as a {@link GateResult}: denominator = skills
+     * verified, findings = drift + local edits. Feeds the shared abstention
+     * helper (#508) so "verified zero skills" can never render as a pass.
+     */
+    gateResult() {
+        return {
+            checked: this.results.length,
+            findings: [...this.stale, ...this.local_edits],
+        };
+    }
+    /**
+     * A gate that verified zero skills has abstained, not passed (#503): the
+     * shape matched nothing, so nothing was checked and "in sync" would be a
+     * silent false pass -- the #456 class. Reported as its own exit code and
+     * flagged in every output surface. Delegates to the shared helper (#508).
+     */
+    get abstained() {
+        return gateOutcome(this.gateResult(), 'gate').abstained;
+    }
+    /**
+     * 0 in sync, 1 drift, 2 local edits (safety refusal wins), 3 abstained.
+     * The abstention path comes from the shared helper; the 1/2 mapping is
+     * this surface's own contract (local edits outrank drift).
+     */
     exit_code() {
+        if (this.abstained)
+            return EXIT_ABSTAINED;
         if (this.has_local_edits)
             return 2;
         if (this.has_drift)
@@ -609,6 +636,8 @@ export class FreshnessReport {
             in_sync: this.in_sync,
             has_drift: this.has_drift,
             has_local_edits: this.has_local_edits,
+            checked: this.results.length,
+            abstained: this.abstained,
             exit_code: this.exit_code(),
             skills: this.results.map((r) => ({
                 skill_name: r.skill_name,
@@ -628,6 +657,13 @@ export class FreshnessReport {
         ];
         if (this.results.length === 0) {
             lines.push("_No overlay skills match this project's shape._", '');
+            lines.push(`${WARN} **Abstained** ${EMDASH} the gate verified zero skills, so this is not a pass.`, '');
+            if (this.shape === 'unknown') {
+                lines.push('The shape could not be detected. Set `canary_shape` in', '`.canary/company.json` or pass `--framework <name>`.', '');
+            }
+            else {
+                lines.push(`The overlay ships no skills with \`deploy_to\` covering \`${this.shape}\`.`, "Check the overlay's `deploy_to` lists or the resolved `canary_shape`.", '');
+            }
             lines.push(...workflowMarkdown(this.workflows, false));
             return lines.join('\n');
         }
@@ -719,6 +755,17 @@ export class MigrationReport {
         this.installed_workflows = init.installed_workflows ?? [];
         this.config_warnings = init.config_warnings ?? [];
     }
+    /**
+     * The dry run's denominator (#504): config files that would be created,
+     * skills that would deploy, workflows that would install. Zero means the
+     * dry run has nothing to apply -- an advisory abstention, not a
+     * completed migration.
+     */
+    get would_migrate_count() {
+        return (this.would_create.length +
+            this.deployed_skills.filter((r) => r.status === 'dry_run').length +
+            this.installed_workflows.filter((r) => r.status === 'dry_run').length);
+    }
     to_markdown() {
         const lines = ['# Canary Migration Report', ''];
         if (this.dry_run) {
@@ -822,6 +869,28 @@ export class MigrationReport {
                 lines.push(`- ${item}`);
             lines.push('');
         }
+        else if (this.dry_run) {
+            // #504 abstention half: a dry run never completed anything. Zero
+            // pending work is an advisory abstention (D3) -- gateOutcome is the
+            // only summary-line path AND the only decision point (no local
+            // n === 0 arithmetic), so the refusal is structural.
+            const n = this.would_migrate_count;
+            const outcome = gateOutcome({ checked: n, findings: [] }, 'advisory', {
+                noun: 'item(s)',
+            });
+            lines.push('## Status', '');
+            if (outcome.abstained) {
+                lines.push(outcome.summaryLine, '', 'This dry run would migrate zero item(s) ' +
+                    EMDASH +
+                    ' the project already carries everything this migration would ' +
+                    'produce. If you expected changes, check `--from <overlay>` and ' +
+                    'the detected framework/shape above.', '');
+            }
+            else {
+                lines.push(`Dry run ${EMDASH} would migrate ${n} item(s). ` +
+                    'Re-run with `--apply` to write them.', '');
+            }
+        }
         else {
             lines.push('## Status', '', 'Migration complete. Run `canary recommend "<test description>"` to verify framework detection.', '');
         }
@@ -1260,19 +1329,23 @@ export class HarnessMigrator {
         this.installWorkflows(shape, overlayPath, projectRoot, true, false));
     }
     detectFramework(root, config) {
-        // 0. Explicit override in .canary/company.json ("canary_shape" field).
+        // Explicit override in .canary/company.json ("canary_shape" field) is
+        // user intent: it wins over every probe tier's shape, including a total
+        // probe miss (#502 — monorepos often have no root framework config).
+        // Framework detection still runs so framework-dependent behavior keeps
+        // working when a probe does match.
         const rawShape = config['canary_shape'];
         const explicitShape = (rawShape == null ? '' : String(rawShape))
             .trim()
             .toLowerCase();
-        if (explicitShape) {
-            for (const [filename, framework, , confidence] of _CONFIG_PROBES) {
-                if (existsSync(join(root, filename))) {
-                    return [framework, explicitShape, filename, confidence];
-                }
-            }
-            // Fall through to content probes.
-        }
+        const [framework, shape, source, confidence] = this.probeFramework(root, config);
+        if (!explicitShape)
+            return [framework, shape, source, confidence];
+        return framework === null
+            ? [null, explicitShape, 'canary_shape (.canary/company.json)', 'explicit']
+            : [framework, explicitShape, source, confidence];
+    }
+    probeFramework(root, config) {
         // 1. Dedicated config file (highest confidence).
         for (const [filename, framework, shape, confidence] of _CONFIG_PROBES) {
             if (existsSync(join(root, filename))) {

package/dist/engine/core/skill-registry.js

@@ -339,7 +339,7 @@ export class SkillRegistry {
         catch {
             return null;
         }
-        const fm = SkillRegistry.parseFrontmatter(text);
+        const { frontmatter: fm, errors } = SkillRegistry.parseFrontmatterWithDiagnostics(text);
         const stem = basename(path, extname(path));
         const name = pyTruthy(fm['name']) ? fm['name'] : stem;
         return new SkillInfo({
@@ -351,7 +351,7 @@ export class SkillRegistry {
             entry: SkillRegistry.scalar(fm['entry']),
             deploy_to: SkillRegistry.parseDeployTo(fm),
             requires: SkillRegistry.parseStrList(fm, 'requires'),
-            error: SkillRegistry.validateExecutableFields(fm),
+            error: SkillRegistry.discoveryError(fm, errors),
         });
     }
     // Public (Python `_parse_nested` is underscore-private but used cross-module):
@@ -365,7 +365,7 @@ export class SkillRegistry {
         catch {
             return null;
         }
-        const fm = SkillRegistry.parseFrontmatter(text);
+        const { frontmatter: fm, errors } = SkillRegistry.parseFrontmatterWithDiagnostics(text);
         const name = pyTruthy(fm['name']) ? fm['name'] : dirName;
         // Python: `fm.get("description") or self._blockquote_tagline(text)`.
         const description = pyTruthy(fm['description'])
@@ -380,7 +380,7 @@ export class SkillRegistry {
             entry: SkillRegistry.scalar(fm['entry']),
             deploy_to: SkillRegistry.parseDeployTo(fm),
             requires: SkillRegistry.parseStrList(fm, 'requires'),
-            error: SkillRegistry.validateExecutableFields(fm),
+            error: SkillRegistry.discoveryError(fm, errors),
         });
     }
     /** Python `dict.get(key, default)`: default only on a missing key. */
@@ -408,39 +408,104 @@ export class SkillRegistry {
         return [];
     }
     /**
-     * Tiny YAML-subset parser: top-level scalar and flow-list fields between `---`
-     * delimiters. No nesting, no block sequences, no quoting. Python:
-     * `_parse_frontmatter`.
+     * Tiny YAML-subset parser: top-level scalar and list fields between `---`
+     * delimiters. Convenience wrapper over
+     * {@link parseFrontmatterWithDiagnostics} that drops the diagnostics.
      */
     static parseFrontmatter(text) {
-        const result = {};
+        return SkillRegistry.parseFrontmatterWithDiagnostics(text).frontmatter;
+    }
+    /**
+     * YAML-subset parser with parse diagnostics (#501). The historical
+     * one-line-per-key subset read formatter-emitted YAML — wrapped flow lists,
+     * block sequences, indented scalar continuations — as silently EMPTY, so
+     * `migrate` skipped declared `deploy_to`/`install_workflows` entries while
+     * everything stayed green. Those shapes now parse, and a list-shaped value
+     * that still cannot be read (an unterminated `[`) is a recorded error,
+     * never a silent empty list. Still a deliberate subset: no nested mappings,
+     * no quoting, and top-level lines without a colon are skipped (pinned).
+     * Mirrored by npm/src/skill-frontmatter.ts for `overlay lint` — keep in sync.
+     */
+    static parseFrontmatterWithDiagnostics(text) {
+        const frontmatter = {};
+        const errors = [];
         if (!text.startsWith('---'))
-            return result;
-        const lines = text.split('\n');
-        for (let i = 1; i < lines.length; i++) {
-            const line = lines[i];
-            if (line.trim() === '---')
-                break;
-            if (!line || line.replace(/^\s+/, '').startsWith('#'))
-                continue;
-            if (!line.includes(':'))
-                continue;
+            return { frontmatter, errors };
+        const rest = text.split('\n').slice(1);
+        const end = rest.findIndex((l) => l.trim() === '---');
+        const body = (end === -1 ? rest : rest.slice(0, end)).filter((l) => !l.trim().startsWith('#'));
+        let i = 0;
+        while (i < body.length) {
+            const line = body[i];
             const idx = line.indexOf(':'); // Python str.partition -> first colon.
-            const key = line.slice(0, idx);
-            const value = line.slice(idx + 1);
-            const v = value.trim();
-            if (v.startsWith('[') && v.endsWith(']')) {
-                const inner = v.slice(1, -1);
-                result[key.trim()] = inner
-                    .split(',')
-                    .map((item) => item.trim())
-                    .filter((item) => item);
+            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++;
             }
-            else {
-                result[key.trim()] = v;
+            SkillRegistry.assignFrontmatterValue(frontmatter, errors, line.slice(0, idx).trim(), line.slice(idx + 1).trim(), cont);
+        }
+        return { frontmatter, errors };
+    }
+    /**
+     * Assign one entry from its inline value plus indented continuations: flow
+     * lists (inline, wrapped mid-list, or entirely on a continuation line —
+     * prettier's rewrite), block sequences, and folded plain scalars.
+     */
+    static assignFrontmatterValue(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 = SkillRegistry.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();
+        }
+    }
+    /** Block-sequence items; a dash-less line folds into the item above it. */
+    static 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);
+    }
+    /**
+     * Frontmatter parse diagnostics + executable-field validation combined into
+     * the `SkillInfo.error` channel; parse errors win (#501: loud, never silent).
+     */
+    static discoveryError(fm, parseErrors) {
+        if (parseErrors.length > 0) {
+            return `frontmatter parse error: ${parseErrors.join('; ')}`;
         }
-        return result;
+        return SkillRegistry.validateExecutableFields(fm);
     }
     /** Return an error string if the cli/entry combination is invalid. */
     static validateExecutableFields(fm) {

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.4.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": {
@@ -36,6 +37,7 @@
   },
   "files": [
     "bin/canary.js",
+    "bin/canary-mcp.js",
     "dist/"
   ],
   "dependencies": {