lakutata 3.0.0 → 3.1.0

package/doc/en/Overview.md

@@ -1,82 +1,27 @@
 # Lakutata Overview
 
-**Lakutata** is an IoC-based application framework for Node.js and TypeScript: one programming model for web
-services, CLI tools, desktop (Electron) applications and embedded devices. An application is a tree of objects created
-by a container (components, providers, modules, controllers), whose options and inputs are validated by DTOs, and whose
-controllers are served by transports: HTTP (Express, Fastify), CLI (Commander), service RPC (HTTP, Socket.IO,
-JSON-RPC 2.0, gRPC, NATS, Electron IPC) and schedules. One controller method can be all of them at once.
+**Lakutata** is an IoC application framework for Node.js and TypeScript. It gives web services, CLI tools, desktop
+(Electron) applications and embedded devices one programming model: an application is a tree of objects (components,
+providers, controllers) that a container creates. DTOs validate their options and inputs, and transports expose
+the controllers: HTTP (Express, Fastify), CLI (Commander), service RPC (HTTP, Socket.IO, JSON-RPC 2.0, gRPC, NATS,
+Electron IPC), schedules and message queues. One controller method can serve all of them at once.
 
 The package `lakutata` re-exports the `@lakutata/*` packages under its subpaths (see the table below) and presets two
-components in every application: `log` (the pino `Logger`) and `entrypoint` (the `Entrypoint` that serves the
-controllers).
+components in every application: `log` (the `Logger`, which writes pino-compatible JSON lines) and `entrypoint` (the
+`Entrypoint` that serves the controllers).
 
-## Requirements
+## Where to start
 
-- Node.js 22 or later.
-- ESM (`"type": "module"`); the package also ships CommonJS builds.
-- TypeScript with `experimentalDecorators` and `emitDecoratorMetadata`. The package publishes the compiler options the
-  framework needs as `lakutata/tsconfig.json`.
-
-## Installation
-
-```bash
-npx @lakutata/cli create --name my-app   # a new project from a template (web, service, CLI, Electron…)
-npm install lakutata                      # or the framework in an existing project
-```
-
-```json
-{
-  "extends": "lakutata/tsconfig.json",
-  "compilerOptions": {"rootDir": "src", "outDir": "dist"}
-}
-```
-
-The transports and the integrations use optional peer dependencies, installed when used: `express` or `fastify`,
-`commander`, `socket.io`, `ws`, the database drivers (`pg`, `mysql2`, `sqlite3`…), the cache stores (`redis`…).
-
-## A first application
-
-```typescript
-import {Application, DTO, type ILogger} from 'lakutata'
-import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
-import {GET, ServiceAction} from 'lakutata/decorator/ctrl'
-import {Expect} from 'lakutata/decorator/dto'
-import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
-
-class GreetDTO extends DTO {
-    @Expect(DTO.String().optional().default('world'))
-    public name: string
-}
-
-class GreetController extends Controller {
-    //GET /greet?name=you, and the service action {cmd: 'greet', name: 'you'}
-    @GET('/greet', GreetDTO)
-    @ServiceAction({cmd: 'greet'}, GreetDTO)
-    public async greet(input: GreetDTO): Promise<{ message: string }> {
-        return {message: `Hello, ${input.name}!`}
-    }
-}
-
-Application
-    .run(() => ({
-        id: 'com.example.greeter',
-        name: 'Greeter',
-        components: {
-            entrypoint: buildEntrypoints({
-                controllers: [GreetController],
-                http: expressHTTPEntrypoint({port: 8080})
-            })
-        },
-        bootstrap: ['entrypoint']
-    }))
-    .onLaunched((app: Application, log: ILogger): void => log.info('%s started', app.appName))
-```
+[GettingStarted](GettingStarted.md) creates a first project from a template and shows a first application;
+[ProjectStructure](ProjectStructure.md) describes the files of a project; the guides below cover each part of the
+framework. The [examples](examples/README.md) build whole applications from the templates: a REST API, a command line
+tool, a web and a desktop application, calls between services, background jobs, an MCP server and a service on a device.
 
 ## The subpaths
 
 | Subpath | What it provides |
 |---|---|
