@gadmin2n/cli 0.0.111 → 0.0.113

package/actions/new.action.js

@@ -25,6 +25,10 @@ const schematics_1 = require("../lib/schematics");
 const ui_1 = require("../lib/ui");
 const formatting_1 = require("../lib/utils/formatting");
 const abstract_action_1 = require("./abstract.action");
+const schematics_root_1 = require("../lib/schematics-root");
+const base_store_1 = require("../lib/template-merge/base-store");
+const types_1 = require("../lib/template-merge/types");
+const executable_paths_1 = require("../lib/executable-paths");
 class NewAction extends abstract_action_1.AbstractAction {
     handle(inputs, options) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -42,6 +46,32 @@ class NewAction extends abstract_action_1.AbstractAction {
                 yield applyEnvConfig(projectDirectory, options).catch((err) => {
                     console.error(chalk.yellow(`[warn] Failed to apply env config: ${err && err.message ? err.message : err}`));
                 });
+                // Pin the 3-way merge base at project init time. Recording the exact
+                // schematics version that scaffolded this project means the FIRST
+                // `gadmin2 update` can immediately do a real 3-way merge — no
+                // bootstrap-then-rerun dance. Failure is non-fatal: if meta can't be
+                // written here, `gadmin2 update` still has its bootstrap fallback.
+                try {
+                    const projectAbsDir = (0, path_1.join)(process.cwd(), projectDirectory);
+                    const schematicsVersion = (0, schematics_root_1.getSchematicsVersion)();
+                    (0, base_store_1.writeMeta)(projectAbsDir, {
+                        schematicsVersion,
+                        schemaVersion: types_1.CURRENT_META_SCHEMA_VERSION,
+                    });
+                    (0, base_store_1.writeReadme)(projectAbsDir);
+                }
+                catch (err) {
+                    console.warn(chalk.yellow(`[warn] Failed to write .gadmin/.meta.json (first \`gadmin2 update\` will bootstrap instead): ${err && err.message ? err.message : err}`));
+                }
+                // @angular-devkit/schematics drops the source mode bits when writing
+                // generated files, so executable scripts (compose-ctl.sh, etc.) come
+                // out as 0644. Re-apply +x for known entry points.
+                try {
+                    (0, executable_paths_1.ensureExecutableBits)((0, path_1.join)(process.cwd(), projectDirectory));
+                }
+                catch (_a) {
+                    // best-effort, never fatal
+                }
             }
             if (!shouldSkipInstall) {
                 console.info('Begin to install server dependence ...');

package/actions/update.action.js

@@ -19,6 +19,7 @@ const child_process_1 = require("child_process");
 const abstract_action_1 = require("./abstract.action");
 const self_update_action_1 = require("./self-update.action");
 const version_check_1 = require("../lib/version-check");
+const executable_paths_1 = require("../lib/executable-paths");
 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");
@@ -46,58 +47,6 @@ function formatMaterializeError(schematicsVersion, err) {
     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
- * ------------------------------------------------------------------ */
-/**
- * Locate the @gadmin2n/schematics install root, searching:
- *   1. the instance project dir
- *   2. the instance project's server/ subdir (where deps usually live)
- *   3. the CLI's own node_modules (covers globally installed CLI where
- *      schematics ships alongside @gadmin2n/cli but is NOT installed in
- *      the user's project)
- * Throws a helpful error if none of these resolve.
- */
-function findSchematicsRoot(instanceDir = process.cwd()) {
-    const searchPaths = [
-        instanceDir,
-        path.join(instanceDir, 'server'),
-        path.resolve(__dirname, '..'),
-    ];
-    for (const searchPath of searchPaths) {
-        try {
-            const pkgPath = require.resolve('@gadmin2n/schematics/package.json', {
-                paths: [searchPath],
-            });
-            return path.dirname(pkgPath);
-        }
-        catch (_a) {
-            // continue
-        }
-    }
-    throw new Error('Cannot resolve @gadmin2n/schematics package. ' +
-        'Make sure it is installed globally (alongside @gadmin2n/cli) ' +
-        'or as a dependency of the project.');
-}
-function resolveTemplatePath(templateName) {
-    const schematicsRoot = findSchematicsRoot();
-    const nameVariants = [templateName];
-    if (templateName.startsWith('gadmin2n-')) {
-        nameVariants.push(templateName.replace('gadmin2n-', 'gadmin2-'));
-    }
-    else if (templateName.startsWith('gadmin2-')) {
-        nameVariants.push(templateName.replace('gadmin2-', 'gadmin2n-'));
-    }
-    for (const name of nameVariants) {
-        const distPath = path.join(schematicsRoot, 'dist/lib/application/files', name);
-        const srcPath = path.join(schematicsRoot, 'src/lib/application/files', name);
-        if (fs.existsSync(distPath))
-            return distPath;
-        if (fs.existsSync(srcPath))
-            return srcPath;
-    }
-    throw new Error(`Template directory not found for "${templateName}" in ${schematicsRoot}`);
-}
 /* ------------------------------------------------------------------ *
  * .claude context sync (from remote git repo)
  * ------------------------------------------------------------------ */
@@ -584,19 +533,79 @@ function applyPlan(plan, baseRoot, oursRoot, theirsRoot, opts) {
 /* ------------------------------------------------------------------ *
  * 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)`));
+/**
+ * Unified file-list printer for a `ClassifiedPlan`. Used by both pre-apply
+ * preview / dry-run output AND post-apply summary so the wording stays
+ * consistent across the three call sites.
+ *
+ * Sections that have zero files are skipped entirely (no "0 files added"
+ * noise). Structural conflicts (add/add, modify/delete, delete/modify) are
+ * shown together because they're all "needs decision" situations the user
+ * should see before applying.
+ *
+ * The "kept" footer (`plan.keep + plan.noop`) is shown by default; pass
+ * `{ showKept: false }` to suppress it.
+ */
+function printPlanFileLists(plan, opts) {
+    var _a;
+    const showKept = (_a = opts === null || opts === void 0 ? void 0 : opts.showKept) !== null && _a !== void 0 ? _a : true;
+    const plural = (n) => (n === 1 ? '' : 's');
+    if (plan.update.length > 0) {
+        console.info(chalk.yellow(`📝 Updated (3-way merged) — ${plan.update.length} file${plural(plan.update.length)}`));
+        for (const f of plan.update)
+            console.info(`   ${f}`);
+        console.info();
+    }
+    if (plan.add.length > 0) {
+        console.info(chalk.green(`➕ Added (template-only) — ${plan.add.length} file${plural(plan.add.length)}`));
+        for (const f of plan.add)
+            console.info(`   ${f}`);
+        console.info();
+    }
+    if (plan.delete.length > 0) {
+        console.info(chalk.red(`🗑  Deleted (template removed) — ${plan.delete.length} file${plural(plan.delete.length)}`));
+        for (const f of plan.delete)
+            console.info(`   ${f}`);
+        console.info();
+    }
+    const structural = [
+        ...plan.addAddConflict.map((p) => ['add/add', p]),
+        ...plan.modifyDeleteConflict.map((p) => ['modify/delete', p]),
+        ...plan.deleteModifyConflict.map((p) => ['delete/modify', p]),
+    ];
+    if (structural.length > 0) {
+        console.info(chalk.magenta(`⚠️  Structural conflicts — ${structural.length} file${plural(structural.length)}`));
+        const padKind = (k) => k.padEnd(16);
+        for (const [kind, p] of structural) {
+            console.info(`   ${chalk.magenta(padKind(`[${kind}]`))} ${p}`);
+        }
+        console.info();
+    }
+    if (showKept) {
+        const keptCount = plan.keep.length + plan.noop.length;
+        if (keptCount > 0) {
+            console.info(chalk.gray(`   ${keptCount} file${plural(keptCount)} kept (instance-only or identical)`));
+        }
+    }
+}
+/**
+ * Print post-apply conflict records (output of `applyPlan`). These differ
+ * from a `ClassifiedPlan` because they include `kind: 'content' | 'binary'`
+ * which is only known after the merge actually runs.
+ */
+function printConflictRecords(conflicts) {
+    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})`) : ''));
     }
 }
 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);
+    printPlanFileLists(plan);
     console.info();
     if (conflicts.length === 0) {
         console.info(chalk.green('✅ Template update complete — no conflicts.'));
@@ -604,12 +613,7 @@ function printSummary(plan, conflicts, templateName, schematicsVersion) {
         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})`) : ''));
