@nutin/cli 1.3.1 → 2.0.0

package/CHANGELOG.md

@@ -1,6 +1,86 @@
 # Changelog
 
-## V1.3.1
+## 2.0.0
+
+Version 2.0.0 focuses on simplicity and clear APIs over feature accumulation: fewer abstractions, clearer responsibilities, and a more focused API. 
+
+### Breaking Changes
+
+- Renamed `BaseComponent`'s `childConfigs()` to `registerChildren()` and `catalogConfig` to `createCatalogComponents()`.
+- Raised the required Node.js version from `>=18` to `>=22`.
+- Removed all libraries except `Pipes`, as they did not fit Nutin's philosophy.
+- Removed `Store`. Its responsibilities were unclear and largely duplicated what services already provide.
+- Removed the `force` parameter from `listenToRenderEvents()`. It is no longer needed.
+
+### Architecture & API
+
+- Clarified and separated the responsibilities of the base classes:
+  - **`BaseComponent`**: render lifecycle, hydration, DOM lifecycle, DOM and EventBus subscriptions, teardown, render guard, and composition orchestration.
+  - **`Component`**: props (`className`, `style`, `data-bindings`), configuration/defaults/normalization, and template generation through `templateFn`.
+  - **`View`**: route parameters, navigation hooks (`onEnter()` / `onExit()`), and view identity (`viewName`).
+
+- Components and Views now inherit `listen()` and `listenToRenderEvents()` methods with automatic unsubscription.
+- Added explicit lifecycle hooks:
+  - **Component:** `onBeforeRender()`, `onAfterRender()`, `onBeforeDestroy()`, `onAfterDestroy()`
+  - **View:** `onEnter()`, `onExit()`
+
+- Simplified the EventBus API:
+    - Added `AppEventMap` for app-level events. Nutin's internal events are no longer declared in `globals.d.ts`.
+    - Event payload types are now objects.
+    - EventBus now exposes domain facades for `Navigation` and `Lifecycle` events.
+    - Event subscription functions (`on*`) now return a closure for unsubscription.
+    - `AppEventBus` can still be used directly when needed (`once()`, etc.), but subscriptions must then be unsubscribed manually through the `onBeforeDestroy()` hook.
+```ts
+// emit
+Navigation.navigateTo('path');
+// closure
+const unsub = Navigation.onNavigate(this.doStuff);
+// onDestroy
+unsub()
+```
+
+### Services
+
+- Services now expose a single `getInstance()` method.
+- Arguments can be passed to `getInstance()`, but are only used during the first instantiation.
+
+### Configuration & Build
+
+- Added `nutin.config.js` as the central configuration file for Nutin options, builder, generator, and testing.
+- Added optional Tailwind CSS v4 support as a utility layer alongside SASS.
+- Added globally scoped stylesheets co-located with feature files. **Use unique class names.** Nutin's naming convention encourages prefixes such as `home__header`.
+- HTML templates can now be either inline or external `.html` files. Defining both, or neither, fails the build.
+- Added configurable Docker ports through `nutin.config.js`.
+- Dockerfile now builds a Brotli-enabled image.
+
+### SEO & i18n
+
+- Added optional generation of static SEO files from `config/seo.json`.
+  - Production builds generate static HTML for each route using the actual components.
+  - Only `title`, `description`, and `ogImage` remain hand-authored SEO content.
+  - Generates `robots.txt` and `sitemap.xml`.
+  - Supports per-route `disallow` and `disallowBots`.
+
+- i18n now uses the URL, aligning with common practices and allowing static SEO HTML to be generated for each language.
+
+### CLI & Developer Experience
+
+- Added `nutin-update`, which updates Nutin to the latest patch or minor version by diffing the project against the new templates and merging compatible changes. Unresolved conflicts are reported.
+- Added `nutin-add docker`.
+- Added `GETTING_STARTED.md`, providing the architectural context and conventions needed to start working with a Nutin project without immediately consulting the full documentation.
+- Added `AGENTS.md`, providing LLMs with the minimal context required to work effectively in a Nutin project.
+
+### TestinNutin
+
+- Added code coverage summaries for branches, functions, and lines.
+- Added `it.todo`.
+- Added clock mocking for `setTimeout` and `setInterval`.
+
+### Bug Fixes
+
+- Numerous bug fixes and stability improvements.
+
+## 1.3.1
 
 - Minor features:
     - New BaseComponent protected method.
