canary-test-cli 5.7.0 → 5.11.0

package/dist/overlay-commands.js

@@ -0,0 +1,390 @@
+"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.classifyCloneFailure = classifyCloneFailure;
+exports.add = add;
+exports.skillCount = skillCount;
+exports.workingTreeStatus = workingTreeStatus;
+exports.freshness = freshness;
+exports.list = list;
+exports.update = update;
+exports.remove = remove;
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+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 defaultGit = (args, opts = {}) => {
+    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: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+};
+function today() {
+    return new Date().toISOString().slice(0, 10);
+}
+/** Default consent prompt: reads a line from the TTY; declines when non-interactive. */
+function defaultConfirm(question) {
+    if (!process.stdin.isTTY) {
+        return false;
+    }
+    process.stdout.write(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";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Consent for an overlay's `command-succeeds` doctor checks, collected at add
+ * time. Overlays with no such checks (or a malformed manifest) record no
+ * consent (`null`) — there is nothing to gate, and a bad manifest surfaces
+ * later in `doctor`. Otherwise the check list is printed and confirmed.
+ */
+function collectConsent(dest, name, confirm, out) {
+    const load = (0, doctor_manifest_js_1.loadManifest)(dest);
+    if (!load.ok) {
+        return { consent: null, consentCommandsHash: null };
+    }
+    const hash = (0, doctor_manifest_js_1.commandSucceedsHash)(load.checks);
+    if (hash === null) {
+        return { consent: null, consentCommandsHash: null };
+    }
+    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`);
+    }
+    const granted = confirm(`Allow 'canary doctor' to run these commands for "${name}"? [y/N] `);
+    if (!granted) {
+        out.write("Declined — 'canary doctor' will skip these command checks. Re-add the overlay to change this.\n");
+    }
+    return { consent: granted, consentCommandsHash: hash };
+}
+/** 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: "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: "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";
+    }
+    for (const { reason, needles } of CLONE_FAILURE_SIGNATURES) {
+        if (needles.some((needle) => s.includes(needle))) {
+            return reason;
+        }
+    }
+    return "unknown error";
+}
+/**
+ * `canary overlay add <source> [--ref <tag>]` — clone a tracked overlay into
+ * `~/.canary/overlays/<name>/` and register it. Returns a process exit code.
+ * Nothing is registered unless the clone succeeds.
+ */
+function add(source, options = {}, deps = {}) {
+    const git = deps.git ?? defaultGit;
+    const homeDir = deps.homeDir ?? os.homedir();
+    const out = deps.out ?? process.stdout;
+    const err = deps.err ?? process.stderr;
+    const stamp = deps.now ?? today;
+    const ref = options.ref ?? null;
+    let parsed;
+    try {
+        parsed = (0, source_spec_js_1.parseSource)(source);
+    }
+    catch (e) {
+        if (e instanceof source_spec_js_1.SourceSpecError) {
+            err.write(`canary overlay add: ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+    let reg;
+    try {
+        reg = registry.read(homeDir);
+    }
+    catch (e) {
+        err.write(`canary overlay add: ${e.message}\n`);
+        return 1;
+    }
+    // Idempotent: re-adding a registered overlay is a no-op with an update hint.
+    if (registry.get(reg, parsed.name)) {
+        out.write(`overlay "${parsed.name}" is already added — run 'canary overlay update ${parsed.name}' to refresh it.\n`);
+        return 0;
+    }
+    const dest = registry.clonePath(parsed.name, homeDir);
+    if (fs.existsSync(dest)) {
+        err.write(`canary overlay add: ${dest} already exists but is not registered — remove it and retry.\n`);
+        return 1;
+    }
+    fs.mkdirSync(registry.overlaysDir(homeDir), { recursive: true });
+    const args = ["clone", "--quiet"];
+    if (ref) {
+        args.push("--branch", ref);
+    }
+    args.push(parsed.cloneUrl, dest);
+    const res = git(args);
+    if (res.status !== 0) {
+        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` : "") +
+            `Nothing was registered. Check the overlay's access docs and your git credentials.\n`);
+        return 1;
+    }
+    const confirm = deps.confirm ?? defaultConfirm;
+    const { consent, consentCommandsHash } = collectConsent(dest, parsed.name, confirm, out);
+    const entry = {
+        name: parsed.name,
+        source,
+        ref,
+        path: dest,
+        addedDate: stamp(),
+        consent,
+        consentCommandsHash,
+    };
+    try {
+        registry.write(registry.add(reg, entry), homeDir);
+    }
+    catch (e) {
+        fs.rmSync(dest, { recursive: true, force: true });
+        err.write(`canary overlay add: ${e.message}\n`);
+        return 1;
+    }
+    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");
+    let entries;
+    try {
+        entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    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
+ * git status is unreadable. Shared by `overlay update` (refuses on dirty) and
+ * the `doctor` engine check ("no local overlay modifications").
+ */
+function workingTreeStatus(dest, git) {
+    const status = git(["status", "--porcelain"], { cwd: dest });
+    if (status.status !== 0) {
+        return "unreadable";
+    }
+    return status.stdout.trim() === "" ? "clean" : "dirty";
+}
+/**
+ * Freshness of a clone against its LOCAL knowledge of the upstream — no fetch
+ * is performed (that is `overlay update`'s job). Returns a human-readable
+ * status string.
+ */
+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 });
+    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)";
+    }
+    const n = Number.parseInt(behind.stdout.trim(), 10);
+    if (!Number.isFinite(n) || n === 0) {
+        return "up to date";
+    }
+    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 = {}) {
+    const git = deps.git ?? defaultGit;
+    const homeDir = deps.homeDir ?? os.homedir();
+    const out = deps.out ?? process.stdout;
+    const err = deps.err ?? process.stderr;
+    let reg;
+    try {
+        reg = registry.read(homeDir);
+    }
+    catch (e) {
+        err.write(`canary overlay list: ${e.message}\n`);
+        return 1;
+    }
+    if (reg.overlays.length === 0) {
+        out.write("No overlays added. Add one with 'canary overlay add <source>'.\n");
+        return 0;
+    }
+    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(`  status:  ${freshness(o.path, o, git)}\n`);
+        out.write(`  skills:  ${skillCount(o.path)}\n`);
+    }
+    return 0;
+}
+/** Update one overlay clone. Returns 0 on success, 1 on refusal/failure. */
+function updateOne(o, git, out, err) {
+    if (!fs.existsSync(o.path)) {
+        err.write(`overlay "${o.name}": clone missing at ${o.path} — remove and re-add it.\n`);
+        return 1;
+    }
+    const clean = workingTreeStatus(o.path, git);
+    if (clean === "unreadable") {
+        err.write(`overlay "${o.name}": cannot read git status at ${o.path}.\n`);
+        return 1;
+    }
+    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 });
+        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 });
+        if (co.status !== 0) {
+            err.write(`overlay "${o.name}": checkout ${o.ref} failed.\n${co.stderr.trim()}\n`);
+            return 1;
+        }
+        out.write(`overlay "${o.name}": fetched, pinned @ ${o.ref}.\n`);
+        return 0;
+    }
+    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` : ""));
+        return 1;
+    }
+    out.write(`overlay "${o.name}": updated.\n`);
+    return 0;
+}
+/**
+ * `canary overlay update [name]` — fast-forward tracked overlays. With no name,
+ * updates all; refuses on local modifications or a non-fast-forward.
+ */
+function update(name, deps = {}) {
+    const git = deps.git ?? defaultGit;
+    const homeDir = deps.homeDir ?? os.homedir();
+    const out = deps.out ?? process.stdout;
+    const err = deps.err ?? process.stderr;
+    let reg;
+    try {
+        reg = registry.read(homeDir);
+    }
+    catch (e) {
+        err.write(`canary overlay update: ${e.message}\n`);
+        return 1;
+    }
+    let targets;
+    if (name) {
+        const entry = registry.get(reg, name);
+        if (!entry) {
+            err.write(`canary overlay update: no overlay named "${name}".\n`);
+            return 1;
+        }
+        targets = [entry];
+    }
+    else {
+        if (reg.overlays.length === 0) {
+            out.write("No overlays to update.\n");
+            return 0;
+        }
+        targets = reg.overlays;
+    }
+    let failures = 0;
+    for (const o of targets) {
+        if (updateOne(o, git, out, err) !== 0) {
+            failures += 1;
+        }
+    }
+    return failures === 0 ? 0 : 1;
+}
+/**
+ * `canary overlay remove <name>` — deregister an overlay and delete its clone.
+ * Unknown name is an error; the registry is left unchanged in that case.
+ */
+function remove(name, deps = {}) {
+    const homeDir = deps.homeDir ?? os.homedir();
+    const out = deps.out ?? process.stdout;
+    const err = deps.err ?? process.stderr;
+    let reg;
+    try {
+        reg = registry.read(homeDir);
+    }
+    catch (e) {
+        err.write(`canary overlay remove: ${e.message}\n`);
+        return 1;
+    }
+    const entry = registry.get(reg, name);
+    if (!entry) {
+        err.write(`canary overlay remove: no overlay named "${name}".\n`);
+        return 1;
+    }
+    fs.rmSync(entry.path, { recursive: true, force: true });
+    const { registry: next } = registry.remove(reg, name);
+    registry.write(next, homeDir);
+    out.write(`Removed overlay "${name}".\n`);
+    return 0;
+}

package/dist/overlays-registry.js

@@ -0,0 +1,162 @@
+"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.RegistryError = exports.SCHEMA_VERSION = void 0;
+exports.canaryHome = canaryHome;
+exports.registryPath = registryPath;
+exports.overlaysDir = overlaysDir;
+exports.clonePath = clonePath;
+exports.emptyRegistry = emptyRegistry;
+exports.read = read;
+exports.consentGranted = consentGranted;
+exports.write = write;
+exports.get = get;
+exports.list = list;
+exports.add = add;
+exports.remove = remove;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+/**
+ * Reader/writer for `~/.canary/overlays.json` — the tracked-overlay registry.
+ *
+ * Cross-runtime contract (spec Assumption): this file is written ONLY by the
+ * TS side. The Python skill loader never parses it; it directory-scans the
+ * `~/.canary/overlays/<name>/` clone dirs instead. So the schema here serves
+ * the `overlay` commands alone.
+ */
+exports.SCHEMA_VERSION = 1;
+/** Raised when the registry file exists but cannot be read or parsed. */
+class RegistryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RegistryError";
+    }
+}
+exports.RegistryError = RegistryError;
+function canaryHome(homeDir = os.homedir()) {
+    return path.join(homeDir, ".canary");
+}
+function registryPath(homeDir = os.homedir()) {
+    return path.join(canaryHome(homeDir), "overlays.json");
+}
+function overlaysDir(homeDir = os.homedir()) {
+    return path.join(canaryHome(homeDir), "overlays");
+}
+function clonePath(name, homeDir = os.homedir()) {
+    return path.join(overlaysDir(homeDir), name);
+}
+function emptyRegistry() {
+    return { schemaVersion: exports.SCHEMA_VERSION, overlays: [] };
+}
+/**
+ * Read the registry. A missing file is an empty registry (not an error); a
+ * present-but-unparseable file throws {@link RegistryError} so callers can
+ * report it rather than silently discarding overlays.
+ */
+/** Parse registry JSON, throwing a RegistryError on unreadable/malformed input. */
+function parseRegistryFile(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return emptyRegistry();
+        }
+        throw new RegistryError(`cannot read ${file}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new RegistryError(`malformed ${file}: ${err.message}`);
+    }
+    const overlays = parsed?.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 };
+}
+function read(homeDir = os.homedir()) {
+    const reg = parseRegistryFile(registryPath(homeDir));
+    return {
+        schemaVersion: typeof reg.schemaVersion === "number" ? reg.schemaVersion : exports.SCHEMA_VERSION,
+        overlays: reg.overlays.map(normalizeEntry),
+    };
+}
+/**
+ * Whether `command-succeeds` doctor checks may run for an overlay: consent must
+ * have been granted (`true`) AND still cover the live manifest's command set
+ * (`liveHash` matching the recorded fingerprint). A changed manifest (hash
+ * mismatch) revokes consent until it is re-confirmed at `overlay add`.
+ */
+function consentGranted(entry, 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.renameSync(tmp, file);
+}
+function get(registry, name) {
+    return registry.overlays.find((o) => o.name === name) ?? null;
+}
+function list(registry) {
+    return [...registry.overlays];
+}
+/** Add an entry. Throws if one with the same name is already registered. */
+function add(registry, entry) {
+    if (get(registry, entry.name)) {
+        throw new RegistryError(`overlay "${entry.name}" is already registered`);
+    }
+    return { ...registry, overlays: [...registry.overlays, entry] };
+}
+/** Remove an entry by name. Returns the new registry and whether it existed. */
+function remove(registry, name) {
+    const kept = registry.overlays.filter((o) => o.name !== name);
+    return {
+        registry: { ...registry, overlays: kept },
+        removed: kept.length !== registry.overlays.length,
+    };
+}

