lakutata 3.0.0 → 3.1.0

package/doc/en/Command.md

@@ -0,0 +1,110 @@
+# Lakutata Command Line Tool
+
+The **`lakutata` command** (package `@lakutata/cli`) creates projects from templates, runs scripts across the packages
+of a workspace and gives them versions, adds packages and native addons, runs the migrations of an application, checks
+its translations, and packs it into bundles, executables and installers. The README of `@lakutata/cli` lists every
+option.
+
+## 1. Installing and running it
+
+```bash
+npx @lakutata/cli create --name my-app     # without installing it
+npm install --global @lakutata/cli         # or once for the machine, then: lakutata create --name my-app
+```
+
+The templates add `@lakutata/cli` to the `devDependencies` of the project, so its scripts call `lakutata` directly and
+`npx lakutata` works inside it. The tool needs Node.js `^22.13.0 || >=24.11.0`: 22.13 or a later 22.x, or 24.11 and
+later (not 23).
+
+- `lakutata --help` lists the commands, `lakutata help <command>` (or `lakutata <command> --help`) describes one, and
+  `lakutata --version` prints the version of the tool. Without a command, the tool prints its help and exits with code
+  1.
+- Options are written in kebab case (`--package-manager`). A boolean option that is on by default is turned off with
+  `--no-` (`--no-git`, `--no-bail`).
+- Results go to standard output, warnings (`! …`) to standard error. A failure prints `error: <message>` on standard
+  error and exits with code 1. Colors are used on a terminal only, and `NO_COLOR` turns them off.
+- **Language**: the help, the prompts and the validation errors are in English, Simplified Chinese or Traditional
+  Chinese, chosen from `LAKUTATA_LANG`, then `LANGUAGE`, `LC_ALL`, `LC_MESSAGES`, `LANG`, then the language of the
+  system (`LAKUTATA_LANG=zh-CN lakutata --help`). The names of commands and options, and the other messages of the
+  tool, stay in English.
+
+## 2. Projects
+
+### `lakutata create`
+
+```bash
+lakutata create --name my-app                                    # the default template, in ./my-app
+lakutata create --name shop --template service --with i18n,installer --yes
+lakutata create --name tool --template cli --package-manager none --no-git
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `--name` | asked in a terminal | The name of the application, and of its directory |
+| `--id` | the name in lower case | The ID of the application and the name of its package |
+| `--template` | `default` | An official template (`lakutata templates`), `npm:<package>[@<version>]`, `github:<owner>/<repo>[#<ref>]`, or a directory |
+| `--path` | `.` | Where the project directory is created (`<path>/<name>`) |
+| `--init` | | Create the project in `--path` itself, a directory that already exists |
+| `--description`, `--author`, `--license` | license `UNLICENSED` | The information of the package |
+| `--with` | | The optional features of the template, separated by commas (`i18n`, `installer`) |
+| `--package-manager` | `npm`, or pnpm or yarn when one of them started the tool | `npm`, `pnpm`, `yarn`, or `none` to skip the installation |
+| `--no-git` | | Do not create a git repository |
+| `--yes` | | Do not ask for the features or for a confirmation |
+
+In a terminal, the tool asks for a missing name, offers the features of the template, shows what it is going to create
+and asks for a confirmation. It then copies the template, fills in the name, the ID and the other information of the
+package, installs the dependencies (`<manager> install`) and runs `git init` (without a commit). An official template
+is the newest release for the major version of the tool, downloaded from the npm registry and kept in the cache of the
+tool; without a network, a template downloaded earlier is used when there is one.
+
+With `--init`, the files the directory already has are kept: a file of the template with the same name is not copied,
+and a warning lists these files so that you can merge what you need by hand (for `package.json`, its scripts and
+dependencies).
+
+### `lakutata templates`, `info` and `clean`
+
+- `lakutata templates` lists the official templates and their features. The list comes from the npm registry and is
+  kept for a day (`--refresh` fetches it again). [ProjectStructure](ProjectStructure.md) describes what the templates
+  contain.
+- `lakutata info` shows the versions of the tool, of the framework (with the latest ones when the registry can be
+  reached) and of Node.js, and the version of the framework that the project of the current directory uses.
+- `lakutata clean [paths...]` removes paths of the package in the current directory, on every platform; without paths,
+  the `outDir` and `declarationDir` of its `tsconfig.json`. It refuses paths outside the package, and `src`,
+  `node_modules`, `package.json` and `.git`. The templates call it from their `build` or `rebuild` scripts.
+
+## 3. Workspaces and native addons
+
+`lakutata list`, `run`, `version` and `add` work on a workspace, a repository of several packages: they list its
+packages, run a script in each of them in the order of their dependencies, give them one version, and add packages. See
+[Workspaces](Workspaces.md).
+
+`lakutata add <name> --native gyp|cmake|rust` adds a native addon written in C++ or Rust, and
+`lakutata native <link|include|define> <value>` links libraries to it. See [NativeAddons](NativeAddons.md).
+
+## 4. Migrations and translations
+
+`lakutata migration <action>` generates, creates, runs, reverts and shows the migrations of the databases of an
+application. It builds and starts the application with its `dev` script, in a mode where only the databases are
+connected. See [Migrations](Migrations.md), section 2.
+
+`lakutata i18n <action>` checks the messages of the languages of an application, declares the types of their keys, and
+adds a language. See [I18n](I18n.md#command-line-tools).
+
+## 5. Packaging
+
+`lakutata package bundle` and `package exe` pack a compiled application into one JavaScript file, or into an executable
+that runs without Node.js: see [Packaging](Packaging.md). `lakutata package installer` makes its installers, which can
+register it as a service: see [Installers](Installers.md).
+
+## 6. Environment variables
+
+| Variable | Meaning |
+|---|---|
+| `LAKUTATA_LANG` | The language of the tool (`en`, `zh-CN`, `zh-TW`) |
+| `LAKUTATA_NPM_REGISTRY` | The registry the templates come from (else `npm_config_registry`, else `https://registry.npmjs.org`) |
+| `LAKUTATA_GITHUB_DOWNLOAD` | Where the `github:` templates are downloaded from (`https://github.com` by default) |
+| `LAKUTATA_CACHE_DIR` | The cache of the tool: the templates, and the tools that make installers (`$XDG_CACHE_HOME/lakutata`, else `~/.cache/lakutata`) |
+| `NO_COLOR` | Turns the colors off |
+
+The scripts and the applications the tool runs get the environment the tool was started with. The variables of the
+packed applications are described in [Packaging](Packaging.md), section 6.

package/doc/en/ContainerdIntegration.md

@@ -1,21 +1,21 @@
-# Lakutata containerd Integration
+# Lakutata Containerd Integration
 
 The **containerd component** (`lakutata/com/containerd`, package `@lakutata/containerd`) manages the images, containers,
 CNI networks and named volumes of a [containerd](https://containerd.io) namespace over the gRPC API of containerd,
 without Docker and without nerdctl. It targets the Linux machines that run containerd alone, such as embedded devices:
 the component talks to the socket of containerd (its gRPC client is written in TypeScript, no native addon), and does
 by itself what nerdctl does on top of it (pulling from the registries, unpacking the layers, generating the OCI
-specifications of the containers, their logs). Its API follows the one of the Docker component
+specifications of the containers, their logs). Its API follows that of the Docker component
 ([DockerIntegration](DockerIntegration.md)). The README of `@lakutata/containerd` gives every option.
 
-The containers it creates are the ones of nerdctl: they carry its labels (`nerdctl/name`, `nerdctl/hostname`…), so
-`nerdctl ps` and `ctr containers ls` list them.
+The containers it creates are the same as the containers nerdctl creates: they carry its labels (`nerdctl/name`,
+`nerdctl/hostname`…), so `nerdctl ps` and `ctr containers ls` list them.
 
 ## 1. Requirements
 
 | Feature | Needs |
 |---|---|
-| Everything | Linux, containerd 1.6 or later with runc, Node.js 22 or later; the application runs as root or as a member of the group owning the socket of containerd |
+| Everything | Linux, containerd 1.6 or later with runc, Node.js `^22.13.0 || >=24.11.0`; the application runs as root or as a member of the group owning the socket of containerd |
 | CNI networks (the default `bridge` included), published ports | The CNI plugins (`bridge`, `portmap`, `host-local`… in `/opt/cni/bin`, `/usr/lib/cni` or `/usr/libexec/cni`, the `cniPath` option) and iptables |
 | `exec()` with `stdin`, separate `stdout`/`stderr`, terminals | `mkfifo` on the host (without it, `exec()` puts both outputs in `stdout`) |
 | Builds | A BuildKit daemon (`buildkitd`), local or remote |
@@ -42,7 +42,7 @@ Application
                 cgroupManager: 'cgroupfs',
                 //The logs, hosts, resolv.conf and settings of the containers, and the named volumes
                 dataRoot: '/var/lib/lakutata/containerd',
-                //The log file of a container rotated beyond 10 MiB when the component starts it (0: never)
+                //The log file of a container rotated beyond 10 MiB when the component starts it (default 0: never)
                 logMaxSize: 10 * 1024 * 1024,
                 registryAuths: {'registry.example.com': {username: 'deploy', password: 'secret'}},
                 //The registries served over HTTP
@@ -63,9 +63,10 @@ Application
     })
 ```
 
-The component connects when it is created: without containerd on `socketPath`, the application fails to start with a
-`ContainerdConnectionException`. Its namespace is created when it does not exist. Each component works in one
-namespace; declare one component per namespace to manage several.
+The component connects when it is created: without containerd on `socketPath`, its creation fails with a
+`ContainerdConnectionException`; when the component is listed in `bootstrap`, the application then fails to start. Its
+namespace is created when it does not exist. Each component works in one namespace; declare one component per namespace
+to manage several.
 
 ### What differs from the Docker component
 
@@ -178,7 +179,7 @@ async function containers(containerd: Containerd): Promise<void> {
     //Its snapshot and its state removed
     await container.remove({force: true})
 
-    //By its name, its identifier or a prefix of it; by labels
+    //The containers with these labels; getContainer() finds one by its name, its id or a prefix of its id
     console.log(await containerd.listContainers({app: 'worker'}))
 }
 ```