@@ -34,7 +114,7 @@
             CI/CD: Minimal + deployment helpers
         - Remaining flags: `--i18n`, `--deploy-helper`, `--testin-nutin`, `--transition`
 
-## V1.3.0
+## 1.3.0
 
 Version 1.3.0 marks a stability milestone with various improvements and refinements, making this the recommended version for new projects.
 
@@ -69,11 +149,11 @@ Version 1.3.0 marks a stability milestone with various improvements and refineme
 - TestinNutin
     - Now applies `setupJsdom()` beforeAll (was beforeEach) and `teardownJsdom()` afterAll (was afterEach) in `test-queue.js` (improved efficiency / speed)
 
-## V1.2.3
+## 1.2.3
 
 - `nginx.conf` : fixed multi-line CSP map warning (single line map)
 
-## V1.2.2
+## 1.2.2
 
 - Fixed Nginx security headers in child location blocks.
 
@@ -81,7 +161,7 @@ Version 1.3.0 marks a stability milestone with various improvements and refineme
 
 - Removed ghost files
 
-## V1.2.1
+## 1.2.1
 
 - Builder
 
@@ -109,7 +189,7 @@ Version 1.3.0 marks a stability milestone with various improvements and refineme
 
 - Added explicit chokidar devDependency (sass & live-server transitive).
 
-## V1.2.0
+## 1.2.0
 
 - Fixed `npm run dev` command. Added middleware to reload nested routes.
 
@@ -140,7 +220,7 @@ Version 1.3.0 marks a stability milestone with various improvements and refineme
 - stylin-nutin (generator)
     - When generating a component, prompts (boolean) to generate a `_component-name.scss` file in `styles/components` (forwarded by `styles/components/_index.scss`).
 
-## V1.1.0
+## 1.1.0
 
 - Added index access in CatalogConfig. Use with `config.index`.
 ```typescript
@@ -159,10 +239,10 @@ type CatalogItemConfig<T = any> =
 
 **Notes:** *Primitive data arrays (string, number, etc) needs to be accessed with `config.value`.*
 
-## V1.0.2
+## 1.0.2
 
 - Partially fixed `npm run dev` script when using internal templates. *Page still needs to be reload manually from time to time.*
 
-## V1.0.1
+## 1.0.1
 
 - Fixed typo issue when using i18n feature

package/README.md

@@ -1,11 +1,12 @@
-# [nutin](https://www.nutin.org)
+# [Nutin](https://www.nutin.org)
 
-**Build SPAs by understanding SPAs. A minimal frontend toolkit crafted for learning and lean applications.**                    
-Includes essential features out of the box.                          
-*Pure TypeScript, SASS, and DOM-driven components — zero runtime dependencies.*
+`The structure of a framework. The freedom of vanilla.`
 
-- Required : Node >=18 
-- **JSDOM requirement** (testin-nutin companion) : `{ node: '^20.19.0 || ^22.12.0 || >=24.0.0' }`
+Nutin provides the structure and tooling you'd expect from a framework, while keeping the underlying web platform visible and giving you code ownership.
+
+**Your app owns Nutin — not the other way around.** The source code lives alongside your application, so you can read it, modify it, and make it yours. Nutin's update system is designed to preserve those changes.
+
+Nutin is deliberately pragmatic, lightweight, and dependency-free on runtime.
 
 ## Install
 
@@ -18,44 +19,28 @@ npm install -g @nutin/cli
 
 ```bash
 # create a new app