package/dist/router.js

@@ -0,0 +1,140 @@
+"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.TS_COMMANDS = void 0;
+exports.isTsCommand = isTsCommand;
+exports.route = route;
+/**
+ * Router for TS-handled `canary` subcommands — the strangler seam (Decision 10).
+ *
+ * The npm shim (`bin/canary.js`) forwards every command to the bundled Python
+ * binary except the ones handled here in TypeScript. Phase 1 wires `overlay`;
+ * `doctor` slots into the same table in Phase 2.
+ *
+ * `route()` returns a process exit code, or `null` when the command is not
+ * TS-handled and the shim should fall through to the Python binary.
+ */
+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"];
+/** 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]);
+}
+/** Minimal flag parser: `--k v`, `--k=v`, and boolean `--k`. */
+function parseArgs(args) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        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("--")) {
+                    flags[key] = next;
+                    i += 1;
+                }
+                else {
+                    flags[key] = true;
+                }
+            }
+        }
+        else {
+            positionals.push(a);
+        }
+    }
+    return { positionals, flags };
+}
+function refFrom(flags) {
+    const ref = flags.ref;
+    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";
+/** 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");
+            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),
+    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");
+            return 1;
+        }
+        return overlay.remove(positionals[0], deps);
+    },
+};
+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}`);
+        return 1;
+    }
+    const { positionals, flags } = parseArgs(args.slice(1));
+    return handler({ positionals, flags, deps, err });
+}
+/**
+ * Dispatch a TS-handled command. Returns the process exit code (or a Promise of
+ * one for async commands like `doctor`), or `null` when the command should fall
+ * through to the Python binary. `deps` is threaded to the command handlers for
+ * testing (real dependencies by default).
+ */
+function route(argv, deps = {}) {
+    if (!isTsCommand(argv)) {
+        return null;
+    }
+    if (argv[0] === "overlay") {
+        return runOverlay(argv.slice(1), deps);
+    }
+    if (argv[0] === "doctor") {
+        return (0, doctor_js_1.runDoctor)(argv.slice(1), deps);
+    }
+    return null;
+}