@toa.io/operations 1.0.0-alpha.291 → 1.0.0-alpha.293

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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.293](https://github.com/toa-io/toa/compare/v1.0.0-alpha.292...v1.0.0-alpha.293) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.292](https://github.com/toa-io/toa/compare/v1.0.0-alpha.291...v1.0.0-alpha.292) (2026-09-07)
+
+### Features
+
+* **cli:** the deployment library is a peer, and the binary is the CLI's ([a923f81](https://github.com/toa-io/toa/commit/a923f8173a55ed1c091213a7c7db1863ca1d0ba6))
+* **norm:** a package's definition is read by one resolver ([bffd41c](https://github.com/toa-io/toa/commit/bffd41c8d18c42786b0bf321623088b9dabc4724))
+
+
 # [1.0.0-alpha.291](https://github.com/toa-io/toa/compare/v1.0.0-alpha.290...v1.0.0-alpha.291) (2026-09-07)
 
 **Note:** Version bump only for package @toa.io/operations

package/image/runtime.Dockerfile

@@ -1,4 +1,18 @@
 FROM node:24.14.0-alpine3.22
 
 ARG VERSION
-RUN npm i -g @toa.io/runtime@${VERSION} --omit=dev
+
+# installed locally rather than globally: the binary is @toa.io/cli's, which the runtime depends
+# on, and npm links a dependency's binaries only into a local `node_modules/.bin`
+WORKDIR /toa
+
+# mounted rather than written: npm's cache is a hundred megabytes, and a layer keeps whatever
+# the command left behind.
+# `--legacy-peer-deps` installs no peer this does not ask for: `promex`, `reretry` and
+# `matchacho` declare `typescript` a peer without marking it optional, and nothing here imports
+# it. Every other peer in the closure is a dependency of the runtime's already. Drop the flag
+# once those three are published with `peerDependenciesMeta`.
+RUN --mount=type=cache,target=/root/.npm,sharing=locked \
+  npm i @toa.io/runtime@${VERSION} --omit=dev --legacy-peer-deps
+
+ENV PATH=/toa/node_modules/.bin:$PATH

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/operations",
-  "version": "1.0.0-alpha.291",
+  "version": "1.0.0-alpha.293",
   "type": "module",
   "description": "Toa Deployment",
   "homepage": "https://toa.io",
@@ -28,9 +28,11 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/generic": "1.0.0-alpha.291",
-    "@toa.io/norm": "1.0.0-alpha.291",
-    "js-yaml": "5.4.1"
+    "@toa.io/generic": "1.0.0-alpha.292",
+    "@toa.io/kubernetes": "1.0.0-alpha.293",
+    "@toa.io/norm": "1.0.0-alpha.293",
+    "oxc-parser": "0.149.0",
+    "paseto": "4.0.0"
   },
-  "gitHead": "bcd8d8d07bd3e64fc826af8719472404662cc37f"
+  "gitHead": "1e05b3ab64758324c58c425f1f8e52e9f35f1da8"
 }

package/readme.md

@@ -1,5 +1,27 @@
 # Toa Operations
 
+## Installing
+
+`toa deploy`, `toa build`, `toa push`, `toa env`, `toa export` and `toa conceal` need this package
+beside the CLI; the runtime does not carry it, and a container that runs a composition cannot
+deploy one. An application that deploys lists it with the runtime:
+
+```shell
+$ npm i -D @toa.io/runtime @toa.io/operations
+```
+
+A machine that only deploys needs no runtime and no extension:
+
+```shell
+$ npm i @toa.io/cli @toa.io/operations
+$ npx toa deploy production -p application
+```
+
+What the extensions declare is read from `@toa.io/definitions`, which the CLI brings; what they run
+is not needed to render a chart. `registry.services: build` is the exception: it builds an
+extension's service image from the installed package, so it needs the runtime installed beside
+this one. `published` does not.
+
 ## Compositions
 
 A composition is deployed as one pod. Beside its components it may run extension services,
@@ -27,7 +49,8 @@ Deploy images default to `FROM ghcr.io/toa-io/runtime:<runtime.version>`
 installed; composition/service Dockerfiles only install component dependencies.
 
 To use a custom base image, set `registry.build.image` (or `composition.image`).