-| `lakutata` | `Application`, `Module`, `Component`, `Provider`, `BaseObject`, `Container`, `DTO`, `Exception`, `Time`, `isPackaged`, `resourcesPath`, the validation messages |
+| `lakutata` | `Application`, `Component`, `Provider`, `BaseObject`, `Container`, `DTO`, `Exception`, `Time`, `isPackaged`, `resourcesPath`, the validation messages |
 | `lakutata/decorator/di` | `@Inject`, `@Configurable`, `@Autoload`, `@Singleton`, `@Scoped`, `@Transient`, `@Lifetime` |
 | `lakutata/decorator/dto` | `@Expect`, `@Accept`, `@Return`, `@IndexSignature` |
 | `lakutata/decorator/asst` | `@Before`, `@After` |
@@ -86,38 +31,70 @@ Application
 | `lakutata/adapter/express`, `lakutata/adapter/fastify` | The HTTP transports |
 | `lakutata/adapter/commander` | The CLI transport |
 | `lakutata/adapter/socket.io`, `lakutata/adapter/jsonrpc`, `lakutata/adapter/electron` | The service transports |
-| `lakutata/com/logger` | The `Logger` component (pino), preset as `log` |
+| `lakutata/com/logger` | The `Logger` component, preset as `log` (pino-compatible JSON lines) |
 | `lakutata/orm`, `lakutata/decorator/orm` | TypeORM and its decorators |
 | `lakutata/com/database`, `lakutata/provider/database` | The `Database` component and provider |
 | `lakutata/com/cacher` | The `Cacher` component |
 | `lakutata/com/mutex` | The `Mutex` component, `@Synchronized` |
+| `lakutata/com/queue` | The `Queue` component, `@QueueAction`, `queueEntrypoint` |
 | `lakutata/com/i18n` | The `I18n` component, the `Translator`, the language middleware |
 | `lakutata/com/docker` | The `Docker` component |
 | `lakutata/com/containerd` | The `Containerd` component |
-| `lakutata/com/monitor` | The CPU, memory, event loop and HTTP monitors |
+| `lakutata/com/monitor` | CPU, memory, event loop and HTTP monitors |
 | `lakutata/security`, `lakutata/provider/passwordHash` | Hashing, ciphers, signatures, the `PasswordHash` provider |
 | `lakutata/utils` | The helper functions |
 
-Outside this package: `@lakutata/cli` (the `lakutata` command: projects, bundles, executables, migrations),
-`@lakutata/grpc` (gRPC client, server and service transport), `@lakutata/nats` (NATS component and service transport),
-`@lakutata/dbus` (D-Bus) and `@lakutata/mcp` (the Model Context Protocol).
+Not part of this package: `@lakutata/cli` (the `lakutata` command for creating projects, running migrations and packing
+applications, see [Command](Command.md)), `@lakutata/grpc` (a gRPC client, server and service transport),
+`@lakutata/nats` (a NATS component and service transport), `@lakutata/dbus` (D-Bus) and `@lakutata/mcp` (the Model
+Context Protocol).
 
 ## The guides
 
 | Guide | Topic |
 |---|---|
