canary-test-cli 5.11.0 → 5.13.0

package/dist/overlay-lint.js

@@ -0,0 +1,211 @@
+'use strict';
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALID_DEPLOY_TARGETS = void 0;
+exports.lintOverlay = lintOverlay;
+/**
+ * `canary overlay lint` — validate an overlay against the authoring contract
+ * (#332). Overlay quality otherwise depends on each author's discipline;
+ * downstream audits found frontmatter chaos, dead `cli:` paths, and invalid
+ * doctor manifests that nothing caught mechanically.
+ *
+ * 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;
+ *   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
+ *      `loadManifest` so the lint and `canary doctor` never disagree.
+ */
+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. */
+exports.VALID_DEPLOY_TARGETS = new Set([
+    'api',
+    'e2e_ui',
+    'frontend_unit',
+    'load',
+    '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);
+    const target = path.resolve(resolvedDir, cli);
+    if (target !== resolvedDir && !target.startsWith(resolvedDir + path.sep)) {
+        return {
+            skill,
+            level: 'error',
+            message: `cli: path "${cli}" escapes the skill directory`,
+        };
+    }
+    if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {
+        return {
+            skill,
+            level: 'error',
+            message: `cli: path "${cli}" is missing (no file at ${path.relative(skillDir, target)})`,
+        };
+    }
+    return null;
+}
+function lintSkill(name, skillDir) {
+    const findings = [];
+    const mdPath = path.join(skillDir, 'SKILL.md');
+    let text;
+    try {
+        text = fs.readFileSync(mdPath, '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(', ')})`,
+            });
+        }
+    }
+    // 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);
+        if (f)
+            findings.push(f);
+    }
+    return findings;
+}
+/**
+ * Lint an overlay clone at `overlayPath`. Returns every finding; the caller
+ * decides how to render/exit. Never throws on a malformed overlay — a missing
+ * skills dir is itself an error finding.
+ */
+function lintOverlay(overlayPath) {
+    const findings = [];
+    const skillsDir = path.join(overlayPath, '.canary', 'skills');
+    let skillNames = [];
+    try {
+        skillNames = fs
+            .readdirSync(skillsDir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name)
+            .sort();
+    }
+    catch {
+        findings.push({
+            skill: '(overlay)',
+            level: 'error',
+            message: `no .canary/skills directory at ${skillsDir}`,
+        });
+    }
+    for (const name of skillNames) {
+        const skillDir = path.join(skillsDir, name);
+        if (!fs.existsSync(path.join(skillDir, 'SKILL.md'))) {
+            findings.push({
+                skill: name,
+                level: 'warning',
+                message: 'directory has no SKILL.md (not a skill)',
+            });
+            continue;
+        }
+        findings.push(...lintSkill(name, skillDir));
+    }
+    // 4. Overlay-level doctor.json validation (reuse loadManifest).
+    const manifestPath = path.join(overlayPath, '.canary', 'doctor.json');
+    if (fs.existsSync(manifestPath)) {
+        const load = (0, doctor_manifest_js_1.loadManifest)(overlayPath);
+        if (!load.ok) {
+            findings.push({
+                skill: '(overlay)',
+                level: 'error',
+                message: `.canary/doctor.json is invalid: ${load.failure.remedy ?? load.failure.label}`,
+            });
+        }
+    }
+    return { overlay: overlayPath, skillsChecked: skillNames.length, findings };
+}

package/dist/overlays-registry.js

