canary-test-cli 6.1.0 → 6.3.0

package/dist/engine/core/migrator.js

@@ -39,7 +39,7 @@
 import { createHash } from 'node:crypto';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, join, relative, resolve, sep } from 'node:path';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { readJsonWithWarning } from './config-validation.js';
 import { uncertainDetectionMessage } from './detection.js';
 import { FrameworkRegistry } from './framework-registry.js';
@@ -147,34 +147,127 @@ function collectRelFiles(dir) {
     walk(dir, '');
     return out;
 }
+/** An object-valued manifest section, or `{}` when absent/malformed. */
+function manifestSection(data, key) {
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+        return {};
+    }
+    const section = data[key];
+    if (section === null ||
+        typeof section !== 'object' ||
+        Array.isArray(section)) {
+        return {};
+    }
+    return section;
+}
 /**
- * Return `{dirName: {name, hash}}` from the manifest, or `{}` when absent or
- * unreadable (provenance is best-effort).
+ * Read the whole manifest document (skills + workflows). Both sections default
+ * to `{}` when the file is absent, unreadable, or malformed -- provenance is
+ * best-effort and never blocks a deploy.
  */
-function readDeployManifest(targetSkillsDir) {
+function readManifestDoc(targetSkillsDir) {
     const manifestPath = join(targetSkillsDir, DEPLOY_MANIFEST_NAME);
     let data;
     try {
         data = JSON.parse(readFileSync(manifestPath, 'utf-8'));
     }
     catch {
-        return {};
+        return { skills: {}, workflows: {} };
     }
-    if (data === null || typeof data !== 'object' || Array.isArray(data))
-        return {};
-    const skills = data['skills'];
-    if (skills === null || typeof skills !== 'object' || Array.isArray(skills)) {
-        return {};
-    }
-    return skills;
+    return {
+        skills: manifestSection(data, 'skills'),
+        workflows: manifestSection(data, 'workflows'),
+    };
 }
-function writeDeployManifest(targetSkillsDir, skills) {
+/**
+ * Write the manifest. Read-modify-write of the whole document, because the
+ * skill-deploy phase and the workflow-install phase each own one section and
+ * both write this one file. `workflows` is omitted entirely when empty so a
+ * skills-only manifest keeps its historical bytes.
+ */
+function writeManifestDoc(targetSkillsDir, doc) {
     const manifestPath = join(targetSkillsDir, DEPLOY_MANIFEST_NAME);
     mkdirSync(targetSkillsDir, { recursive: true });
-    const body = ensureAscii(JSON.stringify({ schemaVersion: 1, skills }, null, 2)) + '\n';
+    const payload = {
+        schemaVersion: 1,
+        skills: doc.skills,
+    };
+    if (Object.keys(doc.workflows).length > 0)
+        payload['workflows'] = doc.workflows;
+    const body = ensureAscii(JSON.stringify(payload, null, 2)) + '\n';
     writeFileSync(manifestPath, body, 'utf-8');
 }
 // ---------------------------------------------------------------------------
+// Workflow templates (#459)
+// ---------------------------------------------------------------------------
+/** Frontmatter key: templates this skill installs into `.github/workflows/`. */
+const WORKFLOW_DECL_KEY = 'install_workflows';
+/** Frontmatter key: the version stamped into the deploy manifest. */
+const WORKFLOW_VERSION_KEY = 'workflow_template_version';
+/** Default when a skill declares templates but no explicit version. */
+const WORKFLOW_DEFAULT_VERSION = '1';
+/**
+ * An optional `<shape>:` prefix on a declared entry, e.g.
+ * `api:templates/guardian-api.yml`. Two or more leading characters are required
+ * so a Windows drive letter (`C:\...`) can never be mistaken for a shape -- such
+ * a path is refused by {@link resolveTemplatePath} instead.
+ */
+const _WORKFLOW_ENTRY_RE = /^([A-Za-z][A-Za-z0-9_-]+):(.+)$/;
+function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/** File bytes, or null when unreadable (e.g. the path is a directory). */
+function readBytesOrNull(path) {
+    try {
+        return readFileSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The workflow declaration in a skill's SKILL.md frontmatter.
+ *
+ * Parsed here rather than on {@link SkillInfo} because these fields are
+ * migrator-specific: the registry's job is discovery, and every other consumer
+ * of `SkillInfo` would carry two fields it never reads.
+ */
+function readWorkflowDeclaration(skillMd) {
+    const text = readTextOrNull(skillMd);
+    if (text === null)
+        return { entries: [], version: WORKFLOW_DEFAULT_VERSION };
+    const fm = SkillRegistry.parseFrontmatter(text);
+    const entries = SkillRegistry.parseStrList(fm, WORKFLOW_DECL_KEY);
+    const rawVersion = fm[WORKFLOW_VERSION_KEY];
+    const version = typeof rawVersion === 'string' && rawVersion.trim()
+        ? rawVersion.trim()
+        : WORKFLOW_DEFAULT_VERSION;
+    return { entries, version };
+}
+/** Split `[<shape>:]<relative-path>` into its shape filter and path. */
+function parseWorkflowEntry(entry) {
+    const m = _WORKFLOW_ENTRY_RE.exec(entry.trim());
+    if (m === null)
+        return [null, entry.trim()];
+    return [m[1].toLowerCase(), m[2].trim()];
+}
+/**
+ * Resolve a declared template path inside *skillDir*, or null when it escapes.
+ *
+ * An overlay is third-party content, so a declared path is untrusted input: an
+ * absolute path or a `..` climb would let an overlay copy an arbitrary file
+ * from the machine running `migrate` into the consumer's CI directory.
+ */
+function resolveTemplatePath(skillDir, rel) {
+    if (!rel || isAbsolute(rel) || /^[A-Za-z]:/.test(rel))
+        return null;
+    const base = resolve(skillDir);
+    const full = resolve(base, rel);
+    if (full !== base && !full.startsWith(base + sep))
+        return null;
+    return full;
+}
+// ---------------------------------------------------------------------------
 // Constants / probes
 // ---------------------------------------------------------------------------
 /**
@@ -416,6 +509,43 @@ export class SkillDeployResult {
         this.note = note;
     }
 }
+/**
+ * The outcome of installing one declared workflow template (#459).
+ *
+ * `status` is one of:
+ *   - `installed` -- the target had no such workflow; it was written
+ *   - `skipped`   -- byte-identical to the template; nothing to do
+ *   - `outdated`  -- differs, but is unmodified since canary installed it, so
+ *                    the overlay simply moved on (a template fix is waiting)
+ *   - `conflict`  -- differs and was edited locally / has unknown provenance
+ *   - `updated`   -- differed and `--force` replaced it
+ *   - `dry_run`   -- what an `--apply` run would have done
+ *   - `missing`   -- the overlay declares a template it does not ship
+ *   - `invalid`   -- the declared path escapes the skill directory (refused)
+ *
+ * `outdated` and `conflict` are REPORTS. Neither ever writes.
+ */
+export class WorkflowInstallResult {
+    /** File name under `.github/workflows/`. */
+    workflow;
+    skill_name;
+    status;
+    detail;
+    constructor(workflow, skill_name, status, detail = '') {
+        this.workflow = workflow;
+        this.skill_name = skill_name;
+        this.status = status;
+        this.detail = detail;
+    }
+    to_dict() {
+        return {
+            workflow: this.workflow,
+            skill_name: this.skill_name,
+            status: this.status,
+            detail: this.detail,
+        };
+    }
+}
 export class SkillFreshnessResult {
     skill_name;
     dir_name;
@@ -433,10 +563,21 @@ export class FreshnessReport {
     shape;
     overlay_path;
     results;
-    constructor(shape, overlay_path = null, results = []) {
+    /**
+     * What a workflow install WOULD do (#459) -- informational only.
+     *
+     * Deliberately excluded from `has_drift` / `has_local_edits` / `exit_code`:
+     * the freshness gate speaks for overlay-owned skills, and a consumer's
+     * `.github/workflows/` is not overlay-owned. Failing CI because someone
+     * hand-tuned their own workflow, or has not adopted one at all, would be
+     * nagging about something canary has no claim over.
+     */
+    workflows;
+    constructor(shape, overlay_path = null, results = [], workflows = []) {
         this.shape = shape;
         this.overlay_path = overlay_path;
         this.results = results;
+        this.workflows = workflows;
     }
     get stale() {
         return this.results.filter((r) => r.status === 'stale' || r.status === 'missing');
@@ -475,6 +616,7 @@ export class FreshnessReport {
                 status: r.status,
                 detail: r.detail,
             })),
+            workflows: this.workflows.map((r) => r.to_dict()),
         };
     }
     to_markdown() {
@@ -486,6 +628,7 @@ export class FreshnessReport {
         ];
         if (this.results.length === 0) {
             lines.push("_No overlay skills match this project's shape._", '');
+            lines.push(...workflowMarkdown(this.workflows, false));
             return lines.join('\n');
         }
         if (this.in_sync) {
@@ -514,9 +657,37 @@ export class FreshnessReport {
                 'edits above (revert them, or upstream them into the overlay) ' +
                 'before the freshness gate can pass.', '');
         }
+        lines.push(...workflowMarkdown(this.workflows, false));
         return lines.join('\n');
     }
 }
+/**
+ * Render the workflow-install section shared by both reports.
+ *
+ * The closing note is not decoration: it is the only place a consumer is told
+ * that a reported difference will never be applied behind their back, and how
+ * to opt in when they do want the overlay's version.
+ */
+function workflowMarkdown(results, dryRun) {
+    if (results.length === 0)
+        return [];
+    const heading = dryRun
+        ? '## Workflows (would install into `.github/workflows/`)'
+        : '## Workflows (`.github/workflows/`)';
+    const lines = [heading, ''];
+    // Every result carries a detail; the status alone would not tell a consumer
+    // which file was touched or what to do next.
+    for (const r of results) {
+        lines.push(`- \`${r.workflow}\` ${EMDASH} ${r.detail}`);
+    }
+    lines.push('');
+    if (results.some((r) => r.status === 'conflict' || r.status === 'outdated')) {
+        lines.push(`${WARN} Your CI is yours: canary never overwrites a workflow that ` +
+            'differs from the template. Re-run with `--force` to take the ' +
+            "overlay's version.", '');
+    }
+    return lines;
+}
 export class MigrationReport {
     framework;
     shape;
@@ -530,6 +701,7 @@ export class MigrationReport {
     would_create;
     manual_followups;
     deployed_skills;
+    installed_workflows;
     config_warnings;
     constructor(init) {
         this.framework = init.framework;
@@ -544,6 +716,7 @@ export class MigrationReport {
         this.would_create = init.would_create ?? [];
         this.manual_followups = init.manual_followups ?? [];
         this.deployed_skills = init.deployed_skills ?? [];
+        this.installed_workflows = init.installed_workflows ?? [];
         this.config_warnings = init.config_warnings ?? [];
     }
     to_markdown() {
@@ -642,6 +815,7 @@ export class MigrationReport {
             }
             lines.push('');
         }
+        lines.push(...workflowMarkdown(this.installed_workflows, this.dry_run));
         if (this.manual_followups.length > 0) {
             lines.push('## Manual Follow-ups Required', '');
             for (const item of this.manual_followups)
@@ -719,6 +893,7 @@ export class HarnessMigrator {
         const dryRun = options.dryRun ?? true;
         const framework = options.framework ?? null;
         const overlayPath = options.overlayPath ?? null;
+        const force = options.force ?? false;
         const ctx = this.detect(projectRoot);
         if (!ctx.is_harness_project) {
             if (ctx.not_test_project_reason)
@@ -741,7 +916,9 @@ export class HarnessMigrator {
                 candidates: KNOWN_FRAMEWORKS,
                 overrideHint: '`canary migrate --framework <name>`',
             }));
-            // Issue #295 point 3: a detection miss must not block skill deployment.
+            // Issue #295 point 3: a detection miss must not block skill deployment --
+            // nor, for the same reason, the workflow install (#459). The guardian
+            // workflow is exactly what an unrecognised repo most needs.
             const deployed = this.deploySkills(shape, overlayPath, projectRoot, dryRun);
             return new MigrationReport({
                 framework: 'unknown',
@@ -752,6 +929,7 @@ export class HarnessMigrator {
                 manual_followups: followups,
                 config_warnings: ctx.config_warnings,
                 deployed_skills: deployed,
+                installed_workflows: this.installWorkflows(shape, overlayPath, projectRoot, dryRun, force),
             });
         }
         // A framework canary knows but cannot scaffold gets no config boilerplate.
@@ -768,6 +946,9 @@ export class HarnessMigrator {
         const preserved = this.findExistingTests(projectRoot);
         const scaffolder = new Scaffolder();
         const deployed = this.deploySkills(shape, overlayPath, projectRoot, dryRun);
+        // Post-copy install phase: the template bytes already landed under
+        // .canary/skills/ with the skill; this puts them where Actions looks.
+        const installedWorkflows = this.installWorkflows(shape, overlayPath, projectRoot, dryRun, force);
         if (dryRun) {
             const tmpl = TEMPLATES[effectiveFramework];
             const files = tmpl?.files ?? {};
@@ -788,6 +969,7 @@ export class HarnessMigrator {
                 preserved_files: preserved,
                 manual_followups: followups,
                 deployed_skills: deployed,
+                installed_workflows: installedWorkflows,
                 config_warnings: ctx.config_warnings,
             });
         }
@@ -804,6 +986,7 @@ export class HarnessMigrator {
             preserved_files: preserved,
             manual_followups: followups,
             deployed_skills: deployed,
+            installed_workflows: installedWorkflows,
             config_warnings: ctx.config_warnings,
         });
     }
@@ -873,7 +1056,8 @@ export class HarnessMigrator {
         const results = [];
         const skillsToDeploy = this.collectOverlaySkills(shape, overlayPath);
         const targetSkillsDir = join(targetRoot, '.canary', 'skills');
-        const manifest = readDeployManifest(targetSkillsDir);
+        const doc = readManifestDoc(targetSkillsDir);
+        const manifest = doc.skills;
         let manifestDirty = false;
         for (const [info, skillDir] of skillsToDeploy) {
             const dirName = basename(skillDir);
@@ -918,7 +1102,117 @@ export class HarnessMigrator {
             results.push(new SkillDeployResult(info.name, 'copied'));
         }
         if (manifestDirty && !dryRun)
-            writeDeployManifest(targetSkillsDir, manifest);
+            writeManifestDoc(targetSkillsDir, doc);
+        return results;
+    }
+    /**
+     * Install the workflow templates the shape-matching overlay skills declare
+     * into the target's `.github/workflows/` (#459).
+     *
+     * This runs AFTER the skill copy and is a distinct phase, not an extension of
+     * it: the bytes already arrive (whole skill dirs are copied, templates
+     * included) -- what was missing is putting them where GitHub Actions looks.
+     *
+     * **Ownership deliberately differs from `deploySkills`.** Deployed skills are
+     * owned one-way by the overlay (#334); a consumer's CI is NOT. Absent ->
+     * write. Byte-identical -> no-op. Different -> report and leave alone, always,
+     * whatever the provenance. `force` is the deliberate escape hatch. Clobbering
+     * a hand-tuned workflow -- or nagging that it is "stale" via an exit code --
+     * would be a worse failure than the partial adoption this fixes.
+     *
+     * Shape selection reuses the same resolved `canary_shape` that drives
+     * `deploy_to` matching: skills are gated by {@link collectOverlaySkills}, and
+     * an entry may additionally carry a `<shape>:` prefix to pick a variant.
+     */
+    installWorkflows(shape, overlayPath, targetRoot, dryRun, force = false) {
+        const results = [];
+        const skills = this.collectOverlaySkills(shape, overlayPath);
+        const targetSkillsDir = join(targetRoot, '.canary', 'skills');
+        const doc = readManifestDoc(targetSkillsDir);
+        const workflowsDir = join(targetRoot, '.github', 'workflows');
+        let manifestDirty = false;
+        for (const [info, skillDir] of skills) {
+            const { entries, version } = readWorkflowDeclaration(info.path);
+            for (const entry of entries) {
+                const [wantShape, rel] = parseWorkflowEntry(entry);
+                if (wantShape !== null && wantShape !== shape && wantShape !== 'all') {
+                    continue;
+                }
+                const src = resolveTemplatePath(skillDir, rel);
+                if (src === null) {
+                    results.push(new WorkflowInstallResult(basename(rel), info.name, 'invalid', `declared template '${rel}' resolves outside the skill directory ` +
+                        `${EMDASH} refused`));
+                    continue;
+                }
+                if (!isFile(src)) {
+                    results.push(new WorkflowInstallResult(basename(rel), info.name, 'missing', `the overlay declares '${rel}' but does not ship it`));
+                    continue;
+                }
+                const name = basename(src);
+                const dest = join(workflowsDir, name);
+                const templateBytes = readFileSync(src);
+                const templateHash = sha256(templateBytes);
+                const record = () => {
+                    doc.workflows[name] = {
+                        skill: info.name,
+                        template: rel,
+                        version,
+                        hash: templateHash,
+                    };
+                    manifestDirty = true;
+                };
+                const install = () => {
+                    mkdirSync(workflowsDir, { recursive: true });
+                    writeFileSync(dest, templateBytes);
+                    record();
+                };
+                const push = (status, detail) => {
+                    results.push(new WorkflowInstallResult(name, info.name, status, detail));
+                };
+                if (!existsSync(dest)) {
+                    if (dryRun) {
+                        push('dry_run', `would install .github/workflows/${name} (v${version})`);
+                        continue;
+                    }
+                    install();
+                    push('installed', `installed .github/workflows/${name} (v${version})`);
+                    continue;
+                }
+                const installedBytes = readBytesOrNull(dest);
+                if (installedBytes !== null && installedBytes.equals(templateBytes)) {
+                    // Back-fill provenance for a hand-placed but identical file so a later
+                    // template fix can be reported as `outdated` rather than `conflict`.
+                    if (doc.workflows[name]?.hash !== templateHash)
+                        record();
+                    push('skipped', `.github/workflows/${name} already current`);
+                    continue;
+                }
+                if (force) {
+                    if (dryRun) {
+                        push('dry_run', `would overwrite .github/workflows/${name} with v${version} (--force)`);
+                        continue;
+                    }
+                    install();
+                    push('updated', `overwrote .github/workflows/${name} with v${version} (--force)`);
+                    continue;
+                }
+                const recorded = doc.workflows[name];
+                const untouched = installedBytes !== null &&
+                    recorded !== undefined &&
+                    recorded.hash === sha256(installedBytes);
+                if (untouched) {
+                    push('outdated', `.github/workflows/${name} is at v${recorded.version}, the overlay ` +
+                        `ships v${version} ${EMDASH} unmodified since install, so re-run ` +
+                        'with --force to take the update');
+                    continue;
+                }
+                push('conflict', `.github/workflows/${name} differs from the overlay template and was ` +
+                    `left untouched ${EMDASH} your CI is yours; re-run with --force to ` +
+                    'replace it');
+            }
+        }
+        if (manifestDirty && !dryRun)
+            writeManifestDoc(targetSkillsDir, doc);
         return results;
     }
     /**
@@ -937,7 +1231,7 @@ export class HarnessMigrator {
         const shape = ctx.detected_shape;
         const skills = this.collectOverlaySkills(shape, overlayPath);
         const targetSkillsDir = join(projectRoot, '.canary', 'skills');
-        const manifest = readDeployManifest(targetSkillsDir);
+        const manifest = readManifestDoc(targetSkillsDir).skills;
         const results = [];
         for (const [info, skillDir] of skills) {
             const dirName = basename(skillDir);
@@ -960,7 +1254,10 @@ export class HarnessMigrator {
                 results.push(new SkillFreshnessResult(info.name, dirName, 'local_edit', 'deployed skill has local edits; refusing to overwrite'));
             }
         }
-        return new FreshnessReport(shape, overlayPath !== null ? String(overlayPath) : null, results);
+        return new FreshnessReport(shape, overlayPath !== null ? String(overlayPath) : null, results, 
+        // dryRun = true: `--check` reports what an install WOULD do and never
+        // writes. Informational only -- see FreshnessReport.workflows.
+        this.installWorkflows(shape, overlayPath, projectRoot, true, false));
     }
     detectFramework(root, config) {
         // 0. Explicit override in .canary/company.json ("canary_shape" field).

package/dist/engine/guardian/agent-tier.js

@@ -181,7 +181,11 @@ export class AuthoringContext {
     effective_tier; // from resolveTier (2 == can author)
     is_fork; // reuse Phase-2 fork/403 detection -- (b)
     repo_root; // collision + sentinel base
-    authored_sentinel_present; // loop-guard -- (a)
+    // loop-guard -- (a). True only when a sentinel stamped at the CURRENT HEAD
+    // exists (#456): the caller resolves the stamp, and every unverifiable state
+    // (missing/unreadable/malformed sentinel, unresolvable HEAD) passes `false`
+    // so authoring fails OPEN.
+    authored_sentinel_present;
     constructor(author_tests_optin, effective_tier, init = {}) {
         this.author_tests_optin = author_tests_optin;
         this.effective_tier = effective_tier;
@@ -256,7 +260,8 @@ function authoringSkipReason(gap, ctx) {
         return `fork: read-only ${EM_DASH} guardian never writes on a fork PR`;
     }
     if (ctx.authored_sentinel_present) {
-        return `loop-guard: guardian tests already authored this run ${EM_DASH} not re-authoring`;
+        return (`loop-guard: guardian tests already authored at this HEAD ${EM_DASH} ` +
+            `review and commit them to re-enable authoring`);
     }
     const target = joinPosix(ctx.repo_root, targetTestPath(gap));
     if (existsSync(target)) {