@toa.io/operations 1.0.0-alpha.274 → 1.0.0-alpha.277

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 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.277](https://github.com/toa-io/toa/compare/v1.0.0-alpha.276...v1.0.0-alpha.277) (2026-09-03)
+
+### Bug Fixes
+
+* read a manifest the way js-yaml read one before ([fcea1b2](https://github.com/toa-io/toa/commit/fcea1b21996d6efa6c3198acbfc9f70f1ce0c35c))
+* settle what the module loader made asynchronous ([d4ab9df](https://github.com/toa-io/toa/commit/d4ab9dfb09e382da311dba08f52214e7645f4a6c))
+* what the loader resolves, and what it will not ([1b8a02f](https://github.com/toa-io/toa/commit/1b8a02ff0a5e0f18ee62e3f71bc81116f86f9af1))
+
+
+# [1.0.0-alpha.276](https://github.com/toa-io/toa/compare/v1.0.0-alpha.275...v1.0.0-alpha.276) (2026-09-03)
+
+
+### Bug Fixes
+
+* **operations:** let a deployment state that it has no probe ([477b483](https://github.com/toa-io/toa/commit/477b483560cf2464d486a78e432f8e9b47f011dd))
+
+
+
+
+
 # [1.0.0-alpha.274](https://github.com/toa-io/toa/compare/v1.0.0-alpha.273...v1.0.0-alpha.274) (2026-09-02)
 
 **Note:** Version bump only for package @toa.io/operations

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@toa.io/operations",
-  "version": "1.0.0-alpha.274",
+  "version": "1.0.0-alpha.277",
+  "type": "module",
   "description": "Toa Deployment",
   "homepage": "https://toa.io",
   "author": {
@@ -27,11 +28,11 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/generic": "1.0.0-alpha.273",
-    "@toa.io/norm": "1.0.0-alpha.274",
-    "execa": "5.1.1",
-    "fs-extra": "11.1.1",
-    "js-yaml": "4.3.1"
+    "@toa.io/generic": "1.0.0-alpha.277",
+    "@toa.io/norm": "1.0.0-alpha.277",
+    "execa": "10.0.1",
+    "fs-extra": "11.4.0",
+    "js-yaml": "5.4.1"
   },
-  "gitHead": "7df32eb2872155c45681c299036b1efbeefd6518"
+  "gitHead": "0c0071418c2c56a44e621ba5ced5cdd23dff1738"
 }

package/src/deployment/.deployment/.describe/components.js

@@ -1,10 +1,8 @@
-'use strict'
-
 /**
  * @param {toa.deployment.Composition[]} compositions
  * @returns {string[]}
  */
-const components = (compositions) => {
+export const components = (compositions) => {
   /** @type {Set<string>} */
   const components = new Set()
 
@@ -16,5 +14,3 @@ const components = (compositions) => {
 
   return Array.from(components)
 }
-
-exports.components = components

package/src/deployment/.deployment/.describe/compositions.js

@@ -1,9 +1,7 @@
-'use strict'
+import { addVariables } from './variables.js'
+import { addMounts } from './mounts.js'
 
-const { addVariables } = require('./variables')
-const { addMounts } = require('./mounts')
-
-function compositions (compositions, dependency) {
+export function compositions (compositions, dependency) {
   for (const composition of compositions) {
     addVariables(composition, dependency.variables)
     addMounts(composition, dependency.mounts)
@@ -12,5 +10,3 @@ function compositions (compositions, dependency) {
       composition.probe ??= dependency.probe
   }
 }
-
-exports.compositions = compositions

package/src/deployment/.deployment/.describe/dependencies.js

@@ -1,10 +1,8 @@
-'use strict'
-
 /**
  * @param {toa.deployment.dependency.Reference[]} references
  * @returns {*}
  */
-const dependencies = (references) => {
+export const dependencies = (references) => {
   return references?.reduce((map, reference) => {
     const { name, alias, values } = reference
 
@@ -13,6 +11,3 @@ const dependencies = (references) => {
     return map
   }, {})
 }
-
-
-exports.dependencies = dependencies

package/src/deployment/.deployment/.describe/events.js

@@ -1,5 +1,3 @@
-'use strict'
-
 /**
  * Tells each component which of its events something consumes. An event nobody consumes gets
  * no emitter, no exchange and no outbox row, and a component none of whose events are consumed
@@ -11,7 +9,7 @@
  * @param {toa.norm.Context} context
  * @param {toa.deployment.Dependency} dependency
  */
-function events (context, dependency) {
+export function events (context, dependency) {
   const components = deployed(context)
   const consumed = collect(components, context.events, dependency.events)
 
@@ -63,5 +61,3 @@ function collect (components, declared, contributed) {
 }
 
 const VARIABLE = 'TOA_EVENTS_'
-
-exports.events = events

package/src/deployment/.deployment/.describe/index.js

@@ -1,13 +1,4 @@
-'use strict'
-
-const { dependencies } = require('./dependencies')
-const { components } = require('./components')
-const { compositions } = require('./compositions')
-const { variables } = require('./variables')
-const { services } = require('./services')
-
-exports.dependencies = dependencies
-exports.components = components
-exports.compositions = compositions
-exports.variables = variables
-exports.services = services
+export { dependencies } from './dependencies.js'
+export { components } from './components.js'
+export { compositions } from './compositions.js'
+export { services } from './services.js'

package/src/deployment/.deployment/.describe/mounts.js

@@ -1,6 +1,4 @@
-'use strict'
-
-function addMounts (composition, mounts, keys = composition.components) {
+export function addMounts (composition, mounts, keys = composition.components) {
   if (mounts === undefined)
     return
 
@@ -20,5 +18,3 @@ function addMounts (composition, mounts, keys = composition.components) {
     }
   }
 }
-
-exports.addMounts = addMounts

package/src/deployment/.deployment/.describe/resources.js

@@ -1,5 +1,3 @@
-'use strict'
-
 /**
  * Every deployment states what it may take. One that states nothing is `BestEffort`: the
  * first evicted under memory pressure and the last given CPU under contention — which on
@@ -10,7 +8,7 @@
  * Deploying without any is a decision rather than an omission, and it is spelled
  * `resources: null` — at either place.
  */
-function resources (context, values) {
+export function resources (context, values) {
   for (const unit of units(values)) {
     // `null` is an answer and `undefined` is not one, so the fallback reads only the latter
     if (unit.deployment.resources === undefined)
@@ -33,5 +31,3 @@ function * units (values) {
   for (const service of values.services ?? [])
     yield { deployment: service, subject: `Service '${service.name}'` }
 }
-
-exports.resources = resources

package/src/deployment/.deployment/.describe/services.js

@@ -1,8 +1,6 @@
-'use strict'
+import { addVariables } from './variables.js'
 
-const { addVariables } = require('./variables')
-
-function services (services, variables, probe, ingress) {
+export function services (services, variables, probe, ingress) {
   for (const service of services) {
     addVariables(service, variables)
 
@@ -34,5 +32,3 @@ function expose (service, ingress = {}) {
   if (service.port === undefined)
     throw new Error(`Service '${service.name}' declares an ingress, but no port.`)
 }
-
-exports.services = services

package/src/deployment/.deployment/.describe/services.test.js

@@ -1,6 +1,7 @@
-'use strict'
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
 
-const { services } = require('./services')
+import { services } from './services.js'
 
 const service = (extra = {}) => ({ group: 'group', name: 'group-one', version: '0', ...extra })
 
@@ -9,7 +10,7 @@ it('should leave a service without an ingress alone', () => {
 
   services(list, {}, undefined, { hosts: ['api.dev'] })
 
-  expect(list[0].ingress).toBeUndefined()
+  assert.strictEqual(list[0].ingress, undefined)
 })
 
 /*
@@ -21,7 +22,7 @@ it('should supply hosts, class and annotations from the context', () => {
 
   services(list, {}, undefined, { hosts: ['api.dev'], class: 'alb', annotations: { a: 'b' } })
 
-  expect(list[0].ingress).toStrictEqual({
+  assert.deepStrictEqual(list[0].ingress, {
     path: '/.introspection',
     hosts: ['api.dev'],
     class: 'alb',
@@ -34,8 +35,8 @@ it('should keep what the service declared itself', () => {
 
   services(list, {}, undefined, { hosts: ['api.dev'], class: 'alb' })
 
-  expect(list[0].ingress.hosts).toStrictEqual(['own.dev'])
-  expect(list[0].ingress.class).toStrictEqual('alb')
+  assert.deepStrictEqual(list[0].ingress.hosts, ['own.dev'])
+  assert.deepStrictEqual(list[0].ingress.class, 'alb')
 })
 
 it('should ignore properties the service left undefined', () => {
@@ -43,19 +44,18 @@ it('should ignore properties the service left undefined', () => {
 
   services(list, {}, undefined, { hosts: ['api.dev'], class: 'alb' })
 
-  expect(list[0].ingress.class).toStrictEqual('alb')
+  assert.deepStrictEqual(list[0].ingress.class, 'alb')
 })
 
 it('should reject an ingress with nowhere to land', () => {
   const list = [service({ port: 8002, ingress: { path: '/.introspection' } })]
 
-  expect(() => services(list, {}, undefined, undefined))
-    .toThrow("Service 'group-one' declares an ingress, but no hosts are defined")
+  assert.throws(() => services(list, {}, undefined, undefined), (error) => /Service 'group-one' declares an ingress, but no hosts are defined/.test(error.message))
 })
 
 it('should reject an ingress without a port', () => {
   const list = [service({ ingress: { path: '/.introspection' } })]
 
-  expect(() => services(list, {}, undefined, { hosts: ['api.dev'] }))
-    .toThrow("Service 'group-one' declares an ingress, but no port")
+  assert.throws(() => services(list, {}, undefined, { hosts: ['api.dev'] }), (error) => /Service 'group-one' declares an ingress, but no port/.test(error.message))
 })
+

package/src/deployment/.deployment/.describe/variables.js

@@ -1,6 +1,4 @@
-'use strict'
-
-function addVariables (composition, variables, keys = composition.components) {
+export function addVariables (composition, variables, keys = composition.components) {
   composition.variables ??= []
 
   const used = new Set(composition.variables.map((variable) => variable.name))
@@ -17,5 +15,3 @@ function addVariables (composition, variables, keys = composition.components) {
     }
   }
 }
-
-exports.addVariables = addVariables

package/src/deployment/.deployment/declare.js

@@ -1,11 +1,9 @@
-'use strict'
-
 /**
  * @param {toa.norm.Context} context
  * @param {toa.deployment.Dependency} dependency
  * @returns {toa.deployment.Declaration}
  */
-const declare = (context, dependency) => {
+export const declare = (context, dependency) => {
   const { references } = dependency
   const { name, description, version } = context
 
@@ -25,5 +23,3 @@ const DECLARATION = {
   apiVersion: 'v2',
   type: 'application'
 }
-
-exports.declare = declare

package/src/deployment/.deployment/describe.js

@@ -1,12 +1,10 @@
-'use strict'
+import * as desc from './.describe/index.js'
+import { addVariables } from './.describe/variables.js'
+import { addMounts } from './.describe/mounts.js'
+import { resources } from './.describe/resources.js'
+import { events } from './.describe/events.js'
 
-const desc = require('./.describe')
-const { addVariables } = require('./.describe/variables')
-const { addMounts } = require('./.describe/mounts')
-const { resources } = require('./.describe/resources')
-const { events } = require('./.describe/events')
-
-const describe = (context, compositions, dependency, image) => {
+export const describe = (context, compositions, dependency, image) => {
   const { services } = dependency
 
   dependency.variables.global ??= []
@@ -132,6 +130,10 @@ function unit (context, dependency) {
     if (service.port !== undefined)
       (mono.backends ??= []).push({ port: service.port, path: service.ingress?.path ?? '/' })
 
+    // one Service fronts every backend, so its annotations are the union
+    if (service.annotations !== undefined)
+      mono.annotations = Object.assign(mono.annotations ?? {}, service.annotations)
+
     if (service.ingress !== undefined) {
       const { path, hosts, ...ingress } = service.ingress
 
@@ -154,5 +156,3 @@ function unit (context, dependency) {
 
   return mono
 }
-
-exports.describe = describe

package/src/deployment/.deployment/index.js

@@ -1,9 +1,3 @@
-'use strict'
-
-const { declare } = require('./declare')
-const { describe } = require('./describe')
-const { merge } = require('./merge')
-
-exports.declare = declare
-exports.describe = describe
-exports.merge = merge
+export { declare } from './declare.js'
+export { describe } from './describe.js'
+export { merge } from './merge.js'

package/src/deployment/.deployment/merge.js

@@ -1,6 +1,4 @@
-'use strict'
-
-const merge = (dependencies) => {
+export const merge = (dependencies) => {
   /** @type {toa.deployment.dependency.Reference[]} */
   const references = []
 
@@ -74,5 +72,3 @@ const append = (merged, variables) => {
     merged[component].push(...vars)
   }
 }
-
-exports.merge = merge

package/src/deployment/.deployment/merge.test.js

@@ -1,6 +1,7 @@
-'use strict'
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
 
-const { merge } = require('./merge')
+import { merge } from './merge.js'
 
 const service = (name, extra = {}) => ({ group: 'group', name, version: '0', ...extra })
 
@@ -10,7 +11,7 @@ it('should merge services of all dependencies', () => {
     { services: [service('two', { port: 8001 })] }
   ])
 
-  expect(merged.services).toHaveLength(2)
+  assert.strictEqual(merged.services.length, 2)
 })
 
 /*
@@ -24,8 +25,7 @@ describe('port reservation', () => {
       { services: [service('two', { port: 8000 })] }
     ]
 
-    expect(() => merge(dependencies))
-      .toThrow("Port 8000 is claimed by both 'group-one' and 'group-two'")
+    assert.throws(() => merge(dependencies), (error) => /Port 8000 is claimed by both 'group-one' and 'group-two'/.test(error.message))
   })
 
   it('should reject a service claiming the port of the readiness probe', () => {
@@ -34,8 +34,7 @@ describe('port reservation', () => {
       { services: [service('one', { port: 8001 })] }
     ]
 
-    expect(() => merge(dependencies))
-      .toThrow("Port 8001 is claimed by both the readiness probe and 'group-one'")
+    assert.throws(() => merge(dependencies), (error) => /Port 8001 is claimed by both the readiness probe and 'group-one'/.test(error.message))
   })
 
   it('should reject a probe claiming the port of another service', () => {
@@ -44,8 +43,7 @@ describe('port reservation', () => {
       { services: [service('two', { port: 8002, probe: { path: '/.ready', port: 8000 } })] }
     ]
 
-    expect(() => merge(dependencies))
-      .toThrow("Port 8000 is claimed by both 'group-one' and the readiness probe of 'group-two'")
+    assert.throws(() => merge(dependencies), (error) => /Port 8000 is claimed by both 'group-one' and the readiness probe of 'group-two'/.test(error.message))
   })
 
   it('should allow a service to probe its own port', () => {
@@ -53,7 +51,7 @@ describe('port reservation', () => {
       { services: [service('one', { port: 8000, probe: { path: '/.ready', port: 8000 } })] }
     ]
 
-    expect(() => merge(dependencies)).not.toThrow()
+    assert.doesNotThrow(() => merge(dependencies))
   })
 
   it('should ignore services without a port', () => {
@@ -61,7 +59,7 @@ describe('port reservation', () => {
       { services: [service('one'), service('two')] }
     ]
 
-    expect(() => merge(dependencies)).not.toThrow()
+    assert.doesNotThrow(() => merge(dependencies))
   })
 
   it('should ignore a disabled probe', () => {
@@ -69,6 +67,6 @@ describe('port reservation', () => {
       { probe: false, services: [service('one', { port: 8000, probe: false })] }
     ]
 
-    expect(() => merge(dependencies)).not.toThrow()
+    assert.doesNotThrow(() => merge(dependencies))
   })
 })

package/src/deployment/chart/templates/mono.yaml

@@ -116,6 +116,10 @@ apiVersion: v1
 kind: Service
 metadata:
   name: mono
+  {{- if .annotations }}
+  annotations:
+{{ toYaml .annotations | indent 4 }}
+  {{- end }}
 spec:
   type: ClusterIP
   selector:

package/src/deployment/chart/templates/services.yaml

@@ -88,6 +88,10 @@ apiVersion: v1
 kind: Service
 metadata:
   name: extension-{{ .name }}
+  {{- if .annotations }}
+  annotations:
+{{ toYaml .annotations | indent 4 }}
+  {{- end }}
 spec:
   type: ClusterIP
   selector:

package/src/deployment/composition.js

@@ -1,6 +1,4 @@
-'use strict'
-
-class Composition {
+export class Composition {
   name
   image
   /** @type {string[]} */
@@ -15,5 +13,3 @@ class Composition {
 }
 
 const component = (component) => component.locator.label
-
-exports.Composition = Composition

package/src/deployment/deployment.js

@@ -1,13 +1,11 @@
-'use strict'
+import { join } from 'node:path'
+import { writeFile as write } from 'node:fs/promises'
+import { yaml as jsyaml } from '@toa.io/generic'
+import fs from 'fs-extra'
 
-const { join } = require('node:path')
-const { writeFile: write } = require('node:fs/promises')
-const jsyaml = require('js-yaml')
-const fs = require('fs-extra')
+import { merge, declare, describe } from './.deployment/index.js'
 
-const { merge, declare, describe } = require('./.deployment')
-
-class Deployment {
+export class Deployment {
   #chart
   #values
   #process
@@ -89,10 +87,11 @@ function addVariables (list, variables, used = new Set()) {
   }
 }
 
-const TEMPLATES = join(__dirname, 'chart/templates')
+const TEMPLATES = join(import.meta.dirname, 'chart/templates')
+
 
-exports.Deployment = Deployment
 
 function dump (object) {
-  return jsyaml.dump(object, { noRefs: true, lineWidth: -1 })
+  // js-yaml writes plain objects only, and the values carry locators and images
+  return jsyaml.dump(JSON.parse(JSON.stringify(object)), { noRefs: true, lineWidth: -1 })
 }

package/src/deployment/factory.js

@@ -1,15 +1,20 @@
-'use strict'
-
-const { context: load } = require('@toa.io/norm')
-const { Process } = require('../process')
-const { Operator } = require('./operator')
-const { Factory: ImagesFactory } = require('./images')
-const { Deployment } = require('./deployment')
-const { Registry } = require('./registry')
-const { Composition } = require('./composition')
-const { Service } = require('./service')
-
-class Factory {
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
+import { context as load } from '@toa.io/norm'
+import { Process } from '../process.js'
+import { Operator } from './operator.js'
+import { Factory as ImagesFactory } from './images/index.js'
+import { Deployment } from './deployment.js'
+
+// a dependency is resolved the way a package is
+const require = createRequire(import.meta.url)
+import { Registry } from './registry.js'
+import { Composition } from './composition.js'
+import { Service } from './service.js'
+
+export class Factory {
   #context
   #mono
   #compositions
@@ -37,11 +42,12 @@ class Factory {
       this.#compositions = context.compositions.map((composition) => this.#composition(composition))
   }
 
-  operator () {
+  async operator () {
     const deployment = new Deployment(
       this.#context,
       this.#compositions,
-      this.#dependencies,
+      // the constructor cannot await, so what it started is settled here
+      await this.#dependencies,
       this.#process,
       this.#image
     )
@@ -59,14 +65,14 @@ class Factory {
     return new Composition(composition, image)
   }
 
-  #getDependencies () {
+  async #getDependencies () {
     /** @type {toa.deployment.Dependency[]} */
     const dependencies = []
 
     if (this.#context.dependencies === undefined) return dependencies
 
     for (const [reference, instances] of Object.entries(this.#context.dependencies)) {
-      const dependency = this.#getDependency(reference, instances)
+      const dependency = await this.#getDependency(reference, instances)
 
       if (dependency !== undefined) dependencies.push(dependency)
     }
@@ -74,9 +80,11 @@ class Factory {
     return dependencies
   }
 
-  #getDependency (path, instances) {
-    const module = require(path)
-    const pkg = require(path + '/package.json')
+  async #getDependency (reference, instances) {
+    // a dependency may be named the way a package is or written as a directory,
+    // and a module is loaded by file
+    const module = await import(pathToFileURL(require.resolve(reference)).href)
+    const pkg = JSON.parse(readFileSync(require.resolve(join(reference, 'package.json')), 'utf8'))
 
     if (module.deployment === undefined) return
 
@@ -87,7 +95,7 @@ class Factory {
 
     /** @type {toa.deployment.Service[]} */
     const services = dependency.services?.map((service) =>
-      this.#mono ? service : this.#service(path, service))
+      this.#mono ? service : this.#service(reference, service))
 
     return { ...dependency, services }
   }
@@ -109,5 +117,3 @@ class Factory {
     return new Factory(context, options)
   }
 }
-
-exports.Factory = Factory

package/src/deployment/images/composition.Dockerfile

@@ -13,7 +13,7 @@ COPY --chown=node:node . /composition
 
 # run 'npm i' in each component
 RUN --mount=type=cache,target=/root/.npm \
-  for entry in *; do if [ -f "$entry/package.json" ]; then (cd $entry && npm i --omit=dev); fi; done
+  for entry in *; do if grep -qs '"dependencies"' "$entry/package.json"; then (cd $entry && npm i --omit=dev); fi; done
 
 USER node
 CMD toa compose *

package/src/deployment/images/composition.js

@@ -1,13 +1,12 @@
-'use strict'
+import { join } from 'node:path'
+import fs from 'fs-extra'
+import { createHash } from 'node:crypto'
 
-const { join } = require('node:path')
-const fs = require('fs-extra')
-const { createHash } = require('node:crypto')
+import { Image } from './image.js'
+import { declare } from './format.js'
 
-const { Image } = require('./image')
-
-class Composition extends Image {
-  dockerfile = join(__dirname, 'composition.Dockerfile')
+export class Composition extends Image {
+  dockerfile = join(import.meta.dirname, 'composition.Dockerfile')
 
   #name
   #image
@@ -64,11 +63,12 @@ class Composition extends Image {
     const context = await super.prepare(root)
 
     for (const component of this.#components) {
-      await fs.copy(component.path, join(context, component.locator.label))
+      const target = join(context, component.locator.label)
+
+      await fs.copy(component.path, target)
+      await declare(component.path, target, component.locator.label)
     }
 
     return context
   }
 }
-
-exports.Composition = Composition