@nutin/cli 1.3.0 → 2.0.0

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

@@ -0,0 +1,136 @@
+import path from 'path';
+import * as fsExtra from 'fs-extra';
+import inquirer from 'inquirer';
+import { print } from '../utils/print.mjs';
+import { PACKAGE_VERSION as packageVersion, META_FILE_NAME } from '../common/package-data.mjs';
+import { readProjectMeta, updateProjectMeta } from '../common/project-meta.mjs';
+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 { UpdateContextBuilder } from './update-context-builder.mjs';
+import { TemplateDiffer } from './template-differ.mjs';
+
+const fs = fsExtra.default;
+const REPORT_FILE_NAME = 'NUTIN-UPDATE-REPORT.md';
+
+export class ProjectUpdater {
+  constructor() {
+    this.contextBuilder = new UpdateContextBuilder();
+    this.differ = new TemplateDiffer();
+  }
+
+  async updateProject(projectPath, options = {}) {
+    const { yes = false, from } = options;
+    const meta = await this.resolveMeta(projectPath);
+
+    if (this.isUpToDate(meta)) {
+      print.boldSuccess(`✅ Already up to date (nutin v${packageVersion}).`);
+      return;
+    }
+    this.assertUpdatable(meta);
+
+    print.boldHead(`\n🔄 Updating ${projectPath} from nutin v${meta.version} to v${packageVersion}...\n`);
+
+    const { templatesRoot: oldTemplatesRoot, cleanup } = await fetchOldTemplates(meta.version, { from });
+
+    try {
+      const changeSet = await this.computeChangeSet(projectPath, meta, oldTemplatesRoot);
+      await this.applyChangeSet(projectPath, meta, changeSet, { yes });
+    } finally {
+      await cleanup();
+    }
+  }
+
+  async resolveMeta(projectPath) {
+    const meta = (await readProjectMeta(projectPath)) ?? (await bootstrapProjectMeta(projectPath));
+    this.assertValidVersion(meta.version);
+    return meta;
+  }
+
+  // meta.version ends up interpolated into a shell command in fetchOldTemplates
+  // (npm pack), so it must be strictly numeric before anything downstream uses it —
+  // .nutin-meta.json is a plain project file that could be hand-edited or come from
+  // an untrusted clone.
+  assertValidVersion(version) {
+    if (typeof version !== 'string' || !/^\d+\.\d+\.\d+$/.test(version)) {
+      throw new Error(
+        `${META_FILE_NAME} has an invalid version "${version}" — expected a version in major.minor.patch format, e.g. "1.3.1". ` +
+        `Fix or delete ${META_FILE_NAME} and try again.`,
+      );
+    }
+  }
+
+  isUpToDate(meta) {
+    return compareVersions(meta.version, packageVersion) === 0;
+  }
+
+  assertUpdatable(meta) {
+    const comparison = compareVersions(meta.version, packageVersion);
+    if (comparison > 0) {
+      throw new Error(
+        `This project records nutin v${meta.version}, but the installed CLI is v${packageVersion}. ` +
+        'Install the latest nutin with "npm i -g @nutin/cli" before running nutin-update.',
+      );
+    }
+    if (parseVersion(meta.version).major !== parseVersion(packageVersion).major) {
+      throw new Error(
+        `nutin-update only handles minor/patch updates. Project is on v${meta.version}, installed CLI is ` +
+        `v${packageVersion} — that's a major version change. Please migrate manually (see the changelog).`,
+      );
+    }
+  }
+
+  async computeChangeSet(projectPath, meta, oldTemplatesRoot) {
+    const { oldContext, newContext } = await this.contextBuilder.buildContexts(projectPath, meta);
+    return this.differ.diff(projectPath, oldTemplatesRoot, oldContext, newContext);
+  }
+
+  async applyChangeSet(projectPath, meta, changeSet, { yes }) {
+    const { toUpdate, toAdd, conflicts, unknown, removedByUser, noLongerGenerated } = changeSet;
+    printUpdateSummary({ toUpdate, toAdd, conflicts, unknown, removedByUser, noLongerGenerated });
+
+    if (toUpdate.length === 0 && toAdd.length === 0 && conflicts.length === 0) {
+      print.boldSuccess('\n✅ Nothing to update.');
+      await updateProjectMeta(projectPath, { version: packageVersion });
+      return;
+    }
+
+    if (!yes && (toUpdate.length > 0 || toAdd.length > 0)) {
+      const { proceed } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'proceed',
+          message: `\nApply ${toUpdate.length + toAdd.length} safe file update(s)?`,
+          default: true,
+        },
+      ]);
+      if (!proceed) {
+        print.boldInfo('Aborted — no files were changed.');
+        return;
+      }
+    }
+
+    for (const { relPath, newEntry } of [...toUpdate, ...toAdd]) {
+      const outputPath = path.join(projectPath, relPath);
+      await fs.ensureDir(path.dirname(outputPath));
+      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}`);
+    }
+
+    await updateProjectMeta(projectPath, { version: packageVersion });
+
+    print.boldSuccess(`\n✅ Updated to nutin v${packageVersion}.`);
+  }
+}
+
+export const projectUpdater = new ProjectUpdater();
+
+export async function updateProject(projectPath, options = {}) {
+  return projectUpdater.updateProject(projectPath, options);
+}

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

@@ -0,0 +1,124 @@
+import path from 'path';
+import * as fsExtra from 'fs-extra';
+import { FileGenerator } from '../common/file-generator.mjs';
+
+const fs = fsExtra.default;
+
+function contentEquals(a, b) {
+  if (Buffer.isBuffer(a) || Buffer.isBuffer(b)) {
+    return Buffer.compare(Buffer.from(a), Buffer.from(b)) === 0;
+  }
+  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
+// or conflict-flag them.
+const FULLY_EXCLUDED_PATTERNS = [
+  /^config\/[^/]+\.json$/,
+  /^src\/app(\/|$)/,
+  /^src\/assets(\/|$)/,
+];
+
+// 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.
+const ADD_ONLY_PATTERNS = [
+  /^src\/styles(\/|$)/,
+];
+
+function toPosixPath(relPath) {
+  return relPath.split(path.sep).join('/');
+}
+
+function excludeUserOwnedPaths(oldTree, newTree) {
+  for (const relPath of new Set([...oldTree.keys(), ...newTree.keys()])) {
+    const posixPath = toPosixPath(relPath);
+    const fullyExcluded = FULLY_EXCLUDED_PATTERNS.some((re) => re.test(posixPath));
+    const preexistingAddOnly = ADD_ONLY_PATTERNS.some((re) => re.test(posixPath)) && oldTree.has(relPath);
+
+    if (fullyExcluded || preexistingAddOnly) {
+      oldTree.delete(relPath);
+      newTree.delete(relPath);
+    }
+  }
+}
+
+export class TemplateDiffer {
+  constructor() {
+    this.fileGenerator = new FileGenerator();
+  }
+
+  async diff(projectPath, oldTemplatesRoot, oldContext, newContext) {
+    const newTemplatesRoot = this.fileGenerator.getTemplatesRoot();
+
+    const [oldTree, newTree] = await Promise.all([
+      this.fileGenerator.collectTemplateTree(oldTemplatesRoot, oldContext),
+      this.fileGenerator.collectTemplateTree(newTemplatesRoot, newContext),
+    ]);
+
+    excludeUserOwnedPaths(oldTree, newTree);
+
+    const toUpdate = [];
+    const toAdd = [];
+    const conflicts = [];
+    const unknown = [];
+    const removedByUser = [];
+    const noLongerGenerated = [];
+
+    for (const relPath of new Set([...oldTree.keys(), ...newTree.keys()])) {
+      const oldEntry = oldTree.get(relPath);
+      const newEntry = newTree.get(relPath);
+
+      if (oldEntry && newEntry && contentEquals(oldEntry.content, newEntry.content)) {
+        continue;
+      }
+
+      const outputPath = path.join(projectPath, relPath);
+      const existsOnDisk = await fs.pathExists(outputPath);
+
+      if (!oldEntry) {
+        // Brand new file introduced in the new version — nothing to conflict with,
+        // unless something else already occupies that path
+        if (!existsOnDisk) {
+          toAdd.push({ relPath, newEntry });
+          continue;
+        }
+
+        const actualContent = newEntry.isBinary
+          ? await fs.readFile(outputPath)
+          : await fs.readFile(outputPath, 'utf8');
+        if (!contentEquals(actualContent, newEntry.content)) {
+          unknown.push({ relPath });
+        }
+        continue;
+      }
+
+      if (!newEntry) {
+        // Nutin no longer generates this file; leave it alone either way,
+        // but warn if it's still on disk since it may now be stale/broken.
+        if (existsOnDisk) {
+          noLongerGenerated.push({ relPath });
+        }
+        continue;
+      }
+
+      if (!existsOnDisk) {
+        removedByUser.push({ relPath });
+        continue;
+      }
+
+      const actualContent = oldEntry.isBinary
+        ? await fs.readFile(outputPath)
+        : await fs.readFile(outputPath, 'utf8');
+
+      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 });
+      }
+    }
+
+    return { toUpdate, toAdd, conflicts, unknown, removedByUser, noLongerGenerated };
+  }
+}

package/lib/src/update-app/update-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 as packageVersion } from '../common/package-data.mjs';
+
+const fs = fsExtra.default;
+
+export class UpdateContextBuilder {
+  async buildContexts(projectPath, meta) {
+    const packageJson = await fs.readJSON(path.join(projectPath, 'package.json'));
+    const packageManager = meta.packageManager ?? (await detectPackageManager(projectPath));
+
+    const baseContext = {
+      projectName: packageJson.name,
+      packageManager,
+      ...meta.features,
+      ciCommand: getCiCommand(packageManager),
+    };
+
+    return {
+      oldContext: { ...baseContext, version: meta.version },
+      newContext: { ...baseContext, version: packageVersion },
+    };
+  }
+}

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

@@ -0,0 +1,22 @@
+import { print } from '../utils/print.mjs';
+
+export function printUpdateSummary({ toUpdate, toAdd, conflicts, unknown, removedByUser, noLongerGenerated }) {
+  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`);
+  }
+  if (noLongerGenerated.length > 0) {
+    print.boldError(`  ${noLongerGenerated.length} file(s) nutin no longer generates — left in place, review manually:`);
+    noLongerGenerated.forEach(({ relPath }) => print.section(`    - ${relPath}`));
+  }
+  if (unknown.length > 0) {
+    print.section(`  ${unknown.length} file(s) have no baseline to compare against — left untouched:`);
+    unknown.forEach(({ relPath }) => print.section(`    - ${relPath}`));
+  }
+  if (removedByUser.length > 0) {
+    print.section(`  ${removedByUser.length} file(s) nutin used to generate but you removed — not recreated:`);
+    removedByUser.forEach(({ relPath }) => print.section(`    - ${relPath}`));
+  }
+}

