@nutin/cli 1.3.1 → 2.0.0

package/lib/src/common/file-generator.mjs

@@ -0,0 +1,159 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+import * as fsExtra from 'fs-extra';
+import { TemplateCompiler } from './template-compiler.mjs';
+import { print } from '../utils/print.mjs';
+import { FEATURES } from './feature-registry.mjs';
+
+const fs = fsExtra.default;
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const BINARY_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.svg',
+  '.ico', '.woff', '.woff2', '.ttf', '.otf', '.eot',
+  '.mp4', '.webm', '.mp3', '.wav', '.ogg',
+  '.pdf', '.zip', '.tar', '.gz'
+]);
+
+export class FileGenerator {
+  constructor() {
+    this.compiler = new TemplateCompiler();
+  }
+
+  async generateProjectFromTemplates(projectPath, context, templatesRoot = this.getTemplatesRoot()) {
+    const templateDir = path.join(templatesRoot, 'base');
+
+    print.section('📝 Processing templates...');
+    await this.processTemplateDirectory(templateDir, projectPath, context);
+
+    await this.processFeatureTemplates(projectPath, context, templatesRoot);
+  }
+
+  getTemplatesRoot() {
+    return path.join(__dirname, '..', '..', '..', 'templates');
+  }
+
+  async processTemplateDirectory(templateDir, outputDir, context, options = {}) {
+    if (!(await fs.pathExists(templateDir))) {
+      throw new Error(`Template directory not found: ${templateDir}`);
+    }
+
+    const entries = await fs.readdir(templateDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.name === '.DS_Store') continue;
+
+      const templatePath = path.join(templateDir, entry.name);
+
+      if (entry.isDirectory()) {
+        const outputPath = path.join(outputDir, entry.name);
+        await fs.ensureDir(outputPath);
+        await this.processTemplateDirectory(templatePath, outputPath, context, options);
+      } else {
+        await this.processTemplateFile(templatePath, outputDir, entry.name, context, options);
+      }
+    }
+  }
+
+  async processFeatureTemplates(projectPath, context, templatesRoot = this.getTemplatesRoot()) {
+    const featuresDir = path.join(templatesRoot, 'features');
+
+    if (!(await fs.pathExists(featuresDir))) {
+      return;
+    }
+
+    for (const feature of FEATURES) {
+      if (context[feature.key]) {
+        const featureTemplateDir = path.join(featuresDir, feature.key);
+
+        if (await fs.pathExists(featureTemplateDir)) {
+          print.info(`Adding ${feature.key} feature...`);
+          await this.processTemplateDirectory(featureTemplateDir, projectPath, context);
+        }
+      }
+    }
+  }
+
+  async isRenderTemplateFile(templatePath, fileName, context) {
+    const fileExt = path.extname(fileName).toLowerCase();
+    const outputFileName = fileName.endsWith('.hbs') ? fileName.replace('.hbs', '') : fileName;
+    const isBinary = BINARY_EXTENSIONS.has(fileExt);
+
+    let content;
+    if (isBinary) {
+      content = await fs.readFile(templatePath);
+    } else if (fileName.endsWith('.hbs')) {
+      content = await this.compiler.compileFile(templatePath, context);
+    } else {
+      content = await fs.readFile(templatePath, 'utf8');
+    }
+
+    return { outputFileName, isBinary, content };
+  }
+
+  async processTemplateFile(templatePath, outputDir, fileName, context, options = {}) {
+    let rendered;
+    try {
+      rendered = await this.isRenderTemplateFile(templatePath, fileName, context);
+    } catch (error) {
+      print.boldError(`❌ Failed to process template: ${fileName}`);
+      throw error;
+    }
+
+    if (!rendered) {
+      return;
+    }
+
+    const outputPath = path.join(outputDir, rendered.outputFileName);
+
+    if (options.skipExisting && await fs.pathExists(outputPath)) {
+      print.gray(`Skipped (already exists): ${path.relative(outputDir, outputPath)}`);
+      return;
+    }
+
+    await fs.writeFile(outputPath, rendered.content);
+  }
+
+  async collectTemplateTree(templatesRoot, context) {
+    const result = new Map();
+
+    const baseDir = path.join(templatesRoot, 'base');
+    if (await fs.pathExists(baseDir)) {
+      await this.collectTemplateDirectory(baseDir, baseDir, context, result);
+    }
+
+    const featuresDir = path.join(templatesRoot, 'features');
+    for (const feature of FEATURES) {
+      if (!context[feature.key]) continue;
+
+      const featureDir = path.join(featuresDir, feature.key);
+      if (await fs.pathExists(featureDir)) {
+        await this.collectTemplateDirectory(featureDir, featureDir, context, result);
+      }
+    }
+
+    return result;
+  }
+
+  async collectTemplateDirectory(dir, baseDir, context, result) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.name === '.DS_Store') continue;
+
+      const entryPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        await this.collectTemplateDirectory(entryPath, baseDir, context, result);
+      } else {
+        const rendered = await this.isRenderTemplateFile(entryPath, entry.name, context);
+        if (!rendered) continue;
+
+        const relativeDir = path.relative(baseDir, dir);
+        const relativeOutputPath = path.join(relativeDir, rendered.outputFileName);
+        result.set(relativeOutputPath, { content: rendered.content, isBinary: rendered.isBinary });
+      }
+    }
+  }
+}

