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

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 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.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,9 @@
 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
+RUN npm i @toa.io/runtime@${VERSION} --omit=dev
+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.292",
   "type": "module",
   "description": "Toa Deployment",
   "homepage": "https://toa.io",
@@ -28,9 +28,10 @@
     "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",
+    "@toa.io/generic": "1.0.0-alpha.292",
+    "@toa.io/kubernetes": "1.0.0-alpha.286",
+    "@toa.io/norm": "1.0.0-alpha.292",
     "js-yaml": "5.4.1"
   },
-  "gitHead": "bcd8d8d07bd3e64fc826af8719472404662cc37f"
+  "gitHead": "0f6aa3ad9dbec86bb632a7975ea61d1dde1d8fc5"
 }

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,7 +58,9 @@ 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
 ```
 
 #### Composition Images

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'
@@ -110,16 +104,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/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'
@@ -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.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'