-create-nutin-app # or
-nutin-new
+nutin-new # or create-nutin-app
 
 # without global installation
 npx @nutin/cli
 ```
 
-- Flags
+## Update Nutin
 
 ```bash
-# argument: project-name (prompt if not provided)
-
-# Help
--h --help
-
-# Defaults settings - see below
--d --defaults
-
-# Package manager
--pm --package-manager <manager> # npm (Default), yarn, pnpm, bun
+# update Nutin while preserving your changes
+nutin-update
+```
 
-# Presets
---preset <minimal|standard|full|cicd>
-	# minimal: external templates
-	# standard: minimal + i18n & built-in SCSS classes
-	# full: standard + deployment helpers & built-in testing toolkit
-	# cicd: minimal + deployment helpers
+## Add Docker
 
-# Features
---i18n # Use i18n & json-based content
---deploy-helper # Use Docker & deployment helpers
---testin-nutin # Use testin-nutin toolkit
---transition # Use animated view transitions. Note: May interfere with CSS `position: fixed`, `z-index`...
+```bash
+# ready-to-use Dockerfile for Nutin apps
+nutin-add docker
 ```
 
-## [First app tutorial](https://www.nutin.org/tutorial)
-
-## 📄 Docs
+## Useful links
 
-- Docs on [website](https://www.nutin.org).
-- Docs on [repository](https://github.com/LoisKOUNINEF/nutin/tree/main/docs).
+- [Nutin website](https://www.nutin.org)
+- [First app tutorial](https://www.nutin.org/tutorial)
+- [Repository documentation](https://github.com/LoisKOUNINEF/nutin/tree/main/docs)

package/bin/add-feature.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { addFeatureCommand } from '../lib/index.mjs';
+
+addFeatureCommand(new Command()).parseAsync(process.argv).catch((err) => {
+  console.error(err instanceof Error ? err.stack : err);
+  process.exitCode = 1;
+});

package/bin/cli.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { buildCli } from '../lib/index.mjs';
+
+buildCli().parseAsync(process.argv).catch((err) => {
+  console.error(err instanceof Error ? err.stack : err);
+  process.exitCode = 1;
+});

package/bin/create-app.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
-import { createApp } from '../lib/index.mjs';
+import { Command } from 'commander';
+import { createAppCommand } from '../lib/index.mjs';
 
-createApp().catch((error) => {
-  console.error('Error:', error.message);
-  process.exit(1);
+createAppCommand(new Command()).parseAsync(process.argv).catch((err) => {
+  console.error(err instanceof Error ? err.stack : err);
+  process.exitCode = 1;
 });

package/bin/update-app.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { updateAppCommand } from '../lib/index.mjs';
+
+updateAppCommand(new Command()).parseAsync(process.argv).catch((err) => {
+  console.error(err instanceof Error ? err.stack : err);
+  process.exitCode = 1;
+});

package/lib/index.mjs

@@ -1,33 +1,25 @@
-import { program } from 'commander';
-import { print, chalk } from './src/print.mjs';
-import { promptUser } from './src/prompts.mjs';
-import { createProject } from './src/project-generator.mjs';
-import { displaySuccessMessage } from './src/utils.mjs';
-import { packageVersion } from './src/version.mjs';
-
-export async function createApp() {
-  program
-    .version(packageVersion)
+import { Command } from 'commander';
+import { print, chalk } from './src/utils/print.mjs';
+import { newAppPrompt } from './src/create-app/new-app-prompt.mjs';
+import { createProject } from './src/create-app/project-generator.mjs';
+import { displaySuccessMessage } from './src/create-app/success-message.mjs';
+import { PACKAGE_VERSION } from './src/common/package-data.mjs';
+import { FEATURES, findFeatureByCli } from './src/common/feature-registry.mjs';
+import { addFeatureToProject } from './src/add-feature/feature-adder.mjs';
+import { updateProject } from './src/update-app/project-updater.mjs';
+
+export function createAppCommand(command) {
+  return command
+    .version(PACKAGE_VERSION)
     .configureOutput({
-      helpWidth: 100 
+      helpWidth: 100
     })
     .argument('[projectName]', 'Name of the project')
     .option('-pm, --package-manager <manager>', 'Specify package manager (npm, yarn, pnpm, bun)')
-    .option('--preset <preset>', 
-      `${chalk.yellow('Project preset configuration:')}
-      ${chalk.cyan('• minimal')}${chalk.boldGray('   - external templates')}
-      ${chalk.cyan('• standard')}${chalk.boldGray('  - minimal + i18n & built-in SCSS utilities')}
-      ${chalk.cyan('• full')}${chalk.boldGray('      - standard + deployment helpers & built-in testing toolkit')}
-      ${chalk.cyan('• cicd')}${chalk.boldGray('      - minimal + deployment helpers')}`
-    )
-    .option('--i18n', 'Use i18n & json-based content')
-    .option('--deploy-helper', 'Use Docker & deployment helpers')
-    .option('--testin-nutin', 'Use built-in testing toolkit')
-    .option('--transition', 'Use animated view transitions\nNote: may interfere with CSS `position: fixed`, `z-index`…')
     .action(async (projectName, cliOptions) => {
-      print.blue('🚀 Welcome to nutin !');
+      print.boldSuccess('\n🚀 Welcome to your new nutin app!\n');
       try {
-        const preferences = await promptUser(projectName, cliOptions);
+        const preferences = await newAppPrompt(projectName, cliOptions);
         await createProject(preferences);
         displaySuccessMessage(preferences);
       } catch (error) {
@@ -35,7 +27,66 @@ export async function createApp() {
         process.exit(1);
       }
     });
+}
+
+export function addFeatureCommand(command) {
+  const featureChoices = [...FEATURES.map((feature) => feature.cli), 'all'];
+
+  return command
+    .version(PACKAGE_VERSION)
+    .configureOutput({
+      helpWidth: 100
+    })
+    .argument('<feature>', `Feature to add to the current project: ${featureChoices.join(', ')}`)
+    .action(async (featureArg) => {
+      if (!featureChoices.includes(featureArg)) {
+        print.boldError(`❌ Unknown feature "${featureArg}". Choose one of: ${featureChoices.join(', ')}`);
+        process.exit(1);
+      }
+
+      try {
+        if (featureArg === 'all') {
+          for (const feature of FEATURES) {
+            await addFeatureToProject(feature.key);
+          }
+        } else {
+          const feature = findFeatureByCli(featureArg);
+          await addFeatureToProject(feature.key);
+        }
+      } catch (error) {
+        print.boldError(`❌ Error adding feature: ${error.stack}`);
+        process.exit(1);
+      }
+    });
+}
 
-  program.parse();
+export function updateAppCommand(command) {
+  return command
+    .version(PACKAGE_VERSION)
+    .configureOutput({
+      helpWidth: 100
+    })
+    .option('-y, --yes', 'Skip the confirmation prompt and apply safe updates immediately')
+    .option('--from <path>', 'Use a local templates/ directory as the old baseline instead of fetching from npm')
+    .action(async (cliOptions) => {
+      print.boldSuccess('🚀 nutin — update');
+
+      try {
+        await updateProject(process.cwd(), cliOptions);
+      } catch (error) {
+        print.boldError(`❌ Error updating project: ${error.stack}`);
+        process.exit(1);
+      }
+    });
 }
 
+export function buildCli() {
+  const program = new Command();
+  program.name('nutin').version(PACKAGE_VERSION);
+
+  createAppCommand(program.command('new', { isDefault: true }).description('Create a new nutin app'));
+  addFeatureCommand(program.command('add').description('Add a feature to the current project'));
+  updateAppCommand(program.command('update').description('Update nutin while preserving your changes'));
+
+  return program;
+}

package/lib/src/add-feature/feature-adder.mjs

@@ -0,0 +1,83 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+import * as fsExtra from 'fs-extra';
+import { print } from '../utils/print.mjs';
+import { FileGenerator } from '../common/file-generator.mjs';
+import { FEATURES } from '../common/feature-registry.mjs';
+import { PACKAGE_VERSION } from '../common/package-data.mjs';
+import { installDependencies } from '../common/package-json-helper.mjs';
+import { readProjectMeta, updateProjectMeta } from '../common/project-meta.mjs';
+import { FeatureContextBuilder } from './feature-context-builder.mjs';
+import { updatePackageJson } from './package-json-updater.mjs';
+import { updateNutinConfig } from './nutin-config-updater.mjs';
+
+const fs = fsExtra.default;
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export class FeatureAdder {
+  constructor() {
+    this.fileGenerator = new FileGenerator();
+    this.builder = new FeatureContextBuilder();
+  }
+
+  async addFeatureToProject(featureKey) {
+    const feature = FEATURES.find((candidate) => candidate.key === featureKey);
+    if (!feature) {
+      throw new Error(`Unknown feature: ${featureKey}`);
+    }
+
+    const projectPath = process.cwd();
+    await this.validateProject(projectPath, feature);
+
+    const meta = await readProjectMeta(projectPath);
+    if (meta?.features?.[feature.key]) {
+      print.gray(`${feature.key} is already enabled in this project — skipping.`);
+      return;
+    }
+
+    print.boldInfo(`\nAdding ${feature.key} to ${projectPath}...`);
+
+    const context = await this.builder.buildContext(projectPath, feature);
+
+    await this.applyFeatureTemplate(projectPath, feature, context);
+    await this.runPostAddTasks(projectPath, feature, context);
+
+    print.boldInfo(`${feature.key} added.`);
+  }
+
+  async validateProject(projectPath, feature) {
+    const packageJsonPath = path.join(projectPath, 'package.json');
+    if (!(await fs.pathExists(packageJsonPath))) {
+      throw new Error(`No package.json found in ${projectPath} — run this from a nutin project's root.`);
+    }
+    if (!(await fs.pathExists(path.join(projectPath, 'nutin.config.js')))) {
+      throw new Error(`No nutin.config.js file found in ${projectPath} — is this a nutin project?`);
+    }
+  }
+
+  async applyFeatureTemplate(projectPath, feature, context) {
+    const featureTemplateDir = path.join(__dirname, '..', '..', '..', 'templates', 'features', feature.key);
+
+    await this.fileGenerator.processTemplateDirectory(featureTemplateDir, projectPath, context, { skipExisting: true });
+
+    await updatePackageJson(projectPath, feature);
+    await updateNutinConfig(projectPath, feature);
+  }
+
+  async runPostAddTasks(projectPath, feature, context) {
+    await updateProjectMeta(projectPath, {
+      version: PACKAGE_VERSION,
+      packageManager: context.packageManager,
+      features: { [feature.key]: true },
+    });
+    if (feature.key === 'docker') return;
+    await installDependencies(projectPath, context.packageManager);
+  }
+}
+
+export const featureAdder = new FeatureAdder();
+
+export async function addFeatureToProject(featureKey) {
+  return featureAdder.addFeatureToProject(featureKey);
+}

