canary-test-cli 6.2.0 → 6.4.0

package/bin/canary-mcp.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+'use strict';
+
+// Console-script entry for `canary-mcp` (#507): starts the Canary MCP server
+// over stdio from the bundled TypeScript engine (dist/engine/mcp-server.js,
+// staged by scripts/build-engine.mjs). The engine bundle is ESM while this
+// package is CommonJS, so the server module is loaded via dynamic import().
+// stdout carries the JSON-RPC stream and must never be polluted -- every
+// failure path writes to stderr only.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { pathToFileURL } = require('node:url');
+
+/** Absolute path to the bundled engine's MCP server module. */
+function getServerPath() {
+  return path.join(__dirname, '..', 'dist', 'engine', 'mcp-server.js');
+}
+
+/**
+ * Start the server. Returns the exit code (0 when runStdio resolves, 1 when
+ * the bundle is missing). Dependencies are injectable for testing.
+ */
+async function main({
+  serverPath = getServerPath(),
+  existsSync = fs.existsSync,
+  stderr = process.stderr,
+} = {}) {
+  if (!existsSync(serverPath)) {
+    stderr.write(
+      `canary MCP server not found at ${serverPath}.\n` +
+        `The package looks incomplete; try reinstalling: npm install -g canary-test-cli\n`,
+    );
+    return 1;
+  }
+  const { runStdio } = await import(pathToFileURL(serverPath).href);
+  await runStdio();
+  return 0;
+}
+
+if (require.main === module) {
+  main()
+    .then((code) => {
+      if (code !== 0) process.exit(code);
+    })
+    .catch((err) => {
+      console.error(err);
+      process.exit(1);
+    });
+}
+
+module.exports = { getServerPath, main };

package/dist/engine/cli-commands.js

@@ -155,7 +155,7 @@ export function feedbackCmd(message, opts, deps) {
         deps.out(`${pc.bold(pc.red(CROSS))} A feedback message is required.\nUsage: ${pc.bold('canary feedback "<message>" [--category bug|ux|docs|idea]')}`);
         throw new CliExit(1);
     }
-    const fb = buildFeedback(message.trim(), opts.category);
+    const fb = buildFeedback(message.trim(), opts.category, resolveVersion(deps));
     if (opts.json) {
         deps.out(jsonIndent2(fb));
         return;
@@ -344,6 +344,7 @@ export function migrateCmd(opts, deps) {
             dryRun,
             framework: opts.framework || null,
             overlayPath,
+            force: opts.force ?? false,
         });
     }
     catch (e) {
@@ -367,6 +368,7 @@ export function migrateCmd(opts, deps) {
                 status: r.status,
                 note: r.note,
             })),
+            installed_workflows: report.installed_workflows.map((r) => r.to_dict()),
         }));
         return;
     }

package/dist/engine/cli.core.js