@@ -193,8 +194,8 @@ async function containers(containerd: Containerd): Promise<void> {
   `seccompProfile: 'unconfined'` disables it, the path of a file gives an OCI profile; the privileged containers are
   unconfined.
 - `privileged`, `capabilities` / `capabilitiesDrop`, `readonlyRootfs`, `pidMode: 'host'`, `ipcMode: 'host'`, `sysctls`,
-  `extraHosts`, `dns`, `shmSize`, `pidsLimit`, `cpuSet`, `cpuShares`, `memorySwap`, `OOMKillDisable` are the options of
-  Docker of the same names.
+  `extraHosts`, `dns`, `shmSize`, `pidsLimit`, `cpuSet`, `cpuShares`, `memorySwap`, `OOMKillDisable` work as the options
+  of Docker with the same names.
 - `update()` with other settings than the resources and the restart policy only works for the containers the component
   created (it keeps their settings in `dataRoot`).
 
@@ -253,8 +254,8 @@ async function networks(containerd: Containerd): Promise<void> {
 ```
 
 The networks of a container are set up by its runc hooks, as nerdctl does: they are added when its task is created and
-deleted when it stops, also when containerd restarts it by its restart policy (after a reboot, without the
-application). Its address is given at each start and written in its `/etc/hosts`.
+deleted when it stops, also when containerd restarts it under its restart policy (after a reboot, for example, while the
+application is not running). Its address is given at each start and written in its `/etc/hosts`.
 
 ## 6. Builds
 
@@ -291,7 +292,7 @@ BuildKit pulls the base images with the registry credentials of the component (o
 
 ## 7. Platforms and events
 
-`containerd.supportedPlatforms()` gives the platforms the machine runs: its own, and the ones of the emulators
+`containerd.supportedPlatforms()` gives the platforms the machine can run: its own, and the ones of the emulators
 registered in `binfmt_misc` (QEMU, Rosetta). A container of another platform runs once its emulator is registered:
 `createContainer({image: 'alpine:3.20', platform: 'linux/amd64', cmd: ['uname', '-m']})` after pulling that platform.
 
@@ -324,5 +325,5 @@ network exists, its subnet overlaps another one, or a container uses it), `Conta
 
 ## 9. Limits of this version
 
-- The projects of Compose are not supported.
+- Compose projects are not supported.
 - The logs of the containers have no timestamps.

package/doc/en/Controllers.md

@@ -0,0 +1,256 @@
+# Lakutata Controllers and Actions
+
+A controller is a class whose methods answer requests. Each of these methods is an **action**: a decorator gives it an
+address (an HTTP route, a command, a service pattern, a schedule, a queue), and the `entrypoint` component calls it when
+a request arrives at that address. One method can have several addresses: the same code then answers over HTTP, on the
+command line and over a service transport, with the same validation, middlewares and access control.
+
+## 1. A controller
+
+```typescript
+import {Application, DTO} from 'lakutata'
+import {buildEntrypoints, Controller, httpServiceEntrypoint} from 'lakutata/com/entrypoint'
+import {CLIAction, GET, POST, ServiceAction} from 'lakutata/decorator/ctrl'
+import {Expect} from 'lakutata/decorator/dto'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+import {commanderCLIEntrypoint} from 'lakutata/adapter/commander'
+
+class OrderIdDTO extends DTO {
+    //A route parameter is text: strict(false) converts it (the command line converts its arguments itself)
+    @Expect(DTO.Number().integer().strict(false).required())
+    public id: number
+}
+
+class CreateOrderDTO extends DTO {
+    @Expect(DTO.String().required())
+    public product: string
+
+    @Expect(DTO.Number().integer().min(1).default(1))
+    public quantity: number
+}
+
+class OrderController extends Controller {
+    //GET /orders/42, the command "order 42", the service message {cmd: 'order.get', id: 42}
+    @GET('/orders/:id', OrderIdDTO)
+    @CLIAction('order <id>', OrderIdDTO, {description: 'Show an order'})
+    @ServiceAction({cmd: 'order.get'}, OrderIdDTO)
+    public async get(input: OrderIdDTO): Promise<{ id: number, status: string }> {
+        return {id: input.id, status: 'paid'}
+    }
+
+    //POST /orders with a JSON body
+    @POST('/orders', CreateOrderDTO)
+    public async create(input: CreateOrderDTO): Promise<CreateOrderDTO> {
+        return input
+    }
+}
+
+Application.run(() => ({
+    id: 'orders.app',
+    name: 'Orders',
+    components: {
+        entrypoint: buildEntrypoints({
+            controllers: [OrderController],
+            http: expressHTTPEntrypoint({port: 8080}),
+            service: httpServiceEntrypoint({port: 8081}),
+            cli: commanderCLIEntrypoint({bin: 'orders', noCommand: 'ignore'})
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+```text
+$ curl localhost:8080/orders/42
+{"id":42,"status":"paid"}
+$ curl -X POST localhost:8080/orders -H 'Content-Type: application/json' -d '{"product":"tea","extra":1}'
+{"product":"tea","quantity":1}
+$ curl -X POST localhost:8081 -H 'Content-Type: application/json' -d '{"cmd":"order.get","id":42}'
+{"success":true,"error":null,"payload":{"id":42,"status":"paid"}}
+$ node dist/index.js order 42
+{
+  "id": 42,
+  "status": "paid"
+}
+```
+
+- A controller extends `Controller`, from `lakutata/com/entrypoint`.
+- The controllers are listed in the `controllers` option of `buildEntrypoints`, next to the adapters of the transports
+  (see [Entrypoint](Entrypoint.md)). The entrypoint must be listed in `bootstrap`, or nothing starts it.
+- The decorator of a transport has no effect without its adapter: here, without `cli`, the `@CLIAction` would be
+  ignored.
+
+## 2. How a request is handled
+
+1. The adapter receives the request and looks for the action at its address. When there is none, the transport answers
+   that it is not found (404 over HTTP).
+2. A new scope is created for the request.
+3. The middlewares run (see [Middlewares](Middlewares.md)).
+4. A new instance of the controller is created in the scope.
+5. The DTO of the action validates the input (section 4).
+6. The access control checks the request (see [Middlewares](Middlewares.md)).
+7. The method is called with the input, and what it returns is the response (section 5).
+8. The scope is destroyed, with the objects created in it.
+
+So a controller lives as long as one request. The providers it injects that are `@Scoped` (the default for a provider)
+are created once for the request and shared by everything that takes part in it; the components are shared by the whole
+application.
+
+Inside the method, two properties describe the request:
+
+- `this.context` is the context of the request. Its `type` names the transport, and its class gives the details of that
+  transport:
+
+  | Class | `type` | Specific properties |
+  |---|---|---|
+  | `HTTPContext` | `'HTTP'` | `request`, `response`, `route` (the route as declared), `method` |
+  | `CLIContext` | `'CLI'` | `command` (the command as declared) |
+  | `ServiceContext` | `'SERVICE'` | `clientId`, `input` (the whole message) |
+  | `ScheduleContext` | `'SCHEDULE'` | `schedule`, `scheduledAt`, `run` |
+  | `QueueContext` (`lakutata/com/queue`) | `'QUEUE'` | See [Queue](Queue.md) |
+
+  Every context also has `data`, the input as it arrived (before validation), and `locale`, the language of the
+  request when the I18n middleware is used.
+- `this.signal` is an `AbortSignal` (its type allows `undefined`: write `this.signal?.`). It is aborted when the
+  request is: the client went away, the deadline of a gRPC call passed, or the application is stopping and its
+  `shutdownTimeout` ran out. Once it is aborted, the result of the action is dropped; a long action should check it and
+  stop early.
+
+## 3. The action decorators
+
+| Decorator | Address | Guide |
+|---|---|---|
+| `@GET(route)`, `@POST`, `@PUT`, `@PATCH`, `@DELETE`, `@HEAD`, `@OPTIONS`, `@HTTPAction(route, methods)` | An HTTP route | [HTTP](HTTP.md) |
+| `@CLIAction(command)` | A command | [CLI](CLI.md) |
+| `@ServiceAction(pattern)` | A service pattern | [ServiceCalls](ServiceCalls.md), [GRPC](GRPC.md), [NATS](NATS.md) |
+| `@Schedule(schedule)` | An interval or a cron expression | [Schedules](Schedules.md) |
+| `@QueueAction(queue)` (`lakutata/com/queue`) | A message queue | [Queue](Queue.md) |
+| `@MCPTool(name)` (`@lakutata/mcp`), `@DBusMethod(...)` (`@lakutata/dbus`) | An MCP tool, a D-Bus method | [MCP](MCP.md), [DBus](DBus.md) |
+
+The decorators of the first five rows come from `lakutata/decorator/ctrl`, unless the table names another subpath.
+They take the address first, then the DTO class of the input, then the action options; the DTO and the options can be
+left out. `@Schedule` is the exception: it takes no DTO, as a scheduled job has no input.
+
+The action options:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `name` | `'ControllerClass:method'` | The name of the action, unique for each transport |
+| `description` | | A description: the help of a command, the listing of the actions |
+| `middlewares` | | The middlewares of this action (see [Middlewares](Middlewares.md)) |
+| `acl` | `false` | Check the request with the access rules of the entrypoint |
+| `rule` | | An access rule of this action: `(context, input) => Promise<boolean>` |
+| `groups` | | The groups of the action, used by the access rules and the listings (see [Entrypoint](Entrypoint.md)) |
+
+## 4. The input
+
+Each transport builds the input from its request:
+
+| Transport | Input |
+|---|---|
+| HTTP | The query and the body, with the route parameters over them |
+| Command line | The arguments and the options |
+| Service | The message, without the keys of the pattern |
+| Schedule | Nothing |
+| Queue | The message |
+
+The DTO of the action then validates it:
+
+- the values of the query and of the route parameters are text: a schema that expects a number or a boolean needs
+  `.strict(false)` to convert `'42'` or `'true'`. The command line gives its arguments and options the type of their
+  property itself ([CLI](CLI.md));
+- the defaults are applied, and the keys the DTO does not declare are removed (`extra` above);
+- an invalid input stops the request with an `InvalidValueException`, answered with the status 400 over HTTP. The
+  message names the first invalid value: `"product" is required`. With the I18n middleware, it is in the language of
+  the request.
+
+The method receives the validated input as a plain object, a copy: not an instance of the DTO class, which only gives it
+its type. An action without a DTO receives the input as it arrived, with all its keys.
+
+## 5. The result
+
+What the method returns is sent back by the transport:
+
+| Transport | A value | `undefined` | An error thrown |
+|---|---|---|---|
+| HTTP | JSON | Status 204 | Its `statusCode` (500 by default) and `{errno, errMsg}` |
+| Command line | On stdout: text as it is, other values as JSON | Nothing | `error: <message>` on stderr, exit code 1 |
+| Service | `{success: true, error: null, payload}` | `payload` left out | `{success: false, error, payload: null}`, the error with all its properties |
+| Schedule | Ignored | | Given to `onError`, or logged |
+
+`Result`, from `lakutata/com/entrypoint`, controls the response more closely:
+
+- `Result.status(status, data, headers)`: an HTTP status and headers with the data;
+- `Result.file(path)` (or a `Buffer`, or a stream, with `{filename, contentType, etag, headers}`): a file, as a download
+  when `filename` is given;
+- `Result.events(producer)`: Server-Sent Events over HTTP, the data of each event on the command line. The producer
+  `(send, signal) => …` runs after the scope of the request is destroyed, so it should use components rather than
+  request-scoped providers.
+
+The service transports cannot send a file or events: such a result fails the request.
+
+## 6. Prefixes
+
+`@Prefix` on a controller adds a prefix to the addresses of all its actions:
+
+```typescript
+import {DTO} from 'lakutata'
+import {Controller} from 'lakutata/com/entrypoint'
+import {CLIAction, GET, Prefix, ServiceAction} from 'lakutata/decorator/ctrl'
+import {Expect} from 'lakutata/decorator/dto'
+
+class UserIdDTO extends DTO {
+    @Expect(DTO.String().required())
+    public id: string
+}
+
+@Prefix({route: '/users', command: 'user', pattern: {resource: 'user'}})
+class UserController extends Controller {
+    //GET /users/:id, the command "user:get <id>" and the message {resource: 'user', act: 'get', id}
+    @GET('/:id', UserIdDTO)
+    @CLIAction('get <id>', UserIdDTO)
+    @ServiceAction({act: 'get'}, UserIdDTO)
+    public async get(input: UserIdDTO): Promise<{ id: string }> {
+        return {id: input.id}
+    }
+}
+```
+
+- `route` is put before the HTTP routes, `command` before the commands (joined by a colon), and `pattern` is merged
+  into the service patterns. A key set to different values in the prefix and in an action is an error
+  (`InvalidPrefixException`).
+- The scheduled jobs have no prefix.
+- A controller takes the prefix of the nearest class that declares one: its own, or else the one of its parent.
+
+## 7. Inheritance
+
+A controller inherits the actions of its parent classes, so common actions can be written once in a base class. A
+registered subclass serves them under its own prefix:
+
+```typescript
+import {Controller} from 'lakutata/com/entrypoint'
+import {GET, Prefix} from 'lakutata/decorator/ctrl'
+
+abstract class HealthController extends Controller {
+    @GET('/health')
+    public async health(): Promise<string> {
+        return 'ok'
+    }
+}
+
+//GET /v1/health
+@Prefix({route: '/v1'})
+class V1Controller extends HealthController {
+}
+
+//GET /v2/health
+@Prefix({route: '/v2'})
+class V2Controller extends HealthController {
+}
+```
+
+- Register the subclasses only (`controllers: [V1Controller, V2Controller]`). A parent and a subclass registered
+  together, with the same address for an action, would conflict: the one registered last wins.
+- A subclass can override an inherited method: the action keeps its address and runs the new code. A decorator on the
+  overriding method adds an address; the inherited one stays.
+- The base class can be abstract.