-| [Core](Core.md) | The application, the container, the lifetimes, dependency injection, modules, the lifecycle |
-| [DTOValidation](DTOValidation.md) | DTOs, the schemas, the validation of the options, inputs and results |
-| [Decorator](Decorator.md) | The decorators of each subpath |
-| [ActionPattern](ActionPattern.md) | The controllers, their actions and their transports (HTTP, CLI, services, schedules) |
-| [ORMIntegration](ORMIntegration.md) | The `Database` component and TypeORM |
-| [I18n](I18n.md) | The messages of each language |
-| [Mutex](Mutex.md) | The locks between the instances and the processes |
+| [GettingStarted](GettingStarted.md) | Requirements, creating a project, adding Lakutata to an existing project, a first application |
+| [ProjectStructure](ProjectStructure.md) | The files, scripts and features of the projects made from the templates, and templates of your own |
+| [UpgradingFrom2](UpgradingFrom2.md) | Upgrading a project from Lakutata 2.x (the package `lakutata` 2.x) |
+| [UpgradingFrom1](UpgradingFrom1.md) | Porting a project from Lakutata 1.x (`@lakutata/core` 1.x and the `@lakutata-module/*`, `@lakutata-component/*` packages) |
+| [Application](Application.md) | The application: its options, the fluent API, the lifecycle, the mode, packed applications |
+| [Objects](Objects.md) | Components, providers and their container: lifetimes, scopes, creation and teardown, a container without an application |
+| [Injection](Injection.md) | Dependency injection, the options of objects, sharing features between applications |
+| [DTOValidation](DTOValidation.md) | DTOs and schemas: validating options, inputs and results |
+| [Exceptions](Exceptions.md) | Declaring exceptions, their messages, what the clients receive, the exceptions of the framework |
+| [Logger](Logger.md) | The `log` component: writing lines, readable lines or JSON, destinations, another logger |
+| [Decorator](Decorator.md) | The decorators, by subpath |
+| [Time](Time.md) | The `Time` class |
+| [HelperFunctions](HelperFunctions.md) | The helper functions of `lakutata/utils` |
+| [Controllers](Controllers.md) | Controllers and actions: their addresses, input and results, prefixes, inheritance |
+| [Entrypoint](Entrypoint.md) | The entrypoint component: its options and adapters, starting and stopping, the list of the actions |
+| [Middlewares](Middlewares.md) | The middlewares and the access control of the actions |
+| [HTTP](HTTP.md) | The HTTP adapters: routes, input, responses, errors, the features of Express and Fastify |
+| [CLI](CLI.md) | Command line tools: commands, options, prompts, output and exit codes |
+| [ServiceCalls](ServiceCalls.md) | The service actions over HTTP, Socket.IO, JSON-RPC 2.0 and Electron: patterns, responses, clients and their events |
+| [GRPC](GRPC.md) | The service actions over gRPC (`@lakutata/grpc`), and calling them from other applications and languages |
+| [NATS](NATS.md) | The NATS component, the service actions over NATS (`@lakutata/nats`), the service proxies and their events |
+| [Schedules](Schedules.md) | Scheduled jobs: intervals, cron expressions, jobs run by one instance |
+| [Queue](Queue.md) | The message queues: producers, `@QueueAction` consumers, retries, dead letters, results |
+| [Database](Database.md) | The `Database` component and provider, the connection options, several databases |
+| [DatabaseDrivers](DatabaseDrivers.md) | The database drivers, one by one: what to install, their options, their limits |
+| [MongoEmbedded](MongoEmbedded.md) | A MongoDB inside the application, its documents in files |
+| [Entities](Entities.md) | The entities, the queries, the transactions and the errors |
+| [Migrations](Migrations.md) | Writing, generating and running the migrations |
+| [Cache](Cache.md) | The `Cacher` component: `wrap()`, the stores and their tiers, what they keep |
+| [Mutex](Mutex.md) | Locks shared between processes and instances |
+| [I18n](I18n.md) | Messages in several languages |
 | [DockerIntegration](DockerIntegration.md) | The `Docker` component |
 | [ContainerdIntegration](ContainerdIntegration.md) | The `Containerd` component |
+| [Monitor](Monitor.md) | The CPU, memory, event loop and HTTP request monitors |
 | [Security](Security.md) | Hashing, ciphers, signatures, passwords |
-| [Time](Time.md) | The `Time` class |
-| [HelperFunctions](HelperFunctions.md) | The helper functions of `lakutata/utils` |
-
-Each `@lakutata/*` package has its own README, and the typings of each subpath document every declaration with
-examples.
+| [DBus](DBus.md) | A D-Bus service and client (`@lakutata/dbus`): methods, objects, properties, signals |
+| [MCP](MCP.md) | The tools, resources and prompts of the Model Context Protocol (`@lakutata/mcp`), over stdio and HTTP |
+| [Command](Command.md) | The `lakutata` command: creating projects, migrations, translations, environment variables |
+| [Workspaces](Workspaces.md) | Projects of several packages: running their scripts, giving them a version, adding packages |
+| [NativeAddons](NativeAddons.md) | Native addons in C++ or Rust: creating them, linking libraries, shipping them |
+| [Packaging](Packaging.md) | Bundles and executables, and what a packed application reads at run time |
+| [Installers](Installers.md) | The installers of each platform, services, installer scripts, signing |
+
+Each `@lakutata/*` package has its own README, and the type declarations of every subpath document each export with an
+example.

package/doc/en/Packaging.md