package/lib/src/add-feature/feature-context-builder.mjs

@@ -0,0 +1,25 @@
+import path from 'path';
+import * as fsExtra from 'fs-extra';
+import { getCiCommand, detectPackageManager } from '../common/package-json-helper.mjs';
+import { PACKAGE_VERSION } from '../common/package-data.mjs';
+import { readProjectMeta } from '../common/project-meta.mjs';
+import { bootstrapProjectMeta } from '../common/meta-bootstrap-prompt.mjs';
+
+const fs = fsExtra.default;
+
+export class FeatureContextBuilder {
+  async buildContext(projectPath, feature) {
+    const packageJson = await fs.readJSON(path.join(projectPath, 'package.json'));
+    const packageManager = await detectPackageManager(projectPath);
+    const meta = (await readProjectMeta(projectPath)) ?? (await bootstrapProjectMeta(projectPath));
+
+    return {
+      projectName: packageJson.name,
+      packageManager,
+      ciCommand: getCiCommand(packageManager),
+      version: PACKAGE_VERSION,
+      ...(meta.features ?? {}),
+      [feature.key]: true,
+    };
+  }
+}

package/lib/src/add-feature/nutin-config-updater.mjs

@@ -0,0 +1,29 @@
+import path from 'path';
+import * as fsExtra from 'fs-extra';
+import { print } from '../utils/print.mjs';
+
+const fs = fsExtra.default;
+
+const GENERATE_SEO_LINE_RE = /^([ \t]*generateSEOFiles:[^\n]*\n)/m;
+const DOCKER_PORTS_LINE = '\n// Nutin features\n  dockerPorts: [9090],     // Ports the Docker container exposes/listens on — edit as needed\n';
+
+export async function updateNutinConfig(projectPath, feature) {
+  if (feature.key !== 'docker') return;
+
+  const configPath = path.join(projectPath, 'nutin.config.js');
+  const content = await fs.readFile(configPath, 'utf-8');
+
+  if (/dockerPorts\s*:/.test(content)) {
+    print.info('Kept existing "dockerPorts" value in nutin.config.js');
+    return;
+  }
+
+  if (!GENERATE_SEO_LINE_RE.test(content)) {
+    print.warn('Could not find a "generateSEOFiles:" line in nutin.config.js — add "dockerPorts: [9090]" to it manually before building.');
+    return;
+  }
+
+  const updated = content.replace(GENERATE_SEO_LINE_RE, `$1${DOCKER_PORTS_LINE}`);
+  await fs.writeFile(configPath, updated);
+  print.warn('Added "dockerPorts" to nutin.config.js — edit it if you need different port(s).');
+}

