canary-test-cli 5.7.0 → 5.10.1

package/bin/canary.js

@@ -4,27 +4,59 @@
 const { execFileSync } = require("node:child_process");
 const path = require("node:path");
 const fs = require("node:fs");
+const { isTsCommand, route } = require("../dist/router.js");
 
 function getBinaryPath(platform) {
   const name = platform === "win32" ? "canary.exe" : "canary";
   return path.join(__dirname, name);
 }
 
-function main() {
-  const binaryPath = getBinaryPath(process.platform);
-  if (!fs.existsSync(binaryPath)) {
-    process.stderr.write(
+/**
+ * Forward a command to the bundled Python binary. Returns the exit code
+ * (0 on success, the binary's status on failure, 1 when the binary is missing).
+ * Dependencies are injectable for testing.
+ */
+function forwardToBinary(
+  argv,
+  {
+    execFile = execFileSync,
+    existsSync = fs.existsSync,
+    platform = process.platform,
+    stderr = process.stderr,
+  } = {}
+) {
+  const binaryPath = getBinaryPath(platform);
+  if (!existsSync(binaryPath)) {
+    stderr.write(
       `canary binary not found at ${binaryPath}.\n` +
-      `Try reinstalling: volta install canary-test-cli\n`
+        `Try reinstalling: npm install -g canary-test-cli\n`
     );
-    process.exit(1);
+    return 1;
   }
   try {
-    execFileSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+    execFile(binaryPath, argv, { stdio: "inherit" });
+    return 0;
   } catch (err) {
-    process.exit(err.status ?? 1);
+    return err.status ?? 1;
+  }
+}
+
+/**
+ * Dispatch one invocation: TS-handled commands (e.g. `overlay`, `doctor`) go to
+ * the router; everything else forwards verbatim to the Python binary. Returns
+ * the process exit code, or a Promise of one for async commands (`doctor`).
+ */
+function run(argv, deps = {}) {
+  if (isTsCommand(argv)) {
+    return route(argv, deps) ?? 0;
   }
+  return forwardToBinary(argv, deps);
+}
+
+function main() {
+  // `run` may return a number (sync commands) or a Promise<number> (doctor).
+  Promise.resolve(run(process.argv.slice(2))).then((code) => process.exit(code));
 }
 
-module.exports = { getBinaryPath };
+module.exports = { getBinaryPath, forwardToBinary, run };
 if (require.main === module) main();

package/dist/doctor-manifest.js

@@ -0,0 +1,285 @@
+"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.DEFAULT_CHECK_TIMEOUT_MS = exports.CHECK_TYPES = void 0;
+exports.manifestPath = manifestPath;
+exports.commandSucceedsHash = commandSucceedsHash;
+exports.loadManifest = loadManifest;
+exports.filterByPersona = filterByPersona;
+exports.runCheck = runCheck;
+/**
+ * Overlay check manifest — `<clone>/.canary/doctor.json` (Phase 2, tier 2).
+ *
+ * This module loads and validates the manifest and filters checks by persona.
+ * Execution of the individual check types lives in the runner (added in a
+ * later task). A malformed manifest never throws: {@link loadManifest} returns
+ * a single failing {@link CheckResult} so `doctor` can report it and carry on.
+ */
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const http = __importStar(require("node:http"));
+const https = __importStar(require("node:https"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+exports.CHECK_TYPES = ["file-exists", "url-reachable", "command-succeeds"];
+/** Path to an overlay's manifest. */
+function manifestPath(cloneDir) {
+    return path.join(cloneDir, ".canary", "doctor.json");
+}
+/**
+ * Stable fingerprint of a manifest's `command-succeeds` checks — the (id,
+ * command) pairs, sorted by id. Returns null when there are no such checks
+ * (nothing to gate). Consent is re-requested when this value changes.
+ */
+function commandSucceedsHash(checks) {
+    const cmds = checks
+        .filter((c) => c.type === "command-succeeds")
+        .map((c) => ({ id: c.id, command: c.command ?? [] }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+    if (cmds.length === 0) {
+        return null;
+    }
+    return (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(cmds)).digest("hex");
+}
+/** True when `v` is a non-empty array of strings. */
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((a) => typeof a === "string");
+}
+/**
+ * Validate the type-specific field of a check. Returns an error string, or
+ * null when the field is well-formed for the given type.
+ */
+function validateTypeField(type, c) {
+    if (type === "file-exists" && typeof c.path !== "string") {
+        return `check "${c.id}" (file-exists) is missing a string "path"`;
+    }
+    if (type === "url-reachable" && typeof c.url !== "string") {
+        return `check "${c.id}" (url-reachable) is missing a string "url"`;
+    }
+    if (type === "command-succeeds" && !(isStringArray(c.command) && c.command.length > 0)) {
+        return `check "${c.id}" (command-succeeds) needs a non-empty string[] "command"`;
+    }
+    return null;
+}
+/** Validate the id/type/remedy/persona fields common to every check type. */
+function validateCommonFields(c, index) {
+    if (typeof c.id !== "string" || c.id === "") {
+        return `check[${index}] is missing a string "id"`;
+    }
+    if (typeof c.type !== "string" || !exports.CHECK_TYPES.includes(c.type)) {
+        return `check "${c.id}" has an unknown type (expected one of: ${exports.CHECK_TYPES.join(", ")})`;
+    }
+    if (typeof c.remedy !== "string" || c.remedy === "") {
+        return `check "${c.id}" is missing a string "remedy"`;
+    }
+    if (c.persona !== undefined && !isStringArray(c.persona)) {
+        return `check "${c.id}" has a non-string persona list`;
+    }
+    return null;
+}
+/** Validate one raw check entry. Returns the typed check or an error string. */
+function validateCheck(raw, index) {
+    if (typeof raw !== "object" || raw === null) {
+        return `check[${index}] is not an object`;
+    }
+    const c = raw;
+    const commonError = validateCommonFields(c, index);
+    if (commonError) {
+        return commonError;
+    }
+    const type = c.type;
+    const typeError = validateTypeField(type, c);
+    if (typeError) {
+        return typeError;
+    }
+    return {
+        id: c.id,
+        type,
+        remedy: c.remedy,
+        persona: c.persona,
+        path: c.path,
+        url: c.url,
+        command: c.command,
+    };
+}
+/** Build the single failing check used when a manifest cannot be loaded. */
+function manifestFailure(cloneDir, detail) {
+    const file = manifestPath(cloneDir);
+    return {
+        ok: false,
+        failure: {
+            id: `manifest:${file}`,
+            status: "fail",
+            label: `doctor.json is invalid (${file})`,
+            remedy: detail,
+        },
+    };
+}
+/**
+ * Load and validate `<clone>/.canary/doctor.json`. A missing file is not an
+ * error (no checks). A malformed file or an invalid check degrades to a single
+ * failing check ({@link ManifestLoad} `ok: false`) — never a throw.
+ */
+function loadManifest(cloneDir) {
+    const file = manifestPath(cloneDir);
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT") {
+            return { ok: true, checks: [] };
+        }
+        return manifestFailure(cloneDir, e.message);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        return manifestFailure(cloneDir, `does not parse: ${e.message}`);
+    }
+    const checksRaw = parsed.checks;
+    if (!Array.isArray(checksRaw)) {
+        return manifestFailure(cloneDir, 'expected an object with a "checks" array');
+    }
+    const checks = [];
+    for (let i = 0; i < checksRaw.length; i += 1) {
+        const result = validateCheck(checksRaw[i], i);
+        if (typeof result === "string") {
+            return manifestFailure(cloneDir, result);
+        }
+        checks.push(result);
+    }
+    return { ok: true, checks };
+}
+/**
+ * Keep checks that should run for `persona`: a null persona runs everything;
+ * otherwise keep checks with no persona plus those whose persona list contains
+ * the tag (case-insensitive).
+ */
+function filterByPersona(checks, persona) {
+    if (persona === null) {
+        return [...checks];
+    }
+    const want = persona.toLowerCase();
+    return checks.filter((c) => !c.persona || c.persona.length === 0 || c.persona.some((p) => p.toLowerCase() === want));
+}
+/** Default per-check timeout for url and command checks. */
+exports.DEFAULT_CHECK_TIMEOUT_MS = 10000;
+function defaultProbeUrl(url, timeoutMs) {
+    return new Promise((resolve) => {
+        let mod;
+        try {
+            mod = new URL(url).protocol === "http:" ? http : https;
+        }
+        catch {
+            resolve(false);
+            return;
+        }
+        const req = mod.get(url, (res) => {
+            const s = res.statusCode ?? 0;
+            res.resume();
+            resolve(s >= 200 && s < 400);
+        });
+        req.on("error", () => resolve(false));
+        req.setTimeout(timeoutMs, () => {
+            req.destroy();
+            resolve(false);
+        });
+    });
+}
+const defaultRunCommand = (command, cwd, timeoutMs) => {
+    const r = (0, node_child_process_1.spawnSync)(command[0], command.slice(1), { cwd, timeout: timeoutMs, encoding: "utf8" });
+    if (r.error) {
+        const code = r.error.code;
+        return { ok: false, timedOut: code === "ETIMEDOUT" || r.signal === "SIGTERM", detail: String(r.error.message) };
+    }
+    if (r.signal === "SIGTERM") {
+        return { ok: false, timedOut: true };
+    }
+    return { ok: r.status === 0, timedOut: false, detail: r.status === 0 ? undefined : `exit ${r.status}` };
+};
+function pass(check, label) {
+    return { id: check.id, status: "pass", label };
+}
+function fail(check, label) {
+    return { id: check.id, status: "fail", label, remedy: check.remedy };
+}
+function runFileExists(check, cloneDir) {
+    const target = path.join(cloneDir, check.path ?? "");
+    return fs.existsSync(target)
+        ? pass(check, `${check.id}: ${check.path} exists`)
+        : fail(check, `${check.id}: ${check.path} is missing`);
+}
+async function runUrlReachable(check, ctx, timeoutMs) {
+    const probe = ctx.probeUrl ?? defaultProbeUrl;
+    const reachable = await probe(check.url ?? "", timeoutMs);
+    return reachable
+        ? pass(check, `${check.id}: ${check.url} reachable`)
+        : fail(check, `${check.id}: ${check.url} unreachable`);
+}
+function skipped(check, reason) {
+    return { id: check.id, status: "skip", label: `${check.id}: skipped (${reason})` };
+}
+function runCommandSucceeds(check, ctx, timeoutMs) {
+    if (!ctx.consentGranted) {
+        return skipped(check, "command checks need consent — re-run 'canary overlay add'");
+    }
+    const command = check.command ?? [];
+    const cmd = `\`${command.join(" ")}\``;
+    const runner = ctx.runCommand ?? defaultRunCommand;
+    const r = runner(command, ctx.cloneDir, timeoutMs);
+    if (r.ok) {
+        return pass(check, `${check.id}: ${cmd} succeeded`);
+    }
+    const why = r.timedOut ? `timed out after ${timeoutMs}ms` : (r.detail ?? "failed");
+    return fail(check, `${check.id}: ${cmd} ${why}`);
+}
+/**
+ * Execute one validated check against its overlay clone, under a bounded
+ * timeout. `command-succeeds` is skipped (not failed) unless consent is
+ * granted. Never throws.
+ */
+async function runCheck(check, ctx) {
+    const timeoutMs = ctx.timeoutMs ?? exports.DEFAULT_CHECK_TIMEOUT_MS;
+    if (check.type === "file-exists") {
+        return runFileExists(check, ctx.cloneDir);
+    }
+    if (check.type === "url-reachable") {
+        return runUrlReachable(check, ctx, timeoutMs);
+    }
+    return runCommandSucceeds(check, ctx, timeoutMs);
+}

package/dist/doctor.js

@@ -0,0 +1,130 @@
+"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.runDoctor = runDoctor;
+/**
+ * `canary doctor` — environment self-check (Phase 2).
+ *
+ * Runs two tiers of checks and prints each as pass/fail with a remedy line
+ * under every failure, adopting the `harness doctor` output shape; the process
+ * exits non-zero when any check fails. Tier 1 is built-in engine checks; tier 2
+ * is data-driven checks read from each tracked overlay's `.canary/doctor.json`.
+ */
+const os = __importStar(require("node:os"));
+const engine_checks_js_1 = require("./engine-checks.js");
+const doctor_manifest_js_1 = require("./doctor-manifest.js");
+const registry = __importStar(require("./overlays-registry.js"));
+const SYMBOL = { pass: "✓", fail: "✗", skip: "-", info: "ℹ" };
+/** `--persona <tag>` / `--persona=<tag>`, or null when unset. */
+function parsePersona(args) {
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === "--persona") {
+            return args[i + 1] ?? null;
+        }
+        if (a.startsWith("--persona=")) {
+            return a.slice("--persona=".length);
+        }
+    }
+    return null;
+}
+function renderCheck(r) {
+    const line = `  ${SYMBOL[r.status]} ${r.label}\n`;
+    return r.status === "fail" && r.remedy ? `${line}      → ${r.remedy}\n` : line;
+}
+/** Load, persona-filter, and run one overlay's manifest checks. */
+async function overlayResults(entry, deps, persona) {
+    const header = `Overlay: ${entry.name}`;
+    const load = (0, doctor_manifest_js_1.loadManifest)(entry.path);
+    if (!load.ok) {
+        return { header, results: [load.failure] };
+    }
+    const granted = registry.consentGranted(entry, (0, doctor_manifest_js_1.commandSucceedsHash)(load.checks));
+    const checks = (0, doctor_manifest_js_1.filterByPersona)(load.checks, persona);
+    const ctx = {
+        cloneDir: entry.path,
+        consentGranted: granted,
+        timeoutMs: deps.timeoutMs,
+        probeUrl: deps.probeUrl,
+        runCommand: deps.runCommand,
+    };
+    const results = [];
+    for (const check of checks) {
+        results.push(await (0, doctor_manifest_js_1.runCheck)(check, ctx));
+    }
+    return { header, results };
+}
+/**
+ * Run `canary doctor`. Returns a process exit code: 0 when every check passed
+ * or was skipped/info, non-zero when any check failed. A malformed manifest for
+ * one overlay never blocks engine checks or other overlays.
+ */
+async function runDoctor(args, deps = {}) {
+    const out = deps.out ?? process.stdout;
+    const persona = parsePersona(args);
+    const homeDir = deps.homeDir ?? os.homedir();
+    const engineDeps = {
+        git: deps.git,
+        homeDir,
+        cwd: deps.cwd,
+        currentVersion: deps.currentVersion,
+        getLatestVersion: deps.getLatestVersion,
+        timeoutMs: deps.timeoutMs,
+    };
+    const groups = [{ header: "Engine", results: await (0, engine_checks_js_1.runEngineChecks)(engineDeps) }];
+    let reg;
+    try {
+        reg = registry.read(homeDir);
+    }
+    catch {
+        reg = registry.emptyRegistry();
+    }
+    for (const entry of reg.overlays) {
+        groups.push(await overlayResults(entry, deps, persona));
+    }
+    out.write("canary doctor\n");
+    let failures = 0;
+    for (const group of groups) {
+        out.write(`\n${group.header}\n`);
+        for (const result of group.results) {
+            if (result.status === "fail") {
+                failures += 1;
+            }
+            out.write(renderCheck(result));
+        }
+    }
+    out.write(`\n${failures === 0 ? "All checks passed." : `${failures} check(s) failed.`}\n`);
+    return failures === 0 ? 0 : 1;
+}