canary-test-cli 5.11.0 → 5.12.0

package/dist/overlay-commands.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);
@@ -39,6 +39,7 @@ exports.skillCount = skillCount;
 exports.workingTreeStatus = workingTreeStatus;
 exports.freshness = freshness;
 exports.list = list;
+exports.lint = lint;
 exports.update = update;
 exports.remove = remove;
 const node_child_process_1 = require("node:child_process");
@@ -48,13 +49,23 @@ const path = __importStar(require("node:path"));
 const source_spec_js_1 = require("./source-spec.js");
 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 defaultGit = (args, opts = {}) => {
-    const r = (0, node_child_process_1.spawnSync)("git", args, { cwd: opts.cwd, encoding: "utf8" });
+    const r = (0, node_child_process_1.spawnSync)('git', args, { cwd: opts.cwd, encoding: 'utf8' });
     if (r.error) {
         const code = r.error.code;
-        return { status: code === "ENOENT" ? 127 : 1, stdout: "", stderr: String(r.error.message) };
+        return {
+            status: code === 'ENOENT' ? 127 : 1,
+            stdout: '',
+            stderr: String(r.error.message),
+        };
     }
-    return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+    return {
+        status: r.status ?? 1,
+        stdout: r.stdout ?? '',
+        stderr: r.stderr ?? '',
+    };
 };
 function today() {
     return new Date().toISOString().slice(0, 10);
@@ -68,8 +79,8 @@ function defaultConfirm(question) {
     const buf = Buffer.alloc(256);
     try {
         const n = fs.readSync(0, buf, 0, buf.length, null);
-        const answer = buf.toString("utf8", 0, n).trim().toLowerCase();
-        return answer === "y" || answer === "yes";
+        const answer = buf.toString('utf8', 0, n).trim().toLowerCase();
+        return answer === 'y' || answer === 'yes';
     }
     catch {
         return false;
@@ -90,10 +101,10 @@ function collectConsent(dest, name, confirm, out) {
     if (hash === null) {
         return { consent: null, consentCommandsHash: null };
     }
-    const cmds = load.checks.filter((c) => c.type === "command-succeeds");
+    const cmds = load.checks.filter((c) => c.type === 'command-succeeds');
     out.write(`Overlay "${name}" ships ${cmds.length} command check(s) that 'canary doctor' can run:\n`);
     for (const c of cmds) {
-        out.write(`  - ${c.id}: ${(c.command ?? []).join(" ")}\n`);
+        out.write(`  - ${c.id}: ${(c.command ?? []).join(' ')}\n`);
     }
     const granted = confirm(`Allow 'canary doctor' to run these commands for "${name}"? [y/N] `);
     if (!granted) {
@@ -103,29 +114,43 @@ function collectConsent(dest, name, confirm, out) {
 }
 /** Ordered stderr-substring signatures for `git clone` failure classification. */
 const CLONE_FAILURE_SIGNATURES = [
-    { reason: "git not found on PATH", needles: ["enoent", "not found: git"] },
+    { reason: 'git not found on PATH', needles: ['enoent', 'not found: git'] },
+    {
+        reason: 'network unreachable',
+        needles: [
+            'could not resolve host',
+            'network is unreachable',
+            'failed to connect',
+            'timed out',
+        ],
+    },
     {
-        reason: "network unreachable",
-        needles: ["could not resolve host", "network is unreachable", "failed to connect", "timed out"],
+        reason: 'authentication denied',
+        needles: [
+            'authentication failed',
+            'permission denied',
+            'could not read username',
+            'access denied',
+            '403 forbidden',
+        ],
     },
     {
-        reason: "authentication denied",
-        needles: ["authentication failed", "permission denied", "could not read username", "access denied", "403 forbidden"],
+        reason: 'repository not found',
+        needles: ['repository not found', 'does not exist', 'not found'],
     },
-    { reason: "repository not found", needles: ["repository not found", "does not exist", "not found"] },
 ];
 /** Best-effort classification of a failed `git clone`, for a useful remedy. */
 function classifyCloneFailure(res) {
     const s = res.stderr.toLowerCase();
     if (res.status === 127) {
-        return "git not found on PATH";
+        return 'git not found on PATH';
     }
     for (const { reason, needles } of CLONE_FAILURE_SIGNATURES) {
         if (needles.some((needle) => s.includes(needle))) {
             return reason;
         }
     }
-    return "unknown error";
+    return 'unknown error';
 }
 /**
  * `canary overlay add <source> [--ref <tag>]` — clone a tracked overlay into
@@ -169,9 +194,9 @@ function add(source, options = {}, deps = {}) {
         return 1;
     }
     fs.mkdirSync(registry.overlaysDir(homeDir), { recursive: true });
-    const args = ["clone", "--quiet"];
+    const args = ['clone', '--quiet'];
     if (ref) {
-        args.push("--branch", ref);
+        args.push('--branch', ref);
     }
     args.push(parsed.cloneUrl, dest);
     const res = git(args);
@@ -179,7 +204,7 @@ function add(source, options = {}, deps = {}) {
         fs.rmSync(dest, { recursive: true, force: true }); // never leave a partial clone
         const reason = classifyCloneFailure(res);
         err.write(`canary overlay add: clone failed (${reason}).\n` +
-            (res.stderr.trim() ? `${res.stderr.trim()}\n` : "") +
+            (res.stderr.trim() ? `${res.stderr.trim()}\n` : '') +
             `Nothing was registered. Check the overlay's access docs and your git credentials.\n`);
         return 1;
     }
@@ -193,6 +218,9 @@ function add(source, options = {}, deps = {}) {
         addedDate: stamp(),
         consent,
         consentCommandsHash,
+        // Undeclared precedence (#333). Set a number in overlays.json to declare
+        // which overlay wins a skill-name collision; higher wins.
+        precedence: null,
     };
     try {
         registry.write(registry.add(reg, entry), homeDir);
@@ -202,12 +230,12 @@ function add(source, options = {}, deps = {}) {
         err.write(`canary overlay add: ${e.message}\n`);
         return 1;
     }
-    out.write(`Added overlay "${parsed.name}"${ref ? ` @ ${ref}` : ""} → ${dest}\n`);
+    out.write(`Added overlay "${parsed.name}"${ref ? ` @ ${ref}` : ''} → ${dest}\n`);
     return 0;
 }
 /** Count `.canary/skills/<name>/SKILL.md` entries in a clone. */
 function skillCount(dest) {
-    const skillsDir = path.join(dest, ".canary", "skills");
+    const skillsDir = path.join(dest, '.canary', 'skills');
     let entries;
     try {
         entries = fs.readdirSync(skillsDir, { withFileTypes: true });
@@ -215,7 +243,8 @@ function skillCount(dest) {
     catch {
         return 0;
     }
-    return entries.filter((d) => d.isDirectory() && fs.existsSync(path.join(skillsDir, d.name, "SKILL.md"))).length;
+    return entries.filter((d) => d.isDirectory() &&
+        fs.existsSync(path.join(skillsDir, d.name, 'SKILL.md'))).length;
 }
 /**
  * Whether a clone's working tree is clean, dirty (local modifications), or its
@@ -223,11 +252,11 @@ function skillCount(dest) {
  * the `doctor` engine check ("no local overlay modifications").
  */
 function workingTreeStatus(dest, git) {
-    const status = git(["status", "--porcelain"], { cwd: dest });
+    const status = git(['status', '--porcelain'], { cwd: dest });
     if (status.status !== 0) {
-        return "unreadable";
+        return 'unreadable';
     }
-    return status.stdout.trim() === "" ? "clean" : "dirty";
+    return status.stdout.trim() === '' ? 'clean' : 'dirty';
 }
 /**
  * Freshness of a clone against its LOCAL knowledge of the upstream — no fetch
@@ -238,22 +267,20 @@ function freshness(dest, entry, git) {
     if (!fs.existsSync(dest)) {
         return "missing — clone not found (run 'canary overlay update' or re-add)";
     }
-    const behind = git(["rev-list", "--count", "HEAD..@{u}"], { cwd: dest });
+    const behind = git(['rev-list', '--count', 'HEAD..@{u}'], { cwd: dest });
     if (behind.status !== 0) {
         // No upstream tracking ref — typically a pinned tag/detached HEAD.
-        return entry.ref ? `pinned @ ${entry.ref}` : "unknown (no upstream tracking ref)";
+        return entry.ref
+            ? `pinned @ ${entry.ref}`
+            : 'unknown (no upstream tracking ref)';
     }
     const n = Number.parseInt(behind.stdout.trim(), 10);
     if (!Number.isFinite(n) || n === 0) {
-        return "up to date";
+        return 'up to date';
     }
-    return `${n} commit${n === 1 ? "" : "s"} behind`;
+    return `${n} commit${n === 1 ? '' : 's'} behind`;
 }
-/**
- * `canary overlay list` — one block per registered overlay: name, source, ref,
- * freshness, and skill count.
- */
-function list(deps = {}) {
+function list(deps = {}, opts = {}) {
     const git = deps.git ?? defaultGit;
     const homeDir = deps.homeDir ?? os.homedir();
     const out = deps.out ?? process.stdout;
@@ -266,6 +293,9 @@ function list(deps = {}) {
         err.write(`canary overlay list: ${e.message}\n`);
         return 1;
     }
+    if (opts.conflicts) {
+        return listConflicts(reg, out);
+    }
     if (reg.overlays.length === 0) {
         out.write("No overlays added. Add one with 'canary overlay add <source>'.\n");
         return 0;
@@ -273,12 +303,93 @@ function list(deps = {}) {
     for (const o of reg.overlays) {
         out.write(`${o.name}\n`);
         out.write(`  source:  ${o.source}\n`);
-        out.write(`  ref:     ${o.ref ?? "(default branch)"}\n`);
+        out.write(`  ref:     ${o.ref ?? '(default branch)'}\n`);
         out.write(`  status:  ${freshness(o.path, o, git)}\n`);
         out.write(`  skills:  ${skillCount(o.path)}\n`);
     }
     return 0;
 }
+/**
+ * Print the skill-name conflict report (`overlay list --conflicts`, #333).
+ * Returns 0 when there are no *unresolved* conflicts, 1 when at least one skill
+ * name collides with no declared precedence winner — so the flag doubles as a
+ * scriptable gate.
+ */
+function listConflicts(reg, out) {
+    const conflicts = (0, overlay_conflicts_js_1.detectSkillConflicts)(reg);
+    if (conflicts.length === 0) {
+        out.write('No skill-name conflicts across registered overlays.\n');
+        return 0;
+    }
+    let unresolved = 0;
+    for (const c of conflicts) {
+        const sources = c.contenders
+            .map((ct) => `${ct.overlay} (precedence ${ct.precedence})`)
+            .join(', ');
+        if (c.resolved) {
+            out.write(`✓ ${c.skill}: ${sources}\n      → resolved: ${c.winner} wins\n`);
+        }
+        else {
+            unresolved += 1;
+            out.write(`✗ ${c.skill}: ${sources}\n      → UNRESOLVED (tie) — set a higher ` +
+                `precedence on the overlay you want to win in overlays.json\n`);
+        }
+    }
+    out.write(`\n${conflicts.length} conflict(s), ${unresolved} unresolved.\n`);
+    return unresolved === 0 ? 0 : 1;
+}
+/** Resolve an overlay `<name|path>` to a clone directory, or null if absent. */
+function resolveOverlayDir(nameOrPath, homeDir) {
+    // A value with a path separator, or `.`/`..`/a dot-relative form, is a path;
+    // a bare token is a tracked overlay name (mirrors agent/core/overlays.py's
+    // disambiguation, extended so the natural CI form `overlay lint .` works).
+    const looksLikePath = nameOrPath.includes('/') ||
+        nameOrPath.includes(path.sep) ||
+        nameOrPath === '.' ||
+        nameOrPath === '..' ||
+        nameOrPath.startsWith('.');
+    const dir = looksLikePath
+        ? path.resolve(nameOrPath)
+        : registry.clonePath(nameOrPath, homeDir);
+    return fs.existsSync(dir) ? dir : null;
+}
+/**
+ * `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.
+ */
+function lint(nameOrPath, deps = {}, opts = {}) {
+    const homeDir = deps.homeDir ?? os.homedir();
+    const out = deps.out ?? process.stdout;
+    const err = deps.err ?? process.stderr;
+    if (!nameOrPath) {
+        err.write('usage: canary overlay lint <name|path> [--json]\n');
+        return 1;
+    }
+    const dir = resolveOverlayDir(nameOrPath, homeDir);
+    if (dir === null) {
+        err.write(`canary overlay lint: no overlay found for "${nameOrPath}" (not a tracked name or an existing path).\n`);
+        return 1;
+    }
+    const result = (0, overlay_lint_js_1.lintOverlay)(dir);
+    const errors = result.findings.filter((f) => f.level === 'error');
+    if (opts.json) {
+        out.write(`${JSON.stringify(result, null, 2)}\n`);
+        return errors.length === 0 ? 0 : 1;
+    }
+    const symbol = (f) => (f.level === 'error' ? '✗' : '⚠');
+    out.write(`canary overlay lint: ${nameOrPath}\n`);
+    if (result.findings.length === 0) {
+        out.write(`\n✓ ${result.skillsChecked} skill(s) — no issues.\n`);
+        return 0;
+    }
+    for (const f of result.findings) {
+        out.write(`  ${symbol(f)} ${f.skill}: ${f.message}\n`);
+    }
+    const warnings = result.findings.length - errors.length;
+    out.write(`\n${result.skillsChecked} skill(s) checked — ${errors.length} error(s), ${warnings} warning(s).\n`);
+    return errors.length === 0 ? 0 : 1;
+}
 /** Update one overlay clone. Returns 0 on success, 1 on refusal/failure. */
 function updateOne(o, git, out, err) {
     if (!fs.existsSync(o.path)) {
@@ -286,23 +397,25 @@ function updateOne(o, git, out, err) {
         return 1;
     }
     const clean = workingTreeStatus(o.path, git);
-    if (clean === "unreadable") {
+    if (clean === 'unreadable') {
         err.write(`overlay "${o.name}": cannot read git status at ${o.path}.\n`);
         return 1;
     }
-    if (clean === "dirty") {
+    if (clean === 'dirty') {
         err.write(`overlay "${o.name}": local modifications in ${o.path} — refusing to update. ` +
             `Commit/stash them, or 'canary overlay remove ${o.name}' and re-add.\n`);
         return 1;
     }
     if (o.ref) {
         // Pinned to a tag/branch: fetch (incl. tags), then re-checkout the ref.
-        const fetch = git(["fetch", "--quiet", "--tags", "origin"], { cwd: o.path });
+        const fetch = git(['fetch', '--quiet', '--tags', 'origin'], {
+            cwd: o.path,
+        });
         if (fetch.status !== 0) {
             err.write(`overlay "${o.name}": fetch failed.\n${fetch.stderr.trim()}\n`);
             return 1;
         }
-        const co = git(["checkout", "--quiet", o.ref], { cwd: o.path });
+        const co = git(['checkout', '--quiet', o.ref], { cwd: o.path });
         if (co.status !== 0) {
             err.write(`overlay "${o.name}": checkout ${o.ref} failed.\n${co.stderr.trim()}\n`);
             return 1;
@@ -310,11 +423,11 @@ function updateOne(o, git, out, err) {
         out.write(`overlay "${o.name}": fetched, pinned @ ${o.ref}.\n`);
         return 0;
     }
-    const pull = git(["pull", "--ff-only", "--quiet"], { cwd: o.path });
+    const pull = git(['pull', '--ff-only', '--quiet'], { cwd: o.path });
     if (pull.status !== 0) {
         err.write(`overlay "${o.name}": cannot fast-forward ${o.path} ` +
             `(diverged or rewritten history) — 'canary overlay remove ${o.name}' and re-add.\n` +
-            (pull.stderr.trim() ? `${pull.stderr.trim()}\n` : ""));
+            (pull.stderr.trim() ? `${pull.stderr.trim()}\n` : ''));
         return 1;
     }
     out.write(`overlay "${o.name}": updated.\n`);
@@ -348,7 +461,7 @@ function update(name, deps = {}) {
     }
     else {
         if (reg.overlays.length === 0) {
-            out.write("No overlays to update.\n");
+            out.write('No overlays to update.\n');
             return 0;
         }
         targets = reg.overlays;

package/dist/overlay-conflicts.js

@@ -0,0 +1,121 @@
+'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.readOverlaySkillNames = readOverlaySkillNames;
+exports.detectSkillConflicts = detectSkillConflicts;
+/**
+ * Overlay skill-name conflict detection (#333).
+ *
+ * When two registered overlays ship a skill of the same name, which definition
+ * wins was previously undefined and undocumented. This module detects those
+ * collisions and decides — from each overlay's declared `precedence` — whether
+ * the winner is *declared* (resolved) or *accidental* (unresolved).
+ *
+ * Winner rule (must match the Python skill loader, `agent/core/skill_registry`):
+ * among the overlays contending for a skill name, the one with the highest
+ * `precedence` wins; a null/absent precedence counts as 0. The collision is
+ * only **resolved** when exactly one overlay holds that highest value —
+ * otherwise the winner is arbitrary (directory-name order) and `doctor` flags
+ * it so the operator declares a precedence.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** Effective precedence: null/absent is 0. */
+function effectivePrecedence(entry) {
+    return typeof entry.precedence === 'number' ? entry.precedence : 0;
+}
+/**
+ * Skill (directory) names an overlay ships, read from
+ * `<overlay>/.canary/skills/<name>/SKILL.md`. A missing or unreadable skills
+ * dir yields no names (never throws) — mirrors the Python loader's tolerance.
+ */
+function readOverlaySkillNames(entry) {
+    // A hand-edited overlays.json (which #333 invites, to add `precedence`) may
+    // carry an entry with no `path`. Tolerate it rather than throwing — the
+    // "never throws" contract must hold before path.join, not only around readdir.
+    if (typeof entry.path !== 'string' || entry.path === '')
+        return [];
+    const skillsDir = path.join(entry.path, '.canary', 'skills');
+    let dirents;
+    try {
+        dirents = fs.readdirSync(skillsDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const names = [];
+    for (const d of dirents) {
+        if (!d.isDirectory())
+            continue;
+        if (fs.existsSync(path.join(skillsDir, d.name, 'SKILL.md'))) {
+            names.push(d.name);
+        }
+    }
+    return names;
+}
+/**
+ * Detect skill-name collisions across the registered overlays. Returns one
+ * {@link SkillConflict} per skill name shipped by two or more overlays, sorted
+ * by skill name.
+ */
+function detectSkillConflicts(reg, deps = {}) {
+    const readSkillNames = deps.readSkillNames ?? readOverlaySkillNames;
+    // skill name -> contending overlays
+    const bySkill = new Map();
+    for (const entry of reg.overlays) {
+        const precedence = effectivePrecedence(entry);
+        for (const skill of readSkillNames(entry)) {
+            const list = bySkill.get(skill) ?? [];
+            list.push({ overlay: entry.name, precedence });
+            bySkill.set(skill, list);
+        }
+    }
+    const conflicts = [];
+    for (const [skill, contenders] of bySkill) {
+        if (contenders.length < 2)
+            continue;
+        const ordered = [...contenders].sort((a, b) => b.precedence - a.precedence || a.overlay.localeCompare(b.overlay));
+        const top = ordered[0].precedence;
+        const topHolders = ordered.filter((c) => c.precedence === top);
+        const resolved = topHolders.length === 1;
+        conflicts.push({
+            skill,
+            contenders: ordered,
+            winner: resolved ? topHolders[0].overlay : null,
+            resolved,
+        });
+    }
+    return conflicts.sort((a, b) => a.skill.localeCompare(b.skill));
+}