@3fn/core 14.0.0 → 15.0.0

package/dist/cli/sync/Migration.js

@@ -0,0 +1,764 @@
+"use strict";
+/**
+ * Component-copy migration — pre-123 consumers (Spec 123 Task 5.5; design.md
+ * § "C7" Migration steps 2–5; Lina L2-D2, Le-D1).
+ *
+ * Pre-123 `init` copied `src/components/core/**` into the consumer (with
+ * `rewriteBuildImports` applied to `.ts` files from Spec 104 on). Under Model B
+ * components are consumed BY NAME from the package, so every copy now SHADOWS
+ * the package's version. This module judges each copy:
+ *
+ *  - **Against SHIPPED content, never the first-sync baseline** (Le-D1(1)). The
+ *    content is fetched THE WAY THE CONSUMER INSTALLED: her own npm resolution
+ *    (`.npmrc` scope mapping), npm cache first (`--prefer-offline`), run in her
+ *    project directory — so pre-13 versions that exist only on GitHub Packages
+ *    stay fetchable. This runs BEFORE the registry-pin repair is offered.
+ *  - **Any version in the range** — earliest available through the installed
+ *    one. A legacy manifest's `version` is the LAST SYNC (it can lag the installed
+ *    version — dp-portfolio: 12.0.3 vs 12.0.5), so it is never the bound.
+ *  - **The transform, byte-exact, loaded from each fetched tarball itself**, and
+ *    applied to `.ts` files only; non-`.ts` files hash raw; `__tests__` excluded.
+ *  - **Per file**: a component is `unmodified` iff every file is; a file deleted
+ *    from a copy makes the component a fork.
+ *  - **Version unknown, fetch failed, or transform unknown → `cannot-tell`.**
+ *    Never "unmodified".
+ *
+ * Nothing is removed without `--migrate-components` (relocate forks to
+ * `src/components/<Name>/`, remove unmodified copies; `cannot-tell` stays).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TSCONFIG_UNPARSEABLE_MESSAGE = exports.REGISTRY_PIN_ORDER_CAUTION = exports.REGISTRY_PIN_MESSAGE = exports.TOKEN_SIDE_SLOTS = exports.CONSUMER_COMPONENT_ROOT = exports.LEGACY_COMPONENT_ROOT = void 0;
+exports.npmRailFetcher = npmRailFetcher;
+exports.loadTransform = loadTransform;
+exports.compareVersions = compareVersions;
+exports.resolveUpperBound = resolveUpperBound;
+exports.migrationTrigger = migrationTrigger;
+exports.hasLegacyCopies = hasLegacyCopies;
+exports.assessComponentCopies = assessComponentCopies;
+exports.stripComments = stripComments;
+exports.modifiedCopiesMessage = modifiedCopiesMessage;
+exports.cannotTellMessage = cannotTellMessage;
+exports.cannotTellRemedyMessage = cannotTellRemedyMessage;
+exports.unmodifiedCopiesMessage = unmodifiedCopiesMessage;
+exports.yoursUnderCoreMessage = yoursUnderCoreMessage;
+exports.migrationReportLines = migrationReportLines;
+exports.relocateComponents = relocateComponents;
+exports.detectRegistryPin = detectRegistryPin;
+exports.detectTsconfigPins = detectTsconfigPins;
+exports.tsconfigPinMessage = tsconfigPinMessage;
+exports.repairOffers = repairOffers;
+exports.repairRegistryPin = repairRegistryPin;
+exports.repairTsconfigPins = repairTsconfigPins;
+exports.legacyCopyEntries = legacyCopyEntries;
+exports.assessLegacyCopies = assessLegacyCopies;
+exports.legacyCopiesMessage = legacyCopiesMessage;
+exports.legacyModifiedMessage = legacyModifiedMessage;
+exports.legacyMissingMessage = legacyMissingMessage;
+exports.migrateLegacyOfferMessage = migrateLegacyOfferMessage;
+exports.migrateLegacyUnavailableMessage = migrateLegacyUnavailableMessage;
+exports.migrateLegacyNeedsTargetMessage = migrateLegacyNeedsTargetMessage;
+exports.migrateLegacyRefusedMessage = migrateLegacyRefusedMessage;
+exports.legacyCopyReportLines = legacyCopyReportLines;
+exports.removeLegacyCopies = removeLegacyCopies;
+exports.legacyRemovalSummary = legacyRemovalSummary;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const FileScanner_1 = require("./FileScanner");
+const Manifest_1 = require("./Manifest");
+const vocabulary_1 = require("../shared/vocabulary");
+exports.LEGACY_COMPONENT_ROOT = 'src/components/core';
+exports.CONSUMER_COMPONENT_ROOT = 'src/components';
+const NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+/**
+ * The production fetcher: `npm view` / `npm pack --prefer-offline`, run with
+ * `cwd = projectRoot` so HER `.npmrc` (scope → registry mapping, auth) applies.
+ */
+function npmRailFetcher(projectRoot) {
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'dp-sync-migration-'));
+    const run = (args) => (0, child_process_1.execFileSync)(NPM, args, { cwd: projectRoot, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 180000 });
+    return {
+        listVersions() {
+            try {
+                const out = JSON.parse(run(['view', '@3fn/core', 'versions', '--json', '--prefer-offline']));
+                return Array.isArray(out) ? out.map(String) : typeof out === 'string' ? [out] : null;
+            }
+            catch {
+                return null;
+            }
+        },
+        fetch(version) {
+            try {
+                const dest = path.join(scratch, version);
+                fs.mkdirSync(dest, { recursive: true });
+                const packed = JSON.parse(run(['pack', `@3fn/core@${version}`, '--prefer-offline', '--pack-destination', dest, '--json']));
+                const filename = Array.isArray(packed) ? packed[0]?.filename : undefined;
+                if (!filename)
+                    return null;
+                (0, child_process_1.execFileSync)('tar', ['-xzf', path.join(dest, path.basename(filename)), '-C', dest], { stdio: 'ignore', timeout: 180000 });
+                const root = path.join(dest, 'package');
+                return fs.existsSync(root) ? root : null;
+            }
+            catch {
+                return null;
+            }
+        },
+        dispose() {
+            fs.rmSync(scratch, { recursive: true, force: true });
+        },
+    };
+}
+/**
+ * Load the copy transform THIS version's `init` applied, from its own files:
+ *  1. `dist/cli/shared/transforms.js` (13.0.0+ ship compiled CLI modules);
+ *  2. `src/cli/shared/transforms.ts` (11.9.0–12.x ran the CLI from `src/` via
+ *     tsx and did not ship `dist/cli/shared/`) — loaded through tsx;
+ *  3. no module, and the version's `init` never mentions `rewriteBuildImports`
+ *     → the IDENTITY (before Spec 104);
+ *  4. otherwise (11.3.0–11.8.x: the transform is private to `init.ts`) → unknown.
+ */
+function loadTransform(pkgRoot) {
+    const js = path.join(pkgRoot, 'dist/cli/shared/transforms.js');
+    const ts = path.join(pkgRoot, 'src/cli/shared/transforms.ts');
+    const pick = (mod, source) => {
+        const fn = mod?.rewriteBuildImports;
+        return typeof fn === 'function'
+            ? { kind: 'fn', fn: fn, source }
+            : { kind: 'unknown', reason: `${source} does not export rewriteBuildImports` };
+    };
+    try {
+        if (fs.existsSync(js))
+            return pick(require(js), 'dist/cli/shared/transforms.js');
+        if (fs.existsSync(ts))
+            return pick(requireTs(ts), 'src/cli/shared/transforms.ts');
+    }
+    catch (err) {
+        return { kind: 'unknown', reason: `the version's transform module failed to load (${err.message})` };
+    }
+    for (const initRel of ['dist/cli/init.js', 'src/cli/init.ts']) {
+        const initPath = path.join(pkgRoot, initRel);
+        if (!fs.existsSync(initPath))
+            continue;
+        return fs.readFileSync(initPath, 'utf-8').includes('rewriteBuildImports')
+            ? { kind: 'unknown', reason: `${initRel} applies rewriteBuildImports but does not export it` }
+            : { kind: 'identity', source: `${initRel} (before Spec 104 — no copy transform)` };
+    }
+    return { kind: 'unknown', reason: 'the version ships neither a transform module nor its init' };
+}
+function requireTs(file) {
+    // Under ts-jest (tests) plain require compiles .ts; at runtime the CLI is plain
+    // Node, so tsx's scoped require does it (tsx is a runtime dependency).
+    if (process.env.JEST_WORKER_ID !== undefined)
+        return require(file);
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const tsx = require('tsx/cjs/api');
+    return tsx.require(file, __filename);
+}
+// ---------------------------------------------------------------------------
+// Versions
+// ---------------------------------------------------------------------------
+function parseVersion(v) {
+    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+function compareVersions(a, b) {
+    const pa = parseVersion(a) ?? [0, 0, 0];
+    const pb = parseVersion(b) ?? [0, 0, 0];
+    for (let i = 0; i < 3; i++)
+        if (pa[i] !== pb[i])
+            return pa[i] - pb[i];
+    return 0;
+}
+/**
+ * The installed version bounding the range: the manifest's `installedVersion`,
+ * else `package-lock.json`, else unknown (→ every verdict `cannot-tell`).
+ */
+function resolveUpperBound(projectRoot, manifestInstalledVersion) {
+    if (manifestInstalledVersion && parseVersion(manifestInstalledVersion)) {
+        return { version: manifestInstalledVersion, source: 'manifest' };
+    }
+    const lockPath = path.join(projectRoot, 'package-lock.json');
+    if (fs.existsSync(lockPath)) {
+        try {
+            const lock = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+            const v = lock?.packages?.['node_modules/@3fn/core']?.version ?? lock?.dependencies?.['@3fn/core']?.version;
+            if (typeof v === 'string' && parseVersion(v))
+                return { version: v, source: 'lockfile' };
+        }
+        catch {
+            /* unreadable lockfile → unknown */
+        }
+    }
+    return { version: null, source: 'unknown' };
+}
+/** The migration trigger (C7): a legacy manifest, or legacy copies on disk. */
+function migrationTrigger(projectRoot, legacyManifest) {
+    if (legacyManifest)
+        return 'legacy-manifest';
+    return hasLegacyCopies(projectRoot) ? 'legacy-copies' : null;
+}
+function hasLegacyCopies(projectRoot) {
+    const core = path.join(projectRoot, exports.LEGACY_COMPONENT_ROOT);
+    return fs.existsSync(core) && fs.readdirSync(core, { withFileTypes: true }).some((e) => e.isDirectory());
+}
+function listFiles(dir, base = dir) {
+    const out = [];
+    if (!fs.existsSync(dir))
+        return out;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (e.isDirectory()) {
+            if (e.name === '__tests__')
+                continue;
+            out.push(...listFiles(path.join(dir, e.name), base));
+        }
+        else if (e.isFile()) {
+            out.push(path.relative(base, path.join(dir, e.name)).split(path.sep).join('/'));
+        }
+    }
+    return out.sort();
+}
+function assessComponentCopies(projectRoot, opts) {
+    const coreDir = path.join(projectRoot, exports.LEGACY_COMPONENT_ROOT);
+    const names = fs
+        .readdirSync(coreDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort();
+    const consumer = new Map(); // name → file → hash
+    for (const name of names) {
+        const m = new Map();
+        for (const f of listFiles(path.join(coreDir, name)))
+            m.set(f, (0, FileScanner_1.hashBuffer)(fs.readFileSync(path.join(coreDir, name, f))));
+        consumer.set(name, m);
+    }
+    const assessment = {
+        trigger: opts.trigger,
+        upperBound: opts.upperBound,
+        range: [],
+        fetched: [],
+        failed: [],
+        unknownTransform: {},
+        fetchLog: [],
+        components: [],
+        oldNameReferenceMaps: [],
+        brandedTokenFiles: [],
+    };
+    // The range: earliest available → the installed version, newest first.
+    let listed = null;
+    if (opts.upperBound.version)
+        listed = opts.fetcher.listVersions();
+    const rangeKnown = listed !== null && opts.upperBound.version !== null;
+    if (rangeKnown) {
+        assessment.range = listed
+            .filter((v) => parseVersion(v) && compareVersions(v, opts.upperBound.version) <= 0)
+            .sort((a, b) => compareVersions(b, a));
+    }
+    // Per-file state.
+    const matched = new Map(); // name → file → version
+    const poisoned = new Map(); // name → file → unknown-transform versions that left it undecidable
+    const presentIn = new Map(); // name → versions shipping the component
+    const versionFileSets = new Map(); // version → name → files
+    for (const name of names) {
+        matched.set(name, new Map());
+        poisoned.set(name, new Map());
+        presentIn.set(name, []);
+    }
+    const allMatched = () => names.every((n) => consumer.get(n).size > 0 && [...consumer.get(n).keys()].every((f) => matched.get(n).has(f)));
+    for (const version of assessment.range) {
+        if (allMatched())
+            break;
+        assessment.fetchLog.push(version);
+        const root = opts.fetcher.fetch(version);
+        if (!root) {
+            assessment.failed.push(version);
+            continue;
+        }
+        assessment.fetched.push(version);
+        const side = { version, root, transform: loadTransform(root) };
+        if (side.transform.kind === 'unknown')
+            assessment.unknownTransform[version] = side.transform.reason;
+        const perName = new Map();
+        versionFileSets.set(version, perName);
+        for (const name of names) {
+            const pkgCompDir = path.join(root, exports.LEGACY_COMPONENT_ROOT, name);
+            if (!fs.existsSync(pkgCompDir))
+                continue;
+            presentIn.get(name).push(version);
+            const pkgFiles = new Set(listFiles(pkgCompDir));
+            perName.set(name, pkgFiles);
+            for (const [file, hash] of consumer.get(name)) {
+                if (matched.get(name).has(file) || !pkgFiles.has(file))
+                    continue;
+                const raw = fs.readFileSync(path.join(pkgCompDir, file));
+                let candidate;
+                if (!file.endsWith('.ts') || side.transform.kind === 'identity')
+                    candidate = (0, FileScanner_1.hashBuffer)(raw);
+                else if (side.transform.kind === 'fn')
+                    candidate = (0, FileScanner_1.hashBuffer)(side.transform.fn(raw.toString('utf-8')));
+                else
+                    candidate = null;
+                if (candidate === null) {
+                    const byFile = poisoned.get(name);
+                    if (!byFile.has(file))
+                        byFile.set(file, new Set());
+                    byFile.get(file).add(version);
+                }
+                else if (candidate === hash)
+                    matched.get(name).set(file, version);
+            }
+        }
+    }
+    const undecidableRange = !rangeKnown || assessment.failed.length > 0;
+    for (const name of names) {
+        const files = [];
+        for (const file of consumer.get(name).keys()) {
+            const v = matched.get(name).get(file);
+            if (v)
+                files.push({ file, verdict: 'unmodified', matchedVersion: v });
+            else if (undecidableRange || poisoned.get(name).has(file)) {
+                // Cause precedence: an unknown installed version, then a retrieval failure
+                // (the version list or a version's tarball), then an unrecoverable transform.
+                let cause;
+                if (!opts.upperBound.version)
+                    cause = { kind: 'version-unknown' };
+                else if (!rangeKnown)
+                    cause = { kind: 'fetch-failed', version: opts.upperBound.version };
+                else if (assessment.failed.length > 0)
+                    cause = { kind: 'fetch-failed', version: assessment.failed.join(', ') };
+                else
+                    cause = { kind: 'transform-unrecoverable', version: [...poisoned.get(name).get(file)].sort(compareVersions).join(', ') };
+                files.push({ file, verdict: 'cannot-tell', cause });
+            }
+            else
+                files.push({ file, verdict: 'modified' });
+        }
+        const shippedBy = presentIn.get(name);
+        const kind = shippedBy.length === 0 && !undecidableRange ? 'yours' : 'copy';
+        // A deletion: a file shipped by EVERY version that matched part of this copy, absent on disk.
+        const matchedVersions = [...new Set(matched.get(name).values())];
+        const deletedFiles = [];
+        if (matchedVersions.length > 0) {
+            const sets = matchedVersions.map((v) => versionFileSets.get(v).get(name));
+            for (const f of sets[0])
+                if (sets.every((s) => s.has(f)) && !consumer.get(name).has(f))
+                    deletedFiles.push(f);
+        }
+        let verdict;
+        if (kind === 'yours')
+            verdict = 'modified';
+        else if (files.some((f) => f.verdict === 'modified') || deletedFiles.length > 0)
+            verdict = 'modified';
+        else if (files.length === 0 || files.some((f) => f.verdict === 'cannot-tell'))
+            verdict = 'cannot-tell';
+        else
+            verdict = 'unmodified';
+        assessment.components.push({ name, kind, verdict, files, deletedFiles: deletedFiles.sort() });
+    }
+    scanTokenFiles(projectRoot, assessment);
+    return assessment;
+}
+/**
+ * Comments blanked out (same approach as `scripts/floor-closure.ts`'s
+ * `stripComments`): block comments, then `//` line comments not preceded by `:`
+ * (so `https://` inside a string survives). Not a tokenizer.
+ */
+function stripComments(content) {
+    const noBlock = content.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+    return noBlock.replace(/([^:]|^)\/\/.*$/gm, (m, prefix) => prefix + ' '.repeat(m.length - prefix.length));
+}
+/**
+ * Lina A5: find the token files `generate`'s recursive scan will reach under
+ * `core/`. A TEXT approximation of Task 8's runtime brand count (the migration
+ * never executes the consumer's copied `.ts`): a file counts as branded iff
+ * `defineComponentTokens` appears OUTSIDE comments. Known residual: an aliased
+ * import (`import { defineComponentTokens as dct }`) still reads as branded,
+ * because the identifier appears in code.
+ *
+ * `brandedTokenFiles` is scoped to COPIES — a consumer-authored ("yours")
+ * component's branded file was always hers, so "now register as YOUR component
+ * tokens" is no news for it. `oldNameReferenceMaps` keeps every component: the
+ * lint fires on hers too.
+ */
+function scanTokenFiles(projectRoot, a) {
+    for (const c of a.components) {
+        for (const f of listFiles(path.join(projectRoot, exports.LEGACY_COMPONENT_ROOT, c.name))) {
+            const base = path.posix.basename(f);
+            if (base !== 'tokens.ts' && !base.endsWith('.tokens.ts'))
+                continue;
+            const rel = `${exports.LEGACY_COMPONENT_ROOT}/${c.name}/${f}`;
+            const code = stripComments(fs.readFileSync(path.join(projectRoot, rel), 'utf-8'));
+            if (!code.includes('defineComponentTokens'))
+                a.oldNameReferenceMaps.push(rel);
+            else if (c.kind === 'copy')
+                a.brandedTokenFiles.push(rel);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Report strings
+// ---------------------------------------------------------------------------
+/** Design catalog row "migration — modified copies (Le-D1(3))". */
+function modifiedCopiesMessage(n, names) {
+    return `these ${n} modified copies now override the package's ${names.join(', ')} and will not receive updates. Keep them as your forks, or move them with 'sync --migrate-components' (relocates modified copies to src/components/<Name>/).`;
+}
+/**
+ * Design catalog row "migration — cannot tell" — THREE-CAUSE per the design.md
+ * erratum of 2026-09-26 (Thurgood, `completion/task-5-erratum-cannot-tell.md`):
+ * `cannot tell whether <path> was modified — <the package content for version <v>
+ * could not be retrieved|version <v>'s copy transform cannot be recovered|the
+ * installed version is unknown>. Review before removing.`
+ */
+function cannotTellMessage(p, cause) {
+    const reason = cause.kind === 'fetch-failed'
+        ? `the package content for version ${cause.version} could not be retrieved`
+        : cause.kind === 'transform-unrecoverable'
+            ? `version ${cause.version}'s copy transform cannot be recovered`
+            : 'the installed version is unknown';
+    return `cannot tell whether ${p} was modified — ${reason}. Review before removing.`;
+}
+/**
+ * Follows the catalog `cannot tell` lines (Peter's 2026-09-26 ruling on the
+ * migration fork, condition 1: the cannot-tell outcome must be ACTIONABLE —
+ * both manual paths, and the legacy warning's persistence). The catalog row
+ * itself stays string-equal; this line is additional.
+ */
+function cannotTellRemedyMessage(names) {
+    const them = names.length === 1 ? 'it' : 'them';
+    return `sync cannot judge ${names.join(', ')}, so 'sync --migrate-components' leaves ${them} in src/components/core/. Decide each by hand: if you edited it, move it to src/components/<Name>/ (it becomes your fork); if you didn't, delete it and you'll get the package's version. Until then, the old core/ level keeps logging its legacy warning each time the component index loads.`;
+}
+/** C7 step 3: unmodified copies shadow updates (the design's quoted phrase, verbatim inside). */
+function unmodifiedCopiesMessage(n, names) {
+    return `these ${n} unmodified copies (${names.join(', ')}) shadow package updates — remove them to receive updates (\`sync --migrate-components\`)`;
+}
+/** Not in the catalog: a component under core/ that no fetched version ships. Authored at Task 5.5. */
+function yoursUnderCoreMessage(n, names) {
+    return `these ${n} components under src/components/core/ are not DesignerPunk's (${names.join(', ')}) — they are yours; 'sync --migrate-components' moves them to src/components/<Name>/ with the forks.`;
+}
+/**
+ * Lina A5 / C7 step 5. Authored at Task 5.5 (Ada). Each takes the file list
+ * the assessment found (names are always printed with the line).
+ *
+ * `oldNameReferenceMaps` is deliberately ownership-agnostic: `scanTokenFiles`
+ * classifies by filename + content alone, so this list mixes DesignerPunk's
+ * own old-name files (the 7 renamed to `*.refs.ts` in #200 — a pre-123 copy
+ * predates that rename and still carries the old name) with a consumer's own
+ * semantic-reference map that happens to be named `tokens.ts` — the exact
+ * collision Req 8's user story names. The string must not claim authorship it
+ * cannot verify per-file.
+ */
+exports.TOKEN_SIDE_SLOTS = {
+    /** C7 5 (i): old-name `tokens.ts` reference maps in the copied tree → C11's lint on first generate. */
+    oldNameReferenceMaps: (files) => `${files.length} reference map${files.length === 1 ? '' : 's'} named like token files (${files.join(', ')}) will trip the component-token lint on your first 'npx designerpunk generate' — a tokens.ts or *.tokens.ts file that doesn't call defineComponentTokens registers no tokens, whether it's one of ours or one you named yourself. It's a warning, not an error, so generate still runs. Rename the file${files.length === 1 ? '' : 's'} off the tokens.ts pattern (e.g., <Name>.refs.ts) to stop it, or leave as is.`,
+    /** C7 5 (ii): branded copied `*.tokens.ts` now harvest as the consumer's component tokens. */
+    brandedTokenFiles: (files) => `${files.length} copied component token file${files.length === 1 ? '' : 's'} (${files.join(', ')}) now register as YOUR component tokens when you run generate — they're yours while the copies stay, and DesignerPunk's release won't overwrite them. Keep the copy and they stay registered; remove it (see above) and they go with it.`,
+};
+function migrationReportLines(a) {
+    const lines = [];
+    const bound = a.upperBound.version
+        ? `${a.upperBound.version} (from the ${a.upperBound.source})`
+        : 'unknown (no manifest installedVersion and no package-lock.json)';
+    lines.push(`pre-123 component copies under ${exports.LEGACY_COMPONENT_ROOT}/ judged against the content each version shipped, through your npm registry settings; installed version: ${bound}`);
+    const of = (v, k = 'copy') => a.components.filter((c) => c.verdict === v && c.kind === k);
+    const unmodified = of('unmodified');
+    const forks = of('modified');
+    const yours = a.components.filter((c) => c.kind === 'yours');
+    const unknown = of('cannot-tell');
+    if (unmodified.length > 0)
+        lines.push(unmodifiedCopiesMessage(unmodified.length, unmodified.map((c) => c.name)));
+    if (forks.length > 0)
+        lines.push(modifiedCopiesMessage(forks.length, forks.map((c) => c.name)));
+    if (yours.length > 0)
+        lines.push(yoursUnderCoreMessage(yours.length, yours.map((c) => c.name)));
+    for (const c of unknown) {
+        const undecided = c.files.filter((f) => f.verdict === 'cannot-tell');
+        const causes = new Set(undecided.map((f) => JSON.stringify(f.cause)));
+        if (undecided.length === c.files.length && causes.size === 1) {
+            lines.push(cannotTellMessage(`${exports.LEGACY_COMPONENT_ROOT}/${c.name}/`, undecided[0].cause));
+        }
+        else {
+            for (const f of undecided)
+                lines.push(cannotTellMessage(`${exports.LEGACY_COMPONENT_ROOT}/${c.name}/${f.file}`, f.cause));
+        }
+    }
+    if (unknown.length > 0)
+        lines.push(cannotTellRemedyMessage(unknown.map((c) => c.name)));
+    if (a.oldNameReferenceMaps.length > 0)
+        lines.push(exports.TOKEN_SIDE_SLOTS.oldNameReferenceMaps(a.oldNameReferenceMaps));
+    if (a.brandedTokenFiles.length > 0)
+        lines.push(exports.TOKEN_SIDE_SLOTS.brandedTokenFiles(a.brandedTokenFiles));
+    return lines;
+}
+function relocateComponents(projectRoot, a) {
+    const r = { removed: [], relocated: [], skipped: [], leftInPlace: [] };
+    const coreDir = path.join(projectRoot, exports.LEGACY_COMPONENT_ROOT);
+    for (const c of a.components) {
+        const from = path.join(coreDir, c.name);
+        if (c.verdict === 'cannot-tell') {
+            r.leftInPlace.push(c.name);
+        }
+        else if (c.verdict === 'unmodified') {
+            fs.rmSync(from, { recursive: true, force: true });
+            r.removed.push(c.name);
+        }
+        else {
+            const to = path.join(projectRoot, exports.CONSUMER_COMPONENT_ROOT, c.name);
+            if (fs.existsSync(to)) {
+                r.skipped.push(c.name);
+                continue;
+            }
+            fs.renameSync(from, to);
+            r.relocated.push(c.name);
+        }
+    }
+    if (fs.existsSync(coreDir) && fs.readdirSync(coreDir).length === 0)
+        fs.rmdirSync(coreDir);
+    return r;
+}
+// ---------------------------------------------------------------------------
+// Repairs (C7 step 6; Reqs 5.1, 5.2) — OFFERED only after the migration fetch
+// ---------------------------------------------------------------------------
+/** The exact line the pre-2026-09-20 `init` scaffolded (issue archive/2026-09-20-init-npmrc-registry-pin). */
+const REGISTRY_PIN_RE = /^\s*@3fn:registry\s*=\s*https:\/\/npm\.pkg\.github\.com\/?\s*$/;
+/** Req 5.1: detect the `@3fn` → GitHub Packages scope mapping in the consumer's `.npmrc`. Reads only that line's shape; never prints other lines. */
+function detectRegistryPin(projectRoot) {
+    const p = path.join(projectRoot, '.npmrc');
+    if (!fs.existsSync(p))
+        return false;
+    return fs.readFileSync(p, 'utf-8').split(/\r?\n/).some((l) => REGISTRY_PIN_RE.test(l));
+}
+/** Req 5.2: the scaffolded `tsconfig.test.json` `paths` keys that re-pin `@3fn/core` subpaths to raw `src/`. */
+function detectTsconfigPins(projectRoot) {
+    const p = path.join(projectRoot, 'tsconfig.test.json');
+    if (!fs.existsSync(p))
+        return { keys: [], unparseable: false };
+    const text = fs.readFileSync(p, 'utf-8');
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch {
+        return { keys: [], unparseable: text.includes('@3fn/core/src/') };
+    }
+    const paths = doc.compilerOptions?.paths ?? {};
+    const keys = Object.entries(paths)
+        .filter(([k, v]) => k.startsWith('@3fn/core') && JSON.stringify(v).includes('@3fn/core/src/'))
+        .map(([k]) => k);
+    return { keys, unparseable: false };
+}
+exports.REGISTRY_PIN_MESSAGE = ".npmrc maps @3fn to GitHub Packages (@3fn:registry=https://npm.pkg.github.com). An older 'init' wrote that line; DesignerPunk now publishes to the public npm registry, and the mapping makes every install of @3fn/core need a GitHub token and can leave you on versions npm no longer serves. To remove just that line (your other settings, including any auth lines, stay): npx designerpunk sync --repair-npmrc";
+exports.REGISTRY_PIN_ORDER_CAUTION = "Do this after 'sync --migrate-components': once the mapping is gone, versions before 13.0.0 can no longer be fetched to judge your component copies.";
+function tsconfigPinMessage(keys) {
+    return `tsconfig.test.json re-pins ${keys.join(', ')} to raw TypeScript in node_modules/@3fn/core/src — an older 'init' wrote that. The package resolves those subpaths to its compiled types, and several of the pinned source files no longer ship. To remove just those paths entries: npx designerpunk sync --repair-tsconfig`;
+}
+exports.TSCONFIG_UNPARSEABLE_MESSAGE = "tsconfig.test.json points @3fn/core subpaths at node_modules/@3fn/core/src, but it is not plain JSON (comments?), so sync will not rewrite it. Remove the compilerOptions.paths entries for @3fn/core/* by hand.";
+/**
+ * Build the offers. Called AFTER the migration assessment (the fetch runs
+ * through the pin the npmrc repair removes — L2-D2). `copiesPending` adds the
+ * ordering caution while pre-123 copies are still on disk.
+ */
+function repairOffers(projectRoot, copiesPending) {
+    const offers = [];
+    if (detectRegistryPin(projectRoot)) {
+        offers.push({ kind: 'npmrc', lines: copiesPending ? [exports.REGISTRY_PIN_MESSAGE, exports.REGISTRY_PIN_ORDER_CAUTION] : [exports.REGISTRY_PIN_MESSAGE] });
+    }
+    const ts = detectTsconfigPins(projectRoot);
+    if (ts.keys.length > 0)
+        offers.push({ kind: 'tsconfig', lines: [tsconfigPinMessage(ts.keys)] });
+    else if (ts.unparseable)
+        offers.push({ kind: 'tsconfig', lines: [exports.TSCONFIG_UNPARSEABLE_MESSAGE] });
+    return offers;
+}
+/** Remove only the pin line(s). Returns true iff the file changed. */
+function repairRegistryPin(projectRoot) {
+    const p = path.join(projectRoot, '.npmrc');
+    if (!fs.existsSync(p))
+        return false;
+    const text = fs.readFileSync(p, 'utf-8');
+    const kept = text.split(/(\r?\n)/);
+    const out = [];
+    let changed = false;
+    for (let i = 0; i < kept.length; i += 2) {
+        const line = kept[i];
+        const eol = kept[i + 1] ?? '';
+        if (REGISTRY_PIN_RE.test(line)) {
+            changed = true;
+            continue;
+        }
+        out.push(line + eol);
+    }
+    if (changed)
+        fs.writeFileSync(p, out.join(''), 'utf-8');
+    return changed;
+}
+/** Remove only the re-pinning `paths` entries (and `paths` itself if emptied); `baseUrl` is kept. */
+function repairTsconfigPins(projectRoot) {
+    const { keys } = detectTsconfigPins(projectRoot);
+    if (keys.length === 0)
+        return false;
+    const p = path.join(projectRoot, 'tsconfig.test.json');
+    const doc = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    for (const k of keys)
+        delete doc.compilerOptions.paths[k];
+    if (Object.keys(doc.compilerOptions.paths).length === 0)
+        delete doc.compilerOptions.paths;
+    fs.writeFileSync(p, JSON.stringify(doc, null, 2) + '\n', 'utf-8');
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Legacy copies — C7 Migration item 4 (Task 16.5): "Copied governance /
+// steering / agents / skills → the imposter-surface report and
+// --migrate-legacy, THEN attach."
+// ---------------------------------------------------------------------------
+/**
+ * The legacy-copy entries: `origin: 'copy'`, file grain, under one of the
+ * release-1 copy roots (`COPY_ROOTS`). Keyed on ORIGIN, never on the manifest's
+ * version (Ada D-T-B2, design C7 erratum): release-1 `init` wrote a
+ * CURRENT-format manifest, so a version key would miss the whole cohort.
+ */
+function legacyCopyEntries(entries) {
+    return Object.entries(entries)
+        .filter(([key, e]) => e.origin === 'copy' && e.grain === 'file' && Manifest_1.COPY_ROOTS.some((r) => (0, Manifest_1.isUnder)(key, r)))
+        .map(([key]) => key)
+        .sort();
+}
+/** Judge each legacy copy against the hash recorded when it was copied. `null` when the manifest records none. */
+function assessLegacyCopies(projectRoot, entries) {
+    const keys = legacyCopyEntries(entries);
+    if (keys.length === 0)
+        return null;
+    const a = {
+        roots: Manifest_1.COPY_ROOTS.filter((r) => keys.some((k) => (0, Manifest_1.isUnder)(k, r))),
+        unmodified: [],
+        modified: [],
+        missing: [],
+    };
+    for (const key of keys) {
+        const abs = path.join(projectRoot, key);
+        if (!fs.existsSync(abs) || !fs.statSync(abs).isFile())
+            a.missing.push(key);
+        else if ((0, FileScanner_1.hashFile)(abs) === entries[key].hash)
+            a.unmodified.push(key);
+        else
+            a.modified.push(key);
+    }
+    return a;
+}
+function legacyCopiesMessage(count, roots) {
+    return (`${count} file${count === 1 ? '' : 's'} under ${roots.join(', ')} ${count === 1 ? 'is a copy' : 'are copies'} an earlier DesignerPunk init made. ` +
+        `DesignerPunk no longer copies these — it generates your agent layer instead — so sync no longer updates the copies, ` +
+        `and generated agents would sit beside them.`);
+}
+function legacyModifiedMessage(paths) {
+    return (`${paths.length} of them ${paths.length === 1 ? 'was' : 'were'} edited after ${paths.length === 1 ? 'it was' : 'they were'} copied ` +
+        `(${paths.join(', ')}) — --migrate-legacy leaves ${paths.length === 1 ? 'it' : 'those'} on disk as yours and stops tracking ${paths.length === 1 ? 'it' : 'them'}.`);
+}
+function legacyMissingMessage(count) {
+    return `${count} of them ${count === 1 ? 'was' : 'were'} deleted since ${count === 1 ? 'it was' : 'they were'} copied — --migrate-legacy drops ${count === 1 ? 'its record' : 'their records'}.`;
+}
+/** The offer — printed ONLY when attach is available; it names the attach step it runs. */
+function migrateLegacyOfferMessage(targets, declared) {
+    const run = targets.length > 0 ? 'npx designerpunk sync --migrate-legacy' : `npx designerpunk sync --migrate-legacy --target=<${declared.join('|')}>`;
+    const forWhom = targets.length > 0 ? `for ${targets.join(' and ')}` : 'for the target you name';
+    return (`to replace them with your generated agent layer in one step: ${run} — it removes the unmodified copies, then, in the same run, ` +
+        `does what 'npx designerpunk attach --target=<t>' does (${(0, vocabulary_1.attachUsage)()}) ${forWhom}.`);
+}
+/** Printed INSTEAD of the offer when attach is not available. Nothing is offered for removal. */
+function migrateLegacyUnavailableMessage(reason) {
+    return (`sync cannot ${(0, vocabulary_1.attachUsage)()} with the installed package here (${reason}), so it does not offer to remove the copies: ` +
+        `they stay on disk and in the manifest, and sync leaves them alone.`);
+}
+/** `--migrate-legacy` was given, but there is no target to attach (the manifest records none and no --target was given). */
+function migrateLegacyNeedsTargetMessage(declared) {
+    return `--migrate-legacy needs a target to attach — this manifest records none. Re-run with --target=<${declared.join('|')}>; nothing was removed.`;
+}
+/** `--migrate-legacy` was given while attach is unavailable — refused; nothing removed. */
+function migrateLegacyRefusedMessage(reason) {
+    return `--migrate-legacy runs only together with the attach step, and sync cannot ${(0, vocabulary_1.attachUsage)()} here (${reason}) — nothing was removed.`;
+}
+function legacyCopyReportLines(a, availability) {
+    const total = a.unmodified.length + a.modified.length + a.missing.length;
+    const lines = [legacyCopiesMessage(total, a.roots)];
+    if (a.modified.length > 0)
+        lines.push(legacyModifiedMessage(a.modified));
+    if (a.missing.length > 0)
+        lines.push(legacyMissingMessage(a.missing.length));
+    lines.push(availability.available
+        ? migrateLegacyOfferMessage(availability.targets, availability.declared)
+        : migrateLegacyUnavailableMessage(availability.reason));
+    return lines;
+}
+/**
+ * The removal half of `--migrate-legacy` (the caller runs the attach half next,
+ * in the same flow). Every legacy entry leaves the manifest, so no `origin:
+ * 'copy'` entry remains under the release-1 copy roots; only files whose bytes
+ * still equal the recorded copy are deleted (re-checked here, not trusted from
+ * the report). Directories the deletions empty are removed, up to the copy root.
+ */
+function removeLegacyCopies(projectRoot, entries) {
+    const r = { removed: [], keptAsYours: [], dropped: [] };
+    const touchedDirs = new Set();
+    for (const key of legacyCopyEntries(entries)) {
+        const abs = path.join(projectRoot, key);
+        if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+            r.dropped.push(key);
+        }
+        else if ((0, FileScanner_1.hashFile)(abs) === entries[key].hash) {
+            fs.rmSync(abs);
+            r.removed.push(key);
+            touchedDirs.add(path.dirname(abs));
+        }
+        else {
+            r.keptAsYours.push(key);
+        }
+        delete entries[key];
+    }
+    const stopAt = new Set(Manifest_1.COPY_ROOTS.map((root) => path.dirname(path.join(projectRoot, root))));
+    for (const dir of [...touchedDirs].sort((x, y) => y.length - x.length)) {
+        let d = dir;
+        while (!stopAt.has(d) && d.startsWith(projectRoot + path.sep) && fs.existsSync(d) && fs.readdirSync(d).length === 0) {
+            fs.rmdirSync(d);
+            d = path.dirname(d);
+        }
+    }
+    return r;
+}
+function legacyRemovalSummary(r) {
+    return (`  ✓ --migrate-legacy: removed ${r.removed.length} unmodified cop${r.removed.length === 1 ? 'y' : 'ies'}` +
+        (r.keptAsYours.length ? `; kept ${r.keptAsYours.length} edited cop${r.keptAsYours.length === 1 ? 'y' : 'ies'} on disk as yours (no longer tracked)` : '') +
+        (r.dropped.length ? `; dropped ${r.dropped.length} record${r.dropped.length === 1 ? '' : 's'} of copies already deleted` : ''));
+}
+//# sourceMappingURL=Migration.js.map