-That image must provide the `toa` CLI, or install it via `registry.build.run`:
+That image must provide the `toa` CLI, or install it via `registry.build.run`. The binary is
+`@toa.io/cli`'s, which the runtime depends on, so a local install puts it on the `PATH`:
 
 ```yaml
 # context.toa.yaml
@@ -35,25 +58,44 @@ That image must provide the `toa` CLI, or install it via `registry.build.run`:
 registry:
   build:
     image: node:24.14.0-alpine3.22
-    run: npm i -g @toa.io/runtime --omit=dev
+    run: |
+      npm i --prefix /toa @toa.io/runtime --omit=dev
+      ln -s /toa/node_modules/.bin/toa /usr/local/bin/toa
 ```
 
+`/toa` is where it goes: what an extension needs for what a component declares is installed
+there, beside the extension that reads the declaration.
+
 #### Composition Images
 
 A composition is two images in one repository. `composition-<name>:deps-<hash>` is what its
 components depend on, installed on the base image: it is tagged by everything the install
-reads — the runtime version, the base image, the build options and each component's
-`package.json` (and `package-lock.json`, where there is one) — and is built only when one of
-those changes. `composition-<name>:<hash>` is the sources laid over it in a single linked
+reads — the runtime version, the base image, the build options, each component's
+`package.json` (and `package-lock.json`, where there is one), and what the extensions install
+for what the components declare — and is built only when one of those changes. `composition-<name>:<hash>` is the sources laid over it in a single linked
 layer, so a deploy that changes code alone builds and pushes that layer, and neither
 downloads nor uploads the dependencies again. The same holds for `mono`.
 
+Beside each component's sources the layer carries `manifest.toa.json`, the manifest as this
+build normalised it. A composition reads it instead of normalising again, so it loads no
+bridge to read what a module declares; a workspace has no such file and is read as it always
+was. What a build cannot express there — a prototype in a directory of the application's own
+rather than in a package — fails the build, where before it failed the container.
+
 A pushed image builds on the `toa` container builder, whose registry exporter is what lays
 an image over a base it never pulled; `toa build` loads on the daemon's own.
 
 A dependency named by a moving git ref is installed when the dependencies image is built and
 not again until its manifest changes, so pin such a dependency to a commit and bump it there.
 
+An extension's heavy dependency is not installed with the extension: `@toa.io/extensions.storages`
+declares the AWS and Cloudinary SDKs as optional peers, so the base image carries neither. What a
+component declares is what a deploy installs — the storages named in its `manifest.toa.yaml`,
+resolved through the context's annotation to their providers' packages, installed into `/toa`
+beside the extension that reads them. A composition whose components declare no `s3` storage
+carries no AWS SDK, whatever the context declares for another composition. A workspace installs
+the same set with `toa npm`.
+
 #### Extension Service Images
 
 `registry.services` says where an extension service's image comes from.

package/src/deployment/factory.js

@@ -1,15 +1,9 @@
-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 { context as load, definition } 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'
@@ -47,7 +41,9 @@ export class Factory {
 
     if (this.#mono)
       this.#image = this.#registry.mono({
-        components: context.components
+        components: context.components,
+        // mono runs every service, so it installs what every one of them brings
+        packages: context.packages
       })
     else
       this.#compositions = context.compositions.map((composition) =>
@@ -110,16 +106,11 @@ export class Factory {
   }
 
   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')
-    )
+    const { name, module } = await definition(reference)
 
     if (module.deployment === undefined) return
 
-    const annotation = this.#context.annotations?.[pkg.name]
+    const annotation = this.#context.annotations?.[name]
 
     /** @type {toa.deployment.dependency.Declaration} */
     const dependency = module.deployment(instances, annotation)

package/src/deployment/images/bundle.js

@@ -4,7 +4,7 @@ import { createHash } from 'node:crypto'
 
 import { Image } from './image.js'
 import { Dependencies } from './dependencies.js'
-import { declare } from './format.js'
+import { declare, normalized } from './format.js'
 
 /**
  * Components in one image: their sources laid over their dependencies, which are an image
@@ -23,11 +23,16 @@ export class Bundle extends Image {
   /** @type {toa.norm.Component[]} */
   components
 
