@gadmin2n/cli 0.0.105 → 0.0.107

package/actions/update.action.js

@@ -17,157 +17,37 @@ const path = require("path");
 const inquirer = require("inquirer");
 const child_process_1 = require("child_process");
 const abstract_action_1 = require("./abstract.action");
-const template_merge_1 = require("../lib/template-merge");
 const version_check_1 = require("../lib/version-check");
+const merge3way_1 = require("../lib/template-merge/merge3way");
+const binary_detect_1 = require("../lib/template-merge/binary-detect");
+const residual_scan_1 = require("../lib/template-merge/residual-scan");
+const classify_1 = require("../lib/template-merge/classify");
+const excludes_1 = require("../lib/template-merge/excludes");
+const base_store_1 = require("../lib/template-merge/base-store");
+const materialize_1 = require("../lib/template-merge/materialize");
+const config_validate_1 = require("../lib/template-merge/config-validate");
+const types_1 = require("../lib/template-merge/types");
 /* ------------------------------------------------------------------ *
  * Config / constants
  * ------------------------------------------------------------------ */
-const DEFAULT_EXCLUDES = [
-    'node_modules',
-    '.git',
-    'dist',
-    'generated',
-    '.DS_Store',
-    '.env.local',
-    'readme.md',
-    // package manager lock files & PnP artifacts —
-    // regenerated by the auto-install stage based on the merged package.json.
-    // Letting template versions overwrite instance lock files is semantically
-    // wrong (lock should reflect actually-installed deps) and clutters diff output.
-    'yarn.lock',
-    'package-lock.json',
-    'pnpm-lock.yaml',
-    '.yarn',
-    '.pnp.cjs',
-    '.pnp.loader.mjs',
-];
 const CLAUDE_CONTEXT_REPO_HTTPS = 'https://git.tencent.com/OIT-OMC/erp-ai-coding-context.git';
 const CLAUDE_CONTEXT_REPO_SSH = 'git@git.tencent.com:OIT-OMC/erp-ai-coding-context.git';
 const CLAUDE_CONTEXT_BRANCH = 'master';
 const CLAUDE_SOURCE_SUBDIR = '.claude';
 const CLAUDE_TARGET_DIRS = ['.claude-internal', '.agent'];
-/* ------------------------------------------------------------------ *
- * Glob / pattern utilities
- * ------------------------------------------------------------------ */
 /**
- * Convert a glob pattern to a RegExp.
- * Supports: * (any chars except /), ** (any path segments), ? (single char)
+ * Canonical formatting for "failed to materialize the base" errors.
+ * All three handlers (handleDiff/handleStatus/handleUpdate) share this so the
+ * user sees the same wording regardless of entry point.
  */
-function globToRegex(pattern) {
-    let regexStr = '^';
-    let i = 0;
-    while (i < pattern.length) {
-        const c = pattern[i];
-        if (c === '*') {
-            if (pattern[i + 1] === '*') {
-                if (pattern[i + 2] === '/') {
-                    regexStr += '(?:.+/)?';
-                    i += 3;
-                }
-                else {
-                    regexStr += '.*';
-                    i += 2;
-                }
-            }
-            else {
-                regexStr += '[^/]*';
-                i++;
-            }
-        }
-        else if (c === '?') {
-            regexStr += '[^/]';
-            i++;
-        }
-        else if (c === '.' ||
-            c === '(' ||
-            c === ')' ||
-            c === '[' ||
-            c === ']' ||
-            c === '{' ||
-            c === '}' ||
-            c === '+' ||
-            c === '^' ||
-            c === '$' ||
-            c === '|' ||
-            c === '\\') {
-            regexStr += '\\' + c;
-            i++;
-        }
-        else {
-            regexStr += c;
-            i++;
-        }
-    }
-    regexStr += '$';
-    return new RegExp(regexStr);
-}
-function matchesPattern(filePath, pattern) {
-    if (filePath === pattern)
-        return true;
-    if (filePath.startsWith(pattern + '/'))
-        return true;
-    const parts = filePath.split('/');
-    if (!pattern.includes('/') &&
-        !pattern.includes('*') &&
-        !pattern.includes('?')) {
-        if (parts.includes(pattern))
-            return true;
-    }
-    if (pattern.includes('*') || pattern.includes('?')) {
-        const regex = globToRegex(pattern);
-        return regex.test(filePath);
-    }
-    return false;
-}
-function shouldExclude(filePath, excludes) {
-    for (const pattern of excludes) {
-        if (matchesPattern(filePath, pattern))
-            return true;
-    }
-    return false;
-}
-function collectFiles(dir, excludes, base = '') {
-    const results = [];
-    const entries = fs.readdirSync(path.join(dir, base), { withFileTypes: true });
-    for (const entry of entries) {
-        const rel = base ? `${base}/${entry.name}` : entry.name;
-        if (shouldExclude(rel, excludes))
-            continue;
-        if (entry.isDirectory()) {
-            results.push(...collectFiles(dir, excludes, rel));
-        }
-        else if (entry.isFile()) {
-            results.push(rel);
-        }
-    }
-    return results.sort();
-}
-function loadTemplateConfig() {
-    const configPaths = [
-        path.join(process.cwd(), 'server/gadmin-cli.json'),
-        path.join(process.cwd(), 'gadmin-cli.json'),
-    ];
-    let templateName;
-    let userExcludes = [];
-    for (const configPath of configPaths) {
-        if (fs.existsSync(configPath)) {
-            const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-            templateName = config.template;
-            if (Array.isArray(config.templateExcludes)) {
-                userExcludes = config.templateExcludes;
-            }
-            break;
-        }
-    }
-    if (!templateName) {
-        throw new Error('Cannot find "template" field in gadmin-cli.json. ' +
-            'Make sure you are in a gadmin2 project root directory.');
-    }
-    return {
-        templateName,
-        excludes: [...DEFAULT_EXCLUDES, ...userExcludes],
-    };
+function formatMaterializeError(schematicsVersion, err) {
+    var _a;
+    const m = (_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : String(err);
+    return `\n❌ Failed to materialize base @ schematics ${schematicsVersion}: ${m}\n`;
 }
+/* ------------------------------------------------------------------ *
+ * Template config / path resolution
+ * ------------------------------------------------------------------ */
 function resolveTemplatePath(templateName) {
     let schematicsRoot;
     const searchPaths = [
@@ -208,101 +88,6 @@ function resolveTemplatePath(templateName) {
     }
     throw new Error(`Template directory not found for "${templateName}" in ${schematicsRoot}`);
 }
-/* ------------------------------------------------------------------ *
- * Diff / merge utilities
- * ------------------------------------------------------------------ */
-function createUnifiedDiff(filePath, instanceContent, templateContent) {
-    const instanceLines = instanceContent.split('\n');
-    const templateLines = templateContent.split('\n');
-    const lines = [];
-    lines.push(chalk.bold(`--- a/${filePath} (instance)`));
-    lines.push(chalk.bold(`+++ b/${filePath} (template)`));
-    const maxLen = Math.max(instanceLines.length, templateLines.length);
-    const hunks = [];
-    let currentHunk = null;
-    for (let i = 0; i < maxLen; i++) {
-        const a = i < instanceLines.length ? instanceLines[i] : undefined;
-        const b = i < templateLines.length ? templateLines[i] : undefined;
-        if (a !== b) {
-            if (!currentHunk) {
-                currentHunk = { start: i, instanceLines: [], templateLines: [] };
-            }
-            if (a !== undefined)
-                currentHunk.instanceLines.push(a);
-            if (b !== undefined)
-                currentHunk.templateLines.push(b);
-        }
-        else {
-            if (currentHunk) {
-                hunks.push(currentHunk);
-                currentHunk = null;
-            }
-        }
-    }
-    if (currentHunk)
-        hunks.push(currentHunk);
-    for (const hunk of hunks.slice(0, 10)) {
-        const contextStart = Math.max(0, hunk.start - 2);
-        lines.push(chalk.cyan(`@@ -${hunk.start + 1},${hunk.instanceLines.length} +${hunk.start + 1},${hunk.templateLines.length} @@`));
-        for (let i = contextStart; i < hunk.start; i++) {
-            if (i < instanceLines.length) {
-                lines.push(` ${instanceLines[i]}`);
-            }
-        }
-        for (const line of hunk.instanceLines) {
-            lines.push(chalk.red(`-${line}`));
-        }
-        for (const line of hunk.templateLines) {
-            lines.push(chalk.green(`+${line}`));
-        }
-        const afterStart = hunk.start + Math.max(hunk.instanceLines.length, hunk.templateLines.length);
-        for (let i = afterStart; i < Math.min(afterStart + 2, instanceLines.length); i++) {
-            lines.push(` ${instanceLines[i]}`);
-        }
-    }
-    if (hunks.length > 10) {
-        lines.push(chalk.yellow(`  ... and ${hunks.length - 10} more hunks`));
-    }
-    return lines.join('\n');
-}
-function createConflictContent(instanceContent, templateContent) {
-    return [
-        '<<<<<<< INSTANCE',
-        instanceContent,
-        '=======',
-        templateContent,
-        '>>>>>>> TEMPLATE',
-    ].join('\n');
-}
-function tryAutoMerge(instanceContent, templateContent) {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gadmin-merge-'));
-    const basePath = path.join(tmpDir, 'base');
-    const oursPath = path.join(tmpDir, 'ours');
-    const theirsPath = path.join(tmpDir, 'theirs');
-    try {
-        fs.writeFileSync(basePath, '', 'utf-8');
-        fs.writeFileSync(oursPath, instanceContent, 'utf-8');
-        fs.writeFileSync(theirsPath, templateContent, 'utf-8');
-        try {
-            (0, child_process_1.execSync)(`git merge-file -L "INSTANCE" -L "BASE" -L "TEMPLATE" "${oursPath}" "${basePath}" "${theirsPath}"`, { stdio: 'pipe' });
-            const merged = fs.readFileSync(oursPath, 'utf-8');
-            return { merged, hasConflicts: false };
-        }
-        catch (err) {
-            if (err.status > 0) {
-                const merged = fs.readFileSync(oursPath, 'utf-8');
-                return { merged, hasConflicts: true };
-            }
-            return {
-                merged: createConflictContent(instanceContent, templateContent),
-                hasConflicts: true,
-            };
-        }
-    }
-    finally {
-        fs.rmSync(tmpDir, { recursive: true, force: true });
-    }
-}
 /* ------------------------------------------------------------------ *
  * .claude context sync (from remote git repo)
  * ------------------------------------------------------------------ */
@@ -591,40 +376,288 @@ function maybeInstallChangedDeps(snapshots, dryRun) {
         }
     });
 }
