@toa.io/userland 1.0.0-alpha.326 → 1.0.0-alpha.327

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.0.0-alpha.327](https://github.com/toa-io/toa/compare/v1.0.0-alpha.326...v1.0.0-alpha.327) (2026-10-10)
+
+### Features
+
+* **cli:** create an application in the working directory ([6d44704](https://github.com/toa-io/toa/commit/6d44704ce27e12e796448d9db9b55390ef0a6196))
+* **userland:** install what the declarations require with the packages ([52a99da](https://github.com/toa-io/toa/commit/52a99da800e37117250377ae87245634cfba4a85))
+* **userland:** run what is created as two processes under PM2 ([fe37a05](https://github.com/toa-io/toa/commit/fe37a0583cdccb0f4fdcaf5ae9f73bb1cc10e843))
+
+
 # [1.0.0-alpha.326](https://github.com/toa-io/toa/compare/v1.0.0-alpha.325...v1.0.0-alpha.326) (2026-10-06)
 
 **Note:** Version bump only for package @toa.io/userland

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/userland",
-  "version": "1.0.0-alpha.326",
+  "version": "1.0.0-alpha.327",
   "type": "module",
   "description": "Toa development kit",
   "homepage": "https://toa.io",
@@ -32,12 +32,13 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@toa.io/boot": "1.0.0-alpha.326",
-    "@toa.io/core": "1.0.0-alpha.326",
+    "@toa.io/agent": "1.0.0-alpha.320",
+    "@toa.io/boot": "1.0.0-alpha.327",
+    "@toa.io/core": "1.0.0-alpha.327",
     "@toa.io/generic": "1.0.0-alpha.311",
-    "@toa.io/norm": "1.0.0-alpha.326",
+    "@toa.io/norm": "1.0.0-alpha.327",
     "@toa.io/schemas": "1.0.0-alpha.326",
-    "@toa.io/storages.null": "1.0.0-alpha.326"
+    "@toa.io/storages.null": "1.0.0-alpha.327"
   },
-  "gitHead": "60f11bdc805d0c39bcb06064b2218b11114a35ad"
+  "gitHead": "cd6d6d77f19fbae5d7ff85d18005ca8deb9c77f3"
 }

package/readme.md

@@ -1,7 +1,64 @@
 # Toa development kit
 
 - [Stage](./stage): integration tests framework (Node.js)
+- [Template](#template): the application `toa create` writes
 
 See [example](./example).
 
-[^1]: not yet implemented
+## Template
+
+[`toa create <name>`](/runtime/cli/readme.md#create) writes an application into an empty
+directory. Running it takes [Docker](https://docs.docker.com/get-docker/), for the services it
+connects to, and [PM2](https://pm2.keymetrics.io), which keeps its processes:
+
+```shell
+$ npm install -g pm2
+```
+
+```text
+package.json
+tsconfig.json
+docker-compose.yaml
+ecosystem.config.js
+context.toa.yaml
+cucumber.js
+components/
+  hello/
+    manifest.toa.yaml
+    operations/greet.ts
+  notes/
+    manifest.toa.yaml
+features/
+  hello.feature
+  notes.feature
+  steps/
+    application.ts
+    http.ts
+```
+
+| File                  | Is                                                                                                                                                             |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `context.toa.yaml`    | The Context: the application's name and where its infrastructure is. It is the least a Context holds.                                                          |
+| `docker-compose.yaml` | RabbitMQ, MongoDB as a replica set of one, and Redis, on their conventional ports, with the credentials `toa env --dev` writes.                                |
+| `ecosystem.config.js` | The two processes PM2 keeps: `sys`, what Toa serves beside an application — its gateway, configuration and introspection — and `app`, the components.          |
+| `components/hello`    | A component with code and no state: `greet`, a computation, served at `GET /hello/`.                                                                           |
+| `components/notes`    | A component with state and no code: an entity, `create` forwarded to the operation every component inherits, served at `/notes/`.                              |
+| `features`            | A scenario for each component, sent over HTTP. The steps start the components with the [stage](./stage), in the process of the test; `sys` is running already. |
+| `package.json`        | The packages of Toa at the version that created the application, and the scripts below.                                                                        |
+| `tsconfig.json`       | What `tsc` checks the components and the steps with.                                                                                                           |
+
+| Script              | Runs                                                                                                      |
+| ------------------- | --------------------------------------------------------------------------------------------------------- |
+| `npm install`       | Installs the packages, then `toa npm`, which adds what the declarations require beyond them.              |
+| `npm run dock`      | The services, and waits until they are ready.                                                             |
+| `npm run env`       | `toa types`, `toa env --dev` and `toa map`. Run it again when a manifest or a component's source changes. |
+| `npm run sys`       | `sys` alone: what the scenarios need, since they start the components themselves.                         |
+| `npm run features`  | The scenarios.                                                                                            |
+| `npm start`         | `sys` and `app`: the application, with its gateway on `http://localhost:8000`.                            |
+| `npm run restart`   | `npm run env`, and both processes again.                                                                  |
+| `npm stop`          | Stops and forgets both.                                                                                   |
+| `npm run typecheck` | `tsc`.                                                                                                    |
+
+`pm2 logs` shows what the processes write, and `pm2 ls` whether they run.
+
+The routes are open to anyone, which is right for a first run and for nothing else.

package/stage/src/workload.js

@@ -34,9 +34,7 @@ const create = async (references, workload) => {
  */
 export const workload = async (paths, options, services = []) => {
   const workload = new boot.Workload(async (workload) => {
-    const composition = workload.gate(
-      async () => await boot.composition(paths, options)
-    )
+    const composition = workload.gate(async () => await boot.composition(paths, options))
 
     if (services.length === 0) return composition
 

package/template/_gitignore

@@ -0,0 +1,3 @@
+node_modules/
+.env*
+.map.json

package/template/components/hello/manifest.toa.yaml

@@ -0,0 +1,22 @@
+name: hello
+
+operations:
+  greet:
+    input:
+      type: object
+      properties:
+        name: { type: string, maxLength: 64 }
+    output:
+      type: object
+      properties:
+        greeting: { type: string }
+      required: [greeting]
+
+exposition:
+  /:
+    anonymous: true
+    io:output: true
+    GET:
+      endpoint: greet
+      query:
+        parameters: [name]

package/template/components/hello/operations/greet.ts

@@ -0,0 +1,5 @@
+import type { GreetInput } from '../types/index.d.ts'
+
+export async function computation(input: GreetInput) {
+  return { greeting: `Hello, ${input.name ?? 'world'}!` }
+}

package/template/components/notes/manifest.toa.yaml

@@ -0,0 +1,25 @@
+name: notes
+
+entity:
+  properties:
+    text: { type: string, maxLength: 1024 }
+  required: [text]
+
+operations:
+  create:
+    forward: transit
+    query: false
+    input:
+      type: object
+      properties:
+        text: { type: string, maxLength: 1024 }
+      required: [text]
+
+exposition:
+  /:
+    anonymous: true
+    io:output: [id, text]
+    GET: enumerate
+    POST: create
+    /:id:
+      GET: observe

package/template/context.toa.yaml

@@ -0,0 +1,29 @@
+name: {{name}}
+registry: registry.example.com/{{name}}
+
+amqp: amqp://localhost
+mongodb: mongodb://localhost
+stash: redis://localhost
+
+atomicity:
+  redis: redis://localhost
+
+storages:
+  tmp:
+    provider: tmp
+    directory: {{name}}
+
+exposition:
+  authorities:
+    local: localhost:8000
+
+configuration:
+  identity.tokens:
+    keys:
+      - id: key0
+        key: $IDENTITY_TOKENS_ENCRYPTION_KEY0
+
+ingress:
+  hosts: [localhost]
+
+resources: ~

package/template/cucumber.js

@@ -0,0 +1,4 @@
+export default {
+  import: ['features/steps/*.ts'],
+  failFast: true
+}

package/template/docker-compose.yaml

@@ -0,0 +1,62 @@
+# What a local run connects to. `developer` and `secret` are what `toa env --dev` writes.
+name: {{name}}
+volumes:
+  mongo-data:
+  mongo-key:
+services:
+  rabbitmq:
+    image: rabbitmq:4.2.4-management
+    ports:
+      - "5672:5672"
+      - "15672:15672"
+    environment:
+      RABBITMQ_DEFAULT_USER: developer
+      RABBITMQ_DEFAULT_PASS: secret
+    healthcheck:
+      test: rabbitmq-diagnostics -q ping
+      interval: 5s
+      timeout: 5s
+      retries: 30
+
+  # a replica set of one member: transactions and change streams need one
+  mongodb:
+    image: mongo:8.0.16
+    ports:
+      - "27017:27017"
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: developer
+      MONGO_INITDB_ROOT_PASSWORD: secret
+    volumes:
+      - mongo-data:/data/db
+      - mongo-key:/etc/mongo-keyfile
+    entrypoint: >
+      bash -c '
+        set -e
+
+        if [ ! -f /etc/mongo-keyfile/keyfile ]; then
+          umask 077
+          openssl rand -base64 756 > /etc/mongo-keyfile/keyfile
+          chown mongodb:mongodb /etc/mongo-keyfile/keyfile
+        fi
+
+        exec docker-entrypoint.sh mongod --replSet rs0 --bind_ip_all --keyFile /etc/mongo-keyfile/keyfile
+      '
+    healthcheck:
+      test: >
+        mongosh "mongodb://developer:secret@localhost:27017/admin?directConnection=true" --quiet --eval '
+          try { rs.status() } catch (e) { rs.initiate({ _id: "rs0", members: [{ _id: 0, host: "localhost:27017" }] }) }
+          if (!db.hello().isWritablePrimary) quit(1)
+        '
+      interval: 5s
+      timeout: 5s
+      retries: 30
+
+  redis:
+    image: redis:8.6.1
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: redis-cli ping
+      interval: 5s
+      timeout: 5s
+      retries: 30

package/template/ecosystem.config.js

@@ -0,0 +1,29 @@
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+// the binary of this project's Toa, by its path: pm2 resolves a script through the PATH of the
+// shell that starts it, which has `node_modules/.bin` only under `npm run`
+const toa = join(import.meta.dirname, 'node_modules/.bin/toa')
+
+const components = readdirSync(join(import.meta.dirname, 'components'), {
+  withFileTypes: true
+})
+  .filter((entry) => entry.isDirectory())
+  .map((entry) => join('components', entry.name))
+
+const common = {
+  script: toa,
+  cwd: import.meta.dirname,
+  autorestart: false,
+  watch: false,
+  merge_logs: true,
+  wait_ready: true,
+  listen_timeout: 60_000
+}
+
+export const apps = [
+  // what Toa serves beside an application: its gateway, configuration and introspection
+  { ...common, name: 'sys', args: 'serve configuration exposition introspection' },
+  // the application's components
+  { ...common, name: 'app', args: `compose ${components.join(' ')}` }
+]

package/template/features/hello.feature

@@ -0,0 +1,14 @@
+Feature: Hello
+
+  Scenario: Greeting by name
+    When the request is sent:
+      """
+      GET /hello/?name=Toa HTTP/1.1
+      accept: application/yaml
+      """
+    Then the response is received:
+      """
+      200 OK
+
+      greeting: Hello, Toa!
+      """

package/template/features/notes.feature

@@ -0,0 +1,29 @@
+Feature: Notes
+
+  Scenario: Keeping a note
+    When the request is sent:
+      """
+      POST /notes/ HTTP/1.1
+      content-type: application/yaml
+      accept: application/yaml
+
+      text: Buy milk
+      """
+    Then the response is received:
+      """
+      201 Created
+
+      id: ${{ id }}
+      text: Buy milk
+      """
+    When the request is sent:
+      """
+      GET /notes/${{ id }}/ HTTP/1.1
+      accept: application/yaml
+      """
+    Then the response is received:
+      """
+      200 OK
+
+      text: Buy milk
+      """

package/template/features/steps/application.ts

@@ -0,0 +1,22 @@
+import { readdir, readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { BeforeAll, AfterAll } from '@cucumber/cucumber'
+import * as stage from '@toa.io/userland/stage'
+
+const root = resolve(import.meta.dirname, '../..')
+const components = resolve(root, 'components')
+
+BeforeAll({ timeout: 60_000 }, async function () {
+  const map = await readFile(resolve(root, '.map.json'), 'utf8')
+  const entries = await readdir(components)
+  const paths = entries.map((entry) => resolve(components, entry))
+
+  stage.map(JSON.parse(map))
+
+  // the components run in this process; what serves them is started with `npm run sys`
+  await stage.compose(paths)
+})
+
+AfterAll(async function () {
+  await stage.shutdown()
+})

package/template/features/steps/http.ts

@@ -0,0 +1,19 @@
+import { Before, When, Then } from '@cucumber/cucumber'
+import { Agent } from '@toa.io/agent'
+
+// what the steps of one scenario share
+export interface World {
+  agent: Agent
+}
+
+Before(function (this: World) {
+  this.agent = new Agent('http://localhost:8000')
+})
+
+When('the request is sent:', async function (this: World, text: string) {
+  await this.agent.request(text)
+})
+
+Then('the response is received:', function (this: World, text: string) {
+  this.agent.responseIncludes(text)
+})

package/template/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "postinstall": "toa npm",
+    "dock": "docker compose up -d --wait",
+    "env": "toa types --quiet && toa env --dev && toa map",
+    "start": "pm2 start ecosystem.config.js",
+    "restart": "npm run env && pm2 restart ecosystem.config.js",
+    "stop": "pm2 delete ecosystem.config.js",
+    "sys": "pm2 start ecosystem.config.js --only sys",
+    "features": "cucumber-js",
+    "typecheck": "tsc"
+  },
+  "workspaces": [
+    "components/*"
+  ],
+  "devDependencies": {
+    "@cucumber/cucumber": "13.2.1",
+    "@toa.io/agent": "{{agent}}",
+    "@toa.io/operations": "{{version}}",
+    "@toa.io/runtime": "{{version}}",
+    "@toa.io/userland": "{{version}}",
+    "@types/node": "26.6.4",
+    "typescript": "7.0.2"
+  }
+}

package/template/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "esnext",
+    "types": ["node"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true
+  },
+  "include": ["components", "features"]
+}