+  /** What the services this workload runs install, which no component of it declares.
+   *  @type {Record<string, string> | undefined} */
+  packages
+
   constructor(scope, runtime, registry, composition) {
     super(scope, runtime, registry)
 
     this.image = composition.image
     this.components = composition.components
+    this.packages = composition.packages
     this.dependencies = new Dependencies(scope, runtime, registry, this)
   }
 
@@ -73,6 +78,7 @@ export class Bundle extends Image {
       // what was installed in the workspace is not what the image installs
       await cp(component.path, target, { recursive: true, filter: sources })
       await declare(component.path, target, component.locator.label)
+      await normalized(component, target)
     }
 
     return context

package/src/deployment/images/dependencies.Dockerfile

@@ -11,6 +11,13 @@ COPY --chown=node:node . /composition
 
 {{build.run}}
 
-# the context holds the manifests alone, so this is every dependency and none of the sources
+# the context holds the manifests alone, so this is every dependency and none of the sources.
+# `.packages` is a dotfile, so the glob does not reach it
 RUN --mount=type=cache,target=/root/.npm,sharing=locked \
   for entry in *; do if grep -qs '"dependencies"' "$entry/package.json"; then (cd $entry && npm i --omit=dev); fi; done
+
+# what the extensions need for what these components declare: installed beside the extension
+# that reads the declaration, in Toa's own install, because that is where Node resolves an
+# extension's imports from — and one copy for the composition rather than one per component
+RUN --mount=type=cache,target=/root/.npm,sharing=locked \
+  if [ -s .packages ]; then npm i --prefix /toa --omit=dev $(cat .packages); fi

package/src/deployment/images/dependencies.js

@@ -1,6 +1,6 @@
 import { basename, join } from 'node:path'
 import { existsSync, readFileSync } from 'node:fs'
-import { copyFile, mkdir } from 'node:fs/promises'
+import { copyFile, mkdir, writeFile } from 'node:fs/promises'
 import { createHash } from 'node:crypto'
 
 import { Image } from './image.js'