@@ -0,0 +1,193 @@
+# Lakutata Packaging
+
+A compiled application can be shipped without its `node_modules`, in three forms:
+
+- a **bundle**: one JavaScript file that Node.js runs;
+- an **executable**: one program that runs without Node.js installed;
+- **installers**: the packages of the system (deb, rpm, pkg, msi…) that install the executable, put its program in the
+  PATH and can register it as a service ([Installers](Installers.md)).
+
+`lakutata package bundle`, `package exe` and `package installer` make them with `@lakutata/builder`, which the project
+installs (`npm install --save-dev @lakutata/builder`; the templates that pack their application already have it).
+
+## 1. What is packed
+
+- **The compiled application**: the output of `tsc` (which emits the metadata of the decorators), not the TypeScript
+  sources, so build it first. The entry is `--entry`, else the `main` of the `package.json`, else `build/App.js`.
+- **Its dependencies**, bundled by esbuild into one file, except the native addons and the files read by path
+  (sections 3 and 4). The packages of the framework, and those built on it, are always bundled, so that there is one
+  copy of the framework, of its classes and of its container.
+- **CommonJS**: the bundle is a CommonJS file, so the application cannot use top-level `await`; await inside an async
+  function instead.
+- **Optional dependencies** that are not installed (the drivers of the stores the application does not use) are left
+  out: loading one throws at run time, as it would without the bundle.
+- **Resources**: the other files the application reads at run time (the built pages of a web interface, templates,
+  data) are declared in its `package.json` (section 6).
+
+## 2. Bundles
+
+```bash
+npm run build
+npx lakutata package bundle      # dist/<name>.cjs
+node dist/greet.cjs
+```
+
+```
+✔ dist/greet.cjs (1.1 MB): node dist/greet.cjs
+✔ dist/greet.native: the native addons (better-sqlite3) and the scripts run on their own (build/child.js), distributed with the bundle
+✔ dist/greet.resources: the resources (texts), distributed with the bundle
+```
+
+The name is the first `bin` of the `package.json`, else the name of the package without its scope. When needed, two
+directories are written next to the bundle and must be shipped with it: `dist/<name>.native/` (native addons, scripts
+run on their own, files read by path) and `dist/<name>.resources/` (the resources). The bundle runs from any
+directory, once moved with them.
+
+| Option | Meaning |
+|---|---|
+| `--entry <file>` | The compiled entry |
+| `--outfile <file>` | The bundle, `dist/<name>.cjs` by default |
+| `--no-minify` | Do not minify the bundle (the names of the classes are kept either way) |
+| `--external <modules...>` | Modules left out of the bundle, loaded at run time from a `node_modules` next to it |
+
+## 3. Native addons
+
+The packages holding `.node` files (better-sqlite3, the addons of the workspace made by
+[`lakutata add --native`](NativeAddons.md)), and the packages that load them through computed paths (sharp), cannot be
+bundled. They are left out, and laid out as in `node_modules` in `dist/<name>.native/`, with what they load at run time:
+
+- all their files, and those of the packages of the shared libraries their addons link (such as the libvips of sharp),
+  but not their C and C++ sources and objects (better-sqlite3 holds the sources of SQLite), nor what built them (the
+  files of node-gyp and of CMake in `build/`, the `target` directory of cargo, the static and import libraries);
+- the JavaScript they load;
+- the addons of the application itself (`createRequire(import.meta.url)('./x.node')`).
+
+The type declarations, source maps, TypeScript sources and documentation of the packages are left out. An addon is
+built for the platform and the architecture of the machine, and needs the system libraries it was built for, so pack
+the application of each platform on that platform.
+
+## 4. Files read by path
+
+The bundle is not where the modules were: a script started on its own (a worker, a child process of `fork()`) or a
+file the application reads (`defaults.json`, a directory of schemas) would not be found next to it. The tool finds the
+paths built from the location of a module, in the modules of the application and in those of its packages, and
+rewrites them to point into `dist/<name>.native/`:
+
+| Path | |
+|---|---|
+| `new URL('./worker.js', import.meta.url)` | Also `pathToFileURL(__filename)` |
+| `path.join(import.meta.dirname, 'child.js')`, `path.resolve(__dirname, '../schema')` | Also with `path.dirname(fileURLToPath(import.meta.url))` |
+| `__dirname + '/worker.js'`, `` `${__dirname}/worker.js` `` | |
+| `require.resolve('./worker')` | The extension is found as Node.js finds it |
+| `` path.join(__dirname, 'locales', `${lang}.json`) `` | Partly known: every file its pattern matches is shipped |
+
+| The path names | |
+|---|---|
+| A script (`.js`, `.cjs`) | Bundled on its own, with what it loads |
+| Another file, a directory of data | Copied |
+| A directory that holds the module (`path.join(__dirname, '..')`: the application, its package) | Not shipped, with a warning: declare its files as resources |
+| A directory that holds scripts or packages (`package.json`, `node_modules`) | Not shipped, with a warning: its scripts would need their packages at run time |
+| Nothing yet (a directory the application creates) | Left as it is |
+
+```typescript
+import {fork} from 'node:child_process'
+import {readFileSync} from 'node:fs'
+import path from 'node:path'
+
+//Both are shipped: the script bundled on its own, the file copied
+fork(path.join(import.meta.dirname, 'child.js'), ['one', 'two'])
+const defaults: Record<string, unknown> = JSON.parse(readFileSync(new URL('./defaults.json', import.meta.url), 'utf8'))
+```
+
+The tool warns, with the file and the line, of what it cannot follow in the modules of the application: a worker whose
+path is known only at run time (`new Worker(file)`) or relative to the current directory (`new Worker('./worker.js')`),
+and a script that the application also imports (it would be bundled twice, with two copies of its module). Build these
+paths from the directory of their module, or ship the files as resources.
+
+## 5. Executables
+
+```bash
+npx lakutata package exe                   # dist/<name> (dist/<name>.exe on Windows), with Node.js
+npx lakutata package exe --runtime bun     # with Bun
+```
+
+```
+› Node.js v24.11.1 embedded
+› Resources embedded, extracted at the first run: texts
+› Scripts run on their own embedded, extracted at the first run: build/child.js
+✔ dist/greet (darwin-arm64, 112.9 MB)
+```
+
+An executable is made for the platform it is made on. Make the executables of the other platforms on those platforms,
+as their native addons are built there: a CI matrix of Linux, macOS and Windows machines, or a container of the
+architecture for Linux (`docker run --platform linux/arm64`); the README of the `cli` template shows both.
+
+| Option | Meaning |
+|---|---|
+| `--runtime node` (default) | The bundle is embedded in a copy of the Node.js running the tool (a single executable application of Node.js): about 110 MB on macOS arm64 |
+| `--runtime bun` | The bundle is compiled by Bun (the `bun` package of the project, else the `bun` of the system): about 70 MB on macOS arm64, and it starts faster; the runtime is then Bun |
+| `--layout file` (default) | One file: the native addons, the files read by path and the resources are embedded, and extracted when it starts |
+| `--layout directory` | `dist/<name>/` holds the executable, `native/` and `resources/`, loaded from there without extraction (the installers use it) |
+| `--outdir <directory>` | Where the executable is written, `dist` by default |
+| `--entry`, `--no-minify`, `--external` | As for a bundle |
+
+- **Extraction**: an executable of the file layout extracts what it embeds at its first run, into its cache directory,
+  in a directory named after the content, so each version extracts once: `~/Library/Caches/<name>` on macOS,
+  `%LOCALAPPDATA%\<name>\Cache` on Windows, `$XDG_CACHE_HOME/<name>` or `~/.cache/<name>` on Linux, or the directory
+  given by `LAKUTATA_NATIVE_DIR`. When the cache directory cannot be written, it uses `<name>` in the temporary
+  directory (not when `LAKUTATA_NATIVE_DIR` is given).
+- **Native addons**: Bun loads the addons of Node-API, but may not load those built on the V8 API of Node.js: an
+  executable of Bun warns of them, and fails when it loads such a package (better-sqlite3, for example). On Alpine
+  (musl), the executables of Node.js do not load native addons: make them with Bun.
+- **External modules**: the `--external` modules are loaded from a `node_modules` next to the executable.
+- **Child processes**: an executable started for one of its scripts (`fork(path.join(import.meta.dirname, 'child.js'))`)
+  runs that script, in both layouts, with its arguments. With Node.js, `require.main` is that script, as in Node.js;
+  with Bun, it is not.
+- **No `.env`**: the executables do not load the `.env` of the directory they run in; use `LAKUTATA_ENV_FILE`
+  (section 6).
+- **Icon and signature**: `lakutata.icon` in the `package.json` (a square PNG of 256 px or more) becomes the icon of the
+  Windows executables. The executables of macOS are signed ad hoc. The ones of Windows made with Node.js keep the
+  signature of `node.exe`, which no longer matches: sign them (signtool) before distributing them.
+
+## 6. At run time
+
+The resources are declared as a list of `{from, to}` objects in `lakutata.resources`: `from` is a file or a directory
+of the project (it may be outside the package, such as `../ui/dist`), `to` its path among the resources.
+
+```json
+{
+  "lakutata": {
+    "resources": [{"from": "../ui/dist", "to": "ui"}]
+  }
+}
+```
+
+`isPackaged()` and `resourcesPath()` (from `lakutata`) tell the application how it runs:
+
+| How it runs | `isPackaged()` | `resourcesPath()` |
+|---|---|---|
+| Not packed (`node build/App.js`, `electron .`) | `false` | `undefined` |
+| A bundle | `true` | `dist/<name>.resources` next to the bundle |
+| An executable, file layout | `true` | The directory the resources were extracted to |
+| An executable, directory layout, or an installed application | `true` | `resources` next to the executable |
+| A packaged Electron application | `true` | `main.resources` in the resources of Electron |
+
+`resourcesPath()` returns the path even when the application declares no resources, so the directory may not exist.
+The application chooses where to read its files from:
+
+```typescript
+import {createRequire} from 'node:module'
+import path from 'node:path'
+import {resourcesPath} from 'lakutata'
+
+const resources: string | undefined = resourcesPath()
+//The built pages of the "ui" package of the workspace: among the resources when packed, in its dist directory otherwise
+const ui: string = resources ? path.join(resources, 'ui') : path.join(path.dirname(createRequire(import.meta.url).resolve('ui/package.json')), 'dist')
+```
+
+Every packed form loads the environment file named by `LAKUTATA_ENV_FILE` before the application starts: its lines
+`NAME=value` or `NAME="value"`, and comments (`#`). Its values replace the variables already set.
+
+```bash
+LAKUTATA_ENV_FILE=/etc/greet.env ./greet
+```