package/lib/src/common/meta-bootstrap-prompt.mjs

@@ -0,0 +1,33 @@
+import inquirer from 'inquirer';
+import { print } from '../utils/print.mjs';
+import { FEATURES } from './feature-registry.mjs';
+import { detectPackageManager } from './package-json-helper.mjs';
+import { writeProjectMeta } from './project-meta.mjs';
+
+export async function bootstrapProjectMeta(projectPath) {
+  print.warn('⚠️  No .nutin-meta.json found for this project.');
+  print.section('Answer a couple of questions so a baseline can be reconstructed:\n');
+
+  const { version } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'version',
+      message: 'Which nutin version was this project originally created with (e.g. 1.3.1)?',
+      validate: (input) => /^\d+\.\d+\.\d+$/.test(input.trim()) || 'Enter a version like 1.3.1',
+    },
+  ]);
+
+  const { features } = await inquirer.prompt([
+    {
+      type: 'checkbox',
+      name: 'features',
+      message: 'Which optional features does this project have?',
+      choices: FEATURES.map((feature) => ({ name: feature.key, value: feature.key })),
+    },
+  ]);
+
+  const packageManager = await detectPackageManager(projectPath);
+  const flags = Object.fromEntries(FEATURES.map((f) => [f.key, features.includes(f.key)]));
+
+  return writeProjectMeta(projectPath, { version: version.trim(), packageManager, ...flags });
+}

package/lib/src/common/package-data.mjs

@@ -0,0 +1,10 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const packageJson = require('../../../package.json');
+
+export const PACKAGE_VERSION = packageJson.version;
+export const PACKAGE_NAME = packageJson.name;
+export const PACKAGE_HOMEPAGE = packageJson.homepage;
+
+export const META_FILE_NAME = '.nutin-meta.json';

package/lib/src/common/package-json-helper.mjs

