canary-test-cli 5.10.1 → 5.12.0

package/bin/canary.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
-"use strict";
+'use strict';
 
-const { execFileSync } = require("node:child_process");
-const path = require("node:path");
-const fs = require("node:fs");
-const { isTsCommand, route } = require("../dist/router.js");
+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";
+  const name = platform === 'win32' ? 'canary.exe' : 'canary';
   return path.join(__dirname, name);
 }
 
@@ -23,18 +23,18 @@ function forwardToBinary(
     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: npm install -g canary-test-cli\n`
+        `Try reinstalling: npm install -g canary-test-cli\n`,
     );
     return 1;
   }
   try {
-    execFile(binaryPath, argv, { stdio: "inherit" });
+    execFile(binaryPath, argv, { stdio: 'inherit' });
     return 0;
   } catch (err) {
     return err.status ?? 1;
@@ -55,7 +55,9 @@ function run(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));
+  Promise.resolve(run(process.argv.slice(2))).then((code) =>
+    process.exit(code),
+  );
 }
 
 module.exports = { getBinaryPath, forwardToBinary, run };

package/dist/doctor-manifest.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);
@@ -37,12 +37,13 @@ exports.DEFAULT_CHECK_TIMEOUT_MS = exports.CHECK_TYPES = void 0;
 exports.manifestPath = manifestPath;
 exports.commandSucceedsHash = commandSucceedsHash;
 exports.loadManifest = loadManifest;
-exports.filterByPersona = filterByPersona;
+exports.collectAudiences = collectAudiences;
+exports.filterByAudience = filterByAudience;
 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.
+ * This module loads and validates the manifest and filters checks by audience.
  * 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.
@@ -53,10 +54,14 @@ 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"];
+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");
+    return path.join(cloneDir, '.canary', 'doctor.json');
 }
 /**
  * Stable fingerprint of a manifest's `command-succeeds` checks — the (id,
@@ -65,53 +70,60 @@ function manifestPath(cloneDir) {
  */
 function commandSucceedsHash(checks) {
     const cmds = checks
-        .filter((c) => c.type === "command-succeeds")
+        .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");
+    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");
+    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") {
+    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") {
+    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)) {
+    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. */
+/** The audience tags on a raw check: `audience:` (canonical) or `persona:` (legacy). */
+function rawAudience(c) {
+    return c.audience !== undefined ? c.audience : c.persona;
+}
+/** Validate the id/type/remedy/audience fields common to every check type. */
 function validateCommonFields(c, index) {
-    if (typeof c.id !== "string" || c.id === "") {
+    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.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 === "") {
+    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`;
+    const audience = rawAudience(c);
+    if (audience !== undefined && !isStringArray(audience)) {
+        return `check "${c.id}" has a non-string audience 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) {
+    if (typeof raw !== 'object' || raw === null) {
         return `check[${index}] is not an object`;
     }
     const c = raw;
@@ -128,7 +140,7 @@ function validateCheck(raw, index) {
         id: c.id,
         type,
         remedy: c.remedy,
-        persona: c.persona,
+        audience: rawAudience(c),
         path: c.path,
         url: c.url,
         command: c.command,
@@ -141,7 +153,7 @@ function manifestFailure(cloneDir, detail) {
         ok: false,
         failure: {
             id: `manifest:${file}`,
-            status: "fail",
+            status: 'fail',
             label: `doctor.json is invalid (${file})`,
             remedy: detail,
         },
@@ -156,10 +168,10 @@ function loadManifest(cloneDir) {
     const file = manifestPath(cloneDir);
     let raw;
     try {
-        raw = fs.readFileSync(file, "utf8");
+        raw = fs.readFileSync(file, 'utf8');
     }
     catch (e) {
-        if (e.code === "ENOENT") {
+        if (e.code === 'ENOENT') {
             return { ok: true, checks: [] };
         }
         return manifestFailure(cloneDir, e.message);
@@ -178,7 +190,7 @@ function loadManifest(cloneDir) {
     const checks = [];
     for (let i = 0; i < checksRaw.length; i += 1) {
         const result = validateCheck(checksRaw[i], i);
-        if (typeof result === "string") {
+        if (typeof result === 'string') {
             return manifestFailure(cloneDir, result);
         }
         checks.push(result);
@@ -186,16 +198,39 @@ function loadManifest(cloneDir) {
     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).
+ * The distinct audience tags declared across a set of checks, in first-seen
+ * order and de-duplicated case-insensitively (original casing preserved for
+ * display). This is the discoverable audience *vocabulary* — the engine ships
+ * none of its own, so it is derived entirely from overlay manifests. Used to
+ * tell a user which `--audience` values actually mean something (issue #294).
+ */
+function collectAudiences(checks) {
+    const seen = new Set();
+    const out = [];
+    for (const check of checks) {
+        for (const tag of check.audience ?? []) {
+            const key = tag.toLowerCase();
+            if (!seen.has(key)) {
+                seen.add(key);
+                out.push(tag);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Keep checks that should run for `audience`: a null audience runs everything;
+ * otherwise keep checks with no audience plus those whose audience list
+ * contains the tag (case-insensitive).
  */
-function filterByPersona(checks, persona) {
-    if (persona === null) {
+function filterByAudience(checks, audience) {
+    if (audience === null) {
         return [...checks];
     }
-    const want = persona.toLowerCase();
-    return checks.filter((c) => !c.persona || c.persona.length === 0 || c.persona.some((p) => p.toLowerCase() === want));
+    const want = audience.toLowerCase();
+    return checks.filter((c) => !c.audience ||
+        c.audience.length === 0 ||
+        c.audience.some((p) => p.toLowerCase() === want));
 }
 /** Default per-check timeout for url and command checks. */
 exports.DEFAULT_CHECK_TIMEOUT_MS = 10000;
@@ -203,7 +238,7 @@ function defaultProbeUrl(url, timeoutMs) {
     return new Promise((resolve) => {
         let mod;
         try {
-            mod = new URL(url).protocol === "http:" ? http : https;
+            mod = new URL(url).protocol === 'http:' ? http : https;
         }
         catch {
             resolve(false);
@@ -214,7 +249,7 @@ function defaultProbeUrl(url, timeoutMs) {
             res.resume();
             resolve(s >= 200 && s < 400);
         });
-        req.on("error", () => resolve(false));
+        req.on('error', () => resolve(false));
         req.setTimeout(timeoutMs, () => {
             req.destroy();
             resolve(false);
@@ -222,50 +257,68 @@ function defaultProbeUrl(url, timeoutMs) {
     });
 }
 const defaultRunCommand = (command, cwd, timeoutMs) => {
-    const r = (0, node_child_process_1.spawnSync)(command[0], command.slice(1), { cwd, timeout: timeoutMs, encoding: "utf8" });
+    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) };
+        return {
+            ok: false,
+            timedOut: code === 'ETIMEDOUT' || r.signal === 'SIGTERM',
+            detail: String(r.error.message),
+        };
     }
-    if (r.signal === "SIGTERM") {
+    if (r.signal === 'SIGTERM') {
         return { ok: false, timedOut: true };
     }
-    return { ok: r.status === 0, timedOut: false, detail: r.status === 0 ? undefined : `exit ${r.status}` };
+    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 };
+    return { id: check.id, status: 'pass', label };
 }
 function fail(check, label) {
-    return { id: check.id, status: "fail", label, remedy: check.remedy };
+    return { id: check.id, status: 'fail', label, remedy: check.remedy };
 }
 function runFileExists(check, cloneDir) {
-    const target = path.join(cloneDir, check.path ?? "");
+    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);
+    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})` };
+    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 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");
+    const why = r.timedOut
+        ? `timed out after ${timeoutMs}ms`
+        : (r.detail ?? 'failed');
     return fail(check, `${check.id}: ${cmd} ${why}`);
 }
 /**
@@ -275,10 +328,10 @@ function runCommandSucceeds(check, ctx, timeoutMs) {
  */
 async function runCheck(check, ctx) {
     const timeoutMs = ctx.timeoutMs ?? exports.DEFAULT_CHECK_TIMEOUT_MS;
-    if (check.type === "file-exists") {
+    if (check.type === 'file-exists') {
         return runFileExists(check, ctx.cloneDir);
     }
-    if (check.type === "url-reachable") {
+    if (check.type === 'url-reachable') {
         return runUrlReachable(check, ctx, timeoutMs);
     }
     return runCommandSucceeds(check, ctx, timeoutMs);

package/dist/doctor.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);
@@ -33,46 +33,97 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseJsonFlag = parseJsonFlag;
+exports.unknownAudienceHint = unknownAudienceHint;
 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`.
+ * under every failure; 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`.
+ *
+ * Output shape (issue #318): the human text is loosely modeled on
+ * `harness doctor`, but the two are NOT a shared contract and have diverged —
+ * canary uses richer per-check fields (`id`/`label`/`remedy`) and a `skip`
+ * status tier that harness lacks. `--json` therefore emits a *canary-owned*
+ * machine contract, `{ version, checks, allPassed, warnings }`, documented in
+ * `JsonReport` below. Only the top-level `allPassed` boolean intentionally
+ * matches `harness doctor --json`; per-check fields are canary's own. Do not
+ * build a parser that assumes the two JSON shapes are interchangeable.
  */
 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);
+const SYMBOL = {
+    pass: '✓',
+    fail: '✗',
+    skip: '-',
+    info: 'ℹ',
+};
+/** `--json` requests machine output on stdout instead of the human report. */
+function parseJsonFlag(args) {
+    return args.includes('--json');
+}
+/**
+ * `--audience <tag>` / `--audience=<tag>`, or null when unset (#319 B). The
+ * former name `--persona` is accepted as a legacy alias so existing invocations
+ * keep working; `--audience` is canonical. (Renamed to end the collision with
+ * harness's unrelated persona system.)
+ */
+function parseAudience(args) {
+    for (const flag of ['--audience', '--persona']) {
+        for (let i = 0; i < args.length; i += 1) {
+            const a = args[i];
+            if (a === flag) {
+                return args[i + 1] ?? null;
+            }
+            if (a.startsWith(`${flag}=`)) {
+                return a.slice(flag.length + 1);
+            }
         }
     }
     return null;
 }
+/**
+ * Fail-loud hint for an unrecognized `--audience` value (issue #294). Returns
+ * null when there is nothing to say — no audience was passed, or the passed
+ * audience is part of the known vocabulary. Otherwise returns a one-line,
+ * actionable message: the engine ships no audience vocabulary, so this lists
+ * the tags overlays actually declared (or says none are defined) instead of
+ * silently running only the audience-less checks and leaving the user to
+ * guess why their filter matched nothing.
+ */
+function unknownAudienceHint(audience, known) {
+    if (audience === null) {
+        return null;
+    }
+    const want = audience.toLowerCase();
+    if (known.some((p) => p.toLowerCase() === want)) {
+        return null;
+    }
+    if (known.length === 0) {
+        return `--audience '${audience}' matched no checks: no overlay defines any audiences, so every check already runs. Drop the flag.`;
+    }
+    return `--audience '${audience}' is not a known audience. Valid options: ${known.join(', ')}. (Omit --audience to run every check.)`;
+}
 function renderCheck(r) {
     const line = `  ${SYMBOL[r.status]} ${r.label}\n`;
-    return r.status === "fail" && r.remedy ? `${line}      → ${r.remedy}\n` : line;
+    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) {
+/** Load, audience-filter, and run one overlay's manifest checks. */
+async function overlayResults(entry, deps, audience) {
     const header = `Overlay: ${entry.name}`;
     const load = (0, doctor_manifest_js_1.loadManifest)(entry.path);
     if (!load.ok) {
-        return { header, results: [load.failure] };
+        return { group: { header, results: [load.failure] }, loadedChecks: [] };
     }
     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 checks = (0, doctor_manifest_js_1.filterByAudience)(load.checks, audience);
     const ctx = {
         cloneDir: entry.path,
         consentGranted: granted,
@@ -84,7 +135,9 @@ async function overlayResults(entry, deps, persona) {
     for (const check of checks) {
         results.push(await (0, doctor_manifest_js_1.runCheck)(check, ctx));
     }
-    return { header, results };
+    // Return the full (pre-filter) check set so the caller can build the
+    // audience vocabulary for a fail-loud hint on an unknown --audience.
+    return { group: { header, results }, loadedChecks: load.checks };
 }
 /**
  * Run `canary doctor`. Returns a process exit code: 0 when every check passed
@@ -93,7 +146,7 @@ async function overlayResults(entry, deps, persona) {
  */
 async function runDoctor(args, deps = {}) {
     const out = deps.out ?? process.stdout;
-    const persona = parsePersona(args);
+    const audience = parseAudience(args);
     const homeDir = deps.homeDir ?? os.homedir();
     const engineDeps = {
         git: deps.git,
@@ -103,7 +156,9 @@ async function runDoctor(args, deps = {}) {
         getLatestVersion: deps.getLatestVersion,
         timeoutMs: deps.timeoutMs,
     };
-    const groups = [{ header: "Engine", results: await (0, engine_checks_js_1.runEngineChecks)(engineDeps) }];
+    const groups = [
+        { header: 'Engine', results: await (0, engine_checks_js_1.runEngineChecks)(engineDeps) },
+    ];
     let reg;
     try {
         reg = registry.read(homeDir);
@@ -111,20 +166,46 @@ async function runDoctor(args, deps = {}) {
     catch {
         reg = registry.emptyRegistry();
     }
+    const allChecks = [];
     for (const entry of reg.overlays) {
-        groups.push(await overlayResults(entry, deps, persona));
+        const { group, loadedChecks } = await overlayResults(entry, deps, audience);
+        groups.push(group);
+        allChecks.push(...loadedChecks);
+    }
+    // Issue #294: if the user passed a --audience that no overlay declares,
+    // tell them the valid vocabulary instead of silently filtering to only
+    // the audience-less checks and leaving them to wonder why.
+    const audienceHint = unknownAudienceHint(audience, (0, doctor_manifest_js_1.collectAudiences)(allChecks));
+    const failures = groups.reduce((n, g) => n + g.results.filter((r) => r.status === 'fail').length, 0);
+    // Issue #318: `--json` emits the canary-owned machine contract instead of
+    // the human report — nothing else is written to stdout, so the whole stream
+    // parses as one JSON object.
+    if (parseJsonFlag(args)) {
+        const report = {
+            version: 1,
+            checks: groups.flatMap((g) => g.results.map((r) => ({
+                id: r.id,
+                status: r.status,
+                label: r.label,
+                ...(r.remedy !== undefined ? { remedy: r.remedy } : {}),
+                group: g.header,
+            }))),
+            allPassed: failures === 0,
+            warnings: audienceHint ? [audienceHint] : [],
+        };
+        out.write(`${JSON.stringify(report, null, 2)}\n`);
+        return failures === 0 ? 0 : 1;
+    }
+    out.write('canary doctor\n');
+    if (audienceHint) {
+        out.write(`\n! ${audienceHint}\n`);
     }
-    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`);
+    out.write(`\n${failures === 0 ? 'All checks passed.' : `${failures} check(s) failed.`}\n`);
     return failures === 0 ? 0 : 1;
 }