@@ -107,6 +107,7 @@ export function createCanaryCommand(depsInit = {}) {
         .option('-o, --overlay <path>', '[deprecated: use --from] Path to an overlay repo whose .canary/skills/ are deployed.')
         .option('--apply', 'Write files. Without this flag the command is a dry run.')
         .option('--check', 'Freshness gate: report drift without writing.')
+        .option('--force', 'Overwrite a .github/workflows/ file that differs from the overlay template. Without this flag a difference is only reported -- your CI is never rewritten behind your back.')
         .option('--json', 'Emit the report as JSON.')
         .action((opts) => {
         migrateCmd(opts, deps);

package/dist/engine/core/company-knowledge.js

@@ -13,9 +13,11 @@
  *   2. .canary/company.json            -- project-local config
  *   3. .canary/company.<env>.json      -- environment override (CANARY_ENV or explicit)
  *
- * List fields are unioned across sources; scalar fields (dashboard_url,
- * dashboard_token_env, notes) are replaced by the highest-priority source that
- * sets them.
+ * List fields ({@link _LIST_FIELDS}) are unioned across sources; scalar fields
+ * ({@link _SCALAR_FIELDS}) are replaced by the highest-priority source that
+ * sets a non-empty value. Those two arrays are the single place a new field
+ * opts into a merge rule, and both are checked for exhaustiveness at compile
+ * time.
  *
  * Python->TS nuances:
  *   - Python patches `Path.home()` in its tests to isolate the home tier. There
@@ -118,6 +120,12 @@ const _KNOWN_KEYS = new Set([
     // warning that it is told anyone adopting an overlay that the single field
     // driving their adoption does nothing.
     'canary_shape',
+    // #459: repo-relative pointers a generated workflow interpolates (the
+    // coverage report the guardian reads; the controllers dir it scopes SUT
+    // analysis to). See `validateRepoRelativePath` for why they are validated
+    // rather than stored verbatim.
+    'coverage_report_path',
+    'sut_controllers_path',
 ]);
 const _HEX_COLOR_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
 const _BRAND_TEXT_MAX = 200;
@@ -240,6 +248,50 @@ function validateOtelEndpoint(raw, fieldName, warnings) {
     }
     return raw;
 }
+// A path that is absolute in any flavour git checkouts run under: POSIX
+// (`/x`), UNC / Windows-separator (`\x`), or drive-qualified (`C:x`, `C:/x`).
+// Drive-relative `C:x` is included deliberately -- it is not repo-relative.
+const _ABSOLUTE_PATH_RE = /^(?:[/\\]|[A-Za-z]:)/;
+// Newlines would break out of the scalar these values are interpolated into
+// when a workflow template is generated, so they are refused outright rather
+// than escaped -- no legitimate repo path contains one.
+const _PATH_CONTROL_RE = /[\r\n\t\0]/;
+/**
+ * A repo-relative path pointer (#459: `coverage_report_path`,
+ * `sut_controllers_path`).
+ *
+ * These are interpolated into generated GitHub Actions YAML, so validation is
+ * a safety boundary, not tidiness: an absolute path aims the generated CI at
+ * something outside the checkout, and a `..` segment escapes the repo. Both are
+ * dropped with a warning (the module's degrade-never-throw convention); a
+ * secret-like value raises so the whole layer is refused, exactly as every
+ * other non-notes field does.
+ *
+ * `..` is rejected as a SUBSTRING, not just as a path component. A component
+ * check would have to agree with the separator handling of whatever consumes
+ * the value later (shell, Actions expression, node `path`); refusing the two
+ * characters outright cannot disagree with anything. The cost is rejecting the
+ * vanishingly rare legitimate `report..xml`.
+ */
+function validateRepoRelativePath(raw, fieldName, warnings) {
+    if (typeof raw !== 'string') {
+        warnings.push(`${fieldName}: expected string, got ${pyTypeName(raw)} ${EMDASH} skipped`);
+        return '';
+    }
+    const value = raw.trim();
+    if (!value)
+        return '';
+    if (looksLikeSecret(value))
+        throw new SecretDetected(fieldName, value);
+    if (_ABSOLUTE_PATH_RE.test(value) ||
+        value.includes('..') ||
+        _PATH_CONTROL_RE.test(value)) {
+        warnings.push(`${fieldName}: dropped invalid repo-relative path ${pyRepr(raw)} ` +
+            `${EMDASH} must stay inside the repo (no absolute path, no '..')`);
+        return '';
+    }
+    return value;
+}
 /** Accept #RGB / #RRGGBB (any case); drop anything else with a warning. */
 function validateHexColor(raw, fieldName, warnings) {
     if (typeof raw !== 'string' || !raw)
@@ -432,6 +484,14 @@ function parseLayer(data, source) {
     if (Object.prototype.hasOwnProperty.call(data, 'otel_exporter_endpoint')) {
         otel_exporter_endpoint = validateOtelEndpoint(data['otel_exporter_endpoint'], 'otel_exporter_endpoint', warns);
     }
+    let coverage_report_path = '';
+    if (Object.prototype.hasOwnProperty.call(data, 'coverage_report_path')) {
+        coverage_report_path = validateRepoRelativePath(data['coverage_report_path'], 'coverage_report_path', warns);
+    }
+    let sut_controllers_path = '';
+    if (Object.prototype.hasOwnProperty.call(data, 'sut_controllers_path')) {
+        sut_controllers_path = validateRepoRelativePath(data['sut_controllers_path'], 'sut_controllers_path', warns);
+    }
     let notes = '';
     if (Object.prototype.hasOwnProperty.call(data, 'notes')) {
         const rawNotes = data['notes'];
@@ -455,6 +515,8 @@ function parseLayer(data, source) {
         dashboard_url,
         dashboard_token_env,
         otel_exporter_endpoint,
+        coverage_report_path,
+        sut_controllers_path,
         notes,
         brand,
         warnings: warns,
@@ -509,51 +571,66 @@ function union(a, b) {
     }
     return out;
 }
+const _LIST_FIELDS = [
+    'confluence_spaces',
+    'jira_projects',
+    'internal_doc_urls',
+    'internal_domains',
+    'mcp_servers',
+    'claude_code_skills',
+];
+const _SCALAR_FIELDS = [
+    'dashboard_url',
+    'dashboard_token_env',
+    'otel_exporter_endpoint',
+    'coverage_report_path',
+    'sut_controllers_path',
+    'notes',
+];
+// Compile-time exhaustiveness: adding a field to `Layer`/`MergedFields` without
+// adding it to the matching array above fails the build here (the assertion
+// type collapses to `never`) rather than silently dropping the field at merge.
+const _LIST_FIELDS_EXHAUSTIVE = true;
+const _SCALAR_FIELDS_EXHAUSTIVE = true;
+void _LIST_FIELDS_EXHAUSTIVE;
+void _SCALAR_FIELDS_EXHAUSTIVE;
+function mergeListFields(layers) {
+    const out = {};
+    for (const field of _LIST_FIELDS) {
+        let merged = [];
+        for (const layer of layers)
+            merged = union(merged, layer[field]);
+        out[field] = merged;
+    }
+    return out;
+}
+function mergeScalarFields(layers) {
+    const out = {};
+    for (const field of _SCALAR_FIELDS) {
+        let merged = '';
+        // Highest-priority non-empty wins. A layer whose value was DROPPED as
+        // invalid contributes '' and therefore leaves the lower layer's valid value
+        // standing (degrade, never blank out) -- load-bearing, and pinned by tests.
+        for (const layer of layers)
+            if (layer[field])
+                merged = layer[field];
+        out[field] = merged;
+    }
+    return out;
+}
 function mergeLayers(layers) {
-    let confluence_spaces = [];
-    let jira_projects = [];
-    let internal_doc_urls = [];
-    let internal_domains = [];
-    let mcp_servers = [];
-    let claude_code_skills = [];
-    let dashboard_url = '';
-    let dashboard_token_env = '';
-    let otel_exporter_endpoint = '';
-    let notes = '';
-    const warns = [];
+    const warnings = [];
     const sources = [];
     for (const layer of layers) {
-        confluence_spaces = union(confluence_spaces, layer.confluence_spaces);
-        jira_projects = union(jira_projects, layer.jira_projects);
-        internal_doc_urls = union(internal_doc_urls, layer.internal_doc_urls);
-        internal_domains = union(internal_domains, layer.internal_domains);
-        mcp_servers = union(mcp_servers, layer.mcp_servers);
-        claude_code_skills = union(claude_code_skills, layer.claude_code_skills);
-        if (layer.dashboard_url)
-            dashboard_url = layer.dashboard_url;
-        if (layer.dashboard_token_env)
-            dashboard_token_env = layer.dashboard_token_env;
-        if (layer.otel_exporter_endpoint)
-            otel_exporter_endpoint = layer.otel_exporter_endpoint;
-        if (layer.notes)
-            notes = layer.notes;
-        warns.push(...layer.warnings);
+        warnings.push(...layer.warnings);
         if (layer.source)
             sources.push(layer.source);
     }
     return {
-        confluence_spaces,
-        jira_projects,
-        internal_doc_urls,
-        internal_domains,
-        mcp_servers,
-        claude_code_skills,
-        dashboard_url,
-        dashboard_token_env,
-        otel_exporter_endpoint,
-        notes,
+        ...mergeListFields(layers),
+        ...mergeScalarFields(layers),
         brand: mergeBrand(layers),
-        warnings: warns,
+        warnings,
         sources,
     };
 }
@@ -585,6 +662,10 @@ export class CompanyKnowledge {
     dashboard_url;
     dashboard_token_env;
     otel_exporter_endpoint;
+    /** Repo-relative path to the coverage report a generated workflow reads. */
+    coverage_report_path;
+    /** Repo-relative path to the SUT controllers dir analysis is scoped to. */
+    sut_controllers_path;
     notes;
     brand;
     warnings;
@@ -600,6 +681,8 @@ export class CompanyKnowledge {
         this.dashboard_url = init.dashboard_url ?? '';
         this.dashboard_token_env = init.dashboard_token_env ?? '';
         this.otel_exporter_endpoint = init.otel_exporter_endpoint ?? '';
+        this.coverage_report_path = init.coverage_report_path ?? '';
+        this.sut_controllers_path = init.sut_controllers_path ?? '';
         this.notes = init.notes ?? '';
         this.brand = init.brand ?? new Brand();
         this.warnings = init.warnings ?? [];
@@ -733,6 +816,8 @@ export class CompanyKnowledge {
             dashboard_url: this.dashboard_url,
             dashboard_token_env: this.dashboard_token_env,
             otel_exporter_endpoint: this.otel_exporter_endpoint,
+            coverage_report_path: this.coverage_report_path,
+            sut_controllers_path: this.sut_controllers_path,
             notes: this.notes,
             brand: this.brand.toDict(),
             sources: this.sources,

package/dist/engine/core/feedback.js

@@ -12,10 +12,10 @@
  * never reads environment variables or file contents.
  *
  * Python→TS nuances:
- *   - **Context shape is a contract**: the four keys `{version, os, python,
- *     install}` (and their order) are preserved. The `python` value is the JS
- *     *runtime* version (`process.version`) — the Node analog of Python's
- *     `platform.python_version()`; the field name is kept for shape fidelity.
+ *   - The context keys are `{version, os, runtime, install}` (insertion order
+ *     preserved). `runtime` carries `process.version`; the key was named
+ *     `python` for golden-parity shape fidelity until #506 — in filed issues
+ *     it misled triage ("user on python v22?") once the Python engine retired.
  *   - `urlencode(...)` (which uses `quote_plus`, space -> `+`) maps to
  *     `URLSearchParams`, which also form-encodes with space -> `+` and preserves
  *     insertion order. Exotic-character percent-encoding can differ byte-for-byte
@@ -26,12 +26,6 @@ import { release, type } from 'node:os';
 /** The public issue tracker (from npm/package.json `repository`). */
 export const TRACKER_URL = 'https://github.com/bop-clocktower/canary';
 export const VALID_CATEGORIES = ['bug', 'ux', 'docs', 'idea'];
-function canaryVersion() {
-    // Python reads `importlib.metadata.version("canary-test-ai")`, falling back to
-    // "unknown". The TS pilot has no equivalent package-metadata lookup wired in,
-    // so we return the same best-effort "unknown" sentinel.
-    return 'unknown';
-}
 /** Best-effort install-method label — never fails, never inspects secrets. */
 function installMethod() {
     const exe = (process.execPath || '').toLowerCase();
@@ -45,23 +39,43 @@ function installMethod() {
  *
  * Deliberately excludes environment variables and file contents — only the
  * coarse runtime facts a maintainer needs to triage a CLI report.
+ *
+ * `version` comes from the caller (#506): this module is pure and cannot know
+ * which package it shipped in, but the CLI layer does (`deps.pkgVersion()`),
+ * and the version is the single most useful triage field.
  */
-export function collectContext() {
+export function collectContext(version = 'unknown') {
     return {
-        version: canaryVersion(),
+        version,
         os: `${type()} ${release()}`.trim(),
-        python: process.version,
+        runtime: process.version,
         install: installMethod(),
     };
 }
+// Horizontal ellipsis, kept as an escape so this source stays ASCII.
+const ELLIPSIS = '\u{2026}';
+/**
+ * Cap the title at 60 code points (`Array.from` slices by code point, not
+ * UTF-16 unit, so astral chars do not truncate early). When the cap bites,
+ * break on the last word boundary inside the budget (falling back to a hard
+ * cut for an unbreakable token) and append an ellipsis so the truncation is
+ * visible instead of ending mid-word (#506).
+ */
+function truncateTitle(message) {
+    const points = Array.from(message);
+    if (points.length <= 60)
+        return message;
+    const hard = points.slice(0, 60).join('');
+    const lastBreak = hard.search(/\s+\S*$/);
+    const cut = lastBreak > 0 ? hard.slice(0, lastBreak) : hard;
+    return `${cut}${ELLIPSIS}`;
+}
 /**
  * A pre-filled GitHub 'new issue' URL: category in the title, message + context
  * in the body, category as a label. All parts are URL-encoded.
  */
 export function buildIssueUrl(category, message, context) {
-    // Python `message[:60]` slices by code point; JS `slice` slices by UTF-16
-    // unit, so an astral char would truncate the title early. Match the oracle.
-    const title = `[${category}] ${Array.from(message).slice(0, 60).join('')}`.trim();
+    const title = `[${category}] ${truncateTitle(message)}`.trim();
     const bodyLines = [
         message,
         '',
@@ -81,8 +95,8 @@ export function buildIssueUrl(category, message, context) {
     return `${TRACKER_URL}/issues/new?${query.toString()}`;
 }
 /** Bundle a report: message, category, context, and the pre-filled URL. */
-export function buildFeedback(message, category) {
-    const context = collectContext();
+export function buildFeedback(message, category, version = 'unknown') {
+    const context = collectContext(version);
     return {
         message,
         category,

package/dist/engine/core/gate-result.js

@@ -0,0 +1,73 @@
+/**
+ * Shared gate-abstention helper (issue #508, no-silent-abstention spec).
+ *
+ * Doctrine: a check that verified zero items has ABSTAINED, not passed.
+ * Every gate reports its denominator (`checked`); zero is a distinct loud
+ * outcome. "Skipped" renders in every summary line and never aggregates
+ * into "passed" (D7).
+ *
+ * `gateOutcome` is the only path to a summary line for swept commands, so
+ * the refusal to print bare success on a zero denominator is structural.
+ * Surfaces append their own remediation text (why the denominator
+ * collapsed, first fix step) after the summary line.
+ *
+ * Output glyphs are written as `\u{...}` escapes so this source stays
+ * ASCII while the emitted bytes match the rest of the CLI (warning sign
+ * U+26A0, em dash U+2014).
+ */
+/**
+ * Reserved CLI-wide (D4): exit 3 always means "abstained -- verified zero
+ * items", distinct from 0 (clean), 1 (findings), 2 (surface-specific).
+ */
+export const EXIT_ABSTAINED = 3;
+const WARN = '\u{26A0}'; // warning sign
+const EMDASH = '\u{2014}'; // em dash
+// C0 controls (incl. \n, ESC) and DEL: a skip name must never be able to
+// forge output lines or smuggle ANSI sequences into the summary.
+const CONTROL_CHARS = /[\u0000-\u001F\u007F]/g;
+/** D7: skipped entries render in EVERY summary line. */
+function skippedSuffix(skipped) {
+    if (!skipped || skipped.length === 0)
+        return '';
+    const names = skipped
+        .map((s) => s.name.replace(CONTROL_CHARS, ''))
+        .join(', ');
+    return ` (${skipped.length} skipped: ${names})`;
+}
+/**
+ * The single summary-line/exit-code path for swept commands.
+ *
+ * Non-abstained exit codes are helper defaults (findings -> 1 for gates);
+ * surfaces with richer contracts (e.g. freshness 2 = local edits) apply
+ * their own mapping AFTER checking `abstained`.
+ */
+export function gateOutcome(result, kind, opts = {}) {
+    const noun = opts.noun ?? 'check(s)';
+    const suffix = skippedSuffix(result.skipped);
+    // Findings outrank abstention: a finding proves something was checked,
+    // so it must never be masked by a collapsed/invalid denominator.
+    if (result.findings.length > 0) {
+        return {
+            exitCode: kind === 'gate' ? 1 : 0,
+            abstained: false,
+            summaryLine: `${result.findings.length} finding(s) across ` +
+                `${result.checked} checked${suffix}`,
+        };
+    }
+    // Negated comparison so 0, negatives, and NaN all abstain: an invalid
+    // denominator must never render as success.
+    if (!(result.checked > 0)) {
+        return {
+            exitCode: kind === 'gate' ? EXIT_ABSTAINED : 0,
+            abstained: true,
+            summaryLine: `${WARN} Abstained ${EMDASH} verified zero items; ` +
+                `this is not a pass.${suffix}`,
+        };
+    }
+    return {
+        exitCode: 0,
+        abstained: false,
+        summaryLine: `All ${result.checked} run ${noun} passed${suffix}`,
+    };
+}
+//# sourceMappingURL=gate-result.js.map