package/lib/src/update-app/version-compare.mjs

@@ -0,0 +1,12 @@
+export function parseVersion(version) {
+  const [major, minor, patch] = version.split('.').map((n) => parseInt(n, 10) || 0);
+  return { major, minor, patch };
+}
+
+export function compareVersions(a, b) {
+  const va = parseVersion(a);
+  const vb = parseVersion(b);
+  if (va.major !== vb.major) return va.major - vb.major;
+  if (va.minor !== vb.minor) return va.minor - vb.minor;
+  return va.patch - vb.patch;
+}

package/lib/src/utils/print.mjs

@@ -0,0 +1,36 @@
+export const chalk = {
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  blue: (s) => `\x1b[34m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+  purple: (s) => `\x1b[35m${s}\x1b[0m`,
+  gray: (s) => `\x1b[90m${s}\x1b[0m`,
+  boldGreen: (s) => `\x1b[1;32m${s}\x1b[0m`,
+  boldRed: (s) => `\x1b[1;31m${s}\x1b[0m`,
+  boldBlue: (s) => `\x1b[1;34m${s}\x1b[0m`,
+  boldYellow: (s) => `\x1b[1;33m${s}\x1b[0m`,
+  boldCyan: (s) => `\x1b[1;36m${s}\x1b[0m`,
+  boldPurple: (s) => `\x1b[1;35m${s}\x1b[0m`,
+  boldGray: (s) => `\x1b[1;90m${s}\x1b[0m`,
+};
+
+export const print = {
+  head: (s) => console.info(`${chalk.purple(s)}`),  
+  boldHead : (s) => console.info(`${chalk.boldPurple(s)}`),
+  section: (s) => console.info(`${chalk.yellow(s)}`),
+  boldSection: (s) => console.info(`${chalk.boldYellow(s)}`),
+  info: (s) => console.info(`${chalk.green(s)}`),
+  boldInfo: (s) => console.info(`${chalk.boldGreen(s)}`),
+  success: (s) => console.log(`${chalk.cyan(s)}`),
+  boldSuccess: (s) => console.log(`${chalk.boldCyan(s)}`),
+  gray: (s) => console.info(`${chalk.gray(s)}`),
+  boldGray: (s) => console.info(`${chalk.boldGray(s)}`),
+  blue: (s) => console.info(`${chalk.blue(s)}`),
+  boldBlue: (s) => console.info(`${chalk.boldBlue(s)}`),
+  error: (s) => console.error(`${chalk.red(s)}`),
+  boldError: (s) => console.error(`${chalk.boldRed(s)}`),
+  grayError: (s) => console.error(`${chalk.boldGray(s)}`),
+  warn: (s) => console.warn(`${chalk.yellow(s)}`),
+  debug: (s) => console.debug(`${chalk.gray(s)}`),
+}

package/lib/src/utils/promise-exec-alias.mjs

@@ -0,0 +1,4 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+export const promiseExec = promisify(exec);

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@nutin/cli",
-  "version": "1.3.0",
-  "description": "Build SPAs by understanding SPAs. A minimal frontend toolkit crafted for learning and lean applications.",
+  "version": "2.0.0",
+  "description": "The structure of a framework. The freedom of vanilla.",
   "preferGlobal": true,
   "main": "lib/index.mjs",
   "bin": {
+    "cli": "./bin/cli.mjs",
+    "nutin": "./bin/cli.mjs",
     "create-nutin-app": "./bin/create-app.mjs",
-    "nutin-new": "./bin/create-app.mjs"
+    "nutin-new": "./bin/create-app.mjs",
+    "nutin-add": "./bin/add-feature.mjs",
+    "nutin-update": "./bin/update-app.mjs"
   },
   "scripts": {
     "patch": "npm version patch -m 'CI/CD: Bump version to %s'",
@@ -16,24 +20,25 @@
     "publish": "npm publish --access public"
   },
   "keywords": [
-    "nutin",
-    "Frontend",
-    "SPA",
-    "Learning",
-    "Minimalist",
-    "Lighweight",
-    "Customizable"
+    "Nutin",
+    "Vanilla",
+    "Framework",
+    "Freedom",
+    "Structure",
+    "Ownership"
   ],
   "author": "Loïs Kouninef <loiskouninef@gmail.com>",
   "license": "MIT",
   "dependencies": {
     "commander": "^9.0.0",
+    "diff": "^9.0.0",
     "fs-extra": "^11.0.0",
     "handlebars": "^4.7.8",
-    "inquirer": "^9.0.0"
+    "inquirer": "^9.0.0",
+    "tar": "^7.5.22"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "repository": {
     "type": "git",

package/templates/base/.gitignore.hbs

@@ -7,6 +7,11 @@ pnpm-debug.log*
 
 /dist/
 /dist-build/
+/coverage/
+
+# Generated by "validate-docker" (run via docker:build) from tools/docker/*.template — only present when the docker feature is added
+/tools/docker/Dockerfile
+/tools/docker/nginx.conf
 
 .DS_Store
 .DS_Store?
@@ -40,4 +45,4 @@ Desktop.ini
 .vscode-test
 
 tmp/
-temp/
+temp/

package/templates/base/AGENTS.md.hbs

@@ -0,0 +1,169 @@
+# Working on this project
+
+This project was generated with Nutin {{version}}.
+
+## Architecture
+
+```
+src/
+  app/            application code (components, views, services)
+  core/           Nutin framework internals — see "Nutin" section before editing
+  styles/         project-level Sass
+config/           i18n (languages.json) and SEO configuration
+tools/            builder, dev server, generator, testin-nutin runner, docker (optional)
+nutin.config.js   build/feature config — see below
+.nutin-meta.json  Nutin version, package manager, enabled features (source of truth for what's installed)
+```
+
+## Conventions
+
+- Favor small, composable components.
+- One `View` = one route.
+- Import everything from barrel files (`core/index.js`, `components/index.js`, `views/index.js`, `services/index.js`) — do not deep-import.
+
+## Commands
+
+- Serve: `{{packageManager}} run serve` (build + serve), `{{packageManager}} run serve:only` (no rebuild), `{{packageManager}} run dev` (watch mode).
+- Build: `{{packageManager}} run build` (dev) or `{{packageManager}} run build:prod` (production).
+- Generate: `{{packageManager}} run generate ELEMENT ELEMENT_NAME` (`ELEMENT` = `component`/`view`/`service`, supports nested paths, updates the nearest `index.ts` barrel).
+- Test: `{{packageManager}} run testin-nutin` (build + run), `{{packageManager}} run testin-nutin:only` (no rebuild), `{{packageManager}} run testin-nutin:watch`.
+
+## Base classes
+
+```
+Service<T>          — app-wide singleton (router, event bus, i18n, http client, pipe registry, app-specific services)
+BaseComponent<T>     — render/destroy engine, data-* parsing, children
+├── Component        — reusable, non-routed UI; config/props + data-bind
+└── View              — one per route; mounted/unmounted by the Router
+```
+
+- `render()`: `onBeforeRender()` → sanitize + set `innerHTML` → mount children (`data-component`/`data-catalog`) → parse `data-i18n`/`data-pipe` → bind `data-event` listeners → `onAfterRender()`. Runs in full on every `render()` call — no virtual DOM/diffing.
+- `destroy()`: unbinds events, unsubscribes bus listeners, destroys children, removes the element.
+- `Service`: direct `new` throws — always use `MyService.getInstance()` (or the exported const). Auto-binds all methods to the instance. `registerCleanup(fn)` for teardown; `Service.destroyAll()` runs on `beforeunload`.
+- Overridable hooks (all no-op by default): `onBeforeRender`, `onAfterRender`, `onBeforeDestroy`, `onAfterDestroy`, `generateTemplate()`, `registerChildren()`. `View` adds router-only `onEnter()`/`onExit()`.
+
+## Children components
+
+- Override `registerChildren(): ComponentConfig[]` to declare children — matched against `[data-component="selector"]` elements in the rendered template. ComponentConfig: `{ selector: 'my-selector', factory: (el) => new MyComponent(el, {...} )}`.
+- For repeated lists, use the inherited `createCatalogComponents({ items, elementName, selector, component })` inside `registerChildren()` instead of hand-writing one entry per item — targets `[data-catalog="selector"]`.
+
+## `data-*` attributes
+
+| Attribute | Purpose |
+|---|---|
+| `data-event="event:handler[:args]"` | Declarative event binding, see below. |
+| `data-i18n="key"` | Sets translated text/placeholder via `I18nService`. |
+| `data-pipe="name[:args]\|name2..."` | Pipes value/text through registered pipes, chainable with `\|`. |
+| `data-pipe-source="..."` | Overrides the raw value fed into `data-pipe`. |
+| `data-optional` | Removes the element post-render if it ends up empty (tag-specific check: `src`/`value`/`textContent`). |
+| `data-component="selector"` | Child component mount point, from `registerChildren()`. |
+| `data-catalog="selector"` | Repeated-children mount point, from `createCatalogComponents()`. |
+| `data-bind="propKey"` | `Component`-only two-way field binding; read back with `getValues()`. |
+
+## DOM events binding
+
+Handlers are (re-)bound on every `render()`, not at build time. Always use private methods prefixed with underscore:
+
+```html
+<div data-event="event:_myFunction:@value,@id">
+```
+```ts
+private _myFunction(value: string, id: string) { doStuff() }
+```
+
+Tokens: `@value`, `@id`, `@class`, `@textContent`, `@event`, `@target`, `@attr:name`, `@dataset:key`, plus string/number literals.
+
+## Core services
+
+- `AppEventBus` — `subscribe`/`once`/`emit`/`off`. Inside a component, prefer `this.listen(event, cb)` (auto-unsubscribes on `destroy()`) or `this.listenToRenderEvents([event1, event2, ...])` (re-runs `this.render()` whenever any of the given events fire) over calling the bus directly. Typed facades — each `on*` subscriber returns a closure you call directly to unsubscribe (`const off = Navigation.onNavigate(cb); ...; off();`), no need to keep the original callback reference around for `off()`:
+  - `Navigation` — `navigateTo(path)`/`onNavigate`, `reload()`/`onReload`.
+  - `Lifecycle` — `viewMount(viewName)`/`onViewMount`, `viewUnmount(viewName)`/`onViewUnmount`, plus generic `beforeRender`/`afterRender`/`beforeDestroy`/`afterDestroy`.
+- `AppRouter(routes)` — call once in `main.ts`; routes support `:param`/`:param?` and per-route guards.
+- `registerGlobals({ before?, after? })` — each entry is `{ component, id }` (a bare class, constructed internally); mounts them outside `<main id="app">` (`before`/`after` control placement relative to it), stamping each root element with `id`. `hideGlobals(ids)`/`revealGlobals(ids)` (same module) toggle visibility by those ids from any component or view. Call once in `main.ts`.
+- `AppHttpClient` — `get/post/put/patch/delete<T>(endpoint, data?, config?)`; non-OK responses throw `HttpError`.
+- `I18nService` — `translate(key, fallback?)`, `setCurrentLanguage(lang)`; language list comes from `config/languages.json`.
+- `AppPipeRegistry` — `register(name, fn)` / `apply(name, value, args)`; backs `data-pipe`.
+
+## Styling
+
+- Sass is the primary styling system; Tailwind is optional (`nutin.config.js`'s `tailwind` flag).
+- Naming convention: `.my-element__my-class`.
+
+## Pipes
+
+```
+// currency
+AppPipeRegistry.register('currency');
+    
+// date
+AppPipeRegistry.register('date');
+
+// number (toFixed)
+AppPipeRegistry.register('number');
+
+// string pipes
+AppPipeRegistry.register('uppercase');
+AppPipeRegistry.register('lowercase');    
+AppPipeRegistry.register('capitalize');
+AppPipeRegistry.register('capitalizeAll');
+AppPipeRegistry.register('truncate');
+    
+// utility pipes
+AppPipeRegistry.register('default');
+AppPipeRegistry.register('json');
+```
+
+## Configuration
+
+### `nutin.config.js`
+
+Central options/tools config (see the inline comments for details):
+- `i18n`, `tailwind`, `generateSEO`, `dockerPorts` — top-level feature toggles (`dockerPorts` only applies once the docker feature is added).
+- `generator.{generateStylesheet, generateLocales, generateTest}` — what the generator scaffolds alongside new elements.
+- `builder.{sass.paths, esbuild}` — build pipeline behavior.
+- `testinNutin.{includeFramework, includeTools, includeApp, jsdomOptions}` — test discovery/environment.
+
+### `config/seo.json`
+
+Consumed by builder (production only) to generate static HTML per route. Unused if `nutin.config.js -> generateSEO` is disabled.
+
+### `config/languages.json`
+
+Consumed by i18nService and builder. Unused if i18n is disabled.
+
+## Security
+
+`SecurityHelper.sanitizeTemplate()` runs on every `render()` before `innerHTML` is set — `trustLevel` (`'strict' | 'normal' | 'trusted'`, default `'normal'`) controls how much is stripped (`<script>`/inline handlers always; `<iframe>`/`javascript:`/`data:` under `strict` only). Use `SecurityHelper.escapeHtml()` when manually interpolating strings into templates.
+
+## Testing (testin-nutin)
+
+Nutin's own hand-built test runner + jsdom - not Jest. `describe`/`it` only (**no `test()` alias**), `beforeAll`/`beforeEach`/`afterEach`/`afterAll` (one of each per suite, no stacking - inside `describe` statement, not top-level). All globals — no imports needed in test files.
+
+- Matchers: `toBe`, `toEqual`, `toContain`, `toBeTruthy`/`toBeFalsy`, `toBeDefined`/`toBeUndefined`, `toBeInstanceOf`, `toHaveBeenCalled`/`toHaveBeenCalledWith`, `toBeLessThan`/`toBeGreaterThan`, `toThrow` — each has a `.not` counterpart.
+- `spyOn(obj, 'method')` returns `.calls`/`.callCount`/`.lastCall`, `.andCallFake(fn)`/`.andReturn(v)`, `.restore()` — unlike mocks, calls pass through by default.
+- `tools/testin-nutin/mocks/` has ready-made `MockEventBus`/`MockHttpClient`/`MockI18n`/`MockRouter` for constructor injection.
+- `useFakeTimers()`/`useRealTimers()`/`advanceTimersByTime(ms)`/`runAllTimers()` for time-dependent code.
+- Test discovery/scope controlled by `nutin.config.js`'s `testinNutin.includeApp`/`includeFramework`.
+
+## Nutin
+
+Nutin provides the project tooling, build pipeline and generated structure. Its source code lives in `src/core/`.
+
+Tests are an important source of documentation. They describe expected behavior and should be consulted before modifying existing functionality.
+Before changing existing functionality, inspect the corresponding tests.
+When adding behavior, add or update tests.
+
+When modifying Nutin `core/` files:
+
+1. Explore the alternatives: is modifying Nutin core files the best approach long-term? Always ask for validation.
+2. Check the corresponding Nutin documentation and tests.
+3. Preserve existing conventions.
+4. Inspect existing implementations before creating new abstractions.
+5. Reuse existing utilities/helpers where appropriate.
+6. Do not rewrite generated configuration unnecessarily.
+7. Keep changes focused on the requested feature.
+8. Run tests.
+
+## Documentation
+
+[Nutin Documentation](https://github.com/LoisKOUNINEF/nutin/tree/main/docs)