canary-test-cli 5.15.0 → 6.0.0

package/dist/engine/core/migrator.js

@@ -0,0 +1,1112 @@
+/**
+ * Canary Migrator -- detects harness-scaffolded test-suite projects and migrates
+ * them to Canary's layout without touching existing test files.
+ *
+ * Faithful TypeScript port of `agent/core/migrator.py`.
+ *
+ * Python->TS nuances:
+ *   - `_PYTHON_DEP_PATTERNS` are `re.MULTILINE | re.IGNORECASE` `^`-anchored
+ *     patterns. Python `re.MULTILINE` anchors `^` on `\n` ONLY, whereas JS `^`
+ *     under the `m` flag also breaks on `\r`, U+2028 and U+2029. To preserve the
+ *     oracle exactly, these do NOT use the `m` flag: the `^` is expressed as
+ *     `(?:^|(?<=\n))` (start-of-string OR immediately after a `\n`), and
+ *     `re.IGNORECASE` maps to the `i` flag. The remaining regexes
+ *     (`_PW_UI_FIXTURE_RE`, `_PACKAGE_SCRIPT_PATTERNS`) contain no `^`/`$`
+ *     anchors, so `re.MULTILINE` there is a no-op and is dropped. None of these
+ *     regexes carry the `g` flag, so `.test()` is not stateful.
+ *   - Skill directories are copied with `cpSync(..., {recursive:true})`
+ *     (shutil.copytree) and removed with `rmSync(..., {recursive:true,
+ *     force:true})` (shutil.rmtree). The deploy manifest is `writeFileSync`'d as
+ *     `JSON.stringify(..., 2) + "\n"` run through {@link ensureAscii} to match
+ *     `json.dumps(indent=2)` (ensure_ascii defaults to True). Python text-mode
+ *     writes `\n` verbatim on POSIX; `writeFileSync` does the same. The manifest
+ *     is round-tripped only by this module, so the file content is an internal
+ *     contract, not a cross-runtime one.
+ *   - `_hash_skill_dir` hashes the sorted `(relative-posix-path, bytes)` pairs of
+ *     every file under a skill dir. Hashes are only ever compared between two
+ *     invocations of THIS function (overlay vs. deployed, or vs. the recorded
+ *     manifest hash), so the sort must merely be internally consistent; sorting
+ *     by relative-posix-path string matches Python's Path ordering for the flat /
+ *     shallow ASCII skill trees in play.
+ *   - Human-facing markdown keeps the exact glyphs the oracle emits (checkmark
+ *     U+2705, warning sign U+26A0, em-dash U+2014); they are written as `\u{...}`
+ *     escapes so this source stays ASCII while the emitted bytes are identical.
+ *   - `Path.home()` (the `~/.canary/skills` overlay tier) is an injectable
+ *     constructor argument (defaults to `os.homedir()`), the same test seam the
+ *     skill-registry port uses -- Python patches `Path.home()` in its tests.
+ *   - Python truthiness (`""`/`None`/`{}`/`[]` falsy) via {@link pyTruthy}.
+ */
+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 { readJsonWithWarning } from './config-validation.js';
+import { uncertainDetectionMessage } from './detection.js';
+import { FrameworkRegistry } from './framework-registry.js';
+import { Scaffolder, scaffoldableFrameworks, TEMPLATES } from './scaffolder.js';
+import { SkillRegistry } from './skill-registry.js';
+// ---------------------------------------------------------------------------
+// Python-compatibility helpers (copied locally per-module, matching reporter.ts)
+// ---------------------------------------------------------------------------
+/** Python-truthiness (`null`/`undefined`/`false`/`0`/`""`/`[]`/`{}` falsy). */
+function pyTruthy(value) {
+    if (value === null || value === undefined || value === false)
+        return false;
+    if (value === 0 || value === '')
+        return false;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === 'object')
+        return Object.keys(value).length > 0;
+    return Boolean(value);
+}
+/**
+ * Reproduce `json.dumps(..., ensure_ascii=True)` on `JSON.stringify` output:
+ * escape every code point >= 0x80 as `\uXXXX`. (Same helper as reporter.ts.)
+ */
+function ensureAscii(json) {
+    return json.replace(/[\u0080-\uffff]/g, (ch) => '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0'));
+}
+// Non-ASCII glyphs kept out of the source text as escapes, emitted verbatim.
+const CHECK = '\u{2705}'; // white heavy check mark
+const WARN = '\u{26A0}'; // warning sign
+const EMDASH = '\u{2014}'; // em dash
+// ---------------------------------------------------------------------------
+// Deploy manifest
+// ---------------------------------------------------------------------------
+// Records the content hash of each skill at deploy time so the freshness gate
+// can tell an untouched deployment (safe to refresh) from a hand-edited one.
+// Lives beside the deployed skills; never a deployable skill itself (leading dot
+// -> skipped by the skill scanner).
+export const DEPLOY_MANIFEST_NAME = '.deploy-manifest.json';
+/**
+ * Order two POSIX-style relative paths the way Python orders `Path` objects:
+ * component-wise (`PurePath.__lt__` compares the parts list), NOT as joined
+ * strings. They differ when a directory name prefixes a sibling file name and
+ * the next char sorts below '/' (0x2F) -- most commonly the '.' extension
+ * separator, e.g. `scripts/run.sh` vs `scripts.md`. A joined-string sort places
+ * `scripts.md` first ('.' 0x2E < '/' 0x2F); Python's component sort places
+ * `scripts/run.sh` first ('scripts' < 'scripts.md'). This ordering feeds the
+ * skill-dir hash, a byte-exact contract compared against Python-written
+ * .deploy-manifest.json files on the upgrade path.
+ */
+function comparePathParts(a, b) {
+    const pa = a.split('/');
+    const pb = b.split('/');
+    const n = Math.min(pa.length, pb.length);
+    for (let i = 0; i < n; i++) {
+        if (pa[i] < pb[i])
+            return -1;
+        if (pa[i] > pb[i])
+            return 1;
+    }
+    return pa.length - pb.length;
+}
+/**
+ * A stable sha256 of every file under *skillDir* (component-sorted rel-path +
+ * bytes). Exported so a test can pin it byte-for-byte to the Python oracle:
+ * this hash is compared against Python-written .deploy-manifest.json files on
+ * the upgrade path, so any drift misclassifies untouched skills.
+ */
+export function hashSkillDir(skillDir) {
+    const h = createHash('sha256');
+    const rels = collectRelFiles(skillDir).sort(comparePathParts);
+    for (const rel of rels) {
+        h.update(Buffer.from(rel, 'utf-8'));
+        h.update(NUL);
+        try {
+            h.update(readFileSync(join(skillDir, rel.split('/').join(sep))));
+        }
+        catch {
+            // OSError -> Python `pass`; the two NUL separators are still written.
+        }
+        h.update(NUL);
+    }
+    return h.digest('hex');
+}
+const NUL = Buffer.from([0]);
+/** Relative (posix-joined) paths of every file under *dir*, recursively. */
+function collectRelFiles(dir) {
+    const out = [];
+    const walk = (d, prefix) => {
+        let entries;
+        try {
+            entries = readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const rel = prefix ? `${prefix}/${e.name}` : e.name;
+            if (e.isDirectory())
+                walk(join(d, e.name), rel);
+            else if (e.isFile())
+                out.push(rel);
+        }
+    };
+    walk(dir, '');
+    return out;
+}
+/**
+ * Return `{dirName: {name, hash}}` from the manifest, or `{}` when absent or
+ * unreadable (provenance is best-effort).
+ */
+function readDeployManifest(targetSkillsDir) {
+    const manifestPath = join(targetSkillsDir, DEPLOY_MANIFEST_NAME);
+    let data;
+    try {
+        data = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+    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;
+}
+function writeDeployManifest(targetSkillsDir, skills) {
+    const manifestPath = join(targetSkillsDir, DEPLOY_MANIFEST_NAME);
+    mkdirSync(targetSkillsDir, { recursive: true });
+    const body = ensureAscii(JSON.stringify({ schemaVersion: 1, skills }, null, 2)) + '\n';
+    writeFileSync(manifestPath, body, 'utf-8');
+}
+// ---------------------------------------------------------------------------
+// Constants / probes
+// ---------------------------------------------------------------------------
+/**
+ * Frameworks a user can pass to `canary migrate --framework <name>`. Surfaced in
+ * the fail-loud message when auto-detection is uncertain (issue #295).
+ */
+export const KNOWN_FRAMEWORKS = [
+    'playwright',
+    'vitest',
+    'pytest',
+    'k6',
+    'wdio',
+    'locust',
+];
+// Layer names that mark a skills/docs *overlay* rather than a test suite (#319 C).
+const _DOC_SKILL_LAYER_NAMES = new Set([
+    'skills',
+    'docs',
+    'guides',
+    'agents',
+    'overlays',
+    'commands',
+    'prompts',
+]);
+// (config_file, framework, shape, confidence)
+const _CONFIG_PROBES = [
+    ['playwright.config.ts', 'playwright', 'e2e_ui', 'config'],
+    ['playwright.config.js', 'playwright', 'e2e_ui', 'config'],
+    ['cypress.config.ts', 'playwright', 'e2e_ui', 'config'],
+    ['cypress.config.js', 'playwright', 'e2e_ui', 'config'],
+    ['vitest.config.ts', 'vitest', 'frontend_unit', 'config'],
+    ['vitest.config.js', 'vitest', 'frontend_unit', 'config'],
+    ['vitest.config.mts', 'vitest', 'frontend_unit', 'config'],
+    ['jest.config.ts', 'vitest', 'frontend_unit', 'config'],
+    ['jest.config.js', 'vitest', 'frontend_unit', 'config'],
+    ['jest.config.mjs', 'vitest', 'frontend_unit', 'config'],
+    ['k6.config.js', 'k6', 'performance', 'config'],
+    ['pytest.ini', 'pytest', 'api', 'config'],
+    ['setup.cfg', 'pytest', 'api', 'config'],
+    ['axe.config.js', 'axe-core', 'accessibility', 'config'],
+    ['backstop.json', 'backstopjs', 'visual', 'config'],
+    ['pact.json', 'pact', 'contract', 'config'],
+    ['.pact', 'pact', 'contract', 'config'],
+    ['stryker.config.js', 'stryker', 'mutation', 'config'],
+    ['stryker.config.mjs', 'stryker', 'mutation', 'config'],
+    ['locust.conf', 'locust', 'load', 'config'],
+    ['locustfile.py', 'locust', 'load', 'config'],
+    ['wdio.conf.ts', 'wdio', 'mobile', 'config'],
+    ['wdio.conf.js', 'wdio', 'mobile', 'config'],
+    ['wdio.conf.mjs', 'wdio', 'mobile', 'config'],
+];
+// pyproject.toml section markers
+const _PYPROJECT_MARKERS = [
+    ['[tool.pytest.ini_options]', 'pytest', 'api'],
+    ['[tool.coverage', 'pytest', 'api'],
+];
+// package.json test script -> (framework, shape)
+const _PACKAGE_SCRIPT_PATTERNS = [
+    [/\bplaywright\b/, 'playwright', 'e2e_ui'],
+    [/\bcypress\b/, 'playwright', 'e2e_ui'],
+    [/\bvitest\b/, 'vitest', 'frontend_unit'],
+    [/\bjest\b/, 'vitest', 'frontend_unit'],
+    [/\bk6\b/, 'k6', 'performance'],
+    [/\blocust\b/, 'locust', 'load'],
+    [/\bstryker\b/, 'stryker', 'mutation'],
+    [/\bwdio\b/, 'wdio', 'mobile'],
+];
+// Python dependency -> (framework, shape). MULTILINE `^` anchored on `\n` only.
+const _PYTHON_DEP_PATTERNS = [
+    [/(?:^|(?<=\n))pytest\b/i, 'pytest', 'api'],
+    [/(?:^|(?<=\n))locust\b/i, 'locust', 'load'],
+    [/(?:^|(?<=\n))pact\b/i, 'pact', 'contract'],
+    [/(?:^|(?<=\n))sdv\b/i, 'sdv', 'synthetic_data'],
+    [/(?:^|(?<=\n))faker\b/i, 'faker', 'synthetic_data'],
+    [/(?:^|(?<=\n))testcontainers\b/i, 'testcontainers', 'integration'],
+];
+// Language -> (framework, shape) fallbacks from harness.config.json
+const _LANGUAGE_FALLBACKS = {
+    python: ['pytest', 'api'],
+    typescript: ['playwright', 'e2e_ui'],
+    javascript: ['playwright', 'e2e_ui'],
+};
+const _TEST_GLOBS = [
+    'tests/**/*.py',
+    'test/**/*.py',
+    'tests/**/*.spec.ts',
+    'tests/**/*.test.ts',
+    'tests/**/*.spec.js',
+    'tests/**/*.test.js',
+    'src/**/*.spec.ts',
+    'src/**/*.test.ts',
+];
+// Detects playwright UI fixture params. MULTILINE is a no-op (no `^`/`$`).
+const _PW_UI_FIXTURE_RE = /async\s*\(\s*\{[^}]*\b(?:page|browser)\b/;
+// ---------------------------------------------------------------------------
+// Small filesystem / glob helpers
+// ---------------------------------------------------------------------------
+function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Compile a single glob segment (with `*` -> `[^/]*`) to an anchored regex. */
+function segGlobRegex(seg) {
+    const body = seg
+        .replace(/[.+^${}()|[\]\\?]/g, '\\$&')
+        .replace(/\*/g, '[^/]*');
+    return new RegExp(`^${body}$`);
+}
+/**
+ * Match files under *root* against a pathlib-style glob (`**` matches zero or
+ * more directories; `*` matches within a single segment). Mirrors the subset of
+ * `Path.glob` the migrator needs.
+ */
+function globFiles(root, pattern) {
+    const segments = pattern.split('/');
+    const out = [];
+    const visit = (dir, si) => {
+        const seg = segments[si];
+        const last = si === segments.length - 1;
+        if (seg === '**') {
+            // `**` consumes zero directories -> continue at the same dir.
+            visit(dir, si + 1);
+            // `**` consumes one-or-more -> descend into each subdir, staying on `**`.
+            for (const d of subDirs(dir))
+                visit(d, si);
+            return;
+        }
+        const re = segGlobRegex(seg);
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (!re.test(e.name))
+                continue;
+            const full = join(dir, e.name);
+            if (last) {
+                if (e.isFile() || isFile(full))
+                    out.push(full);
+            }
+            else if (e.isDirectory()) {
+                visit(full, si + 1);
+            }
+        }
+    };
+    visit(root, 0);
+    return out;
+}
+function subDirs(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => join(dir, e.name));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Return a human reason when *config* describes a skills/docs overlay (not a
+ * migratable test suite), else null. Conservative: fires only when there are no
+ * test `entryPoints` AND every declared layer is a docs/skills layer.
+ */
+function skillsDocsOverlayReason(config) {
+    if (pyTruthy(config['entryPoints']))
+        return null;
+    const layersRaw = config['layers'];
+    // Python does `config.get("layers") or []` then `for layer in layers`. If
+    // `layers` is a truthy non-list (e.g. a dict), Python iterates its keys --
+    // none pass the isinstance(dict) check, so `names` ends up empty and the
+    // result is unchanged from []. Casting a non-array to `unknown[]` and using
+    // for-of would instead THROW (not iterable), crashing detect()/migrate() on a
+    // malformed config the oracle tolerates. Only a real array yields entries.
+    const layers = Array.isArray(layersRaw) ? layersRaw : [];
+    const names = new Set();
+    for (const layer of layers) {
+        if (layer !== null && typeof layer === 'object' && !Array.isArray(layer)) {
+            const raw = layer['name'];
+            const name = (pyTruthy(raw) ? String(raw) : '').toLowerCase();
+            names.add(name);
+        }
+    }
+    names.delete('');
+    const subsetOfDocSkill = [...names].every((n) => _DOC_SKILL_LAYER_NAMES.has(n));
+    if (names.size === 0 || !subsetOfDocSkill)
+        return null;
+    const sortedNames = [...names].sort().join(', ');
+    return ('harness.config.json and .harness/ are present, but this looks like a ' +
+        'skills/docs overlay (no test entryPoints; layers are only ' +
+        `${sortedNames}), not a test suite. \`canary migrate\` ` +
+        'scaffolds a test suite and has nothing to migrate here.');
+}
+export class MigrationContext {
+    project_root;
+    is_harness_project;
+    harness_config;
+    detected_framework;
+    detected_shape;
+    detection_source;
+    /** "config" | "content" | "language" | "none" */
+    detection_confidence;
+    config_warnings;
+    not_test_project_reason;
+    constructor(init) {
+        this.project_root = init.project_root;
+        this.is_harness_project = init.is_harness_project;
+        this.harness_config = init.harness_config ?? {};
+        this.detected_framework = init.detected_framework ?? null;
+        this.detected_shape = init.detected_shape ?? 'unknown';
+        this.detection_source = init.detection_source ?? 'none';
+        this.detection_confidence = init.detection_confidence ?? 'none';
+        this.config_warnings = init.config_warnings ?? [];
+        this.not_test_project_reason = init.not_test_project_reason ?? null;
+    }
+}
+export class SkillDeployResult {
+    skill_name;
+    /** "copied" | "updated" | "skipped" | "dry_run" */
+    status;
+    note;
+    constructor(skill_name, status, note = '') {
+        this.skill_name = skill_name;
+        this.status = status;
+        this.note = note;
+    }
+}
+export class SkillFreshnessResult {
+    skill_name;
+    dir_name;
+    /** "current" | "stale" | "missing" | "local_edit" */
+    status;
+    detail;
+    constructor(skill_name, dir_name, status, detail = '') {
+        this.skill_name = skill_name;
+        this.dir_name = dir_name;
+        this.status = status;
+        this.detail = detail;
+    }
+}
+export class FreshnessReport {
+    shape;
+    overlay_path;
+    results;
+    constructor(shape, overlay_path = null, results = []) {
+        this.shape = shape;
+        this.overlay_path = overlay_path;
+        this.results = results;
+    }
+    get stale() {
+        return this.results.filter((r) => r.status === 'stale' || r.status === 'missing');
+    }
+    get local_edits() {
+        return this.results.filter((r) => r.status === 'local_edit');
+    }
+    get has_drift() {
+        return this.stale.length > 0;
+    }
+    get has_local_edits() {
+        return this.local_edits.length > 0;
+    }
+    get in_sync() {
+        return !this.has_drift && !this.has_local_edits;
+    }
+    /** 0 in sync, 1 drift, 2 local edits (safety refusal wins). */
+    exit_code() {
+        if (this.has_local_edits)
+            return 2;
+        if (this.has_drift)
+            return 1;
+        return 0;
+    }
+    to_dict() {
+        return {
+            shape: this.shape,
+            overlay_path: this.overlay_path,
+            in_sync: this.in_sync,
+            has_drift: this.has_drift,
+            has_local_edits: this.has_local_edits,
+            exit_code: this.exit_code(),
+            skills: this.results.map((r) => ({
+                skill_name: r.skill_name,
+                dir_name: r.dir_name,
+                status: r.status,
+                detail: r.detail,
+            })),
+        };
+    }
+    to_markdown() {
+        const lines = [
+            '# Overlay Freshness',
+            '',
+            `**Shape:** ${this.shape}`,
+            '',
+        ];
+        if (this.results.length === 0) {
+            lines.push("_No overlay skills match this project's shape._", '');
+            return lines.join('\n');
+        }
+        if (this.in_sync) {
+            lines.push(`${CHECK} In sync ${EMDASH} every deployed overlay skill is current.`, '');
+        }
+        const stale = this.results.filter((r) => r.status === 'stale');
+        const missing = this.results.filter((r) => r.status === 'missing');
+        const edits = this.local_edits;
+        if (missing.length > 0) {
+            lines.push('## Missing (overlay ships, target does not carry)', '');
+            lines.push(...missing.map((r) => `- \`${r.skill_name}\``), '');
+        }
+        if (stale.length > 0) {
+            lines.push('## Stale (overlay has a newer version)', '');
+            lines.push(...stale.map((r) => `- \`${r.skill_name}\` ${EMDASH} ${r.detail}`), '');
+        }
+        if (edits.length > 0) {
+            lines.push(`## ${WARN} Local edits (refused ${EMDASH} one-way ownership)`, '');
+            lines.push(...edits.map((r) => `- \`${r.skill_name}\` ${EMDASH} ${r.detail}`), '');
+        }
+        if (this.has_drift && !this.has_local_edits) {
+            lines.push('Run `canary migrate --from <overlay> --apply` to refresh.', '');
+        }
+        else if (this.has_local_edits) {
+            lines.push('Deployed skills are owned by the overlay. Reconcile the local ' +
+                'edits above (revert them, or upstream them into the overlay) ' +
+                'before the freshness gate can pass.', '');
+        }
+        return lines.join('\n');
+    }
+}
+export class MigrationReport {
+    framework;
+    shape;
+    dry_run;
+    detection_source;
+    detection_confidence;
+    created_files;
+    created_dirs;
+    skipped_configs;
+    preserved_files;
+    would_create;
+    manual_followups;
+    deployed_skills;
+    config_warnings;
+    constructor(init) {
+        this.framework = init.framework;
+        this.shape = init.shape;
+        this.dry_run = init.dry_run;
+        this.detection_source = init.detection_source ?? '';
+        this.detection_confidence = init.detection_confidence ?? '';
+        this.created_files = init.created_files ?? [];
+        this.created_dirs = init.created_dirs ?? [];
+        this.skipped_configs = init.skipped_configs ?? [];
+        this.preserved_files = init.preserved_files ?? [];
+        this.would_create = init.would_create ?? [];
+        this.manual_followups = init.manual_followups ?? [];
+        this.deployed_skills = init.deployed_skills ?? [];
+        this.config_warnings = init.config_warnings ?? [];
+    }
+    to_markdown() {
+        const lines = ['# Canary Migration Report', ''];
+        if (this.dry_run) {
+            lines.push('> **Dry run** ' +
+                EMDASH +
+                ' no files were written. Re-run with `--apply` to migrate.', '');
+        }
+        if (this.config_warnings.length > 0) {
+            lines.push(`## ${WARN} Config Warnings`, '');
+            for (const w of this.config_warnings)
+                lines.push(`- ${w}`);
+            lines.push('');
+        }
+        lines.push(`**Framework:** ${this.framework}`, `**Shape:** ${this.shape}`);
+        if (pyTruthy(this.detection_source) &&
+            this.detection_source !== 'none' &&
+            this.detection_source !== '') {
+            const confidenceLabel = {
+                config: `high ${EMDASH} dedicated config file`,
+                content: `medium ${EMDASH} file content / dependency scan`,
+                language: `low ${EMDASH} harness.config.json language fallback`,
+            }[this.detection_confidence] ?? this.detection_confidence;
+            lines.push(`**Detected from:** \`${this.detection_source}\``, `**Confidence:** ${confidenceLabel}`);
+        }
+        lines.push('');
+        if (this.dry_run) {
+            if (this.preserved_files.length > 0) {
+                lines.push('## Existing Tests (will be preserved)', '');
+                for (const f of this.preserved_files)
+                    lines.push(`- \`${f}\``);
+                lines.push('');
+            }
+            if (this.would_create.length > 0) {
+                lines.push('## Would Create', '');
+                for (const f of this.would_create)
+                    lines.push(`- \`${f}\``);
+                lines.push('');
+            }
+            else {
+                lines.push('## Would Create', '', '_Nothing new ' +
+                    EMDASH +
+                    ' project already has all Canary config files._', '');
+            }
+            if (this.skipped_configs.length > 0) {
+                lines.push('## Already Present (will not be touched)', '');
+                for (const f of this.skipped_configs)
+                    lines.push(`- \`${f}\``);
+                lines.push('');
+            }
+        }
+        else {
+            if (this.created_files.length > 0) {
+                lines.push('## Created Files', '');
+                for (const f of this.created_files)
+                    lines.push(`- \`${f}\``);
+                lines.push('');
+            }
+            if (this.created_dirs.length > 0) {
+                lines.push('## Created Directories', '');
+                for (const d of this.created_dirs)
+                    lines.push(`- \`${d}/\``);
+                lines.push('');
+            }
+            if (this.skipped_configs.length > 0) {
+                lines.push('## Skipped (already exist)', '');
+                for (const f of this.skipped_configs) {
+                    lines.push(`- \`${f}\` ${EMDASH} preserved as-is`);
+                }
+                lines.push('');
+            }
+            if (this.preserved_files.length > 0) {
+                lines.push('## Existing Tests Preserved', '');
+                for (const f of this.preserved_files)
+                    lines.push(`- \`${f}\``);
+                lines.push('');
+            }
+        }
+        if (this.deployed_skills.length > 0) {
+            const copied = this.deployed_skills.filter((r) => r.status === 'copied' ||
+                r.status === 'dry_run' ||
+                r.status === 'updated');
+            const skipped = this.deployed_skills.filter((r) => r.status === 'skipped');
+            const section = this.dry_run
+                ? '## Skills (would deploy)'
+                : '## Skills Deployed';
+            lines.push(section, '');
+            for (const r of copied) {
+                const prefix = r.status === 'dry_run' ? '(dry run) ' : '';
+                const verb = r.status === 'updated' ? 'refreshed in' : 'copied to';
+                lines.push(`- \`${r.skill_name}\` ${EMDASH} ${prefix}${verb} \`.canary/skills/\``);
+            }
+            for (const r of skipped) {
+                lines.push(`- \`${r.skill_name}\` ${EMDASH} skipped (${r.note})`);
+            }
+            lines.push('');
+        }
+        if (this.manual_followups.length > 0) {
+            lines.push('## Manual Follow-ups Required', '');
+            for (const item of this.manual_followups)
+                lines.push(`- ${item}`);
+            lines.push('');
+        }
+        else {
+            lines.push('## Status', '', 'Migration complete. Run `canary recommend "<test description>"` to verify framework detection.', '');
+        }
+        return lines.join('\n');
+    }
+}
+/** Detects harness test-suite projects and migrates them to Canary's layout. */
+export class HarnessMigrator {
+    home;
+    /** `home` is a TS-only test seam (Python patches `Path.home()`). */
+    constructor(home) {
+        this.home = home ?? homedir();
+    }
+    detect(projectRoot) {
+        const hasConfig = existsSync(join(projectRoot, 'harness.config.json'));
+        const hasHarnessDir = isDir(join(projectRoot, '.harness'));
+        const isHarness = hasConfig && hasHarnessDir;
+        if (!isHarness) {
+            return new MigrationContext({
+                project_root: projectRoot,
+                is_harness_project: false,
+            });
+        }
+        const configWarnings = [];
+        const [rawConfig, warning] = readJsonWithWarning(join(projectRoot, 'harness.config.json'));
+        if (pyTruthy(warning))
+            configWarnings.push(warning);
+        let harnessConfig = pyTruthy(rawConfig)
+            ? rawConfig
+            : {};
+        // Merge canary_shape from .canary/company.json so _detectFramework can honor
+        // an explicit shape override. A malformed company.json warns but never blocks
+        // detection.
+        const canaryCompany = join(projectRoot, '.canary', 'company.json');
+        const [overlay, warning2] = readJsonWithWarning(canaryCompany);
+        if (pyTruthy(warning2))
+            configWarnings.push(warning2);
+        if (pyTruthy(overlay) &&
+            Object.prototype.hasOwnProperty.call(overlay, 'canary_shape')) {
+            harnessConfig = {
+                ...harnessConfig,
+                canary_shape: overlay['canary_shape'],
+            };
+        }
+        // #319 C: refuse a skills/docs overlay with a distinct reason.
+        const overlayReason = skillsDocsOverlayReason(harnessConfig);
+        if (overlayReason) {
+            return new MigrationContext({
+                project_root: projectRoot,
+                is_harness_project: false,
+                harness_config: harnessConfig,
+                config_warnings: configWarnings,
+                not_test_project_reason: overlayReason,
+            });
+        }
+        const [framework, shape, source, confidence] = this.detectFramework(projectRoot, harnessConfig);
+        return new MigrationContext({
+            project_root: projectRoot,
+            is_harness_project: true,
+            harness_config: harnessConfig,
+            detected_framework: framework,
+            detected_shape: shape,
+            detection_source: source,
+            detection_confidence: confidence,
+            config_warnings: configWarnings,
+        });
+    }
+    migrate(projectRoot, options = {}) {
+        const dryRun = options.dryRun ?? true;
+        const framework = options.framework ?? null;
+        const overlayPath = options.overlayPath ?? null;
+        const ctx = this.detect(projectRoot);
+        if (!ctx.is_harness_project) {
+            if (ctx.not_test_project_reason)
+                throw new Error(ctx.not_test_project_reason);
+            throw new Error(`No harness project detected at ${projectRoot}. ` +
+                'Expected harness.config.json and .harness/ directory.');
+        }
+        const effectiveFramework = pyTruthy(framework)
+            ? framework
+            : ctx.detected_framework;
+        const shape = ctx.detected_shape;
+        const source = pyTruthy(framework) ? 'CLI override' : ctx.detection_source;
+        const confidence = pyTruthy(framework)
+            ? 'config'
+            : ctx.detection_confidence;
+        const followups = [];
+        if (effectiveFramework === null) {
+            followups.push(uncertainDetectionMessage('test framework', {
+                reason: 'no config file, dependency, or language marker matched a known framework',
+                candidates: KNOWN_FRAMEWORKS,
+                overrideHint: '`canary migrate --framework <name>`',
+            }));
+            // Issue #295 point 3: a detection miss must not block skill deployment.
+            const deployed = this.deploySkills(shape, overlayPath, projectRoot, dryRun);
+            return new MigrationReport({
+                framework: 'unknown',
+                shape,
+                dry_run: dryRun,
+                detection_source: source,
+                detection_confidence: confidence,
+                manual_followups: followups,
+                config_warnings: ctx.config_warnings,
+                deployed_skills: deployed,
+            });
+        }
+        // A framework canary knows but cannot scaffold gets no config boilerplate.
+        // Surface that loudly (which also suppresses the "Migration complete" status).
+        const reg = new FrameworkRegistry();
+        if (reg.findByName(effectiveFramework) !== null &&
+            !scaffoldableFrameworks().has(effectiveFramework)) {
+            const cmd = reg.executionInfo(effectiveFramework)?.execution_command ?? null;
+            const run = pyTruthy(cmd) ? ` Run its tests via \`${cmd}\`.` : '';
+            followups.push(`No scaffold template for '${effectiveFramework}' yet ${EMDASH} the ` +
+                'layout and skills were migrated, but test config was not ' +
+                `scaffolded; set it up manually.${run}`);
+        }
+        const preserved = this.findExistingTests(projectRoot);
+        const scaffolder = new Scaffolder();
+        const deployed = this.deploySkills(shape, overlayPath, projectRoot, dryRun);
+        if (dryRun) {
+            const tmpl = TEMPLATES[effectiveFramework];
+            const files = tmpl?.files ?? {};
+            const dirs = tmpl?.dirs ?? [];
+            const wouldCreate = [
+                ...Object.keys(files).filter((f) => !existsSync(join(projectRoot, f))),
+                ...dirs.filter((d) => !existsSync(join(projectRoot, d))),
+            ];
+            const alreadyPresent = Object.keys(files).filter((f) => existsSync(join(projectRoot, f)));
+            return new MigrationReport({
+                framework: effectiveFramework,
+                shape,
+                dry_run: true,
+                detection_source: source,
+                detection_confidence: confidence,
+                would_create: wouldCreate,
+                skipped_configs: alreadyPresent,
+                preserved_files: preserved,
+                manual_followups: followups,
+                deployed_skills: deployed,
+                config_warnings: ctx.config_warnings,
+            });
+        }
+        const result = scaffolder.scaffold(effectiveFramework, String(projectRoot));
+        return new MigrationReport({
+            framework: effectiveFramework,
+            shape,
+            dry_run: false,
+            detection_source: source,
+            detection_confidence: confidence,
+            created_files: result['created_files'],
+            created_dirs: result['created_dirs'],
+            skipped_configs: result['skipped_files'],
+            preserved_files: preserved,
+            manual_followups: followups,
+            deployed_skills: deployed,
+            config_warnings: ctx.config_warnings,
+        });
+    }
+    // -- private helpers --------------------------------------------------------
+    /**
+     * Return `[[SkillInfo, skillDir], ...]` for overlay skills whose `deploy_to`
+     * matches *shape* (or the `all` sentinel). Sources: *overlayPath* first, then
+     * `~/.canary/skills/`. The first definition of a name wins.
+     */
+    collectOverlaySkills(shape, overlayPath) {
+        const candidateRoots = [];
+        if (overlayPath !== null)
+            candidateRoots.push(overlayPath);
+        const homeSkills = join(this.home, '.canary', 'skills');
+        if (isDir(homeSkills))
+            candidateRoots.push(this.home); // registry walks up
+        const reg = new SkillRegistry();
+        const collected = [];
+        const seenNames = new Set();
+        for (const root of candidateRoots) {
+            let overlaySkillsDir = join(root, '.canary', 'skills');
+            if (!isDir(overlaySkillsDir)) {
+                // Maybe root IS the .canary/skills dir directly.
+                if (basename(root) === 'skills' &&
+                    basename(resolve(root, '..')) === '.canary') {
+                    overlaySkillsDir = root;
+                }
+                else {
+                    continue;
+                }
+            }
+            let entries;
+            try {
+                entries = readdirSync(overlaySkillsDir).sort();
+            }
+            catch {
+                entries = [];
+            }
+            for (const name of entries) {
+                const skillDir = join(overlaySkillsDir, name);
+                if (!isDir(skillDir))
+                    continue;
+                const skillMd = join(skillDir, 'SKILL.md');
+                if (!existsSync(skillMd))
+                    continue;
+                // Parse frontmatter directly to avoid full registry overhead.
+                const info = reg.parseNested(skillMd, name, 'overlay');
+                if (info === null || seenNames.has(info.name))
+                    continue;
+                if (!pyTruthy(info.deploy_to))
+                    continue;
+                if (!info.deploy_to.includes(shape) &&
+                    !info.deploy_to.includes('all')) {
+                    continue;
+                }
+                seenNames.add(info.name);
+                collected.push([info, skillDir]);
+            }
+        }
+        return collected;
+    }
+    /**
+     * Copy skills from the overlay's `.canary/skills/` that match *shape*.
+     * Deployment is strictly one-way -- the overlay owns deployed files (#334).
+     */
+    deploySkills(shape, overlayPath, targetRoot, dryRun) {
+        const results = [];
+        const skillsToDeploy = this.collectOverlaySkills(shape, overlayPath);
+        const targetSkillsDir = join(targetRoot, '.canary', 'skills');
+        const manifest = readDeployManifest(targetSkillsDir);
+        let manifestDirty = false;
+        for (const [info, skillDir] of skillsToDeploy) {
+            const dirName = basename(skillDir);
+            const dest = join(targetSkillsDir, dirName);
+            const overlayHash = hashSkillDir(skillDir);
+            if (existsSync(dest)) {
+                const targetHash = hashSkillDir(dest);
+                if (targetHash === overlayHash) {
+                    results.push(new SkillDeployResult(info.name, 'skipped', 'already current'));
+                    if (manifest[dirName]?.hash !== overlayHash) {
+                        manifest[dirName] = { name: info.name, hash: overlayHash };
+                        manifestDirty = true;
+                    }
+                    continue;
+                }
+                const recorded = manifest[dirName]?.hash;
+                if (recorded === undefined || targetHash !== recorded) {
+                    // Hand-edited (or unprovenanced) -- one-way ownership refuses to clobber.
+                    results.push(new SkillDeployResult(info.name, 'skipped', `local edits ${EMDASH} not overwritten`));
+                    continue;
+                }
+                // Untouched since deploy; overlay moved on -> safe to refresh.
+                if (dryRun) {
+                    results.push(new SkillDeployResult(info.name, 'dry_run', 'would update'));
+                    continue;
+                }
+                rmSync(dest, { recursive: true, force: true });
+                cpSync(skillDir, dest, { recursive: true });
+                manifest[dirName] = { name: info.name, hash: overlayHash };
+                manifestDirty = true;
+                results.push(new SkillDeployResult(info.name, 'updated'));
+                continue;
+            }
+            if (dryRun) {
+                results.push(new SkillDeployResult(info.name, 'dry_run'));
+                continue;
+            }
+            mkdirSync(targetSkillsDir, { recursive: true });
+            cpSync(skillDir, dest, { recursive: true });
+            manifest[dirName] = { name: info.name, hash: overlayHash };
+            manifestDirty = true;
+            results.push(new SkillDeployResult(info.name, 'copied'));
+        }
+        if (manifestDirty && !dryRun)
+            writeDeployManifest(targetSkillsDir, manifest);
+        return results;
+    }
+    /**
+     * Compare the overlay's deployable skills against what *projectRoot* carries,
+     * without writing anything (#334).
+     */
+    checkFreshness(projectRoot, options) {
+        const overlayPath = options.overlayPath;
+        const ctx = this.detect(projectRoot);
+        if (!ctx.is_harness_project) {
+            if (ctx.not_test_project_reason)
+                throw new Error(ctx.not_test_project_reason);
+            throw new Error(`No harness project detected at ${projectRoot}. ` +
+                'Expected harness.config.json and .harness/ directory.');
+        }
+        const shape = ctx.detected_shape;
+        const skills = this.collectOverlaySkills(shape, overlayPath);
+        const targetSkillsDir = join(projectRoot, '.canary', 'skills');
+        const manifest = readDeployManifest(targetSkillsDir);
+        const results = [];
+        for (const [info, skillDir] of skills) {
+            const dirName = basename(skillDir);
+            const dest = join(targetSkillsDir, dirName);
+            if (!existsSync(dest)) {
+                results.push(new SkillFreshnessResult(info.name, dirName, 'missing', 'overlay ships this skill; target does not carry it'));
+                continue;
+            }
+            const overlayHash = hashSkillDir(skillDir);
+            const targetHash = hashSkillDir(dest);
+            if (targetHash === overlayHash) {
+                results.push(new SkillFreshnessResult(info.name, dirName, 'current'));
+                continue;
+            }
+            const recorded = manifest[dirName]?.hash;
+            if (recorded !== undefined && targetHash === recorded) {
+                results.push(new SkillFreshnessResult(info.name, dirName, 'stale', 'overlay has a newer version'));
+            }
+            else {
+                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);
+    }
+    detectFramework(root, config) {
+        // 0. Explicit override in .canary/company.json ("canary_shape" field).
+        const rawShape = config['canary_shape'];
+        const explicitShape = (rawShape == null ? '' : String(rawShape))
+            .trim()
+            .toLowerCase();
+        if (explicitShape) {
+            for (const [filename, framework, , confidence] of _CONFIG_PROBES) {
+                if (existsSync(join(root, filename))) {
+                    return [framework, explicitShape, filename, confidence];
+                }
+            }
+            // Fall through to content probes.
+        }
+        // 1. Dedicated config file (highest confidence).
+        for (const [filename, framework, shape, confidence] of _CONFIG_PROBES) {
+            if (existsSync(join(root, filename))) {
+                // For playwright config files, distinguish API vs UI suites.
+                if (framework === 'playwright' && shape === 'e2e_ui') {
+                    const inferred = inferPlaywrightShape(root);
+                    if (inferred !== shape)
+                        return [framework, inferred, filename, 'content'];
+                }
+                return [framework, shape, filename, confidence];
+            }
+        }
+        // 2. pyproject.toml section markers then dependency scan.
+        const pyproject = join(root, 'pyproject.toml');
+        if (existsSync(pyproject)) {
+            const content = readTextOrNull(pyproject);
+            if (content !== null) {
+                for (const [marker, framework, shape] of _PYPROJECT_MARKERS) {
+                    if (content.includes(marker)) {
+                        return [framework, shape, 'pyproject.toml', 'content'];
+                    }
+                }
+                for (const [pattern, framework, shape] of _PYTHON_DEP_PATTERNS) {
+                    if (pattern.test(content)) {
+                        return [
+                            framework,
+                            shape,
+                            'pyproject.toml (dependencies)',
+                            'content',
+                        ];
+                    }
+                }
+            }
+        }
+        // 3. requirements*.txt dependency scan.
+        for (const reqFile of [
+            'requirements.txt',
+            'requirements-test.txt',
+            'requirements-dev.txt',
+        ]) {
+            const reqPath = join(root, reqFile);
+            if (existsSync(reqPath)) {
+                const content = readTextOrNull(reqPath);
+                if (content !== null) {
+                    for (const [pattern, framework, shape] of _PYTHON_DEP_PATTERNS) {
+                        if (pattern.test(content))
+                            return [framework, shape, reqFile, 'content'];
+                    }
+                }
+            }
+        }
+        // 4. package.json scripts.test scan.
+        const pkgJson = join(root, 'package.json');
+        if (existsSync(pkgJson)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgJson, 'utf-8'));
+                const scripts = (pkg['scripts'] ?? {});
+                const testScript = String(scripts['test'] ?? '');
+                for (const [pattern, framework, shape] of _PACKAGE_SCRIPT_PATTERNS) {
+                    if (pattern.test(testScript)) {
+                        return [framework, shape, 'package.json (scripts.test)', 'content'];
+                    }
+                }
+            }
+            catch {
+                // OSError / JSONDecodeError -> ignore.
+            }
+        }
+        // 5. Language fallback from harness config.
+        const language = String(config['language'] ?? '').toLowerCase();
+        if (Object.prototype.hasOwnProperty.call(_LANGUAGE_FALLBACKS, language)) {
+            const [fw, shape] = _LANGUAGE_FALLBACKS[language];
+            return [
+                fw,
+                shape,
+                `harness.config.json (language: ${language})`,
+                'language',
+            ];
+        }
+        return [null, 'unknown', 'none', 'none'];
+    }
+    findExistingTests(root) {
+        const found = [];
+        for (const pattern of _TEST_GLOBS) {
+            // Python sorts Path objects (component-wise); match it so preserved-files
+            // report order agrees (see comparePathParts).
+            for (const path of globFiles(root, pattern).sort(comparePathParts)) {
+                const rel = relative(root, path).split(sep).join('/');
+                if (!found.includes(rel))
+                    found.push(rel);
+            }
+        }
+        return found;
+    }
+}
+function readTextOrNull(path) {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Return 'api' when no playwright spec file uses page/browser fixtures, else
+ * 'e2e_ui' (the default when any UI signal is found or no spec files exist).
+ */
+function inferPlaywrightShape(root) {
+    const specGlobs = [
+        'tests/**/*.spec.ts',
+        'tests/**/*.spec.js',
+        'test/**/*.spec.ts',
+        'test/**/*.spec.js',
+    ];
+    let total = 0;
+    for (const glob of specGlobs) {
+        for (const path of globFiles(root, glob)) {
+            // Python read_text(errors="ignore"); readFileSync substitutes U+FFFD for
+            // invalid bytes -- immaterial for the ASCII fixture pattern below.
+            let content;
+            try {
+                content = readFileSync(path, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            total += 1;
+            if (_PW_UI_FIXTURE_RE.test(content))
+                return 'e2e_ui';
+        }
+    }
+    return total > 0 ? 'api' : 'e2e_ui';
+}
+//# sourceMappingURL=migrator.js.map