+function assertGitAvailable() {
+    try {
+        (0, child_process_1.execSync)('git --version', { stdio: 'pipe' });
+    }
+    catch (_a) {
+        throw new Error('gadmin2 update requires git in PATH (used internally for 3-way merge). Install git and retry.');
+    }
+}
+function assertNotBothOursAndTheirs(opts) {
+    if (opts.ours && opts.theirs) {
+        throw new Error('--ours and --theirs are mutually exclusive');
+    }
+}
+function loadGadminCliJson(instanceDir) {
+    const candidates = [
+        path.join(instanceDir, 'server/gadmin-cli.json'),
+        path.join(instanceDir, 'gadmin-cli.json'),
+    ];
+    for (const p of candidates) {
+        if (fs.existsSync(p)) {
+            const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+            if (!raw.template) {
+                throw new Error('gadmin-cli.json missing "template" field');
+            }
+            return {
+                template: raw.template,
+                templateExcludes: raw.templateExcludes,
+                templateUpdate: raw.templateUpdate,
+                raw,
+            };
+        }
+    }
+    throw new Error('Cannot find "template" field in gadmin-cli.json. ' +
+        'Make sure you are in a gadmin2 project root directory.');
+}
+/**
+ * 整合：必须在 instance 根 / git 可用 / 配置无废弃字段 / 锁可获取 / 没有残留冲突 / flag 不矛盾。
+ */
+function runPreflight(opts) {
+    var _a, _b, _c;
+    const instanceDir = process.cwd();
+    const instanceMarker = path.join(instanceDir, 'server', 'gadmin-cli.json');
+    if (!fs.existsSync(instanceMarker)) {
+        throw new Error('Not at a gadmin2 instance project root.\n' +
+            `  Expected to find: server/gadmin-cli.json\n` +
+            `  Current directory: ${instanceDir}\n\n` +
+            'Run this command from the project root created by `gadmin2 n <name>`.');
+    }
+    assertGitAvailable();
+    assertNotBothOursAndTheirs(opts);
+    const cfg = loadGadminCliJson(instanceDir);
+    (0, config_validate_1.assertNoDeprecatedFields)(cfg.raw);
+    const userExcludes = [
+        ...((_a = cfg.templateExcludes) !== null && _a !== void 0 ? _a : []),
+        ...((_c = (_b = cfg.templateUpdate) === null || _b === void 0 ? void 0 : _b.excludes) !== null && _c !== void 0 ? _c : []),
+    ];
+    const releaseLock = (0, base_store_1.acquireLock)(instanceDir);
+    // Residual conflict scan (instance-side files only).
+    const allExcludes = [...excludes_1.HARDCODED_EXCLUDES, ...excludes_1.DEFAULT_EXCLUDES, ...userExcludes];
+    const instanceFiles = (0, excludes_1.collectFiles)(instanceDir, allExcludes);
+    const residual = (0, residual_scan_1.scanResidualMarkers)(instanceDir, instanceFiles);
+    if (residual.length > 0) {
+        releaseLock();
+        const lines = residual.map((r) => `     ${r.file}:${r.line}`).join('\n');
+        throw new Error(`Refusing to update: ${residual.length} marker(s) from a previous update remain.\n\n` +
+            `${lines}\n\n` +
+            `   Resolve all <<<<<<< / >>>>>>> markers, then re-run.\n` +
+            `   Hint:  git diff --check\n` +
+            `          gadmin2 update status`);
+    }
+    return { instanceDir, templateName: cfg.template, userExcludes, releaseLock };
+}
 /* ------------------------------------------------------------------ *
- * Smart merger registry
+ * Apply phase
  * ------------------------------------------------------------------ */