@@ -1,4 +1,4 @@
-"use strict";
+'use strict';
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -62,18 +62,18 @@ exports.SCHEMA_VERSION = 1;
 class RegistryError extends Error {
     constructor(message) {
         super(message);
-        this.name = "RegistryError";
+        this.name = 'RegistryError';
     }
 }
 exports.RegistryError = RegistryError;
 function canaryHome(homeDir = os.homedir()) {
-    return path.join(homeDir, ".canary");
+    return path.join(homeDir, '.canary');
 }
 function registryPath(homeDir = os.homedir()) {
-    return path.join(canaryHome(homeDir), "overlays.json");
+    return path.join(canaryHome(homeDir), 'overlays.json');
 }
 function overlaysDir(homeDir = os.homedir()) {
-    return path.join(canaryHome(homeDir), "overlays");
+    return path.join(canaryHome(homeDir), 'overlays');
 }
 function clonePath(name, homeDir = os.homedir()) {
     return path.join(overlaysDir(homeDir), name);
@@ -90,10 +90,10 @@ function emptyRegistry() {
 function parseRegistryFile(file) {
     let raw;
     try {
-        raw = fs.readFileSync(file, "utf8");
+        raw = fs.readFileSync(file, 'utf8');
     }
     catch (err) {
-        if (err.code === "ENOENT") {
+        if (err.code === 'ENOENT') {
             return emptyRegistry();
         }
         throw new RegistryError(`cannot read ${file}: ${err.message}`);
@@ -106,19 +106,28 @@ function parseRegistryFile(file) {
         throw new RegistryError(`malformed ${file}: ${err.message}`);
     }
     const overlays = parsed?.overlays;
-    if (typeof parsed !== "object" || parsed === null || !Array.isArray(overlays)) {
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        !Array.isArray(overlays)) {
         throw new RegistryError(`malformed ${file}: expected { schemaVersion, overlays: [] }`);
     }
     return parsed;
 }
 /** Normalize forward-added optional fields so callers never see `undefined`. */
 function normalizeEntry(o) {
-    return { ...o, consent: o.consent ?? null, consentCommandsHash: o.consentCommandsHash ?? null };
+    return {
+        ...o,
+        consent: o.consent ?? null,
+        consentCommandsHash: o.consentCommandsHash ?? null,
+        precedence: typeof o.precedence === 'number' ? o.precedence : null,
+    };
 }
 function read(homeDir = os.homedir()) {
     const reg = parseRegistryFile(registryPath(homeDir));
     return {
-        schemaVersion: typeof reg.schemaVersion === "number" ? reg.schemaVersion : exports.SCHEMA_VERSION,
+        schemaVersion: typeof reg.schemaVersion === 'number'
+            ? reg.schemaVersion
+            : exports.SCHEMA_VERSION,
         overlays: reg.overlays.map(normalizeEntry),
     };
 }
@@ -129,14 +138,16 @@ function read(homeDir = os.homedir()) {
  * mismatch) revokes consent until it is re-confirmed at `overlay add`.
  */
 function consentGranted(entry, liveHash) {
-    return entry.consent === true && liveHash !== null && entry.consentCommandsHash === liveHash;
+    return (entry.consent === true &&
+        liveHash !== null &&
+        entry.consentCommandsHash === liveHash);
 }
 /** Write the registry atomically (temp file + rename), creating `~/.canary`. */
 function write(registry, homeDir = os.homedir()) {
     fs.mkdirSync(canaryHome(homeDir), { recursive: true });
     const file = registryPath(homeDir);
     const tmp = `${file}.tmp`;
-    fs.writeFileSync(tmp, `${JSON.stringify(registry, null, 2)}\n`, "utf8");
+    fs.writeFileSync(tmp, `${JSON.stringify(registry, null, 2)}\n`, 'utf8');
     fs.renameSync(tmp, file);
 }
 function get(registry, name) {

package/dist/router.js

@@ -1,4 +1,4 @@
-"use strict";
+'use strict';
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -49,7 +49,7 @@ exports.route = route;
 const overlay = __importStar(require("./overlay-commands.js"));
 const doctor_js_1 = require("./doctor.js");
 /** Subcommands handled in TypeScript rather than forwarded to the binary. */
-exports.TS_COMMANDS = ["overlay", "doctor"];
+exports.TS_COMMANDS = ['overlay', 'doctor'];
 /** True when `argv` (process.argv.slice(2)) targets a TS-handled command. */
 function isTsCommand(argv) {
     return argv.length > 0 && exports.TS_COMMANDS.includes(argv[0]);
@@ -60,15 +60,15 @@ function parseArgs(args) {
     const flags = {};
     for (let i = 0; i < args.length; i += 1) {
         const a = args[i];
-        if (a.startsWith("--")) {
-            const eq = a.indexOf("=");
+        if (a.startsWith('--')) {
+            const eq = a.indexOf('=');
             if (eq !== -1) {
                 flags[a.slice(2, eq)] = a.slice(eq + 1);
             }
             else {
                 const key = a.slice(2);
                 const next = args[i + 1];
-                if (next !== undefined && !next.startsWith("--")) {
+                if (next !== undefined && !next.startsWith('--')) {
                     flags[key] = next;
                     i += 1;
                 }
@@ -85,26 +85,27 @@ function parseArgs(args) {
 }
 function refFrom(flags) {
     const ref = flags.ref;
-    return typeof ref === "string" ? ref : null;
+    return typeof ref === 'string' ? ref : null;
 }
-const OVERLAY_USAGE = "usage: canary overlay <add|list|update|remove> [args]\n" +
-    "  add <source> [--ref <tag>]   list   update [name]   remove <name>\n";
+const OVERLAY_USAGE = 'usage: canary overlay <add|list|lint|update|remove> [args]\n' +
+    '  add <source> [--ref <tag>]   list [--conflicts]   lint <name|path> [--json]   update [name]   remove <name>\n';
 /** Overlay subcommand handlers, keyed by name. Each returns a process exit code. */
 const OVERLAY_SUBCOMMANDS = {
     add: ({ positionals, flags, deps, err }) => {
         if (positionals.length < 1) {
-            err.write("usage: canary overlay add <source> [--ref <tag>] [--yes]\n");
+            err.write('usage: canary overlay add <source> [--ref <tag>] [--yes]\n');
             return 1;
         }
         // `--yes` grants command-check consent non-interactively (CI); default prompts.
         const addDeps = flags.yes === true ? { ...deps, confirm: () => true } : deps;
         return overlay.add(positionals[0], { ref: refFrom(flags) }, addDeps);
     },
-    list: ({ deps }) => overlay.list(deps),
+    list: ({ flags, deps }) => overlay.list(deps, { conflicts: flags.conflicts === true }),
+    lint: ({ positionals, flags, deps }) => overlay.lint(positionals[0], deps, { json: flags.json === true }),
     update: ({ positionals, deps }) => overlay.update(positionals[0] ?? null, deps),
     remove: ({ positionals, deps, err }) => {
         if (positionals.length < 1) {
-            err.write("usage: canary overlay remove <name>\n");
+            err.write('usage: canary overlay remove <name>\n');
             return 1;
         }
         return overlay.remove(positionals[0], deps);
@@ -114,7 +115,7 @@ function runOverlay(args, deps) {
     const err = deps.err ?? process.stderr;
     const handler = OVERLAY_SUBCOMMANDS[args[0]];
     if (!handler) {
-        err.write(`canary overlay: unknown subcommand ${args[0] ? `'${args[0]}'` : "(none)"}\n${OVERLAY_USAGE}`);
+        err.write(`canary overlay: unknown subcommand ${args[0] ? `'${args[0]}'` : '(none)'}\n${OVERLAY_USAGE}`);
         return 1;
     }
     const { positionals, flags } = parseArgs(args.slice(1));
@@ -130,10 +131,10 @@ function route(argv, deps = {}) {
     if (!isTsCommand(argv)) {
         return null;
     }
-    if (argv[0] === "overlay") {
+    if (argv[0] === 'overlay') {
         return runOverlay(argv.slice(1), deps);
     }
-    if (argv[0] === "doctor") {
+    if (argv[0] === 'doctor') {
         return (0, doctor_js_1.runDoctor)(argv.slice(1), deps);
     }
     return null;

package/dist/skill-requirements.js

@@ -0,0 +1,129 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRequirement = parseRequirement;
+exports.checkRequirement = checkRequirement;
+exports.parseRequiresField = parseRequiresField;
+const OP_RE = /^(.+?)\s*(>=|==|>)\s*([0-9][0-9.]*)\s*$/;
+const BARE_RE = /^[A-Za-z0-9._+-]+$/;
+/** Parse one requirement token into its command + optional version constraint. */
+function parseRequirement(token) {
+    const m = token.match(OP_RE);
+    if (m) {
+        return {
+            raw: token,
+            command: m[1].trim(),
+            op: m[2],
+            version: m[3],
+        };
+    }
+    const bare = token.trim();
+    if (BARE_RE.test(bare)) {
+        return { raw: token, command: bare, op: null, version: null };
+    }
+    return { raw: token, command: null, op: null, version: null };
+}
+/** Numeric tuple from a dotted version; non-numeric parts stop the parse. */
+function toParts(v) {
+    const parts = [];
+    for (const seg of v.split('.')) {
+        const n = Number.parseInt(seg, 10);
+        if (Number.isNaN(n))
+            break;
+        parts.push(n);
+    }
+    return parts;
+}
+/** Compare a against b over the length of `len` segments. -1 / 0 / 1. */
+function cmpParts(a, b, len) {
+    for (let i = 0; i < len; i += 1) {
+        const av = a[i] ?? 0;
+        const bv = b[i] ?? 0;
+        if (av !== bv)
+            return av < bv ? -1 : 1;
+    }
+    return 0;
+}
+/** Does `have` satisfy `op want`? Compares over the constraint's precision. */
+function satisfies(have, op, want) {
+    const h = toParts(have);
+    const w = toParts(want);
+    if (w.length === 0)
+        return true;
+    // `==` compares only the segments the constraint pins (1.22 matches 1.22.4).
+    const c = cmpParts(h, w, op === '==' ? w.length : Math.max(h.length, w.length));
+    if (op === '==')
+        return c === 0;
+    if (op === '>')
+        return c > 0;
+    return c >= 0; // '>='
+}
+/** Verify one requirement against a command probe. Never throws. */
+function checkRequirement(req, probe) {
+    if (req.command === null) {
+        return {
+            requirement: req,
+            status: 'unverifiable',
+            detail: `cannot parse requirement "${req.raw}"`,
+        };
+    }
+    const p = probe(req.command);
+    if (!p.present) {
+        return {
+            requirement: req,
+            status: 'missing',
+            detail: `${req.command} not found on PATH`,
+        };
+    }
+    if (req.version === null) {
+        return { requirement: req, status: 'ok', detail: `${req.command} present` };
+    }
+    if (p.version === null) {
+        return {
+            requirement: req,
+            status: 'unverifiable',
+            detail: `${req.command} present but its version could not be read`,
+        };
+    }
+    if (satisfies(p.version, req.op ?? '>=', req.version)) {
+        return {
+            requirement: req,
+            status: 'ok',
+            detail: `${req.command} ${p.version} satisfies ${req.op}${req.version}`,
+        };
+    }
+    return {
+        requirement: req,
+        status: 'too-old',
+        detail: `${req.command} ${p.version} does not satisfy ${req.op}${req.version}`,
+    };
+}
+/**
+ * Extract the `requires:` flow list from SKILL.md frontmatter — the same
+ * tiny-YAML subset the Python loader parses (`requires: [a, b]`). Returns []
+ * when absent or when there is no frontmatter. Block-sequence form is not
+ * supported (kept in lockstep with the Python parser).
+ */
+function parseRequiresField(md) {
+    if (!md.startsWith('---'))
+        return [];
+    const lines = md.split('\n');
+    for (const line of lines.slice(1)) {
+        if (line.trim() === '---')
+            break;
+        const idx = line.indexOf(':');
+        if (idx === -1)
+            continue;
+        if (line.slice(0, idx).trim() !== 'requires')
+            continue;
+        const value = line.slice(idx + 1).trim();
+        if (value.startsWith('[') && value.endsWith(']')) {
+            return value
+                .slice(1, -1)
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean);
+        }
+        return value ? [value] : [];
+    }
+    return [];
+}

package/dist/source-spec.js

@@ -1,4 +1,4 @@
-"use strict";
+'use strict';
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SourceSpecError = void 0;
 exports.parseSource = parseSource;
@@ -6,14 +6,14 @@ exports.parseSource = parseSource;
 class SourceSpecError extends Error {
     constructor(message) {
         super(message);
-        this.name = "SourceSpecError";
+        this.name = 'SourceSpecError';
     }
 }
 exports.SourceSpecError = SourceSpecError;
-const ACCEPTED_FORMS = "accepted forms: github:owner/repo, an https/git@ URL, or a local path";
+const ACCEPTED_FORMS = 'accepted forms: github:owner/repo, an https/git@ URL, or a local path';
 /** Strip a trailing `.git` and any trailing slashes from a path segment. */
 function stripRepoSuffix(segment) {
-    return segment.replace(/\.git$/i, "").replace(/\/+$/, "");
+    return segment.replace(/\.git$/i, '').replace(/\/+$/, '');
 }
 /** Sanitize a raw `owner/repo` pair into `owner-repo`, rejecting empties. */
 function nameFromOwnerRepo(owner, repo, raw) {
@@ -26,7 +26,7 @@ function nameFromOwnerRepo(owner, repo, raw) {
 }
 /** Extract the last two path segments (owner, repo) from a URL-ish path. */
 function lastTwoSegments(pathPart) {
-    const segments = pathPart.split("/").filter(Boolean);
+    const segments = pathPart.split('/').filter(Boolean);
     if (segments.length < 2) {
         return null;
     }
@@ -34,10 +34,10 @@ function lastTwoSegments(pathPart) {
 }
 /** github:owner/repo shorthand. Returns null when `spec` is not this form. */
 function parseGithubShorthand(spec, raw) {
-    if (!spec.startsWith("github:")) {
+    if (!spec.startsWith('github:')) {
         return null;
     }
-    const parts = spec.slice("github:".length).split("/").filter(Boolean);
+    const parts = spec.slice('github:'.length).split('/').filter(Boolean);
     if (parts.length !== 2) {
         throw new SourceSpecError(`"${raw}" is not github:owner/repo (${ACCEPTED_FORMS})`);
     }
@@ -79,10 +79,13 @@ function parseFullUrl(spec, raw) {
 }
 /** Local filesystem path (absolute, ./relative, ../relative, or ~-relative). */
 function parseLocalPath(spec, raw) {
-    if (!(spec.startsWith("/") || spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("~"))) {
+    if (!(spec.startsWith('/') ||
+        spec.startsWith('./') ||
+        spec.startsWith('../') ||
+        spec.startsWith('~'))) {
         return null;
     }
-    const basename = stripRepoSuffix(spec.split("/").filter(Boolean).pop() ?? "");
+    const basename = stripRepoSuffix(spec.split('/').filter(Boolean).pop() ?? '');
     if (!basename) {
         throw new SourceSpecError(`cannot derive a name from path "${raw}" (${ACCEPTED_FORMS})`);
     }
@@ -93,11 +96,16 @@ function parseLocalPath(spec, raw) {
  * {@link SourceSpecError} on anything that does not match an accepted form.
  */
 function parseSource(raw) {
-    const spec = (raw ?? "").trim();
+    const spec = (raw ?? '').trim();
     if (!spec) {
         throw new SourceSpecError(`empty source (${ACCEPTED_FORMS})`);
     }
-    for (const handler of [parseGithubShorthand, parseScpUrl, parseFullUrl, parseLocalPath]) {
+    for (const handler of [
+        parseGithubShorthand,
+        parseScpUrl,
+        parseFullUrl,
+        parseLocalPath,
+    ]) {
         const parsed = handler(spec, raw);
         if (parsed) {
             return parsed;

package/package.json

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