-    }
+    printConflictRecords(conflicts);
     console.info();
     console.info(chalk.gray('   Recommended workflow:'));
     console.info(chalk.gray('     $ git status                   # see all modified files'));
@@ -762,7 +766,17 @@ class UpdateAction extends abstract_action_1.AbstractAction {
                 ...((_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);
+            let theirsHandle;
+            try {
+                theirsHandle = (0, materialize_1.materializeLatest)(cfg.template);
+            }
+            catch (err) {
+                console.error(chalk.red(`\n❌ ${err.message}\n`));
+                process.exit(1);
+                return; // unreachable; satisfies TS
+            }
+            const theirsRoot = theirsHandle.dir;
+            const theirsVersion = theirsHandle.version;
             const metaExists = fs.existsSync((0, base_store_1.metaPath)(instanceDir));
             let baseHandle = null;
             let baseRoot;
@@ -774,6 +788,7 @@ class UpdateAction extends abstract_action_1.AbstractAction {
                     baseRoot = baseHandle.dir;
                 }
                 catch (err) {
+                    theirsHandle.cleanup();
                     console.error(chalk.red(formatMaterializeError((_e = meta === null || meta === void 0 ? void 0 : meta.schematicsVersion) !== null && _e !== void 0 ? _e : '?', err)));
                     process.exit(1);
                 }
@@ -784,7 +799,7 @@ class UpdateAction extends abstract_action_1.AbstractAction {
                 baseRoot = path.join(instanceDir, '.gadmin/__nonexistent__');
             }
             try {
-                console.info(`\n${chalk.gray('Template:')} ${theirsRoot}`);
+                console.info(`\n${chalk.gray('Template:')} @gadmin2n/schematics@${theirsVersion} (latest)`);
                 console.info(`${chalk.gray('Instance:')} ${instanceDir}`);
                 console.info(`${chalk.gray('Base:    ')} ${metaExists
                     ? `(materialized from schematics ${meta.schematicsVersion})`
@@ -830,6 +845,7 @@ class UpdateAction extends abstract_action_1.AbstractAction {
             finally {
                 if (baseHandle)
                     baseHandle.cleanup();
+                theirsHandle.cleanup();
             }
         });
     }
@@ -863,13 +879,14 @@ class UpdateAction extends abstract_action_1.AbstractAction {
             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;
+            let theirsHandle;
             try {
-                theirsRoot = resolveTemplatePath(cfg.template);
+                theirsHandle = (0, materialize_1.materializeLatest)(cfg.template);
             }
             catch (err) {
                 console.error(chalk.red(err.message + '\n'));
                 process.exit(2);
+                return; // unreachable
             }
             let baseHandle = null;
             try {
@@ -880,7 +897,7 @@ class UpdateAction extends abstract_action_1.AbstractAction {
                     console.error(chalk.red(formatMaterializeError(meta.schematicsVersion, err)));
                     process.exit(2);
                 }
-                const plan = (0, classify_1.classifyAll)(baseHandle.dir, instanceDir, theirsRoot, userExcludes);
+                const plan = (0, classify_1.classifyAll)(baseHandle.dir, instanceDir, theirsHandle.dir, userExcludes);
                 const structural = [
                     ...plan.addAddConflict.map((p) => ({ kind: 'add/add', path: p })),
                     ...plan.modifyDeleteConflict.map((p) => ({ kind: 'modify/delete', path: p })),
@@ -916,6 +933,7 @@ class UpdateAction extends abstract_action_1.AbstractAction {
             finally {
                 if (baseHandle)
                     baseHandle.cleanup();
+                theirsHandle.cleanup();
             }
         });
     }
@@ -929,13 +947,15 @@ class UpdateAction extends abstract_action_1.AbstractAction {
             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;
             if (!templateEnabled && !claudeEnabled) {
-                console.error(chalk.red('\nNothing to do: both --no-template and --no-coding-context were specified.\n'));
+                // Should never happen under the opt-in selector — kept as a safety net.
+                console.error(chalk.red('\nNothing to do: neither stage was selected.\n'));
                 process.exit(1);
             }
             const mergeOpts = { ours, theirs };
             let pkgSnapshots = null;
             let preflight = null;
             let baseHandle = null;
+            let theirsHandle = null;
             try {
                 if (templateEnabled) {
                     try {
@@ -946,8 +966,20 @@ class UpdateAction extends abstract_action_1.AbstractAction {
                         process.exit(1);
                     }
                     const { instanceDir, templateName, userExcludes } = preflight;
-                    const theirsRoot = resolveTemplatePath(templateName);
-                    console.info(`\n${chalk.gray('Template:')} ${theirsRoot}`);
+                    // Pull the latest schematics tarball from npm to use as `theirs`.
+                    // Fail-hard: if the registry is unreachable, abort the update — we
+                    // don't want to silently fall back to a stale local copy.
+                    try {
+                        theirsHandle = (0, materialize_1.materializeLatest)(templateName);
+                    }
+                    catch (err) {
+                        console.error(chalk.red(`\n❌ ${err.message}\n`));
+                        process.exit(1);
+                        return; // unreachable
+                    }
+                    const theirsRoot = theirsHandle.dir;
+                    const schematicsVersion = theirsHandle.version;
+                    console.info(`\n${chalk.gray('Template:')} @gadmin2n/schematics@${schematicsVersion} (latest)`);
                     console.info(`${chalk.gray('Instance:')} ${instanceDir}\n`);
                     // Snapshot package.json before any writes (for stage 3 install)
                     pkgSnapshots = [
@@ -955,13 +987,10 @@ class UpdateAction extends abstract_action_1.AbstractAction {
                         snapshotPackageJson(path.join(instanceDir, 'web'), 'web'),
                         snapshotPackageJson(path.join(instanceDir, 'server'), 'server'),
                     ];
-                    const schematicsRoot = findSchematicsRoot(instanceDir);
-                    const schematicsPkg = require(path.join(schematicsRoot, 'package.json'));
-                    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(chalk.gray('(dry-run: would write .gadmin/.meta.json pinned to latest schematics version, then exit)\n'));
                         }
                         else {
                             (0, base_store_1.writeMeta)(instanceDir, {
@@ -970,7 +999,7 @@ class UpdateAction extends abstract_action_1.AbstractAction {
                             });
                             (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(`   Pinned to schematics ${schematicsVersion} (latest from npm).`));
                             console.info(chalk.gray('   The next `gadmin2 update` will perform a real 3-way merge.'));
                         }
                         // Skip the rest of stage 1 — nothing to merge yet.
@@ -1006,33 +1035,61 @@ class UpdateAction extends abstract_action_1.AbstractAction {
                             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}`));
+                            printPlanFileLists(plan);
                             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);
+                            // Pre-apply preview + confirm (skipped under --yes).
+                            const applyAndReport = () => {
+                                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,
+                                });
+                                // Re-apply +x to known script entry points: applyPlan uses
+                                // fs.copyFileSync for newly-added files, which does not preserve
+                                // the source template's mode bits.
+                                try {
+                                    (0, executable_paths_1.ensureExecutableBits)(instanceDir);
+                                }
+                                catch (_a) {
+                                    // best-effort, never fatal
+                                }
+                                printSummary(plan, conflicts, templateName, schematicsVersion);
+                            };
+                            if (autoYes) {
+                                applyAndReport();
+                            }
+                            else {
+                                console.info(chalk.bold('\n═══════════════════════════════════════════════════'));
+                                console.info(chalk.bold('  Template Update Preview'));
+                                console.info(chalk.bold('═══════════════════════════════════════════════════\n'));
+                                printPlanFileLists(plan);
+                                console.info();
+                                const { proceedTemplate } = yield inquirer.prompt([
+                                    {
+                                        type: 'confirm',
+                                        name: 'proceedTemplate',
+                                        message: 'Apply this template update to your instance?',
+                                        default: true,
+                                    },
+                                ]);
+                                if (proceedTemplate) {
+                                    applyAndReport();
+                                }
+                                else {
+                                    console.info(chalk.gray('\nTemplate update skipped — base & files unchanged.\n'));
+                                    // Fall through to stage 2 (.claude sync) and stage 3 (install).
+                                    // pkgSnapshots are already captured but package.json is unchanged,
+                                    // so maybeInstallChangedDeps will naturally find no diff and skip.
+                                }
+                            }
                         }
                     }
                 }
                 else {
-                    console.info(chalk.gray('\nSkipping template update (--no-template).\n'));
+                    console.info(chalk.gray('\nSkipping template update (not selected).\n'));
                 }
                 // Stage 2: .claude context sync — UNCHANGED.
                 if (claudeEnabled) {
@@ -1043,11 +1100,11 @@ class UpdateAction extends abstract_action_1.AbstractAction {
                         yield syncClaudeContext(process.cwd(), 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 (per user choice).\n'));
                     }
                 }
                 else {
-                    console.info(chalk.gray('\nSkipping .claude context sync (--no-coding-context).\n'));
+                    console.info(chalk.gray('\nSkipping .claude context sync (not selected).\n'));
                 }
                 // Stage 3: Install changed deps — UNCHANGED.
                 if (pkgSnapshots) {
@@ -1057,6 +1114,8 @@ class UpdateAction extends abstract_action_1.AbstractAction {
             finally {
                 if (baseHandle)
                     baseHandle.cleanup();
+                if (theirsHandle)
+                    theirsHandle.cleanup();
                 if (preflight)
                     preflight.releaseLock();
             }

package/commands/update.command.js

@@ -25,23 +25,32 @@ class UpdateCommand extends abstract_command_1.AbstractCommand {
             '  Conflict resolution:\n' +
             '    Conflicts are written into source files as <<<<<<< INSTANCE / >>>>>>> TEMPLATE markers.\n' +
             '    Resolve them in your editor, verify with `gadmin2 update status`, then commit.\n\n' +
-            '  Stage toggles:\n' +
-            '    --no-template          Skip template merge + auto-install.\n' +
-            '    --no-coding-context    Skip .claude context sync.\n')
+            '  Stage selection (opt-in selector — when omitted, both stages run):\n' +
+            '    --template             Run only the template merge + deps install stage.\n' +
+            '    --coding-context       Run only the .claude context sync stage.\n' +
+            '    (pass both / neither)  Run both stages.\n')
             .option('--no-content', '[diff] Only show file list, skip inline diff content.')
             .option('-d, --dry-run', '[update] Show what would be updated without making changes.')
-            .option('-y, --yes', '[update] Skip interactive prompts (currently used only for .claude protocol).')
+            .option('-y, --yes', '[update] Skip interactive prompts (template confirm, .claude protocol).')
             .option('--ours', '[update] Resolve all conflicts by keeping the instance side (mutually exclusive with --theirs).')
             .option('--theirs', '[update] Resolve all conflicts by taking the template side (mutually exclusive with --ours).')
             .option('--no-version-check', '[update | diff] Skip the npm registry version check at startup.')
             .option('--coding-context-repo <url>', '[update] Fully override the .claude context repo URL.')
             .option('--coding-context-protocol <proto>', '[update] One of: https | ssh | skip.')
-            .option('--no-coding-context', '[update] Skip the .claude context sync stage.')
-            .option('--no-template', '[update] Skip the template merge + auto-install stages.')
+            .option('--template', '[update] Run only the template merge + deps install stage.')
+            .option('--coding-context', '[update] Run only the .claude context sync stage.')
             .action((subcommand, arg, command) => __awaiter(this, void 0, void 0, function* () {
             const inputs = [];
             inputs.push({ name: 'subcommand', value: subcommand || '' });
             inputs.push({ name: 'subcommand-arg', value: arg || '' });
+            // Opt-in stage selector: when neither --template nor --coding-context
+            // is passed, run both stages (default). When at least one is passed,
+            // run only the stage(s) explicitly requested.
+            const tplFlag = !!command.template;
+            const ctxFlag = !!command.codingContext;
+            const anySelector = tplFlag || ctxFlag;
+            const templateEnabled = anySelector ? tplFlag : true;
+            const codingContextEnabled = anySelector ? ctxFlag : true;
             const options = [];
             options.push({ name: 'no-content', value: !command.content });
             options.push({ name: 'dry-run', value: !!command.dryRun });
@@ -51,8 +60,8 @@ class UpdateCommand extends abstract_command_1.AbstractCommand {
             options.push({ name: 'version-check', value: command.versionCheck !== false });
             options.push({ name: 'coding-context-repo', value: command.codingContextRepo || '' });
             options.push({ name: 'coding-context-protocol', value: command.codingContextProtocol || '' });
-            options.push({ name: 'coding-context', value: command.codingContext !== false });
-            options.push({ name: 'template', value: command.template !== false });
+            options.push({ name: 'coding-context', value: codingContextEnabled });
+            options.push({ name: 'template', value: templateEnabled });
             yield this.action.handle(inputs, options);
         }));
     }

package/lib/executable-paths.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Files (relative to instance / project root) that must carry the executable
+ * bit. Both `gadmin2 n` and `gadmin2 update` re-apply this set after writing
+ * files because:
+ *
+ *   - @angular-devkit/schematics writes generated files via fs.writeFile, which
+ *     does NOT preserve the source template's mode.
+ *   - update.action's applyPlan uses fs.copyFileSync for "added" files, which
+ *     also does not preserve mode.
+ *
+ * Without this step the user has to `chmod +x compose-ctl.sh` manually after
+ * every `gadmin2 n` / `gadmin2 update`.
+ *
+ * KEEP IN SYNC with the schematics templates: any new shell entry point added
+ * to schematics that the user is expected to invoke directly should be listed
+ * here too.
+ */
+export declare const EXECUTABLE_PATHS: ReadonlyArray<string>;
+/**
+ * Best-effort: add the executable bit to known script entry points under
+ * `projectDir`. Only files that actually exist are touched. Failures are
+ * silently swallowed — chmod is a no-op on Windows and in containers without
+ * permission, but neither is a reason to abort the broader command.
+ *
+ * Returns the list of paths that were updated, suitable for verbose logging.
+ */
+export declare function ensureExecutableBits(projectDir: string): string[];

package/lib/executable-paths.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureExecutableBits = exports.EXECUTABLE_PATHS = void 0;
+const fs = require("fs");
+const path = require("path");
+/**
+ * Files (relative to instance / project root) that must carry the executable
+ * bit. Both `gadmin2 n` and `gadmin2 update` re-apply this set after writing
+ * files because:
+ *
+ *   - @angular-devkit/schematics writes generated files via fs.writeFile, which
+ *     does NOT preserve the source template's mode.
+ *   - update.action's applyPlan uses fs.copyFileSync for "added" files, which
+ *     also does not preserve mode.
+ *
+ * Without this step the user has to `chmod +x compose-ctl.sh` manually after
+ * every `gadmin2 n` / `gadmin2 update`.
+ *
+ * KEEP IN SYNC with the schematics templates: any new shell entry point added
+ * to schematics that the user is expected to invoke directly should be listed
+ * here too.
+ */
+exports.EXECUTABLE_PATHS = [
+    'compose-ctl.sh',
+    'server/start-prod.sh',
+];
+/**
+ * Best-effort: add the executable bit to known script entry points under
+ * `projectDir`. Only files that actually exist are touched. Failures are
+ * silently swallowed — chmod is a no-op on Windows and in containers without
+ * permission, but neither is a reason to abort the broader command.
+ *
+ * Returns the list of paths that were updated, suitable for verbose logging.
+ */
+function ensureExecutableBits(projectDir) {
+    const updated = [];
+    for (const rel of exports.EXECUTABLE_PATHS) {
+        const abs = path.join(projectDir, rel);
+        if (!fs.existsSync(abs))
+            continue;
+        try {
+            const cur = fs.statSync(abs).mode;
+            const next = cur | 0o111; // owner+group+other +x
+            if (next !== cur) {
+                fs.chmodSync(abs, next);
+                updated.push(rel);
+            }
+        }
+        catch (_a) {
+            // ignore — Windows / restricted FS
+        }
+    }
+    return updated;
+}
+exports.ensureExecutableBits = ensureExecutableBits;

package/lib/schematics-root.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Locate the @gadmin2n/schematics install root, searching:
+ *   1. the supplied instance dir (defaults to process.cwd())
+ *   2. <instanceDir>/server (where deps are usually hoisted)
+ *   3. the CLI's own node_modules — covers globally installed CLI where
+ *      schematics ships alongside @gadmin2n/cli but is NOT installed in
+ *      the user's project.
+ *
+ * Throws a helpful error if none of these resolve.
+ *
+ * Used by:
+ *   - update.action  (resolveTemplatePath, schematics version pin)
+ *   - new.action     (meta bootstrap at project init)
+ */
+export declare function findSchematicsRoot(instanceDir?: string): string;
+/**
+ * Convenience wrapper: returns the version field of @gadmin2n/schematics's
+ * package.json. Falls back to '0.0.0' if the field is missing.
+ */
+export declare function getSchematicsVersion(instanceDir?: string): string;

package/lib/schematics-root.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSchematicsVersion = exports.findSchematicsRoot = void 0;
+const path = require("path");
+/**
+ * Locate the @gadmin2n/schematics install root, searching:
+ *   1. the supplied instance dir (defaults to process.cwd())
+ *   2. <instanceDir>/server (where deps are usually hoisted)
+ *   3. the CLI's own node_modules — covers globally installed CLI where
+ *      schematics ships alongside @gadmin2n/cli but is NOT installed in
+ *      the user's project.
+ *
+ * Throws a helpful error if none of these resolve.
+ *
+ * Used by:
+ *   - update.action  (resolveTemplatePath, schematics version pin)
+ *   - new.action     (meta bootstrap at project init)
+ */
+function findSchematicsRoot(instanceDir = process.cwd()) {
+    const searchPaths = [
+        instanceDir,
+        path.join(instanceDir, 'server'),
+        path.resolve(__dirname, '..'),
+    ];
+    for (const searchPath of searchPaths) {
+        try {
+            const pkgPath = require.resolve('@gadmin2n/schematics/package.json', {
+                paths: [searchPath],
+            });
+            return path.dirname(pkgPath);
+        }
+        catch (_a) {
+            // continue
+        }
+    }
+    throw new Error('Cannot resolve @gadmin2n/schematics package. ' +
+        'Make sure it is installed globally (alongside @gadmin2n/cli) ' +
+        'or as a dependency of the project.');
+}
+exports.findSchematicsRoot = findSchematicsRoot;
+/**
+ * Convenience wrapper: returns the version field of @gadmin2n/schematics's
+ * package.json. Falls back to '0.0.0' if the field is missing.
+ */
+function getSchematicsVersion(instanceDir) {
+    const root = findSchematicsRoot(instanceDir);
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const pkg = require(path.join(root, 'package.json'));
+    return (pkg && pkg.version) || '0.0.0';
+}
+exports.getSchematicsVersion = getSchematicsVersion;

package/lib/template-merge/materialize.d.ts

@@ -4,6 +4,10 @@ export interface MaterializedBase {
     /** Idempotent cleanup of any temp dirs created. */
     cleanup: () => void;
 }
+export interface MaterializedLatest extends MaterializedBase {
+    /** Resolved version string (whatever the registry / env override returned). */
+    version: string;
+}
 /**
  * Materialize a base reference for 3-way merge.
  *
@@ -16,3 +20,26 @@ export interface MaterializedBase {
  * Returned `cleanup()` removes any tmp dir we created.
  */
 export declare function materializeBase(schematicsVersion: string, templateName: string): MaterializedBase;
+/**
+ * Resolve the latest published version of `@gadmin2n/schematics`.
+ *
+ * Sources, in priority order:
+ *   1. `GADMIN2_LATEST_VERSION` env var — used by tests and `--use-version=X`
+ *      style overrides.
+ *   2. `npm view @gadmin2n/schematics version --json` — production. Hard
+ *      timeout via npm's own behaviour; we do not catch ENOENT here because a
+ *      missing `npm` is a fatal config error.
+ *
+ * Throws on any failure (fail-hard per design decision: theirs must always be
+ * truly latest, callers should not silently fall back to a stale local copy).
+ */
+export declare function resolveLatestVersion(): string;
+/**
+ * Materialize the LATEST published template as the `theirs` side of a
+ * 3-way merge. Equivalent to `materializeBase(resolveLatestVersion(), ...)`
+ * with the resolved version returned alongside the handle.
+ *
+ * Per design (fail-hard on network failure): if either step throws, the
+ * caller is expected to surface the error and abort the update.
+ */
+export declare function materializeLatest(templateName: string): MaterializedLatest;

package/lib/template-merge/materialize.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.materializeBase = void 0;
+exports.materializeLatest = exports.resolveLatestVersion = exports.materializeBase = void 0;
 // cli/lib/template-merge/materialize.ts
 const fs = require("fs");
 const os = require("os");
@@ -127,3 +127,60 @@ function copyTreeRecursive(src, dst) {
         // symlinks / sockets: skip
     }
 }
+/**
+ * Resolve the latest published version of `@gadmin2n/schematics`.
+ *
+ * Sources, in priority order:
+ *   1. `GADMIN2_LATEST_VERSION` env var — used by tests and `--use-version=X`
+ *      style overrides.
+ *   2. `npm view @gadmin2n/schematics version --json` — production. Hard
+ *      timeout via npm's own behaviour; we do not catch ENOENT here because a
+ *      missing `npm` is a fatal config error.
+ *
+ * Throws on any failure (fail-hard per design decision: theirs must always be
+ * truly latest, callers should not silently fall back to a stale local copy).
+ */
+function resolveLatestVersion() {
+    var _a, _b, _c, _d;
+    const envOverride = process.env.GADMIN2_LATEST_VERSION;
+    if (envOverride)
+        return envOverride.trim();
+    try {
+        const out = (0, child_process_1.execFileSync)('npm', ['view', SCHEMATICS_PKG, 'version', '--json'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+        const trimmed = out.trim();
+        // `--json` wraps the value in quotes for plain strings.
+        const parsed = trimmed.startsWith('"') ? JSON.parse(trimmed) : trimmed;
+        if (typeof parsed !== 'string' || parsed.length === 0) {
+            throw new Error(`unexpected npm view output: ${out}`);
+        }
+        return parsed;
+    }
+    catch (err) {
+        if (err && err.code === 'ENOENT') {
+            throw new Error('npm not in PATH — required to resolve the latest @gadmin2n/schematics version. ' +
+                'Install Node.js / npm and retry.');
+        }
+        const stderr = (_c = (_b = (_a = err === null || err === void 0 ? void 0 : err.stderr) === null || _a === void 0 ? void 0 : _a.toString) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : '';
+        const message = (_d = err === null || err === void 0 ? void 0 : err.message) !== null && _d !== void 0 ? _d : String(err);
+        throw new Error(`Failed to resolve latest @gadmin2n/schematics version from npm registry.\n` +
+            `   ${message.split('\n').join('\n   ')}` +
+            (stderr ? `\n   ${stderr.trim().split('\n').join('\n   ')}` : '') +
+            `\n   Check your network / npm registry config and retry, ` +
+            `or set GADMIN2_LATEST_VERSION=<version> to pin a specific version.`);
+    }
+}
+exports.resolveLatestVersion = resolveLatestVersion;
+/**
+ * Materialize the LATEST published template as the `theirs` side of a
+ * 3-way merge. Equivalent to `materializeBase(resolveLatestVersion(), ...)`
+ * with the resolved version returned alongside the handle.
+ *
+ * Per design (fail-hard on network failure): if either step throws, the
+ * caller is expected to surface the error and abort the update.
+ */
+function materializeLatest(templateName) {
+    const version = resolveLatestVersion();
+    const handle = materializeBase(version, templateName);
+    return Object.assign(Object.assign({}, handle), { version });
+}
+exports.materializeLatest = materializeLatest;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gadmin2n/cli",
-  "version": "0.0.111",
+  "version": "0.0.113",
   "description": "Gadmin - modern, fast, powerful node.js web framework (@cli)",
   "publishConfig": {
     "access": "public"