package/lib/src/add-feature/package-json-updater.mjs

@@ -0,0 +1,49 @@
+import path from 'path';
+import * as fsExtra from 'fs-extra';
+import { print } from '../utils/print.mjs';
+import { getDockerScripts } from '../common/package-json-helper.mjs';
+
+const fs = fsExtra.default;
+
+function mergeAdditive(target, additions) {
+  const merged = { ...target };
+  const added = [];
+  const skipped = [];
+
+  for (const [key, value] of Object.entries(additions)) {
+    if (Object.prototype.hasOwnProperty.call(merged, key)) {
+      skipped.push(key);
+    } else {
+      merged[key] = value;
+      added.push(key);
+    }
+  }
+
+  return { merged, added, skipped };
+}
+
+export async function updatePackageJson(projectPath, feature) {
+  const packageJsonPath = path.join(projectPath, 'package.json');
+  const packageJson = await fs.readJSON(packageJsonPath);
+  
+  const isDocker = feature.key === 'docker';
+
+  let scripts = {};
+
+  if (isDocker) {
+    scripts = getDockerScripts();
+  } else {
+    return;
+  }
+
+  const scriptsResult = mergeAdditive(packageJson.scripts ?? {}, scripts);
+  packageJson.scripts = scriptsResult.merged;
+
+  await fs.writeJSON(packageJsonPath, packageJson, { spaces: 2 });
+
+  const skipped = scriptsResult.skipped;
+  if (skipped.length > 0) {
+    print.info(`Kept existing package.json values for: ${skipped.join(', ')}`);
+  }
+  print.info('Updated package.json');
+}

package/lib/src/common/feature-registry.mjs

@@ -0,0 +1,11 @@
+// Single source of truth for the optional, additive features under templates/features
+export const FEATURES = [
+  {
+    key: 'docker',
+    cli: 'docker',
+  },
+];
+
+export function findFeatureByCli(cliName) {
+  return FEATURES.find((feature) => feature.cli === cliName);
+}