-const DEFAULT_MERGER_RULES = [
-    { pattern: 'package.json', mergerName: 'json' },
-    { pattern: '**/package.json', mergerName: 'json' },
-    { pattern: 'tsconfig*.json', mergerName: 'json' },
-    { pattern: '**/tsconfig*.json', mergerName: 'json' },
-    { pattern: '**/*.module.ts', mergerName: 'ts-module' },
-    { pattern: 'config/prisma/*.prisma', mergerName: 'prisma' },
-    { pattern: 'server/prisma/schema.prisma', mergerName: 'prisma' },
-    { pattern: '.env', mergerName: 'env' },
-    { pattern: '.env.*', mergerName: 'env' },
-    { pattern: '**/.env', mergerName: 'env' },
-    { pattern: '**/.env.*', mergerName: 'env' },
-];
-function buildMergerRegistry(userConfig) {
-    const reg = new template_merge_1.MergerRegistry();
-    reg.register(new template_merge_1.JsonMerger());
-    reg.register(new template_merge_1.EnvMerger());
-    reg.register(new template_merge_1.PrismaMerger());
-    reg.register(new template_merge_1.TsModuleMerger());
-    if ((userConfig === null || userConfig === void 0 ? void 0 : userConfig.mergers) && Object.keys(userConfig.mergers).length > 0) {
-        // 用户配置完全替换默认规则
-        for (const [pattern, mergerName] of Object.entries(userConfig.mergers)) {
-            reg.addRule({ pattern, mergerName });
+function readUtf8Safe(p) {
+    return fs.readFileSync(p, 'utf-8');
+}
+function ensureDir(file) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+}
+function handleBinary(rel, baseRoot, oursRoot, theirsRoot, opts, conflicts) {
+    const basePath = path.join(baseRoot, rel);
+    const oursPath = path.join(oursRoot, rel);
+    const theirsPath = path.join(theirsRoot, rel);
+    const baseBuf = fs.existsSync(basePath) ? fs.readFileSync(basePath) : null;
+    const oursBuf = fs.existsSync(oursPath) ? fs.readFileSync(oursPath) : null;
+    const theirsBuf = fs.existsSync(theirsPath) ? fs.readFileSync(theirsPath) : null;
+    if (oursBuf && theirsBuf && oursBuf.equals(theirsBuf))
+        return;
+    if (baseBuf && oursBuf && baseBuf.equals(oursBuf) && theirsBuf) {
+        ensureDir(oursPath);
+        fs.copyFileSync(theirsPath, oursPath);
+        return;
+    }
+    if (opts.theirs && theirsBuf) {
+        ensureDir(oursPath);
+        fs.copyFileSync(theirsPath, oursPath);
+        return;
+    }
+    if (opts.ours)
+        return; // keep OURS as-is
+    conflicts.push({
+        path: rel,
+        kind: 'binary',
+        detail: `binary differs three-ways. To accept template:  cp "${theirsPath}" "${oursPath}"`,
+    });
+    console.warn(chalk.yellow(`   ⚠️  binary conflict (cannot 3-way merge): ${rel}`));
+    console.warn(chalk.gray(`      template: ${theirsPath}`));
+    console.warn(chalk.gray(`      base:     ${basePath}`));
+}
+function applyPlan(plan, baseRoot, oursRoot, theirsRoot, opts) {
+    const conflicts = [];
+    for (const rel of plan.add) {
+        const dst = path.join(oursRoot, rel);
+        ensureDir(dst);
+        fs.copyFileSync(path.join(theirsRoot, rel), dst);
+    }
+    for (const rel of plan.delete) {
+        const dst = path.join(oursRoot, rel);
+        if (fs.existsSync(dst))
+            fs.rmSync(dst);
+    }
+    for (const rel of plan.update) {
+        const basePath = path.join(baseRoot, rel);
+        const oursPath = path.join(oursRoot, rel);
+        const theirsPath = path.join(theirsRoot, rel);
+        if ((0, binary_detect_1.isAnyBinary)(basePath, oursPath, theirsPath)) {
+            handleBinary(rel, baseRoot, oursRoot, theirsRoot, opts, conflicts);
+            continue;
+        }
+        const result = (0, merge3way_1.merge3Way)(readUtf8Safe(basePath), readUtf8Safe(oursPath), readUtf8Safe(theirsPath));
+        if (result.hasConflicts && opts.ours) {
+            // keep OURS as-is — no write
+            continue;
+        }
+        if (result.hasConflicts && opts.theirs) {
+            ensureDir(oursPath);
+            fs.copyFileSync(theirsPath, oursPath);
+            continue;
+        }
+        ensureDir(oursPath);
+        fs.writeFileSync(oursPath, result.merged, 'utf-8');
+        if (result.hasConflicts)
+            conflicts.push({ path: rel, kind: 'content' });
+    }
+    // add/add
+    for (const rel of plan.addAddConflict) {
+        const oursPath = path.join(oursRoot, rel);
+        const theirsPath = path.join(theirsRoot, rel);
+        if (opts.theirs) {
+            ensureDir(oursPath);
+            fs.copyFileSync(theirsPath, oursPath);
+        }
+        else if (!opts.ours) {
+            conflicts.push({
+                path: rel,
+                kind: 'add/add',
+                detail: 'both added different content; instance kept',
+            });
+        }
+    }
+    // modify/delete (template deleted, instance modified)
+    for (const rel of plan.modifyDeleteConflict) {
+        const oursPath = path.join(oursRoot, rel);
+        if (opts.theirs) {
+            if (fs.existsSync(oursPath))
+                fs.rmSync(oursPath);
+        }
+        else if (!opts.ours) {
+            conflicts.push({
+                path: rel,
+                kind: 'modify/delete',
+                detail: 'template deleted this file; instance modified — file kept',
+            });
+        }
+    }
+    // delete/modify (instance deleted, template modified)
+    for (const rel of plan.deleteModifyConflict) {
+        const oursPath = path.join(oursRoot, rel);
+        const theirsPath = path.join(theirsRoot, rel);
+        if (opts.theirs) {
+            ensureDir(oursPath);
+            fs.copyFileSync(theirsPath, oursPath);
+        }
+        else if (!opts.ours) {
+            conflicts.push({
+                path: rel,
+                kind: 'delete/modify',
+                detail: 'instance deleted this file; template modified — file NOT restored',
+            });
         }
     }
-    else {
-        for (const rule of DEFAULT_MERGER_RULES) {
-            reg.addRule(rule);
+    return conflicts;
+}
+/* ------------------------------------------------------------------ *
+ * Print summary
+ * ------------------------------------------------------------------ */
+function printPlanCounts(plan) {
+    console.info(`   ${plan.update.length} files cleanly merged or 3-way merged\n` +
+        `   ${plan.add.length} files added (template-only)\n` +
+        `   ${plan.delete.length} files deleted (template removed)`);
+    if (plan.keep.length > 0) {
+        console.info(chalk.gray(`   ${plan.keep.length} files kept (instance-only or identical)`));
+    }
+}
+function printSummary(plan, conflicts, templateName, schematicsVersion) {
+    console.info(chalk.bold('\n═══════════════════════════════════════════════════'));
+    console.info(chalk.bold('  Template Update Summary'));
+    console.info(chalk.bold('═══════════════════════════════════════════════════\n'));
+    printPlanCounts(plan);
+    console.info();
+    if (conflicts.length === 0) {
+        console.info(chalk.green('✅ Template update complete — no conflicts.'));
+        console.info(`   Base advanced to: ${templateName} @ schematics ${schematicsVersion}\n`);
+        return;
+    }
+    console.info(chalk.yellow(`⚠️  ${conflicts.length} conflict(s) need your attention:\n`));
+    const padKind = (k) => k.padEnd(16);
+    for (const c of conflicts) {
+        const kindLabel = `[${c.kind}]`;
+        console.info(`   ${chalk.yellow(padKind(kindLabel))} ${c.path}` +
+            (c.detail ? chalk.gray(`   (${c.detail})`) : ''));
+    }
+    console.info();
+    console.info(chalk.gray('   Recommended workflow:'));
+    console.info(chalk.gray('     $ git status                   # see all modified files'));
+    console.info(chalk.gray('     $ git diff --check             # locate residual <<<<<<< / >>>>>>> markers'));
+    console.info(chalk.gray('     $ <editor> <conflicting-file>'));
+    console.info(chalk.gray('     ...'));
+    console.info(chalk.gray('     $ gadmin2 update status        # verify conflicts resolved'));
+    console.info(chalk.gray('     $ git add . && git commit'));
+    console.info();
+    console.info(`   Base advanced to: ${templateName} @ schematics ${schematicsVersion}\n`);
+}
+/* ------------------------------------------------------------------ *
+ * Per-file 3-way diff display (used by `gadmin2 update diff <file>`)
+ * ------------------------------------------------------------------ */
+function printPerFileTriDiff(rel, baseRoot, oursRoot, theirsRoot, baseExists) {
+    const basePath = path.join(baseRoot, rel);
+    const oursPath = path.join(oursRoot, rel);
+    const theirsPath = path.join(theirsRoot, rel);
+    const has = (p) => fs.existsSync(p);
+    console.info(`File: ${chalk.bold(rel)}\n`);
+    if (baseExists && has(basePath) && has(theirsPath)) {
+        console.info(chalk.gray('  base    → theirs    (template increment since last update)'));
+        console.info(chalk.gray('  ──────────────────'));
+        console.info(unifiedDiffSimple(fs.readFileSync(basePath, 'utf-8'), fs.readFileSync(theirsPath, 'utf-8')));
+        console.info();
+    }
+    if (baseExists && has(basePath) && has(oursPath)) {
+        console.info(chalk.gray('  ours    → base      (instance changes since last update)'));
+        console.info(chalk.gray('  ──────────────────'));
+        console.info(unifiedDiffSimple(fs.readFileSync(basePath, 'utf-8'), fs.readFileSync(oursPath, 'utf-8')));
+        console.info();
+    }
+    else if (!baseExists) {
+        console.info(chalk.gray('  ours    vs theirs   (no base — falls back to 2-way)'));
+        console.info(chalk.gray('  ──────────────────'));
+        if (has(oursPath) && has(theirsPath)) {
+            console.info(unifiedDiffSimple(fs.readFileSync(oursPath, 'utf-8'), fs.readFileSync(theirsPath, 'utf-8')));
         }
+        console.info();
     }
-    return reg;
+}
+/** Minimal unified diff output suitable for terminal. */
+function unifiedDiffSimple(a, b) {
+    const A = a.split('\n');
+    const B = b.split('\n');
+    const out = [];
+    const max = Math.max(A.length, B.length);
+    for (let i = 0; i < max; i++) {
+        const x = i < A.length ? A[i] : undefined;
+        const y = i < B.length ? B[i] : undefined;
+        if (x === y)
+            continue;
+        if (x !== undefined)
+            out.push(chalk.red(`-${x}`));
+        if (y !== undefined)
+            out.push(chalk.green(`+${y}`));
+    }
+    return out.length === 0 ? chalk.gray('  (no textual diff)') : out.join('\n');
 }
 /* ------------------------------------------------------------------ *
  * Action
@@ -634,8 +667,8 @@ class UpdateAction extends abstract_action_1.AbstractAction {
         var _a, _b;
         return __awaiter(this, void 0, void 0, function* () {
             const subcommand = (_a = inputs.find((i) => i.name === 'subcommand')) === null || _a === void 0 ? void 0 : _a.value;
-            if (subcommand && subcommand !== 'update' && subcommand !== 'diff') {
-                console.error(chalk.red(`Unknown subcommand "${subcommand}". Expected: (none) | diff`));
+            if (subcommand && subcommand !== 'update' && subcommand !== 'diff' && subcommand !== 'status') {
+                console.error(chalk.red(`Unknown subcommand "${subcommand}". Expected: (none) | diff | status`));
                 process.exit(1);
             }
             // Guard: refuse to run anywhere except a gadmin2 instance project root.
@@ -643,7 +676,7 @@ class UpdateAction extends abstract_action_1.AbstractAction {
             // We check this up-front so commands like `gadmin2 update --no-template`
             // can't silently sync .claude into an unrelated directory.
             const instanceMarker = path.join(process.cwd(), 'server', 'gadmin-cli.json');
-            if (!fs.existsSync(instanceMarker)) {
+            if (subcommand !== 'status' && !fs.existsSync(instanceMarker)) {
                 console.error(chalk.red('\nNot at a gadmin2 instance project root.\n' +
                     `  Expected to find: server/gadmin-cli.json\n` +
                     `  Current directory: ${process.cwd()}\n\n` +
@@ -665,6 +698,10 @@ class UpdateAction extends abstract_action_1.AbstractAction {
                     // never let the version check break update
                 }
             }
+            if (subcommand === 'status') {
+                yield this.handleStatus();
+                return;
+            }
             if (subcommand === 'diff') {
                 yield this.handleDiff(options);
                 return;
@@ -673,88 +710,169 @@ class UpdateAction extends abstract_action_1.AbstractAction {
         });
     }
     handleDiff(options) {
-        var _a;
+        var _a, _b, _c, _d, _e;
         return __awaiter(this, void 0, void 0, function* () {
-            const noContent = (_a = options.find((o) => o.name === 'no-content')) === null || _a === void 0 ? void 0 : _a.value;
-            let templateDir;
-            let excludes;
-            try {
-                const config = loadTemplateConfig();
-                templateDir = resolveTemplatePath(config.templateName);
-                excludes = config.excludes;
-            }
-            catch (err) {
-                console.error(chalk.red(err.message));
-                process.exit(1);
-            }
+            const filterFile = (_a = options.find((o) => o.name === 'subcommand-arg')) === null || _a === void 0 ? void 0 : _a.value;
             const instanceDir = process.cwd();
-            console.info(`\n${chalk.gray('Template:')} ${templateDir}`);
-            console.info(`${chalk.gray('Instance:')} ${instanceDir}\n`);
-            const templateFiles = collectFiles(templateDir, excludes);
-            const instanceFiles = collectFiles(instanceDir, excludes);
-            const templateSet = new Set(templateFiles);
-            const instanceSet = new Set(instanceFiles);
-            const modified = [];
-            const onlyInTemplate = [];
-            const onlyInInstance = [];
-            for (const file of templateFiles) {
-                if (instanceSet.has(file)) {
-                    const tContent = fs.readFileSync(path.join(templateDir, file), 'utf-8');
-                    const iContent = fs.readFileSync(path.join(instanceDir, file), 'utf-8');
-                    if (tContent !== iContent) {
-                        modified.push(file);
-                    }
+            const cfg = loadGadminCliJson(instanceDir);
+            const userExcludes = [
+                ...((_b = cfg.templateExcludes) !== null && _b !== void 0 ? _b : []),
+                ...((_d = (_c = cfg.templateUpdate) === null || _c === void 0 ? void 0 : _c.excludes) !== null && _d !== void 0 ? _d : []),
+            ];
+            const theirsRoot = resolveTemplatePath(cfg.template);
+            const metaExists = fs.existsSync((0, base_store_1.metaPath)(instanceDir));
+            let baseHandle = null;
+            let baseRoot;
+            let meta = null;
+            if (metaExists) {
+                try {
+                    meta = (0, base_store_1.readMeta)(instanceDir);
+                    baseHandle = (0, materialize_1.materializeBase)(meta.schematicsVersion, cfg.template);
+                    baseRoot = baseHandle.dir;
                 }
-                else {
-                    onlyInTemplate.push(file);
+                catch (err) {
+                    console.error(chalk.red(formatMaterializeError((_e = meta === null || meta === void 0 ? void 0 : meta.schematicsVersion) !== null && _e !== void 0 ? _e : '?', err)));
+                    process.exit(1);
                 }
             }
-            for (const file of instanceFiles) {
-                if (!templateSet.has(file)) {
-                    onlyInInstance.push(file);
-                }
+            else {
+                // No bootstrap yet — fall back to "compare instance vs theirs" by pointing
+                // base at a non-existent path so classifyAll treats every file as new.
+                baseRoot = path.join(instanceDir, '.gadmin/__nonexistent__');
             }
-            console.info(chalk.bold('═══════════════════════════════════════════════════'));
-            console.info(chalk.bold('  Template Diff Summary'));
-            console.info(chalk.bold('═══════════════════════════════════════════════════\n'));
-            if (modified.length > 0) {
-                console.info(chalk.yellow(`📝 Modified (${modified.length} files)`));
-                for (const f of modified) {
-                    console.info(`   ${f}`);
-                }
+            try {
+                console.info(`\n${chalk.gray('Template:')} ${theirsRoot}`);
+                console.info(`${chalk.gray('Instance:')} ${instanceDir}`);
+                console.info(`${chalk.gray('Base:    ')} ${metaExists
+                    ? `(materialized from schematics ${meta.schematicsVersion})`
+                    : '(not yet established — run `gadmin2 update` once to bootstrap)'}`);
                 console.info();
-            }
-            if (onlyInTemplate.length > 0) {
-                console.info(chalk.green(`➕ Only in template (${onlyInTemplate.length} files)`));
-                for (const f of onlyInTemplate) {
-                    console.info(`   ${f}`);
+                const plan = (0, classify_1.classifyAll)(baseRoot, instanceDir, theirsRoot, userExcludes);
+                if (filterFile) {
+                    printPerFileTriDiff(filterFile, baseRoot, instanceDir, theirsRoot, metaExists);
+                    return;
                 }
-                console.info();
-            }
-            if (onlyInInstance.length > 0) {
-                console.info(chalk.cyan(`📄 Only in instance (${onlyInInstance.length} files)`));
-                for (const f of onlyInInstance) {
-                    console.info(`   ${f}`);
+                console.info(chalk.bold('═══════════════════════════════════════════════════'));
+                console.info(chalk.bold('  Template Diff Summary (3-way)'));
+                console.info(chalk.bold('═══════════════════════════════════════════════════\n'));
+                if (plan.add.length > 0) {
+                    console.info(chalk.green(`➕ To add (${plan.add.length} files)`));
+                    plan.add.forEach((f) => console.info(`   ${f}`));
+                    console.info();
+                }
+                if (plan.delete.length > 0) {
+                    console.info(chalk.red(`🗑  To delete (${plan.delete.length} files)`));
+                    plan.delete.forEach((f) => console.info(`   ${f}`));
+                    console.info();
+                }
+                if (plan.update.length > 0) {
+                    console.info(chalk.yellow(`📝 To update via 3-way merge (${plan.update.length} files)`));
+                    plan.update.forEach((f) => console.info(`   ${f}`));
+                    console.info();
+                }
+                const conflicts = [
+                    ...plan.addAddConflict.map((p) => ['add/add', p]),
+                    ...plan.modifyDeleteConflict.map((p) => ['modify/delete', p]),
+                    ...plan.deleteModifyConflict.map((p) => ['delete/modify', p]),
+                ];
+                if (conflicts.length > 0) {
+                    console.info(chalk.magenta(`⚠️  Structural conflicts (${conflicts.length} files)`));
+                    conflicts.forEach(([k, p]) => console.info(`   [${k}] ${p}`));
+                    console.info();
+                }
+                if (plan.add.length + plan.delete.length + plan.update.length + conflicts.length === 0) {
+                    console.info(chalk.green('✅ No differences found. Instance matches template.\n'));
                 }
-                console.info();
             }
-            if (modified.length === 0 &&
-                onlyInTemplate.length === 0 &&
-                onlyInInstance.length === 0) {
-                console.info(chalk.green('✅ No differences found. Instance matches template.\n'));
-                return;
+            finally {
+                if (baseHandle)
+                    baseHandle.cleanup();
             }
-            if (!noContent && modified.length > 0) {
-                console.info(chalk.bold('───────────────────────────────────────────────────'));
-                console.info(chalk.bold('  File Diffs (instance vs template)'));
-                console.info(chalk.bold('───────────────────────────────────────────────────\n'));
-                for (const file of modified) {
-                    const tContent = fs.readFileSync(path.join(templateDir, file), 'utf-8');
-                    const iContent = fs.readFileSync(path.join(instanceDir, file), 'utf-8');
-                    const diff = createUnifiedDiff(file, iContent, tContent);
-                    console.info(diff);
+        });
+    }
+    handleStatus() {
+        var _a, _b, _c, _d;
+        return __awaiter(this, void 0, void 0, function* () {
+            const instanceDir = process.cwd();
+            const instanceMarker = path.join(instanceDir, 'server', 'gadmin-cli.json');
+            if (!fs.existsSync(instanceMarker)) {
+                console.error(chalk.red('Not at a gadmin2 instance project root.\n'));
+                process.exit(2);
+            }
+            const cfg = loadGadminCliJson(instanceDir);
+            const userExcludes = [
+                ...((_a = cfg.templateExcludes) !== null && _a !== void 0 ? _a : []),
+                ...((_c = (_b = cfg.templateUpdate) === null || _b === void 0 ? void 0 : _b.excludes) !== null && _c !== void 0 ? _c : []),
+            ];
+            if (!fs.existsSync((0, base_store_1.metaPath)(instanceDir))) {
+                console.error(chalk.red('Base meta missing — run `gadmin2 update` to bootstrap.\n'));
+                process.exit(2);
+            }
+            let meta;
+            try {
+                meta = (0, base_store_1.readMeta)(instanceDir);
+            }
+            catch (err) {
+                console.error(chalk.red(err.message + '\n'));
+                process.exit(2);
+            }
+            console.info(`Template:        ${cfg.template} @ schematics ${meta.schematicsVersion}`);
+            const allExcludes = [...excludes_1.HARDCODED_EXCLUDES, ...excludes_1.DEFAULT_EXCLUDES, ...userExcludes];
+            const instanceFiles = (0, excludes_1.collectFiles)(instanceDir, allExcludes);
+            const residual = (0, residual_scan_1.scanResidualMarkers)(instanceDir, instanceFiles);
+            let theirsRoot;
+            try {
+                theirsRoot = resolveTemplatePath(cfg.template);
+            }
+            catch (err) {
+                console.error(chalk.red(err.message + '\n'));
+                process.exit(2);
+            }
+            let baseHandle = null;
+            try {
+                try {
+                    baseHandle = (0, materialize_1.materializeBase)(meta.schematicsVersion, cfg.template);
+                }
+                catch (err) {
+                    console.error(chalk.red(formatMaterializeError(meta.schematicsVersion, err)));
+                    process.exit(2);
+                }
+                const plan = (0, classify_1.classifyAll)(baseHandle.dir, instanceDir, theirsRoot, userExcludes);
+                const structural = [
+                    ...plan.addAddConflict.map((p) => ({ kind: 'add/add', path: p })),
+                    ...plan.modifyDeleteConflict.map((p) => ({ kind: 'modify/delete', path: p })),
+                    ...plan.deleteModifyConflict.map((p) => ({ kind: 'delete/modify', path: p })),
+                ];
+                const totalConflicts = residual.length + structural.length;
+                if (totalConflicts === 0) {
+                    console.info('Instance state:  ' + chalk.green('✅ clean (no unresolved conflicts)\n'));
+                    return;
+                }
+                console.info(`Instance state:  ${chalk.yellow(`${totalConflicts} unresolved conflict(s)`)}\n`);
+                if (residual.length > 0) {
+                    console.info('  Content conflicts (with markers in source):');
+                    const byFile = new Map();
+                    for (const r of residual)
+                        byFile.set(r.file, ((_d = byFile.get(r.file)) !== null && _d !== void 0 ? _d : 0) + 1);
+                    for (const [f, n] of byFile) {
+                        console.info(`    ${f.padEnd(48)}  (${n} marker${n === 1 ? '' : 's'})`);
+                    }
+                    console.info();
+                }
+                if (structural.length > 0) {
+                    console.info('  Structural conflicts:');
+                    for (const s of structural) {
+                        console.info(`    [${s.kind.padEnd(13)}] ${s.path}`);
+                    }
                     console.info();
                 }
+                console.info('  Resolve them, then run `gadmin2 update status` again to verify.');
+                process.exitCode = 1;
+                return;
+            }
+            finally {
+                if (baseHandle)
+                    baseHandle.cleanup();
             }
         });
     }
@@ -763,324 +881,140 @@ class UpdateAction extends abstract_action_1.AbstractAction {
         return __awaiter(this, void 0, void 0, function* () {
             const dryRun = (_a = options.find((o) => o.name === 'dry-run')) === null || _a === void 0 ? void 0 : _a.value;
             const autoYes = (_b = options.find((o) => o.name === 'yes')) === null || _b === void 0 ? void 0 : _b.value;
-            const smartMergeEnabled = (_d = (_c = options.find((o) => o.name === 'smart-merge')) === null || _c === void 0 ? void 0 : _c.value) !== null && _d !== void 0 ? _d : true;
+            const ours = (_c = options.find((o) => o.name === 'ours')) === null || _c === void 0 ? void 0 : _c.value;
+            const theirs = (_d = options.find((o) => o.name === 'theirs')) === null || _d === void 0 ? void 0 : _d.value;
             const templateEnabled = ((_e = options.find((o) => o.name === 'template')) === null || _e === void 0 ? void 0 : _e.value) !== false;
-            const claudeEnabled = ((_f = options.find((o) => o.name === 'coding-context')) === null || _f === void 0 ? void 0 : _f.value) !==
-                false;
+            const claudeEnabled = ((_f = options.find((o) => o.name === 'coding-context')) === null || _f === void 0 ? void 0 : _f.value) !== false;
             if (!templateEnabled && !claudeEnabled) {
                 console.error(chalk.red('\nNothing to do: both --no-template and --no-coding-context were specified.\n'));
                 process.exit(1);
             }
-            const instanceDir = process.cwd();
-            // Hoisted so stage 3 (auto-install) can see snapshots taken in stage 1.
-            // Remains null when --no-template, which is also the signal to skip stage 3.
+            const mergeOpts = { ours, theirs };
             let pkgSnapshots = null;
-            if (templateEnabled) {
-                let templateDir;
-                let excludes;
-                try {
-                    const config = loadTemplateConfig();
-                    templateDir = resolveTemplatePath(config.templateName);
-                    excludes = config.excludes;
-                }
-                catch (err) {
-                    console.error(chalk.red(err.message));
-                    process.exit(1);
-                }
-                console.info(`\n${chalk.gray('Template:')} ${templateDir}`);
-                console.info(`${chalk.gray('Instance:')} ${instanceDir}\n`);
-                // Build smart-merger registry (or null if disabled)
-                const userTemplateUpdate = smartMergeEnabled
-                    ? (0, template_merge_1.loadTemplateUpdateConfig)(instanceDir)
-                    : null;
-                const registry = smartMergeEnabled
-                    ? buildMergerRegistry(userTemplateUpdate)
-                    : null;
-                const userPolicies = userTemplateUpdate === null || userTemplateUpdate === void 0 ? void 0 : userTemplateUpdate.policies;
-                // Snapshot package.json files BEFORE any writes. We watch:
-                //   - <instanceDir>/package.json       (root, if present — workspace / husky / etc.)
-                //   - <instanceDir>/web/package.json
-                //   - <instanceDir>/server/package.json
-                pkgSnapshots = [
-                    snapshotPackageJson(instanceDir, '(root)'),
-                    snapshotPackageJson(path.join(instanceDir, 'web'), 'web'),
-                    snapshotPackageJson(path.join(instanceDir, 'server'), 'server'),
-                ];
-                const templateFiles = collectFiles(templateDir, excludes);
-                const instanceFiles = collectFiles(instanceDir, excludes);
-                const instanceSet = new Set(instanceFiles);
-                const toUpdate = [];
-                const toAdd = [];
-                for (const file of templateFiles) {
-                    if (instanceSet.has(file)) {
-                        const tContent = fs.readFileSync(path.join(templateDir, file), 'utf-8');
-                        const iContent = fs.readFileSync(path.join(instanceDir, file), 'utf-8');
-                        if (tContent !== iContent) {
-                            toUpdate.push(file);
-                        }
+            let preflight = null;
+            let baseHandle = null;
+            try {
+                if (templateEnabled) {
+                    try {
+                        preflight = runPreflight(mergeOpts);
                     }
-                    else {
-                        toAdd.push(file);
+                    catch (err) {
+                        console.error(chalk.red(`\n❌ ${err.message}\n`));
+                        process.exit(1);
                     }
-                }
-                if (toUpdate.length === 0 && toAdd.length === 0) {
-                    console.info(chalk.green('✅ Instance is up to date with template.\n'));
-                }
-                else {
-                    console.info(chalk.bold('═══════════════════════════════════════════════════'));
-                    console.info(chalk.bold('  Template Update Summary'));
-                    console.info(chalk.bold('═══════════════════════════════════════════════════\n'));
-                    if (toUpdate.length > 0) {
-                        console.info(chalk.yellow(`📝 To update (${toUpdate.length} files)`));
-                        for (const f of toUpdate) {
-                            console.info(`   ${f}`);
+                    const { instanceDir, templateName, userExcludes } = preflight;
+                    const theirsRoot = resolveTemplatePath(templateName);
+                    console.info(`\n${chalk.gray('Template:')} ${theirsRoot}`);
+                    console.info(`${chalk.gray('Instance:')} ${instanceDir}\n`);
+                    // Snapshot package.json before any writes (for stage 3 install)
+                    pkgSnapshots = [
+                        snapshotPackageJson(instanceDir, '(root)'),
+                        snapshotPackageJson(path.join(instanceDir, 'web'), 'web'),
+                        snapshotPackageJson(path.join(instanceDir, 'server'), 'server'),
+                    ];
+                    const schematicsPkg = require(require.resolve('@gadmin2n/schematics/package.json', { paths: [instanceDir, path.join(instanceDir, 'server')] }));
+                    const schematicsVersion = schematicsPkg.version || '0.0.0';
+                    // First-time bootstrap: meta absent → write meta + README, exit.
+                    if (!fs.existsSync((0, base_store_1.metaPath)(instanceDir))) {
+                        if (dryRun) {
+                            console.info(chalk.gray('(dry-run: would write .gadmin/.meta.json pinned to current schematics version, then exit)\n'));
                         }
-                        console.info();
-                    }
-                    if (toAdd.length > 0) {
-                        console.info(chalk.green(`➕ To add (${toAdd.length} files)`));
-                        for (const f of toAdd) {
-                            console.info(`   ${f}`);
+                        else {
+                            (0, base_store_1.writeMeta)(instanceDir, {
+                                schematicsVersion,
+                                schemaVersion: types_1.CURRENT_META_SCHEMA_VERSION,
+                            });
+                            (0, base_store_1.writeReadme)(instanceDir);
+                            console.info(chalk.green('✅ Baseline established at .gadmin/.meta.json'));
+                            console.info(chalk.gray(`   Pinned to schematics ${schematicsVersion}.`));
+                            console.info(chalk.gray('   The next `gadmin2 update` will perform a real 3-way merge.'));
                         }
-                        console.info();
+                        // Skip the rest of stage 1 — nothing to merge yet.
                     }
-                    console.info(chalk.gray('───────────────────────────────────────────────────'));
-                    console.info(chalk.gray(`  Total: ${toUpdate.length} update | ${toAdd.length} add`));
-                    console.info(chalk.gray('───────────────────────────────────────────────────\n'));
-                    if (!dryRun) {
-                        if (!autoYes) {
-                            const { confirm } = yield inquirer.prompt([
-                                {
-                                    type: 'confirm',
-                                    name: 'confirm',
-                                    message: 'Proceed with template update?',
-                                    default: false,
-                                },
-                            ]);
-                            if (!confirm) {
-                                console.info('Cancelled.\n');
-                                return;
-                            }
+                    else {
+                        // Validate meta consistency.
+                        let meta;
+                        try {
+                            meta = (0, base_store_1.validateMetaConsistency)(instanceDir);
+                        }
+                        catch (err) {
+                            console.error(chalk.red(`\n❌ ${err.message}\n`));
+                            process.exit(1);
+                            return; // unreachable; satisfies TS that meta is definitely assigned
                         }
-                        let skippedCount = 0;
-                        let overwrittenCount = 0;
-                        let mergedCount = 0;
-                        let conflictCount = 0;
-                        let smartCount = 0;
-                        let applyAll = null;
-                        for (let i = 0; i < toUpdate.length; i++) {
-                            const file = toUpdate[i];
-                            const tContent = fs.readFileSync(path.join(templateDir, file), 'utf-8');
-                            const iContent = fs.readFileSync(path.join(instanceDir, file), 'utf-8');
-                            // 1. Try smart merger if registered for this file
-                            const smartMerger = registry
-                                ? registry.resolve(file)
-                                : null;
-                            let smartResult = null;
-                            if (smartMerger) {
-                                try {
-                                    smartResult = yield smartMerger.merge({
-                                        filePath: file,
-                                        instancePath: path.join(instanceDir, file),
-                                        templatePath: path.join(templateDir, file),
-                                        instanceContent: iContent,
-                                        templateContent: tContent,
-                                        policies: userPolicies,
-                                    });
-                                }
-                                catch (err) {
-                                    smartResult = {
-                                        ok: false,
-                                        reason: (err === null || err === void 0 ? void 0 : err.message) || String(err),
-                                    };
-                                }
-                            }
-                            let strategy = applyAll;
-                            if (!strategy) {
-                                if (autoYes) {
-                                    // autoYes: prefer smart merge when available, else conflict markers
-                                    strategy =
-                                        smartResult && smartResult.ok ? 'smart' : 'conflict';
-                                }
-                                else {
-                                    const diff = createUnifiedDiff(file, iContent, tContent);
-                                    console.info(`\n${chalk.bold(`[${i + 1}/${toUpdate.length}]`)} ${chalk.yellow(file)}`);
-                                    console.info(diff);
-                                    console.info();
-                                    const choices = [];
-                                    if (smartResult && smartResult.ok) {
-                                        const summary = smartResult.notes.slice(0, 3).join('; ');
-                                        const more = smartResult.notes.length > 3 ? '...' : '';
-                                        choices.push({
-                                            name: `Smart merge — ${smartMerger.name} (recommended): ${summary}${more}`,
-                                            value: 'smart',
-                                            short: 'smart',
-                                        });
-                                    }
-                                    else if (smartMerger) {
-                                        const reason = smartResult && !smartResult.ok
-                                            ? smartResult.reason
-                                            : 'no result';
-                                        choices.push({
-                                            name: `Smart merge — ${smartMerger.name} (UNAVAILABLE: ${reason})`,
-                                            value: 'smart-unavailable',
-                                            short: 'smart-unavailable',
-                                            disabled: reason,
-                                        });
-                                    }
-                                    choices.push({
-                                        name: 'Skip — keep instance as-is',
-                                        value: 'skip',
-                                        short: 'skip',
-                                    }, {
-                                        name: 'Overwrite — use template version',
-                                        value: 'overwrite',
-                                        short: 'overwrite',
-                                    }, {
-                                        name: 'Auto merge — attempt git merge',
-                                        value: 'merge',
-                                        short: 'merge',
-                                    }, {
-                                        name: 'Conflict markers — write both versions for manual resolve',
-                                        value: 'conflict',
-                                        short: 'conflict',
-                                    }, new inquirer.Separator());
-                                    if (smartResult && smartResult.ok) {
-                                        choices.push({
-                                            name: 'Smart-merge ALL remaining (where supported)',
-                                            value: 'smart-all',
-                                            short: 'smart all',
-                                        });
-                                    }
-                                    choices.push({
-                                        name: 'Skip ALL remaining',
-                                        value: 'skip-all',
-                                        short: 'skip all',
-                                    }, {
-                                        name: 'Overwrite ALL remaining',
-                                        value: 'overwrite-all',
-                                        short: 'overwrite all',
-                                    }, {
-                                        name: 'Conflict markers ALL remaining',
-                                        value: 'conflict-all',
-                                        short: 'conflict all',
-                                    });
-                                    const { action } = yield inquirer.prompt([
-                                        {
-                                            type: 'list',
-                                            name: 'action',
-                                            message: `How to handle ${file}?`,
-                                            default: smartResult && smartResult.ok ? 'smart' : 'skip',
-                                            choices,
-                                        },
-                                    ]);
-                                    if (action.endsWith('-all')) {
-                                        applyAll = action.replace('-all', '');
-                                        strategy = applyAll;
-                                    }
-                                    else {
-                                        strategy = action;
-                                    }
-                                }
-                            }
-                            const destPath = path.join(instanceDir, file);
-                            switch (strategy) {
-                                case 'smart':
-                                    if (smartResult && smartResult.ok) {
-                                        fs.writeFileSync(destPath, smartResult.merged, 'utf-8');
-                                        smartCount++;
-                                        console.info(chalk.green(`   ✓  ${file} — smart merge (${smartMerger.name})`));
-                                        for (const note of smartResult.notes) {
-                                            console.info(chalk.gray(`      • ${note}`));
-                                        }
-                                    }
-                                    else {
-                                        // No smart merger usable: fallback to conflict markers
-                                        fs.writeFileSync(destPath, createConflictContent(iContent, tContent), 'utf-8');
-                                        conflictCount++;
-                                        console.info(chalk.yellow(`   ⚠️  ${file} — no smart merger available, wrote conflict markers`));
-                                    }
-                                    break;
-                                case 'skip':
-                                    skippedCount++;
-                                    break;
-                                case 'overwrite':
-                                    fs.writeFileSync(destPath, tContent, 'utf-8');
-                                    overwrittenCount++;
-                                    break;
-                                case 'merge': {
-                                    const result = tryAutoMerge(iContent, tContent);
-                                    fs.writeFileSync(destPath, result.merged, 'utf-8');
-                                    if (result.hasConflicts) {
-                                        conflictCount++;
-                                        console.info(chalk.yellow(`   ⚠️  ${file} — merge has conflicts`));
-                                    }
-                                    else {
-                                        mergedCount++;
-                                        console.info(chalk.green(`   ✓  ${file} — merged cleanly`));
-                                    }
-                                    break;
-                                }
-                                case 'conflict':
-                                default:
-                                    fs.writeFileSync(destPath, createConflictContent(iContent, tContent), 'utf-8');
-                                    conflictCount++;
-                                    break;
-                            }
+                        // Materialize base from npm version recorded in meta.
+                        try {
+                            baseHandle = (0, materialize_1.materializeBase)(meta.schematicsVersion, templateName);
                         }
-                        for (const file of toAdd) {
-                            const destPath = path.join(instanceDir, file);
-                            fs.mkdirSync(path.dirname(destPath), { recursive: true });
-                            fs.copyFileSync(path.join(templateDir, file), destPath);
+                        catch (err) {
+                            console.error(chalk.red(formatMaterializeError(meta.schematicsVersion, err)));
+                            process.exit(1);
                         }
-                        console.info(chalk.bold('\n✅ Template update complete!\n'));
-                        const stats = [];
-                        if (overwrittenCount > 0)
-                            stats.push(`${overwrittenCount} overwritten`);
-                        if (smartCount > 0)
-                            stats.push(`${smartCount} smart-merged`);
-                        if (mergedCount > 0)
-                            stats.push(`${mergedCount} merged`);
-                        if (conflictCount > 0)
-                            stats.push(`${conflictCount} with conflicts`);
-                        if (skippedCount > 0)
-                            stats.push(`${skippedCount} skipped`);
-                        if (toAdd.length > 0)
-                            stats.push(`${toAdd.length} added`);
-                        console.info(`   ${stats.join(' | ')}\n`);
-                        if (conflictCount > 0) {
-                            console.info(chalk.yellow(`⚠️  ${conflictCount} files have conflict markers. ` +
-                                `Search for "<<<<<<< INSTANCE" to resolve them.\n`));
+                        const baseRoot = baseHandle.dir;
+                        // Classify three sides.
+                        const plan = (0, classify_1.classifyAll)(baseRoot, instanceDir, theirsRoot, userExcludes);
+                        const totalChanges = plan.add.length + plan.delete.length + plan.update.length +
+                            plan.addAddConflict.length + plan.modifyDeleteConflict.length + plan.deleteModifyConflict.length;
+                        if (totalChanges === 0) {
+                            console.info(chalk.green('✅ Instance is up to date with template.\n'));
+                        }
+                        else if (dryRun) {
+                            console.info(chalk.bold('═══════════════════════════════════════════════════'));
+                            console.info(chalk.bold('  Template Update Plan (dry-run)'));
+                            console.info(chalk.bold('═══════════════════════════════════════════════════\n'));
+                            for (const f of plan.add)
+                                console.info(chalk.green(`   add     ${f}`));
+                            for (const f of plan.delete)
+                                console.info(chalk.red(`   delete  ${f}`));
+                            for (const f of plan.update)
+                                console.info(chalk.yellow(`   update  ${f}`));
+                            for (const f of plan.addAddConflict)
+                                console.info(chalk.magenta(`   add/add        ${f}`));
+                            for (const f of plan.modifyDeleteConflict)
+                                console.info(chalk.magenta(`   modify/delete  ${f}`));
+                            for (const f of plan.deleteModifyConflict)
+                                console.info(chalk.magenta(`   delete/modify  ${f}`));
+                            console.info();
+                        }
+                        else {
+                            const conflicts = applyPlan(plan, baseRoot, instanceDir, theirsRoot, mergeOpts);
+                            // Always advance meta to new version, even when conflicts present (invariant #2).
+                            (0, base_store_1.writeMeta)(instanceDir, {
+                                schematicsVersion,
+                                schemaVersion: types_1.CURRENT_META_SCHEMA_VERSION,
+                            });
+                            printSummary(plan, conflicts, templateName, schematicsVersion);
                         }
                     }
+                }
+                else {
+                    console.info(chalk.gray('\nSkipping template update (--no-template).\n'));
+                }
+                // Stage 2: .claude context sync — UNCHANGED.
+                if (claudeEnabled) {
+                    const cliRepo = ((_g = options.find((o) => o.name === 'coding-context-repo')) === null || _g === void 0 ? void 0 : _g.value) || '';
+                    const cliProtocol = ((_h = options.find((o) => o.name === 'coding-context-protocol')) === null || _h === void 0 ? void 0 : _h.value) || '';
+                    const claudeSource = yield resolveClaudeContextSource(cliRepo, cliProtocol, autoYes);
+                    if (claudeSource) {
+                        yield syncClaudeContext(process.cwd(), dryRun, claudeSource);
+                    }
                     else {
-                        console.info(chalk.gray('(dry-run mode, no template changes made)\n'));
+                        console.info(chalk.gray('\nSkipping .claude context sync (per user choice / --no-coding-context).\n'));
                     }
                 }
-            }
-            else {
-                console.info(chalk.gray('\nSkipping template update (--no-template).\n'));
-            }
-            // 2. Sync .claude context (regardless of whether template had changes)
-            if (claudeEnabled) {
-                const cliRepo = ((_g = options.find((o) => o.name === 'coding-context-repo')) === null || _g === void 0 ? void 0 : _g.value) ||
-                    '';
-                const cliProtocol = ((_h = options.find((o) => o.name === 'coding-context-protocol')) === null || _h === void 0 ? void 0 : _h.value) || '';
-                const claudeSource = yield resolveClaudeContextSource(cliRepo, cliProtocol, autoYes);
-                if (claudeSource) {
-                    yield syncClaudeContext(instanceDir, dryRun, claudeSource);
-                }
                 else {
-                    console.info(chalk.gray('\nSkipping .claude context sync (per user choice / --no-coding-context).\n'));
+                    console.info(chalk.gray('\nSkipping .claude context sync (--no-coding-context).\n'));
+                }
+                // Stage 3: Install changed deps — UNCHANGED.
+                if (pkgSnapshots) {
+                    yield maybeInstallChangedDeps(pkgSnapshots, dryRun);
                 }
             }
-            else {
-                console.info(chalk.gray('\nSkipping .claude context sync (--no-coding-context).\n'));
-            }
-            // 3. If web/server package.json changed during template update, install deps.
-            //    Skipped entirely under --no-template (no snapshots taken → nothing to compare).
-            if (pkgSnapshots) {
-                yield maybeInstallChangedDeps(pkgSnapshots, dryRun);
+            finally {
+                if (baseHandle)
+                    baseHandle.cleanup();
+                if (preflight)
+                    preflight.releaseLock();
             }
         });
     }