@3fn/core 14.0.0 → 15.0.0

package/dist/cli/sync/index.js

@@ -1,94 +1,744 @@
 "use strict";
 /**
- * `npx designerpunk sync` — Detect and apply package updates.
+ * `npx designerpunk sync` — reconcile what DesignerPunk manages in a consumer
+ * repo with the installed package, and report (never write) everything else.
  *
- * Orchestrates: resolve → manifest → ignore → scan → classify → report → apply → save.
+ * Spec 123 Task 5 (design.md § "C7"; Reqs 5.1, 5.2, 5.5–5.8). Re-scoped from
+ * Spec 111 under Model B:
+ *  - **Ours never flows into theirs.** The token tier (`src/tokens`), `src/types`
+ *    and the pre-123 component copies are NOT managed: never scanned for
+ *    reconciliation, never written (Req 5.8). Their old manifest entries are
+ *    PRUNED with a one-line report per group.
+ *  - **What is managed is what the manifest recorded** — since Task 16.5: the
+ *    GENERATED surfaces (`origin: 'generated'`; the agent layer at file grain,
+ *    the `CLAUDE.md` region at region grain) for the manifest's
+ *    `attachedTargets`, whose package side is freshly generated by
+ *    `emitConsumer` (C7, C20), and the MCP keys (`grain: 'key'`). The release-1
+ *    package copies (`origin: 'copy'` under `COPY_ROOTS`) are NOT managed: they
+ *    are LEGACY COPIES, reported, and offered `--migrate-legacy` only together
+ *    with the attach step (C7 Migration item 4).
+ *  - **No class applies without the report first.** Off a terminal, nothing is
+ *    written without `--apply`; on a terminal, one batch confirmation. A
+ *    `conflict` applies only with `--overwrite <path>`, a `deleted-by-you` only
+ *    with `--restore <path>`.
  *
- * @see Spec 111 — Requirements 1-9
+ * Order: resolve → steward guard → manifest (load | relocate legacy) → prune →
+ * classify (generated files + regions, keys) → legacy copies → migration →
+ * repairs → REPORT → decide → (--migrate-legacy: removal, then attach) → apply →
+ * save.
  */
+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.parseSyncArgs = parseSyncArgs;
 exports.runSync = runSync;
+exports.agentLayerUnavailableMessage = agentLayerUnavailableMessage;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
 const PackageResolver_1 = require("./PackageResolver");
 const FileScanner_1 = require("./FileScanner");
 const Manifest_1 = require("./Manifest");
 const IgnoreFilter_1 = require("./IgnoreFilter");
 const Classifier_1 = require("./Classifier");
+const FileScanner_2 = require("./FileScanner");
+const RegionGrain_1 = require("./RegionGrain");
+const errorCatalog_1 = require("../shared/errorCatalog");
+const attach_1 = require("../attach");
+const KeyGrain_1 = require("./KeyGrain");
 const Reporter_1 = require("./Reporter");
-const Prompter_1 = require("./Prompter");
 const Applier_1 = require("./Applier");
 const SteeringDirCheck_1 = require("./SteeringDirCheck");