@@ -68,6 +68,8 @@ export class Dependencies extends Image {
       for (const file of files)
         hash.update(label).update(basename(file)).update(readFileSync(file))
 
+    hash.update(this.#packages().join('\n'))
+
     this.#version = hash.digest('hex').slice(0, 8)
 
     return this.#version
@@ -112,9 +114,34 @@ export class Dependencies extends Image {
       for (const file of files) await copyFile(file, join(target, basename(file)))
     }
 
+    const packages = this.#packages()
+
+    // written whether or not there are any, so the file is one thing the Dockerfile reads
+    await writeFile(join(context, PACKAGES), packages.join('\n'))
+
     return context
   }
 
+  /**
+   * What the extensions install for what this workload runs, as `name@version`: what its
+   * components declare, and what the services it hosts bring. A component states its own
+   * dependencies in its manifest; this is what the packages that read its declaration need,
+   * which its manifest has no way to say.
+   *
+   * @returns {string[]}
+   */
+  #packages() {
+    /** @type {Record<string, string>} */
+    const packages = { ...this.#owner.packages }
+
+    for (const component of this.#owner.components)
+      Object.assign(packages, component.packages)
+
+    return Object.entries(packages)
+      .map(([name, version]) => `${name}@${version}`)
+      .sort()
+  }
+
   /**
    * The files the install reads, by component label, in a fixed order.
    *
@@ -139,3 +166,6 @@ const PREFIX = 'deps-'
 const DIRECTORY = 'dependencies'
 
 const MANIFESTS = ['package.json', 'package-lock.json']
+
+/** Where the install reads what the extensions need, one `name@version` per line. */
+const PACKAGES = '.packages'

package/src/deployment/images/dependencies.test.js

@@ -90,6 +90,20 @@ describe('reference', () => {
     assert.notStrictEqual(create().dependencies.reference, run.dependencies.reference)
   })
 
+  it('should change with what an extension installs', () => {
+    const before = create()
+
+    composition.components[1].packages = { cloudinary: '2.11.0' }
+
+    const component = create()
+
+    assert.notStrictEqual(component.dependencies.reference, before.dependencies.reference)
+
+    composition.packages = { 'lru-cache': '11.5.2' }
+
+    assert.notStrictEqual(create().dependencies.reference, component.dependencies.reference)
+  })
+
   it('should change with the registry build settings', () => {
     const before = create()
 
@@ -128,6 +142,7 @@ describe('prepare', () => {
 
     assert.deepStrictEqual(entries, [
       '.dockerignore',
+      '.packages',
       'Dockerfile',
       'one',
       'one/package.json',
@@ -144,6 +159,44 @@ describe('prepare', () => {
     assert.doesNotMatch(dockerfile, /USER node|CMD /)
   })
 
+  it('should hold what the extensions install, deduplicated and ordered', async () => {
+    composition.components[0].packages = { cloudinary: '2.11.0' }
+    composition.components[1].packages = {
+      cloudinary: '2.11.0',
+      '@aws-sdk/client-s3': '3.1125.0'
+    }
+
+    const image = create()
+    const context = await image.dependencies.prepare(root)
+
+    assert.strictEqual(
+      await readFile(join(context, '.packages'), 'utf8'),
+      '@aws-sdk/client-s3@3.1125.0\ncloudinary@2.11.0'
+    )
+
+    const dockerfile = await readFile(join(context, 'Dockerfile'), 'utf8')
+
+    assert.ok(dockerfile.includes('npm i --prefix /toa --omit=dev $(cat .packages)'))
+  })
+
+  it('should hold what a service the composition runs brings', async () => {
+    composition.packages = { 'lru-cache': '11.5.2' }
+    composition.components[0].packages = { cloudinary: '2.11.0' }
+
+    const context = await create().dependencies.prepare(root)
+
+    assert.strictEqual(
+      await readFile(join(context, '.packages'), 'utf8'),
+      'cloudinary@2.11.0\nlru-cache@11.5.2'
+    )
+  })
+
+  it('should hold an empty list where nothing is declared', async () => {
+    const context = await create().dependencies.prepare(root)
+
+    assert.strictEqual(await readFile(join(context, '.packages'), 'utf8'), '')
+  })
+
   it('should lay the sources over the dependencies', async () => {
     const image = create()
 
@@ -167,6 +220,7 @@ describe('prepare', () => {
 
     assert.ok(entries.includes('one/index.js'))
     assert.ok(entries.includes('two/package.json')) // declared for the component that had none
+    assert.ok(entries.includes('one/manifest.toa.json')) // what the process reads instead of normalizing
     assert.ok(!entries.some((entry) => entry.includes('node_modules')))
   })
 

package/src/deployment/images/format.js

@@ -2,6 +2,8 @@ import { existsSync, readFileSync } from 'node:fs'
 import { writeFile } from 'node:fs/promises'
 import { dirname, join, parse } from 'node:path'
 
+import { NORMALIZED, plain } from '@toa.io/norm'
+
 /**
  * A component is copied into the image on its own, away from the package that
  * declared what its files are. Node reads a `.js` as CommonJS unless a manifest
@@ -23,6 +25,18 @@ export async function declare(source, target, name) {
   )
 }
 
+/**
+ * The manifest as this build read it, written beside the component so that the process which
+ * runs it does not read it again. See `plain` in `@toa.io/norm` for what is left out and why
+ * a build's answer is the one to trust.
+ *
+ * @param {toa.norm.Component} component
+ * @param {string} target where it was copied
+ */
+export async function normalized(component, target) {
+  await writeFile(join(target, NORMALIZED), JSON.stringify(plain(component)))
+}
+
 /**
  * The module format a directory's files are read as, which the nearest manifest
  * above it decides.

package/src/deployment/images/format.test.js

@@ -4,7 +4,10 @@ import { mkdtemp, mkdir, writeFile, readFile, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
-import { declare, format } from './format.js'
+import { Locator } from '@toa.io/core'
+import { revive } from '@toa.io/norm'
+
+import { declare, format, normalized } from './format.js'
 
 let root
 
@@ -72,3 +75,39 @@ describe('declare', () => {
     assert.strictEqual(await readFile(join(target, 'package.json'), 'utf8'), own)
   })
 })
+
+describe('normalized', () => {
+  it('should write what a process reads instead of normalizing', async () => {
+    const target = join(root, 'image', 'normalized')
+
+    await mkdir(target, { recursive: true })
+
+    const component = {
+      name: 'tasks',
+      namespace: 'todos',
+      version: 'abcdef12',
+      operations: { compute: { type: 'computation' } },
+      path: '/workspace/components/todos.tasks',
+      locator: new Locator('tasks', 'todos'),
+      packages: { cloudinary: '2.11.0' }
+    }
+
+    await normalized(component, target)
+
+    const carried = JSON.parse(
+      await readFile(join(target, 'manifest.toa.json'), 'utf8')
+    )
+
+    // where the manifest is, and what only a deploy reads, are not what it declares
+    assert.ok(!('path' in carried))
+    assert.ok(!('locator' in carried))
+    assert.ok(!('packages' in carried))
+
+    const read = revive(carried, '/composition/todos-tasks')
+
+    assert.deepStrictEqual(read.operations, component.operations)
+    assert.strictEqual(read.version, component.version)
+    assert.strictEqual(read.path, '/composition/todos-tasks')
+    assert.strictEqual(read.locator.id, 'todos.tasks')
+  })
+})

package/src/deployment/images/publish.js

@@ -2,7 +2,7 @@ import { mkdtemp, writeFile } from 'node:fs/promises'
 import { readFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { definition } from '@toa.io/norm'
 
 import { run } from '../../process.js'
 import { Service } from './service.js'
@@ -12,7 +12,7 @@ import { Service } from './service.js'
  * with `registry.services: published` takes it instead of building one.
  *
  * The image is built from the package as npm publishes it, not from the workspace: what
- * `.npmignore` leaves out is not in the tarball, and an application builds from the tarball.
+ * `files` leaves out is not in the tarball, and an application builds from the tarball.
  *
  * @param {string} workspace path to the extension's directory in this repository
  * @param {string} runtime the runtime version, which is the tag and the base image
@@ -23,9 +23,7 @@ export async function publish(workspace, runtime, platforms) {
   const directory = resolve(workspace)
   const manifest = read(join(directory, 'package.json'))
 
-  // read from the workspace, where the extension's own dependencies resolve; what is
-  // installed below carries the same constant but not everything it takes to load it
-  const { image } = await import(pathToFileURL(join(directory, manifest.main)).href)
+  const { image } = (await definition(manifest.name)).module
 
   if (image === undefined)
     throw new Error(

package/src/deployment/images/service.Dockerfile

@@ -10,6 +10,12 @@ COPY --chown=node:node . /service
 RUN --mount=type=cache,target=/root/.npm,sharing=locked \
   npm i --omit=dev
 
+# a component of the extension's own declares what it imports, and it is installed beside the
+# component rather than beside the extension: an application that runs none of them, and the
+# runtime image every application is built on, carry nothing for them
+RUN --mount=type=cache,target=/root/.npm,sharing=locked \
+  for entry in components/*; do if grep -qs '"dependencies"' "$entry/package.json"; then (cd $entry && npm i --omit=dev); fi; done
+
 # no USER: the runtime drops to `node` itself, and only a process that started as root can
 # close its environment under /proc — see runtime/runtime/bin/toa
 CMD toa serve .

package/src/deployment/images/service.js

@@ -66,9 +66,22 @@ export class Service extends Image {
 }
 
 /**
+ * Where the extension is installed, which is what its image is built from. A deploy install
+ * carries what an extension declares and not the extension, so a service is built only where
+ * the runtime is installed beside the deployment library; elsewhere its image is published.
+ *
  * @param {string} reference
  * @returns {string}
  */
 const find = (reference) => {
-  return dirname(require.resolve(join(reference, 'package.json')))
+  try {
+    return dirname(require.resolve(join(reference, 'package.json')))
+  } catch (error) {
+    throw new Error(
+      `'${reference}' is not installed, and \`registry.services: build\` builds its image ` +
+        'from where it is: install the runtime beside @toa.io/operations, or take the ' +
+        'image the release publishes with `registry.services: published`',
+      { cause: error }
+    )
+  }
 }

package/src/index.js

@@ -1 +1,4 @@
 export * as deployment from './deployment/index.js'
+
+// what conceals a secret in the cluster a deployment goes to; the CLI needs no package of its own for it
+export * as kubernetes from '@toa.io/kubernetes'