@nutin/cli 2.1.0 → 3.0.0

package/lib/src/update-app/conflict-report-writer.mjs

@@ -1,31 +1,43 @@
 import path from 'path';
 import * as fsExtra from 'fs-extra';
-import * as Diff from 'diff';
+import { CONFLICT_MARKER } from './three-way-merge.mjs';
 
 const fs = fsExtra.default;
-const REPORT_FILE_NAME = 'NUTIN-UPDATE-REPORT.md';
+export const REPORT_FILE_NAME = 'NUTIN-UPDATE-REPORT.md';
 
-export async function writeConflictReport(projectPath, conflicts, oldVersion, newVersion) {
-  const sections = conflicts.map(({ relPath, actualContent, newEntry }) => {
-    if (newEntry.isBinary || Buffer.isBuffer(actualContent)) {
-      return `## ${relPath}\n\nBinary file — differs from both your recorded baseline and the new nutin version. Compare manually.\n`;
-    }
+const list = (items, describe = ({ relPath }) => `\`${relPath}\``) => items.map((item) => `- ${describe(item)}`).join('\n');
 
-    const patch = Diff.createTwoFilesPatch(
-      relPath,
-      relPath,
-      actualContent,
-      newEntry.content,
-      'yours',
-      `nutin v${newVersion}`,
+// Lists the files you edited that this update touched. No diffs: merged files hold both versions'
+// changes, and overlaps are marked in the files themselves.
+export async function writeUpdateReport(projectPath, { merged, conflicted, binaryConflicts }, oldVersion, newVersion) {
+  const sections = [
+    `# nutin-update report\n\nUpdate from nutin v${oldVersion} to v${newVersion}. These files had changes of yours and changes in the new nutin version.`,
+  ];
+
+  if (conflicted.length > 0) {
+    sections.push(
+      '## Conflicts to resolve\n\n' +
+      'Your edits and nutin\'s overlap in these files. **The project won\'t build until they\'re resolved.** ' +
+      `Each conflict is marked in the file: \`${CONFLICT_MARKER}\` starts your version, \`||||||| nutin v${oldVersion}\` ` +
+      `the original one, \`=======\` the new one, ending at \`>>>>>>> nutin v${newVersion}\`. ` +
+      'Keep what you need, delete the markers, then run nutin-update again to confirm.\n\n' +
+      list(conflicted, ({ relPath, conflictCount }) => `\`${relPath}\` (${conflictCount} conflict${conflictCount > 1 ? 's' : ''})`),
+    );
+  }
+
+  if (merged.length > 0) {
+    sections.push(
+      '## Merged automatically\n\nYour edits and the new version\'s changes didn\'t overlap, so both were kept. Review them.\n\n' +
+      list(merged),
     );
-    return `## ${relPath}\n\n\`\`\`diff\n${patch}\`\`\`\n`;
-  });
+  }
 
-  const header = '# nutin-update report\n\n' +
-    `These files changed between nutin v${oldVersion} and v${newVersion}, but you've customized them ` +
-    'since generation, so they were left untouched. Review each diff below (yours vs. the new nutin ' +
-    'version) and merge by hand.\n\n';
+  if (binaryConflicts.length > 0) {
+    sections.push(
+      '## Binary files left as they are\n\nThese can\'t be merged: your version was kept. Compare it with the new one manually.\n\n' +
+      list(binaryConflicts),
+    );
+  }
 
-  await fs.writeFile(path.join(projectPath, REPORT_FILE_NAME), header + sections.join('\n'));
+  await fs.writeFile(path.join(projectPath, REPORT_FILE_NAME), sections.join('\n\n') + '\n');
 }

package/lib/src/update-app/json-drift.mjs

@@ -0,0 +1,54 @@
+import path from 'path';
+import * as fsExtra from 'fs-extra';
+import { JsonManager } from '../create-app/json-manager.mjs';
+
+const fs = fsExtra.default;
+
+// package.json and tsconfig.json aren't rendered from templates (JsonManager writes them
+// once, at creation), so the template diff never sees them. They're compared with what
+// this CLI would generate instead, and only reported.
+// Only the entries nutin generates are compared; anything the user added is ignored.
+const PACKAGE_JSON_SECTIONS = ['scripts', 'devDependencies'];
+
+function same(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function compareEntries(file, section, yours = {}, generated = {}) {
+  return Object.entries(generated)
+    .filter(([key, value]) => !same(yours[key], value))
+    .map(([key, value]) => ({ file, key: section ? `${section}.${key}` : key, yours: yours[key], nutin: value }));
+}
+
+async function readJsonIfExists(filePath) {
+  if (!(await fs.pathExists(filePath))) return null;
+  try {
+    return await fs.readJSON(filePath);
+  } catch {
+    return null;
+  }
+}
+
+export async function findJsonDrift(projectPath, context) {
+  const jsonManager = new JsonManager();
+  const drift = [];
+
+  const packageJson = await readJsonIfExists(path.join(projectPath, 'package.json'));
+  if (packageJson) {
+    const generated = jsonManager.buildPackageJson(context);
+    for (const section of PACKAGE_JSON_SECTIONS) {
+      drift.push(...compareEntries('package.json', section, packageJson[section], generated[section]));
+    }
+  }
+
+  if (context.lang !== 'js') {
+    const tsconfig = await readJsonIfExists(path.join(projectPath, 'tsconfig.json'));
+    if (tsconfig) {
+      const generated = jsonManager.buildTsconfigJson();
+      drift.push(...compareEntries('tsconfig.json', 'compilerOptions', tsconfig.compilerOptions, generated.compilerOptions));
+      drift.push(...compareEntries('tsconfig.json', null, { include: tsconfig.include, exclude: tsconfig.exclude }, { include: generated.include, exclude: generated.exclude }));
+    }
+  }
+
+  return drift;
+}

package/lib/src/update-app/project-updater.mjs

@@ -8,12 +8,16 @@ import { fetchOldTemplates } from './fetch-old-templates.mjs';
 import { parseVersion, compareVersions } from './version-compare.mjs';
 import { bootstrapProjectMeta } from '../common/meta-bootstrap-prompt.mjs';
 import { printUpdateSummary } from './update-summary-printer.mjs';
-import { writeConflictReport } from './conflict-report-writer.mjs';
+import { writeUpdateReport, REPORT_FILE_NAME } from './conflict-report-writer.mjs';
+import { mergeFile, hasConflictMarkers, CONFLICT_MARKER } from './three-way-merge.mjs';
+import { isGitAvailable, getWorkingTreeStatus } from '../common/git.mjs';
 import { UpdateContextBuilder } from './update-context-builder.mjs';
 import { TemplateDiffer } from './template-differ.mjs';
+import { findJsonDrift } from './json-drift.mjs';
 
 const fs = fsExtra.default;
-const REPORT_FILE_NAME = 'NUTIN-UPDATE-REPORT.md';
+
+const UNDO_COMMAND = 'git checkout -- . && git clean -fd';
 
 export class ProjectUpdater {
   constructor() {
@@ -22,8 +26,12 @@ export class ProjectUpdater {
   }
 
   async updateProject(projectPath, options = {}) {
-    const { yes = false, from } = options;
+    const { yes = false, from, allowDirty = false } = options;
+    // Read before anything here writes .nutin-meta.json (bootstrap, resolved conflicts), so only your
+    // own changes count. Enforced right before the first file write.
+    const gitStatus = allowDirty ? null : await getWorkingTreeStatus(projectPath);
     const meta = await this.resolveMeta(projectPath);
+    await this.assertNoConflictMarkers(projectPath, meta);
 
     if (this.isUpToDate(meta)) {
       print.boldSuccess(`✅ Already up to date (nutin v${packageVersion}).`);
@@ -37,7 +45,7 @@ export class ProjectUpdater {
 
     try {
       const changeSet = await this.computeChangeSet(projectPath, meta, oldTemplatesRoot);
-      await this.applyChangeSet(projectPath, meta, changeSet, { yes });
+      await this.applyChangeSet(projectPath, meta, changeSet, { yes, gitStatus });
     } finally {
       await cleanup();
     }
@@ -62,6 +70,28 @@ export class ProjectUpdater {
     }
   }
 
+  // Files the last update left with conflict markers (meta.unmergedFiles): nothing is updated until
+  // they're resolved, so a merge never runs on top of markers and a re-run still reports them.
+  async assertNoConflictMarkers(projectPath, meta) {
+    const unmerged = meta.unmergedFiles ?? [];
+    if (unmerged.length === 0) return;
+
+    const stillMarked = [];
+    for (const relPath of unmerged) {
+      if (await hasConflictMarkers(path.join(projectPath, relPath))) stillMarked.push(relPath);
+    }
+    if (stillMarked.length > 0) {
+      throw new Error(
+        `${stillMarked.length} file(s) still have conflict markers from the last update — the project won't build until ` +
+        `they're resolved. Search for "${CONFLICT_MARKER}", merge, then run nutin-update again:\n` +
+        stillMarked.map((relPath) => `  - ${relPath}`).join('\n'),
+      );
+    }
+
+    await updateProjectMeta(projectPath, { unmergedFiles: [] });
+    print.info('Conflict markers from the last update are resolved.');
+  }
+
   isUpToDate(meta) {
     return compareVersions(meta.version, packageVersion) === 0;
   }
@@ -84,12 +114,13 @@ export class ProjectUpdater {
 
   async computeChangeSet(projectPath, meta, oldTemplatesRoot) {
     const { oldContext, newContext } = await this.contextBuilder.buildContexts(projectPath, meta);
-    return this.differ.diff(projectPath, oldTemplatesRoot, oldContext, newContext);
+    const changeSet = await this.differ.diff(projectPath, oldTemplatesRoot, oldContext, newContext);
+    return { ...changeSet, jsonDrift: await findJsonDrift(projectPath, newContext) };
   }
 
-  async applyChangeSet(projectPath, meta, changeSet, { yes }) {
-    const { toUpdate, toAdd, conflicts, unknown, removedByUser, noLongerGenerated } = changeSet;
-    printUpdateSummary({ toUpdate, toAdd, conflicts, unknown, removedByUser, noLongerGenerated });
+  async applyChangeSet(projectPath, meta, changeSet, { yes, gitStatus = null }) {
+    const { toUpdate, toAdd, conflicts, unknown, removedByUser, noLongerGenerated, jsonDrift } = changeSet;
+    printUpdateSummary({ toUpdate, toAdd, conflicts, unknown, removedByUser, noLongerGenerated, jsonDrift });
 
     if (toUpdate.length === 0 && toAdd.length === 0 && conflicts.length === 0) {
       print.boldSuccess('\n✅ Nothing to update.');
@@ -97,18 +128,32 @@ export class ProjectUpdater {
       return;
     }
 
-    if (!yes && (toUpdate.length > 0 || toAdd.length > 0)) {
+    // Binary files can't be merged: they're kept as they are and listed in the report.
+    const toMerge = conflicts.filter(({ newEntry, actualContent }) => !newEntry.isBinary && !Buffer.isBuffer(actualContent));
+    const binaryConflicts = conflicts.filter((conflict) => !toMerge.includes(conflict));
+
+    if (gitStatus) this.assertPristine(gitStatus);
+
+    if (toMerge.length > 0 && !(await isGitAvailable())) {
+      throw new Error(
+        `nutin-update needs git to merge the ${toMerge.length} file(s) you edited, but git was not found. ` +
+        'Install git and run nutin-update again. No files were changed.',
+      );
+    }
+
+    if (!yes && (toUpdate.length > 0 || toAdd.length > 0 || toMerge.length > 0)) {
       if (!process.stdin.isTTY) {
         print.warn('\n⚠️ Non-interactive shell detected — skipping the confirmation prompt.');
         print.boldInfo('Re-run with --yes to apply these updates automatically. No files were changed.');
         return;
       }
 
+      const merges = toMerge.length > 0 ? ` and merge ${toMerge.length} file(s) you edited` : '';
       const { proceed } = await inquirer.prompt([
         {
           type: 'confirm',
           name: 'proceed',
-          message: `\nApply ${toUpdate.length + toAdd.length} safe file update(s)?`,
+          message: `\nApply ${toUpdate.length + toAdd.length} file update(s)${merges}?`,
           default: true,
         },
       ]);
@@ -124,15 +169,79 @@ export class ProjectUpdater {
       await fs.writeFile(outputPath, newEntry.content);
     }
 
-    if (conflicts.length > 0) {
-      await writeConflictReport(projectPath, conflicts, meta.version, packageVersion);
-      print.boldError(`\n⚠️  ${conflicts.length} file(s) you modified need manual attention — see ${REPORT_FILE_NAME}`);
+    const { merged, conflicted } = await this.mergeEditedFiles(projectPath, meta, toMerge);
+
+    if (merged.length > 0 || conflicted.length > 0 || binaryConflicts.length > 0) {
+      await writeUpdateReport(projectPath, { merged, conflicted, binaryConflicts }, meta.version, packageVersion);
     }
 
-    await updateProjectMeta(projectPath, { version: packageVersion });
+    await updateProjectMeta(projectPath, {
+      version: packageVersion,
+      unmergedFiles: conflicted.map(({ relPath }) => relPath),
+    });
+
+    if (merged.length > 0) {
+      print.info(`\n${merged.length} file(s) you edited were merged with the new version — review them (listed in ${REPORT_FILE_NAME}).`);
+    }
+    if (binaryConflicts.length > 0) {
+      print.boldError(`\n⚠️  ${binaryConflicts.length} binary file(s) you modified were left as they are — see ${REPORT_FILE_NAME}`);
+    }
+    if (conflicted.length > 0) {
+      print.boldError(
+        `\n⚠️  ${conflicted.length} file(s) have conflict markers — the project won't build until they're resolved ` +
+        `(search for "${CONFLICT_MARKER}"):`,
+      );
+      conflicted.forEach(({ relPath }) => print.boldError(`    - ${relPath}`));
+    }
+    if (gitStatus) {
+      print.info(`\nTo undo this update, run from the project folder: ${UNDO_COMMAND}`);
+      print.info(`Important: this will also remove any untracked folder.`);
+    }
 
     print.boldSuccess(`\n✅ Updated to nutin v${packageVersion}.`);
   }
+
+  // The update must be undoable with git: no uncommitted changes and no untracked files in the
+  // project folder, so checkout + clean only reverts what the update wrote. --allow-dirty skips this.
+  assertPristine({ repo, gitFound, changes }) {
+    if (!gitFound) {
+      throw new Error('git was not found: nutin-update uses it to make the update undoable. Install git, or pass --allow-dirty. No files were changed.');
+    }
+    if (!repo) {
+      throw new Error(
+        'This project isn\'t in a git repository, so the update couldn\'t be undone. Run "git init" and commit, ' +
+        'or pass --allow-dirty. No files were changed.',
+      );
+    }
+    if (changes.length > 0) {
+      throw new Error(
+        'Commit or stash your changes first (untracked files included), so the update can be undone with git, ' +
+        `or pass --allow-dirty. No files were changed:\n${changes.map((line) => `    ${line}`).join('\n')}`,
+      );
+    }
+  }
+
+  // Three-way merge of each file you edited: the old nutin version is the base, so your edits and
+  // nutin's changes are both kept, and only overlapping edits get conflict markers.
+  async mergeEditedFiles(projectPath, meta, toMerge) {
+    const merged = [];
+    const conflicted = [];
+    const labels = { base: `nutin v${meta.version}`, theirs: `nutin v${packageVersion}` };
+
+    for (const { relPath, actualContent, baseContent, newEntry } of toMerge) {
+      const { content, conflictCount } = await mergeFile({
+        base: baseContent,
+        yours: actualContent,
+        theirs: newEntry.content,
+        labels,
+      });
+      await fs.writeFile(path.join(projectPath, relPath), content);
+      if (conflictCount > 0) conflicted.push({ relPath, conflictCount });
+      else merged.push({ relPath });
+    }
+
+    return { merged, conflicted };
+  }
 }
 
 export const projectUpdater = new ProjectUpdater();

package/lib/src/update-app/template-differ.mjs

@@ -11,8 +11,8 @@ function contentEquals(a, b) {
   return a === b;
 }
 
-// Paths the user is expected to hand-edit right after `create-app` — their generated
-// content is just placeholder/starter scaffolding, so nutin-update must never rewrite
+// Paths the user is expected to hand-edit right after `create-app`.
+// Their generated content is just placeholder/starter scaffolding, so nutin-update must never rewrite
 // or conflict-flag them.
 const FULLY_EXCLUDED_PATTERNS = [
   /^config\/[^/]+\.json$/,
@@ -21,7 +21,7 @@ const FULLY_EXCLUDED_PATTERNS = [
 ];
 
 // Like FULLY_EXCLUDED_PATTERNS, but only for files that already existed before this
-// update — a brand new file introduced by a newer template version should still be added.
+// update. A brand new file introduced by a newer template version should still be added.
 const ADD_ONLY_PATTERNS = [
   /^src\/styles(\/|$)/,
 ];
@@ -114,8 +114,8 @@ export class TemplateDiffer {
       if (contentEquals(actualContent, oldEntry.content)) {
         toUpdate.push({ relPath, newEntry });
       } else if (!contentEquals(actualContent, newEntry.content)) {
-        // Differs from both baselines — a real conflict.
-        conflicts.push({ relPath, actualContent, newEntry });
+        // Differs from both baselines: a real conflict, merged from the old baseline at apply time.
+        conflicts.push({ relPath, actualContent, baseContent: oldEntry.content, newEntry });
       }
     }
 

package/lib/src/update-app/three-way-merge.mjs

@@ -0,0 +1,42 @@
+import os from 'os';
+import path from 'path';
+import * as fsExtra from 'fs-extra';
+import { execFileAsync } from '../common/git.mjs';
+
+const fs = fsExtra.default;
+
+export const CONFLICT_MARKER = '<<<<<<< yours';
+
+// Merges nutin's changes (base -> theirs) into your file with `git merge-file`, which needs the git
+// binary but no repository. Overlapping edits get diff3 markers: yours, the old nutin version, the new one.
+export async function mergeFile({ base, yours, theirs, labels }) {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'nutin-merge-'));
+  try {
+    const [yoursPath, basePath, theirsPath] = ['yours', 'base', 'theirs'].map((name) => path.join(tmpDir, name));
+    await Promise.all([
+      fs.writeFile(yoursPath, yours),
+      fs.writeFile(basePath, base),
+      fs.writeFile(theirsPath, theirs),
+    ]);
+
+    const args = ['merge-file', '-p', '--diff3', '-L', 'yours', '-L', labels.base, '-L', labels.theirs, yoursPath, basePath, theirsPath];
+    try {
+      const { stdout } = await execFileAsync('git', args, { maxBuffer: 1024 * 1024 * 50 });
+      return { content: stdout, conflictCount: 0 };
+    } catch (error) {
+      // A positive exit code below 255 is the number of conflicts; anything else is a real failure.
+      if (Number.isInteger(error.code) && error.code > 0 && error.code < 255) {
+        return { content: error.stdout, conflictCount: error.code };
+      }
+      throw error;
+    }
+  } finally {
+    await fs.remove(tmpDir);
+  }
+}
+
+export async function hasConflictMarkers(filePath) {
+  if (!(await fs.pathExists(filePath))) return false;
+  const content = await fs.readFile(filePath, 'utf8');
+  return content.split('\n').some((line) => line.startsWith(CONFLICT_MARKER));
+}

package/lib/src/update-app/update-context-builder.mjs

@@ -13,6 +13,7 @@ export class UpdateContextBuilder {
     const baseContext = {
       projectName: packageJson.name,
       packageManager,
+      lang: meta.lang ?? 'ts',
       ...meta.features,
       ciCommand: getCiCommand(packageManager),
     };

package/lib/src/update-app/update-summary-printer.mjs

@@ -1,11 +1,13 @@
 import { print } from '../utils/print.mjs';
 
-export function printUpdateSummary({ toUpdate, toAdd, conflicts, unknown, removedByUser, noLongerGenerated }) {
+const describeValue = (value) => (value === undefined ? '(missing)' : JSON.stringify(value));
+
+export function printUpdateSummary({ toUpdate, toAdd, conflicts, unknown, removedByUser, noLongerGenerated, jsonDrift = [] }) {
   print.section('\nSummary:');
   print.info(`  ${toUpdate.length} file(s) will be updated (untouched since generation)`);
   print.info(`  ${toAdd.length} new file(s) will be added`);
   if (conflicts.length > 0) {
-    print.boldError(`  ${conflicts.length} file(s) you modified need manual attention`);
+    print.boldError(`  ${conflicts.length} file(s) you edited will be merged with the new version`);
   }
   if (noLongerGenerated.length > 0) {
     print.boldError(`  ${noLongerGenerated.length} file(s) nutin no longer generates — left in place, review manually:`);
@@ -19,4 +21,10 @@ export function printUpdateSummary({ toUpdate, toAdd, conflicts, unknown, remove
     print.section(`  ${removedByUser.length} file(s) nutin used to generate but you removed — not recreated:`);
     removedByUser.forEach(({ relPath }) => print.section(`    - ${relPath}`));
   }
+  if (jsonDrift.length > 0) {
+    print.section(`  ${jsonDrift.length} package.json/tsconfig.json value(s) differ from what this nutin version generates — never changed automatically, apply by hand if wanted:`);
+    jsonDrift.forEach(({ file, key, yours, nutin }) =>
+      print.section(`    - ${file} ${key}: yours ${describeValue(yours)}, nutin ${describeValue(nutin)}`)
+    );
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nutin/cli",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "The structure of a framework. The freedom of vanilla.",
   "preferGlobal": true,
   "main": "lib/index.mjs",
@@ -17,7 +17,7 @@
     "minor": "npm version minor -m 'CI/CD: Bump version to %s'",
     "major": "npm version major -m 'CI/CD: Bump version to %s'",
     "test": "echo \"Error: no test specified\" && exit 1",
-    "publish": "npm publish --access public"
+    "release": "npm publish --access public"
   },
   "keywords": [
     "Nutin",
@@ -30,22 +30,23 @@
   "author": "Loïs Kouninef <loiskouninef@gmail.com>",
   "license": "MIT",
   "dependencies": {
-    "commander": "^9.0.0",
+    "commander": "^15.0.0",
     "diff": "^9.0.0",
-    "fs-extra": "^11.0.0",
-    "handlebars": "^4.7.8",
-    "inquirer": "^9.0.0",
-    "tar": "^7.5.22"
+    "fs-extra": "^11.4.1",
+    "handlebars": "^4.7.10",
+    "inquirer": "^14.2.3",
+    "tar": "^7.5.22",
+    "typescript": "5.9.3"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/loiskouninef/nutin.git"
+    "url": "git+https://github.com/LoisKOUNINEF/nutin.git"
   },
   "bugs": {
-    "url": "https://github.com/loiskouninef/nutin/issues"
+    "url": "https://github.com/LoisKOUNINEF/nutin/issues"
   },
-  "homepage": "www.nutin.org"
+  "homepage": "www.nutin.dev"
 }

package/templates/base/.gitignore.hbs

@@ -7,6 +7,7 @@ pnpm-debug.log*
 
 /dist/
 /dist-build/
+/.build-lock/
 /coverage/
 
 # Generated by "validate-docker" (run via docker:build) from tools/docker/*.template — only present when the docker feature is added