@@ -0,0 +1,103 @@
+import { promiseExec } from '../utils/promise-exec-alias.mjs';
+import { print } from '../utils/print.mjs';
+import * as fsExtra from 'fs-extra';
+import * as path from 'path';
+
+const fs = fsExtra.default;
+
+export async function detectPackageManager(projectPath) {
+  if (await fs.pathExists(path.join(projectPath, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (await fs.pathExists(path.join(projectPath, 'yarn.lock'))) return 'yarn';
+  // bun 1.x switched its default lockfile from the binary bun.lockb to a text-based bun.lock —
+  // check both since either can be present depending on the bun version that created the project.
+  if (await fs.pathExists(path.join(projectPath, 'bun.lock'))) return 'bun';
+  if (await fs.pathExists(path.join(projectPath, 'bun.lockb'))) return 'bun';
+  return 'npm';
+}
+
+export async function installDependencies(projectPath, packageManager) {
+  print.section(`📦 Installing dependencies with ${packageManager}...`);
+
+  const installCommand = getInstallCommand(packageManager);
+  try {
+    await promiseExec(installCommand, { cwd: projectPath, maxBuffer: 1024 * 1024 * 10 });
+  } catch (err) {
+    const output = `${err.stdout ?? ''}\n${err.stderr ?? ''}`;
+
+    // pnpm >=10 refuses to run devDependency postinstall/build scripts (e.g. esbuild's,
+    // chokidar's optional native watcher backends) by default and exits non-zero even though
+    // every package installed successfully. Recover by approving them here (writes pnpm-workspace.yaml,
+    // which also stops every later `pnpm run <script>` from re-triggering the same check).
+    if (packageManager === 'pnpm' && /ERR_PNPM_IGNORED_BUILDS/.test(output)) {
+      print.warn('⚠️ pnpm flagged some build scripts as needing approval — approving automatically...');
+      try {
+        await promiseExec('pnpm approve-builds --all', { cwd: projectPath, maxBuffer: 1024 * 1024 * 10 });
+        return;
+      } catch (approveErr) {
+        print.error(`pnpm approve-builds --all also failed: ${approveErr.message}`);
+      }
+    }
+
+    if (err.stdout) print.gray(err.stdout);
+    if (err.stderr) print.error(err.stderr);
+    throw new Error(`${installCommand} failed (see output above for the real cause).`);
+  }
+}
+
+export function getCiCommand(packageManager) {
+  switch (packageManager) {
+    case 'yarn':
+      return 'yarn install --frozen-lockfile';
+    case 'pnpm':
+      return 'pnpm install --frozen-lockfile';
+    case 'bun':
+      return 'bun install --frozen-lockfile'
+    default:
+      return 'npm ci';
+  }
+}
+
+export function getInstallCommand(packageManager) {
+  switch (packageManager) {
+    case 'yarn':
+      return 'yarn install';
+    case 'pnpm':
+      return 'pnpm install';
+    case 'bun':
+      return 'bun install'
+    default:
+      return 'npm install';
+  }
+}
+
+export function getDockerScripts() {
+  const dockerScriptsDir = 'node tools/docker/scripts'
+  return {
+    "docker:build": `${dockerScriptsDir}/docker-build.js`,
+    "docker:run": `${dockerScriptsDir}/docker-run.js`
+  };
+}
+
+export function getAllScripts(context) {
+  const { packageManager, docker } = context;
+
+  const baseScripts = {
+    "build": "node tools/builder/builder.js",
+    "build:prod": "NODE_ENV=production node tools/builder/builder.js",
+    "serve": `${packageManager} run build && ${packageManager} run serve:only`,
+    "serve:only": "node tools/dev/serve.js",
+    "serve:prod": `${packageManager} run build:prod && ${packageManager} run serve:only`,
+    "dev": "node tools/dev/dev-serve.js",
+    "generate": "node tools/generator/generator.js",
+    "testin-nutin": `${packageManager} run build && node tools/testin-nutin/runner.js`,
+    "testin-nutin:watch": `${packageManager} run build && node tools/testin-nutin/watch-tests.js`,
+    "testin-nutin:coverage": `${packageManager} run build && node tools/testin-nutin/runner.js --coverage`,
+    "testin-nutin:verbose": `${packageManager} run build && node tools/testin-nutin/runner.js --verbose`
+  };
+
+  let scripts = { ...baseScripts };
+
+  if (docker) scripts = { ...scripts, ...getDockerScripts() };
+
+  return scripts;
+}

package/lib/src/common/project-meta.mjs

@@ -0,0 +1,54 @@
+import path from 'path';
+import * as fsExtra from 'fs-extra';
+import { FEATURES } from './feature-registry.mjs';
+
+const fs = fsExtra.default;
+
+const META_FILE_NAME = '.nutin-meta.json';
+
+function metaPath(projectPath) {
+  return path.join(projectPath, META_FILE_NAME);
+}
+
+function extractFeatures(context) {
+  const features = {};
+  for (const feature of FEATURES) {
+    features[feature.key] = Boolean(context[feature.key]);
+  }
+  return features;
+}
+
+export async function writeProjectMeta(projectPath, context) {
+  const meta = {
+    version: context.version,
+    packageManager: context.packageManager,
+    features: extractFeatures(context),
+  };
+
+  await fs.writeJSON(metaPath(projectPath), meta, { spaces: 2 });
+  return meta;
+}
+
+export async function readProjectMeta(projectPath) {
+  const file = metaPath(projectPath);
+  if (!(await fs.pathExists(file))) {
+    return null;
+  }
+  return fs.readJSON(file);
+}
+
+export async function updateProjectMeta(projectPath, patch) {
+  const existing = (await readProjectMeta(projectPath)) ?? {};
+
+  const merged = {
+    ...existing,
+    ...patch,
+    features: {
+      ...(existing.features ?? {}),
+      ...(patch.features ?? {}),
+    },
+  };
+
+  await fs.writeJSON(metaPath(projectPath), merged, { spaces: 2 });
+  return merged;
+}

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

@@ -0,0 +1,21 @@
+import { getCiCommand } from '../common/package-json-helper.mjs';
+import { PACKAGE_VERSION } from '../common/package-data.mjs';
+
+export const defaults = {
+  projectName: 'my-nutin-app',
+  packageManager: 'npm',
+};
+
+export class ContextBuilder {
+	buildContext(preferences) { 
+    const version = PACKAGE_VERSION;
+    const ciCommand = getCiCommand(preferences.packageManager);
+
+    return {
+      projectName: preferences.projectName,
+      packageManager: preferences.packageManager,
+      ciCommand: ciCommand,
+      version: version
+    };
+  }
+}

package/lib/src/{git-manager.mjs → create-app/git-manager.mjs}

@@ -1,5 +1,5 @@
-import { print } from './print.mjs';
-import { promiseExec } from './utils.mjs';
+import { print } from '../utils/print.mjs';
+import { promiseExec } from '../utils/promise-exec-alias.mjs';
 
 export async function initializeGit(projectPath) {
   print.section('⚙️ Initializing Git repository...');

package/lib/src/create-app/json-manager.mjs

@@ -0,0 +1,73 @@
+import path from 'path';
+import * as fsExtra from 'fs-extra';
+import { getAllScripts } from '../common/package-json-helper.mjs';
+
+const fs = fsExtra.default;
+
+export class JsonManager {
+  async generateJsonFiles(projectPath, context) {
+    await this.generatePackageJson(projectPath, context);
+    await this.generateTsconfigJson(projectPath, context);
+  }
+
+  async generatePackageJson(projectPath, context) {
+    const { testinNutin, projectName } = context;
+
+    const devDependencies = {
+      "chokidar": "^4.0.3",
+      "esbuild": "^0.25.12",
+      "html-minifier-terser": "^7.2.0",
+      "jsdom": "^26.1.0",
+      "linkedom": "^0.18.12",
+      "live-server": "^1.2.2",
+      "sass": "^1.89.0",
+      "typescript": "^5.8.3"
+    };
+
+    const scripts = getAllScripts(context);
+
+    const packageJson = {
+      "name": projectName,
+      "version": "0.1.0",
+      "type": "module",
+      "imports": {
+        "#root/*.js": "./*.js"
+      },
+      scripts,
+      devDependencies,
+      "engines": {
+        "node": ">=22"
+      }
+    };
+    
+    await fs.writeJSON(path.join(projectPath, 'package.json'), packageJson, { spaces: 2 });
+  }
+
+  async generateTsconfigJson(projectPath) {
+    const tsconfig = {
+      "compilerOptions": {
+        "baseUrl": "./",
+        "paths": {},
+        "target": "ESNext",
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "rootDir": "src",
+        "outDir": "dist-build/src",
+        "strict": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "noUncheckedIndexedAccess": true,
+        "esModuleInterop": true,
+        "allowSyntheticDefaultImports": true,
+        "lib": ["es2022", "DOM"],
+        "removeComments": true,
+        "resolveJsonModule": true,
+        "typeRoots": ["src/types", "node_modules/@types"]
+      },
+      "include": ["src/app", "src/core"],
+      "exclude": ["node_modules"]
+    };
+    
+    await fs.writeJSON(path.join(projectPath, 'tsconfig.json'), tsconfig, { spaces: 2 });
+  }
+}

package/lib/src/{prompts.mjs → create-app/new-app-prompt.mjs}

@@ -1,7 +1,7 @@
 import inquirer from 'inquirer';
 import { defaults } from './context-builder.mjs';
 
-export async function promptUser(initialName, cliOptions = {}) {
+export async function newAppPrompt(initialName, cliOptions = {}) {
 
   let projectName = initialName;
   if (!projectName) {
@@ -15,6 +15,11 @@ export async function promptUser(initialName, cliOptions = {}) {
       },
     ]);
     projectName = nameInput.projectName;
+  } else {
+    const validationResult = validateProjectName(projectName);
+    if (validationResult !== true) {
+      throw new Error(validationResult);
+    }
   }
 
   let packageManager = cliOptions.packageManager;
@@ -34,11 +39,6 @@ export async function promptUser(initialName, cliOptions = {}) {
   return {
     projectName,
     packageManager,
-    preset: cliOptions.preset,
-    i18n: cliOptions.i18n,
-    deployHelper: cliOptions.deployHelper,
-    testinNutin: cliOptions.testinNutin,
-    transition:   cliOptions.transition,
   };
 }
 

package/lib/src/{project-generator.mjs → create-app/project-generator.mjs}

@@ -1,18 +1,19 @@
 import path from 'path';
 import * as fsExtra from 'fs-extra';
-import { print } from './print.mjs';
+import { print } from '../utils/print.mjs';
 import { initializeGit } from './git-manager.mjs';
-import { installDependencies } from './package-manager.mjs';
-import { FileGenerator } from './file-generator.mjs';
-import { JsonGenerator } from './json-generator.mjs';
+import { installDependencies } from '../common/package-json-helper.mjs';
+import { FileGenerator } from '../common/file-generator.mjs';
+import { JsonManager } from './json-manager.mjs';
 import { ContextBuilder } from './context-builder.mjs';
+import { writeProjectMeta } from '../common/project-meta.mjs';
 
 const fs = fsExtra.default;
 
 export class ProjectGenerator {
   constructor() {
     this.fileGenerator = new FileGenerator();
-    this.jsonGenerator = new JsonGenerator();
+    this.jsonManager = new JsonManager();
     this.builder = new ContextBuilder();
   }
 
@@ -40,8 +41,9 @@ export class ProjectGenerator {
   }
 
   async runPostSetupTasks(projectPath, context) {
-    await this.jsonGenerator.generateJsonFiles(projectPath, context);
-    await initializeGit(projectPath);    
+    await this.jsonManager.generateJsonFiles(projectPath, context);
+    await writeProjectMeta(projectPath, context);
+    await initializeGit(projectPath);
     await installDependencies(projectPath, context.packageManager);
   }
 }
@@ -50,4 +52,4 @@ export const projectGenerator = new ProjectGenerator();
 
 export async function createProject(preferences) {
   return projectGenerator.createProject(preferences);
-}
+}

package/lib/src/create-app/success-message.mjs

@@ -0,0 +1,14 @@
+import { print } from '../utils/print.mjs';
+import { PACKAGE_HOMEPAGE } from '../common/package-data.mjs';
+
+export function displaySuccessMessage(answers) {
+  const { projectName, packageManager, deployHelper } = answers;
+  print.boldSuccess('\n🎉 Your project is ready!\n');
+
+  print.boldInfo('Next steps:');
+  print.info(`cd ${projectName}`);
+  print.info(`${packageManager} run serve\n`);
+
+  print.boldInfo('Documentation:');
+  print.info(`https://${PACKAGE_HOMEPAGE}\n`);
+}

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

@@ -0,0 +1,31 @@
+import path from 'path';
+import * as fsExtra from 'fs-extra';
+import * as Diff from 'diff';
+
+const fs = fsExtra.default;
+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 patch = Diff.createTwoFilesPatch(
+      relPath,
+      relPath,
+      actualContent,
+      newEntry.content,
+      'yours',
+      `nutin v${newVersion}`,
+    );
+    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';
+
+  await fs.writeFile(path.join(projectPath, REPORT_FILE_NAME), header + sections.join('\n'));
+}

package/lib/src/update-app/fetch-old-templates.mjs

@@ -0,0 +1,61 @@
+import os from 'os';
+import path from 'path';
+import * as fsExtra from 'fs-extra';
+import * as tar from 'tar';
+import { promiseExec } from '../utils/promise-exec-alias.mjs';
+import { PACKAGE_NAME } from '../common/package-data.mjs';
+
+const fs = fsExtra.default;
+
+export async function fetchOldTemplates(version, { from } = {}) {
+  if (from) {
+    const templatesRoot = path.resolve(from);
+    if (!(await fs.pathExists(templatesRoot))) {
+      throw new Error(`--from path not found: ${templatesRoot}`);
+    }
+    return { templatesRoot, cleanup: async () => {} };
+  }
+
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'nutin-update-'));
+
+  let tarballName;
+  try {
+    const { stdout } = await promiseExec(
+      `npm pack ${PACKAGE_NAME}@${version} --pack-destination "${tmpDir}" --json`,
+      { maxBuffer: 1024 * 1024 * 10 },
+    );
+    const parsed = JSON.parse(stdout);
+    const packResult = Array.isArray(parsed) ? parsed[0] : Object.values(parsed)[0];
+    tarballName = packResult?.filename;
+  } catch (error) {
+    await fs.remove(tmpDir);
+    throw new Error(
+      `Couldn't fetch ${PACKAGE_NAME}@${version} from the npm registry — (${error.message})`,
+    );
+  }
+
+  if (!tarballName) {
+    await fs.remove(tmpDir);
+    throw new Error(`npm pack did not report a tarball for ${PACKAGE_NAME}@${version}.`);
+  }
+
+  try {
+    await tar.x({ file: path.join(tmpDir, tarballName), cwd: tmpDir });
+  } catch (error) {
+    await fs.remove(tmpDir);
+    throw new Error(`Couldn't extract ${tarballName} for ${PACKAGE_NAME}@${version} — (${error.message})`);
+  }
+
+  await fs.remove(path.join(tmpDir, tarballName));
+
+  const templatesRoot = path.join(tmpDir, 'package', 'templates');
+  if (!(await fs.pathExists(templatesRoot))) {
+    await fs.remove(tmpDir);
+    throw new Error(`${PACKAGE_NAME}@${version}'s package didn't contain a templates/ directory.`);
+  }
+
+  return {
+    templatesRoot,
+    cleanup: async () => fs.remove(tmpDir),
+  };
+}