package/doc/en/ProjectStructure.md

@@ -0,0 +1,124 @@
+# Lakutata Project Structure
+
+This page describes the projects that `lakutata create` makes: the files of the `default` template, the workspaces of
+the other templates, their scripts and their optional features, and how to make a template of your own.
+
+## 1. The default template
+
+```
+my-app/
+  package.json
+  tsconfig.json
+  README.md
+  .gitignore
+  src/
+    App.ts                           starts the application
+    config/Config.ts                 its options: components, entrypoint, adapters
+    controllers/ExampleController.ts the actions
+    dtos/GreetDTO.ts                 the input of the actions
+    tests/App.spec.ts                the tests (node --test)
+  build/                             the compiled application (npm run build)
+```
+
+`src/App.ts` starts the application with the options of `src/config/Config.ts` and logs its launch:
+
+```typescript
+import {Application, type ILogger} from 'lakutata'
+import {config} from './config/Config.js'
+
+Application
+    .run(config)
+    .onLaunched((app: Application, log: ILogger): void => log.info('%s started in %s mode', app.appName, app.mode()))
+    .onFatalException((error: Error, log: ILogger): void => log.error('The application cannot start: %s', error.message))
+```
+
+`config()` returns the options of the application: its ID and name, its mode (`production` when
+`NODE_ENV=production`), and the `entrypoint` component, which serves `ExampleController` over HTTP on the `PORT`
+environment variable (8080 by default). It is a function so that the tests can start the application on a port of
+their own: `src/tests/App.spec.ts` runs `Application.run(config(18080))`, requests `/example?name=you`, then disposes
+of the application.
+
+| Script | What it does |
+|---|---|
+| `dev` | `build`, then starts the application |
+| `build` | Removes `build/` (`lakutata clean`), then compiles `src/` into it (`tsc`) |
+| `start` | Starts the compiled application (`node build/App.js`) |
+| `test` | `build`, then runs the tests (`node --test "build/tests/**/*.spec.js"`) |
+| `migration:generate`, `migration:create`, `migration:run`, `migration:revert`, `migration:show` | The migrations of the databases (`lakutata migration`, see [Migrations](Migrations.md)) |
+
+The template writes its own compiler options in `tsconfig.json` (the ones of `lakutata/tsconfig.json` that it needs,
+with `module: "NodeNext"` and source maps); a project may extend `lakutata/tsconfig.json` instead, as the workspace
+templates other than `cli` do.
+
+## 2. The workspace templates
+
+The other templates are npm workspaces: the application is the package `packages/app`, and the templates with an
+interface or with installers add `packages/ui` (the web pages, or the renderer of Electron) and `packages/resources`
+(the icon). The `service` template:
+
+```
+shop/
+  package.json                       the workspace: workspaces ["packages/*"], the scripts
+  Dockerfile                         the image of the service
+  packages/
+    app/
+      package.json
+      tsconfig.json                  extends lakutata/tsconfig.json
+      src/
+        App.ts
+        config/Config.ts             the express adapter, its middlewares, compression
+        controllers/ExampleController.ts
+        controllers/HealthController.ts    GET /health
+        dtos/GreetDTO.ts
+        middlewares/Authenticate.ts  a bearer token, when API_TOKEN is set
+        tests/App.spec.ts
+```
+
+| Script (root) | What it does |
+|---|---|
+| `npm run build` | Builds every package, in the order of their dependencies (`lakutata run rebuild`) |
+| `npm test` | Builds every package, then runs their tests (`npm run build && lakutata run test`) |
+| `npm run dev` | Starts the `dev` script of every package at once (`lakutata run dev --parallel`): the application, and the dev server of the interface when there is one |
+| `npm start` | Starts the compiled application (`npm start -w app`) |
+| `npm run version:patch` | Gives every package the next patch version (`lakutata version patch --yes`) |
+
+The other templates add to this layout:
+
+- `web-react` and `web-vue`: `packages/ui`, a Vite application. In development, its dev server
+  (`http://localhost:5173`) forwards `/api` to the application; once built, the application serves the pages itself
+  (the actions are under `/api`). The `lakutata.resources` of the application ship the built pages in its packed forms.
+- `web-next` and `web-nuxt`: `packages/ui`, a Next.js or Nuxt application that the application renders in the same
+  process.
+- `cli`: a command line tool (`commanderCLIEntrypoint`), with the scripts `package:bundle` and `package:exe` that pack
+  it into `dist/` ([Packaging](Packaging.md)).
+- `electron-react` and `electron-vue`: the main process of Electron in `packages/app` (its window and its service
+  actions over IPC), the renderer in `packages/ui`, and the scripts that make the installers.
+
+The packed forms are written to `dist/` at the root of the workspace; `.gitignore` leaves out `build`, `dist` and the
+outputs of the interfaces.
+
+## 3. The features
+
+`lakutata create --with <features>` (or the list offered in a terminal) adds optional features to the template:
+
+| Feature | Templates | What it adds |
+|---|---|---|
+| `i18n` | all | The messages of the languages in `src/locales` (`en`, `zh-CN`), the `i18n` component, the language middleware, and the scripts `i18n:check` and `i18n:types` ([I18n](I18n.md)) |
+| `installer` | `cli`, `service`, `web-*` | The `lakutata.installer` of the application, the scripts that make the installers (on the machine, and for Linux in Docker), and for the services a system service ([Installers](Installers.md)) |
+
+The Electron templates make installers without this feature.
+
+## 4. Templates of your own
+
+`--template` also takes a template that is not in the catalog: `npm:<package>[@<version>]`,
+`github:<owner>/<repo>[#<ref>]`, or a directory. A directory without a `template/` subdirectory is copied as it is; a
+template package (as the official ones) holds:
+
+- `template/`: the files of the project. npm does not publish some dotfiles, so they are named with `_` and renamed
+  (`_gitignore` becomes `.gitignore`). `{$APP_NAME}`, `{$APP_ID}`, `{$APP_DESC}`, `{$APP_AUTHOR}`, `{$APP_LICENSE}` and
+  `{$LAKUTATA_VERSION}` are replaced in the text files.
+- `features/<name>/`: the files of each feature, declared with its description in the `lakutata.features` of the
+  `package.json` of the template. They are added to the project: a JSON file the project already has is merged into it
+  (arrays replaced), any other file replaces the one of the template.
+- Blocks kept for a feature only: lines between `//@if i18n` and `//@end` (with `//@else`, and `@if !i18n` for the
+  opposite), written as comments of the file (`#@if`, `<!--@if-->`, `/*@if*/`).