-async function runSync(options) {
-    const { dryRun, force, projectRoot } = options;
-    // Non-TTY guard
-    if (!process.stdin.isTTY && !force && !dryRun) {
-        console.log('Non-interactive environment detected — running in dry-run mode.\n');
-        return runSync({ ...options, dryRun: true });
+const Migration_1 = require("./Migration");
+const NameContract_1 = require("./NameContract");
+const ConfigLoader_1 = require("../../config/ConfigLoader");
+/** The default source: the installed package's own compiled lane. Throws (the reason) when it cannot load. */
+function bundleAgentLayerSource(pkgRoot, projectRoot) {
+    const { entry, profile } = (0, attach_1.resolveAgentTarget)(pkgRoot, undefined, 'sync');
+    return {
+        declaredTargets: () => profile.targets,
+        emit: async (target) => {
+            const r = await entry.emitConsumer({ packageRoot: pkgRoot, consumerRoot: projectRoot, target, mode: 'sync' });
+            return { files: r.files, warnings: r.warnings };
+        },
+    };
+}
+/** Parse `sync`'s CLI flags (everything after `sync`). */
+function parseSyncArgs(argv) {
+    const opts = { restore: [], overwrite: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--dry-run')
+            opts.dryRun = true;
+        else if (a === '--apply')
+            opts.apply = true;
+        else if (a === '--force' || a === '--accept-all')
+            opts.retiredForce = true;
+        else if (a === '--restore' && argv[i + 1])
+            opts.restore.push(argv[++i]);
+        else if (a.startsWith('--restore='))
+            opts.restore.push(a.slice('--restore='.length));
+        else if (a === '--overwrite' && argv[i + 1])
+            opts.overwrite.push(argv[++i]);
+        else if (a.startsWith('--overwrite='))
+            opts.overwrite.push(a.slice('--overwrite='.length));
+        else if (a === '--migrate-components')
+            opts.migrateComponents = true;
+        else if (a === '--repair-npmrc')
+            opts.repairNpmrc = true;
+        else if (a === '--repair-tsconfig')
+            opts.repairTsconfig = true;
+        else if (a === '--migrate-legacy')
+            opts.migrateLegacy = true;
+        else if (a === '--target' && argv[i + 1])
+            (opts.targets ?? (opts.targets = [])).push(argv[++i]);
+        else if (a.startsWith('--target='))
+            (opts.targets ?? (opts.targets = [])).push(a.slice('--target='.length));
+    }
+    return opts;
+}
+function realpathOr(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
     }
-    // 1. Resolve package
+}
+async function terminalConfirm(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => rl.question(`${question} [y/N]: `, resolve));
+    rl.close();
+    return answer.trim().toLowerCase() === 'y' || answer.trim().toLowerCase() === 'yes';
+}
+async function runSync(options) {
+    const { projectRoot } = options;
+    const outcome = { applied: [], manifestWritten: false, report: [], trace: [] };
+    const isTTY = options.isTTY ?? Boolean(process.stdin.isTTY);
+    // 1. Resolve the installed package.
     const pkg = (0, PackageResolver_1.resolvePackage)(projectRoot);
+    // 1b. Steward exemption (design C2; found-not-fixed item 5): the package's own
+    //     tree is not a consumer. Nothing is read or written — including this
+    //     repo's own stale `.kiro/sync-manifest.json`, which sync does not own here.
+    if (realpathOr(pkg.root) === realpathOr(projectRoot)) {
+        console.log(Reporter_1.STEWARD_REPO_MESSAGE);
+        return { ...outcome, stopped: 'steward', report: [Reporter_1.STEWARD_REPO_MESSAGE] };
+    }
     console.log(`📦 @3fn/core v${pkg.version}\n`);
-    // 2. Load manifest (or null for first-time)
-    let manifest = (0, Manifest_1.loadManifest)(projectRoot);
-    const isFirstSync = !manifest;
-    // 3. Load ignore filter
-    const ignore = (0, IgnoreFilter_1.loadIgnoreFilter)(projectRoot);
-    // 4. Scan package and project files
-    const packageFiles = (0, FileScanner_1.scanFiles)(pkg.root, FileScanner_1.MANAGED_DIRS);
-    const projectFiles = (0, FileScanner_1.scanFiles)(projectRoot, FileScanner_1.MANAGED_DIRS);
-    // 5. Bootstrap manifest on first sync
-    if (isFirstSync) {
-        manifest = (0, Manifest_1.bootstrapManifest)(projectFiles, pkg.version);
-        console.log('📋 First sync — bootstrapping manifest from current project state.\n');
-    }
-    // 6. Classify
-    const classified = (0, Classifier_1.classifyFiles)(packageFiles, projectFiles, manifest, ignore);
-    // 7. Report
-    (0, Reporter_1.displayReport)(classified, { dryRun });
-    // 7b. Net-new: detect a stale MCP_STEERING_DIR (pre-119-A '.kiro/steering')
-    //     in the consumer's MCP config and prompt to repoint it at 'governance/'.
-    await (0, SteeringDirCheck_1.reportAndMaybeFixStaleSteeringDir)(projectRoot, { dryRun });
-    // 8. Early exit for dry-run
-    if (dryRun)
-        return;
-    // 9. Apply
-    const allUpdatable = [...classified.new, ...classified.updatedSafe];
-    if (force) {
-        // Force mode: apply everything without prompting
-        const allFiles = [...allUpdatable, ...classified.conflicts];
-        (0, Applier_1.applyForce)(allFiles, pkg.root, projectRoot, manifest);
+    if (options.retiredForce)
+        console.log(`${Reporter_1.RETIRED_FORCE_MESSAGE}\n`);
+    // 2. Manifest — the root manifest, else the legacy one (relocated on apply).
+    const manifestLines = [];
+    const loaded = (0, Manifest_1.loadManifest)(projectRoot);
+    if (loaded.kind === 'corrupt') {
+        const msg = (0, Reporter_1.corruptManifestMessage)(loaded.error);
+        console.log(msg);
+        return { ...outcome, stopped: 'corrupt-manifest', report: [msg] };
+    }
+    let manifest;
+    let pruned = [];
+    let relocateLegacy = false;
+    let persistManifest;
+    if (loaded.kind === 'ok') {
+        manifest = loaded.manifest;
+        persistManifest = true;
     }
     else {
-        // Auto-apply governance tier
-        const govResult = (0, Applier_1.applyGovernance)(allUpdatable, pkg.root, projectRoot, manifest);
-        if (govResult.applied.length > 0) {
-            console.log(`\n  ✓ ${govResult.applied.length} governance file${govResult.applied.length === 1 ? '' : 's'} applied`);
-        }
-        // Confirm and apply source tier
-        const sourceFiles = allUpdatable.filter(f => f.tier === 'source');
-        if (sourceFiles.length > 0) {
-            const confirmed = await (0, Prompter_1.confirmSourceUpdates)(sourceFiles);
-            if (confirmed) {
-                (0, Applier_1.applySource)(allUpdatable, pkg.root, projectRoot, manifest);
-                console.log(`  ✓ ${sourceFiles.length} source file${sourceFiles.length === 1 ? '' : 's'} applied`);
+        const legacy = (0, Manifest_1.loadLegacyManifest)(projectRoot);
+        if (legacy) {
+            const conv = (0, Manifest_1.convertLegacyManifest)(legacy, pkg.version);
+            manifest = conv.manifest;
+            pruned = conv.pruned;
+            relocateLegacy = true;
+            persistManifest = true;
+            manifestLines.push(`found the pre-123 manifest ${Manifest_1.LEGACY_MANIFEST_PATH} (last synced at ${legacy.version}) — it moves to ${Manifest_1.MANIFEST_FILE} at the repo root when changes apply`);
+        }
+        else {
+            manifest = {
+                version: Manifest_1.MANIFEST_SCHEMA_VERSION,
+                posture: 'born',
+                installedVersion: pkg.version,
+                contractHash: '',
+                attachedTargets: [],
+                entries: {},
+            };
+            persistManifest = false;
+            manifestLines.push(`no ${Manifest_1.MANIFEST_FILE} and no ${Manifest_1.LEGACY_MANIFEST_PATH} — nothing here was recorded as DesignerPunk's, so nothing is managed`);
+        }
+    }
+    const entries = manifest.entries;
+    pruned = [...pruned, ...(0, Manifest_1.pruneDemanaged)(entries)];
+    manifestLines.push(...(0, Manifest_1.pruneReportLines)(pruned));
+    // 3. The agent-layer source (C20) — the package side of the generated surfaces, and the
+    //    availability of the attach step `--migrate-legacy` runs. Loaded once.
+    let agentLayer = null;
+    let agentLayerReason = '';
+    if (options.agentLayer !== undefined) {
+        agentLayer = options.agentLayer;
+        if (!agentLayer)
+            agentLayerReason = 'the agent-layer lane is unavailable';
+    }
+    else {
+        try {
+            agentLayer = bundleAgentLayerSource(pkg.root, projectRoot);
+        }
+        catch (err) {
+            agentLayerReason = err.message;
+        }
+    }
+    const emissions = new Map();
+    const emitFor = (target) => {
+        if (!emissions.has(target))
+            emissions.set(target, agentLayer.emit(target));
+        return emissions.get(target);
+    };
+    // 3b. Generated surfaces (C7 rows ADDED) — file and region grain, for attachedTargets ONLY.
+    const ignore = (0, IgnoreFilter_1.loadIgnoreFilter)(projectRoot);
+    const sections = [];
+    let files = (0, Classifier_1.emptyClassification)();
+    if (manifest.attachedTargets.length > 0) {
+        if (!agentLayer) {
+            sections.push({ title: '⚠️  Generated agent layer:', lines: [agentLayerUnavailableMessage(agentLayerReason)] });
+        }
+        else {
+            try {
+                outcome.generated = await classifyGenerated(projectRoot, manifest.attachedTargets, emitFor, entries, ignore);
+                files = outcome.generated.files;
+                const g = outcome.generated;
+                const lines = [
+                    ...g.warnings.map((w) => `⚠️  ${w}`),
+                    ...g.markersMissing.map((f) => (0, errorCatalog_1.managedRegionMarkersMissingMessage)(f)),
+                    ...g.untrackedNew.map((u) => (0, Reporter_1.untrackedNewMessage)(u.path, u.target)),
+                ];
+                if (lines.length > 0)
+                    sections.push({ title: '🧩 Generated agent layer:', lines });
             }
-            else {
-                console.log('  ⏭ Source updates skipped.');
+            catch (err) {
+                sections.push({ title: '⚠️  Generated agent layer:', lines: [agentLayerUnavailableMessage(err.message)] });
             }
         }
-        // Interactive conflict resolution
-        if (classified.conflicts.length > 0) {
-            const decisions = await (0, Prompter_1.resolveConflicts)(classified.conflicts, pkg.root, projectRoot);
-            for (const d of decisions) {
-                if (d.decision === 'overwrite') {
-                    (0, Applier_1.applyFile)(d.file, pkg.root, projectRoot, manifest);
-                }
+    }
+    // 4. Key grain — the package side for every target whose keys the manifest records (attachedTargets,
+    //    plus a target MCP-wired without its agent layer: `init --skip-agents`, `attach --reference`).
+    //    A consume-posture manifest's package side is the reference scope (docs + application only, C20).
+    const keyResults = [];
+    const keyTargets = keyGrainTargets(manifest);
+    if (keyTargets.length > 0) {
+        const pkgKeys = (0, KeyGrain_1.computePackageKeys)(pkg.root, keyTargets);
+        if (pkgKeys.kind === 'unavailable') {
+            sections.push({ title: '⚠️  MCP configuration:', lines: [(0, Reporter_1.packageKeysUnavailableMessage)(pkgKeys.reason)] });
+        }
+        else {
+            if (manifest.posture === 'consume')
+                restrictToReference(pkgKeys.keys);
+            for (const surface of KeyGrain_1.KEY_SURFACES) {
+                const pkgSurfaceKeys = pkgKeys.keys.get(surface.file);
+                if (!pkgSurfaceKeys)
+                    continue;
+                keyResults.push((0, KeyGrain_1.classifySurfaceKeys)(surface, pkgSurfaceKeys, (0, KeyGrain_1.readProjectKeys)(projectRoot, surface), entries));
             }
         }
     }
-    // 10. Save manifest
-    manifest.version = pkg.version;
-    manifest.syncedAt = new Date().toISOString();
-    (0, Manifest_1.saveManifest)(projectRoot, manifest);
-    console.log('\n✅ Sync complete. Manifest updated.');
+    // 4b. Legacy copies (C7 Migration item 4) — keyed on `origin: 'copy'` under the release-1 copy roots,
+    //     never on the manifest's version. REPORTED; `--migrate-legacy` is offered ONLY when the attach
+    //     step is available, and runs it in the same flow.
+    const legacy = (0, Migration_1.assessLegacyCopies)(projectRoot, entries);
+    if (legacy) {
+        outcome.legacyCopies = legacy;
+        outcome.attach = await attachAvailability(projectRoot, manifest, options.targets ?? [], agentLayer, agentLayerReason, emitFor);
+        sections.push({ title: '🧳 Legacy copies from an earlier init:', lines: (0, Migration_1.legacyCopyReportLines)(legacy, outcome.attach) });
+    }
+    // 5. Migration — pre-123 component copies (C7 steps 2–5), judged against shipped content.
+    const trigger = (0, Migration_1.migrationTrigger)(projectRoot, relocateLegacy);
+    if (trigger) {
+        const lines = [];
+        if ((0, Migration_1.hasLegacyCopies)(projectRoot)) {
+            const fetcher = options.fetcher ?? (0, Migration_1.npmRailFetcher)(projectRoot);
+            try {
+                const upperBound = (0, Migration_1.resolveUpperBound)(projectRoot, loaded.kind === 'ok' ? manifest.installedVersion : null);
+                outcome.migration = (0, Migration_1.assessComponentCopies)(projectRoot, { fetcher, upperBound, trigger });
+            }
+            finally {
+                fetcher.dispose?.();
+            }
+            for (const v of outcome.migration.fetchLog)
+                outcome.trace.push(`fetch:${v}`);
+            lines.push(...(0, Migration_1.migrationReportLines)(outcome.migration));
+        }
+        sections.push({ title: '🧬 Migrating from a pre-123 install:', lines });
+    }
+    // 6. Repairs (C7 step 6) — OFFERED only now, after the migration fetch ran
+    //    through the consumer's rail (the npmrc repair removes that rail).
+    const offers = (0, Migration_1.repairOffers)(projectRoot, (0, Migration_1.hasLegacyCopies)(projectRoot));
+    for (const o of offers)
+        outcome.trace.push(`repair-offered:${o.kind}`);
+    if (offers.length > 0)
+        sections.push({ title: '🔧 Repairs offered:', lines: offers.flatMap((o) => o.lines) });
+    // 6b. The name contract (Req 5A; Task 6) — REPORT ONLY: the consumer's token
+    //     tier is never written (5.8). Reads the package's compiled contract and her
+    //     generated web CSS; no output → `cannot check`, never clean.
+    outcome.nameContract = await nameContractSection(projectRoot, pkg.root, options.configLoader);
+    sections.push({ title: '🔤 Name contract (your tokens vs. the names our components reference):', lines: outcome.nameContract.lines });
+    // 6c. The type contract (DD11; Peter's fork-1 ruling (B), 2026-09-27). Only for a
+    //     repo with a manifest. When the recorded hash differs, the PREVIOUS members come
+    //     from the previously installed version's own contract, fetched through her rail.
+    const installedContract = loadNameContractSafe(pkg.root)?.typeContract;
+    if (persistManifest) {
+        let typeFetcher;
+        try {
+            outcome.typeContract = (0, NameContract_1.assessTypeContract)({
+                recordedHash: manifest.contractHash,
+                recordedVersion: manifest.installedVersion,
+                current: installedContract,
+                fetchPrevious: (version) => {
+                    typeFetcher = options.fetcher ?? (0, Migration_1.npmRailFetcher)(projectRoot);
+                    outcome.trace.push(`type-contract-fetch:${version}`);
+                    return (0, NameContract_1.previousContractAt)(typeFetcher.fetch(version));
+                },
+            });
+        }
+        finally {
+            typeFetcher?.dispose?.();
+        }
+        if (outcome.typeContract.lines.length > 0)
+            sections.push({ title: '🧾 Type contract:', lines: outcome.typeContract.lines });
+    }
+    // 7. REPORT — always, before anything applies.
+    const report = (0, Reporter_1.buildReport)({ dryRun: Boolean(options.dryRun), manifestLines, files, keys: keyResults, sections });
+    (0, Reporter_1.displayReport)(report);
+    outcome.report = report;
+    await (0, SteeringDirCheck_1.reportAndMaybeFixStaleSteeringDir)(projectRoot, { dryRun: Boolean(options.dryRun) || !isTTY });
+    // 8. Decide.
+    if (options.dryRun)
+        return { ...outcome, stopped: 'dry-run' };
+    // Explicit per-repair flags are their own authorization (after the report).
+    if (options.repairNpmrc && offers.some((o) => o.kind === 'npmrc') && (0, Migration_1.repairRegistryPin)(projectRoot)) {
+        outcome.trace.push('repair-applied:npmrc');
+        outcome.applied.push('.npmrc');
+        console.log('  ✓ .npmrc: removed the @3fn → GitHub Packages mapping line');
+    }
+    if (options.repairTsconfig && offers.some((o) => o.kind === 'tsconfig') && (0, Migration_1.repairTsconfigPins)(projectRoot)) {
+        outcome.trace.push('repair-applied:tsconfig');
+        outcome.applied.push('tsconfig.test.json');
+        console.log('  ✓ tsconfig.test.json: removed the raw-src @3fn/core paths entries');
+    }
+    if (options.migrateComponents && outcome.migration) {
+        // The explicit flag IS the per-run authorization (nothing is removed without it).
+        outcome.relocation = (0, Migration_1.relocateComponents)(projectRoot, outcome.migration);
+        const r = outcome.relocation;
+        console.log(`\n  ✓ --migrate-components: removed ${r.removed.length} unmodified cop${r.removed.length === 1 ? 'y' : 'ies'}, ` +
+            `relocated ${r.relocated.length} to ${'src/components/<Name>/'}` +
+            (r.skipped.length ? `; not moved (src/components/<Name>/ exists): ${r.skipped.join(', ')}` : '') +
+            (r.leftInPlace.length ? `; left in place (cannot tell): ${r.leftInPlace.join(', ')}` : ''));
+    }
+    if (options.migrateLegacy) {
+        const ran = await runMigrateLegacy(projectRoot, pkg.root, manifest, outcome);
+        if (ran) {
+            // The attach step regenerated the agent layer and its MCP wiring: what was classified before it is
+            // stale, so nothing else applies in this run. The manifest records exactly what attach wrote.
+            manifest.installedVersion = pkg.version;
+            if (installedContract)
+                manifest.contractHash = installedContract.hash;
+            outcome.manifestWritten = (0, Manifest_1.saveManifest)(projectRoot, manifest);
+            if (relocateLegacy && !(0, Manifest_1.legacyHasPointer)(projectRoot))
+                (0, Manifest_1.writeLegacyPointer)(projectRoot);
+            console.log(`✅ Sync complete. ${Manifest_1.MANIFEST_FILE} updated. Run 'npx designerpunk sync' again to review the migrated repo.`);
+            console.log('');
+            console.log((0, errorCatalog_1.restartLineSequencedMessage)());
+            return outcome;
+        }
+    }
+    const restore = new Set(options.restore ?? []);
+    const overwrite = new Set(options.overwrite ?? []);
+    const keyOf = (s, key) => `${s.surface.file}#${key}`;
+    const isRegion = (p) => p.endsWith('#managed');
+    const fileBatch = [...files.new, ...files.updatedSafe].map((f) => f.relativePath);
+    const fileRestore = files.deletedByYou.filter((f) => restore.has(f.relativePath)).map((f) => f.relativePath);
+    // A region conflict is the catalog's "edited inside" row — "not applying without --apply": --apply (or
+    // --overwrite <file>#managed) replaces it; the terminal's batch confirmation alone never does.
+    const fileOverwrite = files.conflicts
+        .filter((f) => overwrite.has(f.relativePath) || (isRegion(f.relativePath) && Boolean(options.apply)))
+        .map((f) => f.relativePath);
+    const keyWork = keyResults.map((s) => ({
+        s,
+        items: s.classified.filter((c) => c.classification === 'new' ||
+            c.classification === 'updated-safe' ||
+            (c.classification === 'deleted-by-you' && restore.has(keyOf(s, c.key))) ||
+            (c.classification === 'conflict' && overwrite.has(keyOf(s, c.key)))),
+    }));
+    const keyCount = keyWork.reduce((n, w) => n + w.items.length, 0);
+    const manifestChanges = relocateLegacy ||
+        pruned.length > 0 ||
+        files.adoptable.length > 0 ||
+        files.dropEntries.length > 0 ||
+        keyResults.some((s) => s.dropEntries.length > 0) ||
+        (persistManifest && manifest.installedVersion !== pkg.version) ||
+        (persistManifest && installedContract !== undefined && manifest.contractHash !== installedContract.hash);
+    const workCount = fileBatch.length + fileRestore.length + fileOverwrite.length + keyCount;
+    if (workCount === 0 && !manifestChanges)
+        return outcome;
+    if (!options.apply) {
+        if (!isTTY) {
+            console.log(`\n${Reporter_1.OFF_TTY_REPORT_ONLY_MESSAGE}`);
+            return { ...outcome, stopped: 'off-tty' };
+        }
+        const confirm = options.confirm ?? terminalConfirm;
+        const ok = await confirm(`\nApply ${workCount} change${workCount === 1 ? '' : 's'}${manifestChanges ? ' and update the manifest' : ''}?`);
+        if (!ok) {
+            console.log('  ⏭ Nothing applied.');
+            return { ...outcome, stopped: 'declined' };
+        }
+    }
+    // 9. Apply — generated content from the package side computed above (never a package-file copy).
+    const contents = outcome.generated?.contents ?? new Map();
+    for (const rel of [...fileBatch, ...fileRestore, ...fileOverwrite]) {
+        const content = contents.get(rel);
+        if (content === undefined)
+            continue;
+        if (isRegion(rel) ? applyGeneratedRegion(projectRoot, rel, content, entries) : applyGeneratedFile(projectRoot, rel, content, entries)) {
+            outcome.applied.push(rel);
+        }
+    }
+    for (const f of files.adoptable) {
+        const content = contents.get(f.relativePath);
+        if (content === undefined)
+            continue;
+        entries[f.relativePath] = isRegion(f.relativePath)
+            ? { hash: (0, FileScanner_2.hashBuffer)((0, RegionGrain_1.normalizeRegionContent)(content)), grain: 'region', origin: 'generated' }
+            : { hash: (0, FileScanner_2.hashBuffer)(content), grain: 'file', origin: 'generated' };
+    }
+    for (const rel of files.dropEntries)
+        delete entries[rel];
+    for (const { s, items } of keyWork) {
+        for (const id of s.dropEntries)
+            delete entries[id];
+        if (items.length === 0)
+            continue;
+        (0, Applier_1.applyKeys)(projectRoot, s.surface, items.map((c) => ({ key: c.key, value: c.packageValue })), entries);
+        for (const c of items)
+            outcome.applied.push(keyOf(s, c.key));
+    }
+    // 10. Save — the root manifest; relocation leaves the legacy file a pointer.
+    if (persistManifest) {
+        manifest.installedVersion = pkg.version;
+        // Re-record the baseline AFTER the report, and only on this write (fork-1 ruling).
+        if (installedContract)
+            manifest.contractHash = installedContract.hash;
+        outcome.manifestWritten = (0, Manifest_1.saveManifest)(projectRoot, manifest);
+        if (relocateLegacy && !(0, Manifest_1.legacyHasPointer)(projectRoot))
+            (0, Manifest_1.writeLegacyPointer)(projectRoot);
+    }
+    if (outcome.applied.length > 0)
+        console.log(`\n  ✓ ${outcome.applied.length} change${outcome.applied.length === 1 ? '' : 's'} applied`);
+    console.log(outcome.manifestWritten ? `✅ Sync complete. ${Manifest_1.MANIFEST_FILE} updated.` : '✅ Sync complete.');
+    return outcome;
+}
+const displayPath = (projectRoot, abs, dir = false) => {
+    const rel = path.relative(projectRoot, abs).split(path.sep).join('/');
+    const shown = rel === '' ? '.' : rel.startsWith('..') ? abs : rel;
+    return dir && !shown.endsWith('/') ? `${shown}/` : shown;
+};
+async function nameContractSection(projectRoot, pkgRoot, configLoader) {
+    const contract = (0, NameContract_1.loadNameContract)(pkgRoot);
+    if (!contract)
+        return { status: 'cannot-check', lines: [(0, NameContract_1.contractMissingMessage)(pkgRoot)] };
+    let outputDir;
+    let tokenRoot;
+    try {
+        const config = configLoader ? await (0, ConfigLoader_1.loadConfig)(projectRoot, configLoader) : await (0, ConfigLoader_1.loadConfig)(projectRoot);
+        outputDir = config.outputDir;
+        tokenRoot = config.tokenSourceMode === 'local' ? config.tokenSourceRoot : path.join(projectRoot, 'src', 'tokens');
+    }
+    catch (err) {
+        return { status: 'cannot-check', lines: [(0, NameContract_1.configUnreadableMessage)(err instanceof Error ? err.message : String(err))] };
+    }
+    return (0, NameContract_1.checkNameContract)(contract, (0, NameContract_1.readPresentNames)(outputDir), {
+        outputDirDisplay: displayPath(projectRoot, outputDir),
+        semanticTierPath: displayPath(projectRoot, path.join(tokenRoot, 'semantic'), true),
+        primitiveTierPath: displayPath(projectRoot, tokenRoot, true),
+    });
+}
+function loadNameContractSafe(pkgRoot) {
+    try {
+        return (0, NameContract_1.loadNameContract)(pkgRoot);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Generated surfaces (Task 16.5; design.md § "C7" managed-set rows ADDED)
+// ---------------------------------------------------------------------------
+function agentLayerUnavailableMessage(reason) {
+    return `could not generate DesignerPunk's agent layer from the installed package — ${reason}. Your generated agent files were not checked.`;
+}
+function markersFor(file) {
+    return (0, RegionGrain_1.regionMarkers)(file.endsWith('.md') ? RegionGrain_1.CLAUDE_MD_COMMENT : RegionGrain_1.GITIGNORE_COMMENT);
+}
+/**
+ * The directories the package's agent layer writes into, derived from the emission itself (never a list
+ * kept here): a path's first two segments (`.claude/agents`, `.kiro/steering`, `.claude/skills`, …). A
+ * recorded generated entry under one of them that the package no longer emits is `removed`; a consumer's
+ * own file there is never classified (it has no entry and no package counterpart).
+ */
+function agentLayerRoots(paths) {
+    const roots = new Set();
+    for (const p of paths) {
+        const seg = p.split('/');
+        roots.add(seg.length >= 3 ? seg.slice(0, 2).join('/') : seg.length === 2 ? seg[0] : p);
+    }
+    return [...roots].sort();
+}
+/**
+ * Classify the generated surfaces for `targets` (the manifest's `attachedTargets` — C7: "the package side
+ * of the generated surfaces is freshly generated, by `emitConsumer`, for the manifest's attachedTargets").
+ * A target with nothing recorded yet yields `untracked-new` (reported, never applied); once `attach` has
+ * recorded any of its surfaces, a newly emitted file is `new`.
+ */
+async function classifyGenerated(projectRoot, targets, emitFor, entries, ignore) {
+    const contents = new Map();
+    const targetOf = new Map();
+    const pkgFiles = [];
+    const regions = [];
+    const warnings = [];
+    for (const target of targets) {
+        const emitted = await emitFor(target);
+        for (const w of emitted.warnings)
+            if (!warnings.includes(w))
+                warnings.push(w);
+        for (const f of emitted.files) {
+            const id = f.grain === 'region' ? (0, Classifier_1.regionEntryId)(f.path) : f.path;
+            if (contents.has(id))
+                continue;
+            contents.set(id, f.content);
+            targetOf.set(id, target);
+            if (f.grain === 'region')
+                regions.push({ ...f, target });
+            else
+                pkgFiles.push({ relativePath: f.path, absolutePath: '', hash: (0, FileScanner_2.hashBuffer)(f.content) });
+        }
+    }
+    const recordedTargets = new Set();
+    for (const [id, target] of targetOf)
+        if (entries[id]?.origin === 'generated')
+            recordedTargets.add(target);
+    const roots = agentLayerRoots(pkgFiles.map((f) => f.relativePath));
+    const files = (0, Classifier_1.classifyFiles)(pkgFiles, (0, FileScanner_1.scanFiles)(projectRoot, roots), entries, ignore, roots, {
+        origin: 'generated',
+        untracked: (rel) => !recordedTargets.has(targetOf.get(rel) ?? ''),
+    });
+    const markersMissing = [];
+    for (const r of regions) {
+        if (ignore.isIgnored(r.path))
+            continue;
+        const id = (0, Classifier_1.regionEntryId)(r.path);
+        const abs = path.join(projectRoot, r.path);
+        const text = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf-8') : undefined;
+        const entry = entries[id]?.origin === 'generated' && entries[id]?.grain === 'region' ? entries[id] : undefined;
+        const c = (0, Classifier_1.classifyRegion)(text, markersFor(r.path), r.content, entry, !recordedTargets.has(r.target));
+        const item = (classification, reason) => ({
+            relativePath: id,
+            classification,
+            packageHash: (0, FileScanner_2.hashBuffer)((0, RegionGrain_1.normalizeRegionContent)(r.content)),
+            ...(entry ? { manifestHash: entry.hash } : {}),
+            ...(reason ? { reason } : {}),
+        });
+        switch (c.kind) {
+            case 'unchanged':
+                files.unchanged.push(item('unchanged'));
+                break;
+            case 'updated-safe':
+                files.updatedSafe.push(item('updated-safe', 'unchanged by you — package updated'));
+                break;
+            case 'conflict':
+                files.conflicts.push(item('conflict', (0, errorCatalog_1.managedRegionEditedInsideMessage)(r.path)));
+                break;
+            case 'new':
+                files.new.push(item('new'));
+                break;
+            case 'untracked-new':
+                files.untrackedNew.push(item('untracked-new'));
+                break;
+            case 'deleted-by-you':
+                files.deletedByYou.push(item('deleted-by-you'));
+                break;
+            case 'adoptable':
+                files.adoptable.push(item('unchanged'));
+                break;
+            case 'markers-missing':
+                markersMissing.push(r.path);
+                break;
+        }
+    }
+    return {
+        files,
+        contents,
+        untrackedNew: files.untrackedNew.map((f) => ({ path: f.relativePath, target: targetOf.get(f.relativePath) ?? '' })),
+        markersMissing,
+        warnings,
+    };
+}
+/** Write one generated file and record exactly the bytes written (`origin: 'generated'`). */
+function applyGeneratedFile(projectRoot, rel, content, entries) {
+    try {
+        const abs = path.join(projectRoot, rel);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, content, 'utf-8');
+        entries[rel] = { hash: (0, FileScanner_2.hashBuffer)(content), grain: 'file', origin: 'generated' };
+        return true;
+    }
+    catch (err) {
+        console.error(`  ❌ Failed to apply ${rel}: ${err.message}`);
+        return false;
+    }
+}
+/**
+ * Write one managed region (`<file>#managed`): splice it when the markers are there, create the file when it
+ * is absent, append the region when the file has none (a `new` region — never a recorded one whose markers
+ * she removed, which the classifier reports and never routes here). Outside bytes are never changed.
+ */
+function applyGeneratedRegion(projectRoot, id, content, entries) {
+    const file = id.slice(0, -'#managed'.length);
+    const abs = path.join(projectRoot, file);
+    const markers = markersFor(file);
+    try {
+        let text;
+        if (!fs.existsSync(abs)) {
+            text = (0, RegionGrain_1.wrapRegion)(markers, content);
+        }
+        else {
+            const existing = fs.readFileSync(abs, 'utf-8');
+            const spliced = (0, RegionGrain_1.spliceRegion)(existing, markers, content, file);
+            text = spliced.ok ? spliced.text : (0, RegionGrain_1.appendRegion)(existing, markers, content);
+        }
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, text, 'utf-8');
+        entries[id] = { hash: (0, FileScanner_2.hashBuffer)((0, RegionGrain_1.normalizeRegionContent)(content)), grain: 'region', origin: 'generated' };
+        return true;
+    }
+    catch (err) {
+        console.error(`  ❌ Failed to apply ${id}: ${err.message}`);
+        return false;
+    }
+}
+/**
+ * The targets whose MCP keys `sync` reconciles: `attachedTargets`, plus any target the manifest records
+ * keys for without attaching its agent layer (`init --skip-agents`; `attach --reference`, whose manifest
+ * exists so `sync` can repair approval drift — DD22).
+ */
+function keyGrainTargets(manifest) {
+    const targets = new Set(manifest.attachedTargets);
+    for (const surface of KeyGrain_1.KEY_SURFACES) {
+        if (Object.entries(manifest.entries).some(([id, e]) => e.grain === 'key' && id.startsWith(`${surface.file}#`)))
+            targets.add(surface.target);
+    }
+    return [...targets];
+}
+/** A consume-posture manifest's package side: the reference servers only (C20 `--reference`; DD22). */
+function restrictToReference(keys) {
+    for (const surfaceKeys of keys.values()) {
+        for (const key of [...surfaceKeys.keys()]) {
+            if (!attach_1.REFERENCE_SERVERS.some((s) => key === s || key.startsWith(`mcp__${s}__`)))
+                surfaceKeys.delete(key);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// --migrate-legacy (C7 Migration item 4; Task 16.5) — offered ONLY with attach,
+// and run in the SAME flow: removal, then attach.
+// ---------------------------------------------------------------------------
+/**
+ * Whether the attach step can run here — decided through `attach`'s own rules: the agent-layer lane loads
+ * from the installed package, `attach` would not refuse this repo (born or package-mode only), every
+ * requested target is declared, and the emission succeeds for each target it would attach.
+ */
+async function attachAvailability(projectRoot, manifest, requested, agentLayer, agentLayerReason, emitFor) {
+    if (!agentLayer)
+        return { available: false, reason: agentLayerReason || 'the agent-layer lane is unavailable' };
+    const refusal = (0, attach_1.attachRefusal)(projectRoot);
+    if (refusal.message !== null)
+        return { available: false, reason: `attach refuses this repo: ${refusal.message}` };
+    const declared = agentLayer.declaredTargets();
+    const undeclared = requested.filter((t) => !declared.includes(t));
+    if (undeclared.length > 0) {
+        return { available: false, reason: `target ${undeclared.join(', ')} is not declared by the installed package (declared: ${declared.join(', ')})` };
+    }
+    const targets = [...new Set([...manifest.attachedTargets, ...requested])];
+    try {
+        for (const t of targets)
+            await emitFor(t);
+    }
+    catch (err) {
+        return { available: false, reason: err.message };
+    }
+    return { available: true, targets, declared };
+}
+/**
+ * `--migrate-legacy`: the removal, then — in the same run, through `attach`'s code path
+ * (`emitAgentLayer`) — the attach step for each target. Refuses, removing nothing, when attach is not
+ * available or there is no target. Returns true iff it ran.
+ */
+async function runMigrateLegacy(projectRoot, pkgRoot, manifest, outcome) {
+    if (!outcome.legacyCopies) {
+        console.log('\n  --migrate-legacy: this manifest records no legacy copies — nothing to migrate.');
+        return false;
+    }
+    const avail = outcome.attach;
+    if (!avail || !avail.available) {
+        outcome.trace.push('migrate-legacy:refused');
+        console.log(`\n  ${(0, Migration_1.migrateLegacyRefusedMessage)(avail && !avail.available ? avail.reason : 'attach availability was not established')}`);
+        return false;
+    }
+    if (avail.targets.length === 0) {
+        outcome.trace.push('migrate-legacy:refused');
+        console.log(`\n  ${(0, Migration_1.migrateLegacyNeedsTargetMessage)(avail.declared)}`);
+        return false;
+    }
+    outcome.legacyRemoval = (0, Migration_1.removeLegacyCopies)(projectRoot, manifest.entries);
+    outcome.trace.push(`migrate-legacy:removed:${outcome.legacyRemoval.removed.length}`);
+    console.log(`\n${(0, Migration_1.legacyRemovalSummary)(outcome.legacyRemoval)}`);
+    for (const target of avail.targets) {
+        const layer = await (0, attach_1.emitAgentLayer)({ pkgRoot, repoRoot: projectRoot, requestedTarget: target, mode: 'attach', manifest });
+        outcome.trace.push(`attach:${target}`);
+        outcome.applied.push(...layer.files);
+        const parts = [`${layer.written} file${layer.written === 1 ? '' : 's'} written`];
+        if (layer.unchanged > 0)
+            parts.push(`${layer.unchanged} unchanged`);
+        if (layer.collided > 0)
+            parts.push(`${layer.collided} skipped (see warnings above)`);
+        console.log(`  ✓ attached ${target} — ${parts.join(', ')}`);
+    }
+    return true;
 }
 //# sourceMappingURL=index.js.map