@toa.io/boot 1.0.0-alpha.288 → 1.0.0-alpha.289

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 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.289](https://github.com/toa-io/toa/compare/v1.0.0-alpha.288...v1.0.0-alpha.289) (2026-09-07)
+
+* A deploy moves only what changed, and a component sees none of the runtime's environment (#1073) ([f38e3db](https://github.com/toa-io/toa/commit/f38e3db533f24db866c57bfa1ef294eff1eaf499)), closes [#1073](https://github.com/toa-io/toa/issues/1073) [#1064](https://github.com/toa-io/toa/issues/1064) [#1066](https://github.com/toa-io/toa/issues/1066) [#1067](https://github.com/toa-io/toa/issues/1067) [#1068](https://github.com/toa-io/toa/issues/1068) [#1069](https://github.com/toa-io/toa/issues/1069) [#1071](https://github.com/toa-io/toa/issues/1071) [#1070](https://github.com/toa-io/toa/issues/1070) [#1072](https://github.com/toa-io/toa/issues/1072)
+
+### BREAKING CHANGES
+
+* a component that read `process.env.TOA_*` reads `context` instead;
+  `echo(input)` no longer substitutes from the environment; a bash operation sees no
+  `TOA_*`; images no longer set `USER node` — see migrations/289.md.
+
+
 # [1.0.0-alpha.288](https://github.com/toa-io/toa/compare/v1.0.0-alpha.287...v1.0.0-alpha.288) (2026-09-06)
 
 **Note:** Version bump only for package @toa.io/boot

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/boot",
-  "version": "1.0.0-alpha.288",
+  "version": "1.0.0-alpha.289",
   "type": "module",
   "description": "Toa Boot",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -21,14 +21,14 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/atomicity": "1.0.0-alpha.288",
-    "@toa.io/core": "1.0.0-alpha.288",
-    "@toa.io/generic": "1.0.0-alpha.286",
-    "@toa.io/norm": "1.0.0-alpha.288",
-    "@toa.io/schemas": "1.0.0-alpha.287",
+    "@toa.io/atomicity": "1.0.0-alpha.289",
+    "@toa.io/core": "1.0.0-alpha.289",
+    "@toa.io/generic": "1.0.0-alpha.289",
+    "@toa.io/norm": "1.0.0-alpha.289",
+    "@toa.io/schemas": "1.0.0-alpha.289",
     "clone-deep": "4.0.1",
     "dotenv": "17.4.2",
     "openspan": "1.0.0-alpha.286"
   },
-  "gitHead": "d3d696f0a4e287c3c297ac81028d600ad7574112"
+  "gitHead": "4fcb482beac5896305d8084cdbc1d5fcf372d108"
 }

package/src/component.js

@@ -1,6 +1,7 @@
 import { Component, Locator, State, entities } from '@toa.io/core'
 import { entity as declaration } from '@toa.io/norm'
 import { schema as compileSchema } from '@toa.io/schemas'
+import { environment } from '@toa.io/generic'
 
 import * as boot from './index.js'
 import { span } from './span.js'
@@ -12,6 +13,10 @@ export const component = async (manifest) => {
 }
 
 const create = async (manifest, locator) => {
+  // what a test set after this package loaded goes to the store now, before a module of the
+  // component is imported: nothing of it is left in `process.env` for that module to read
+  environment.absorb()
+
   await boot.extensions.load(manifest)
 
   // the storage is told whether there will be an outbox, so the events come first

package/src/composition.js

@@ -1,11 +1,16 @@
 import { console } from 'openspan'
 import { Composition } from '@toa.io/core'
 import { version } from '@toa.io/runtime'
+import { environment } from '@toa.io/generic'
 
 import * as boot from './index.js'
 import { span } from './span.js'
 
 export async function composition(paths, options) {
+  // what a test set after this package loaded goes to the store now, before a module of a
+  // component is imported: nothing of it is left in `process.env` for that module to read
+  environment.absorb()
+
   options = Object.assign({}, options)
 
   return span('boot composition', async () => {

package/src/env.js

@@ -1,15 +1,22 @@
+import { readFileSync } from 'node:fs'
 import dotenv from 'dotenv'
-import { findUp } from '@toa.io/generic'
+import { environment, findUp } from '@toa.io/generic'
 
 /*
- * A local run reads what `toa env` wrote. `dotenv` leaves a variable that is already set
- * alone, so what the environment says still wins and reading the file costs nothing where
- * there is none — a deployment has no `.env` to find.
+ * A local run reads what `toa env` wrote. What the file says goes to the environment store
+ * and never into `process.env`: a `.env` is where a local run keeps its secrets, and a
+ * component's code must not find them. A variable already set is left alone, as `dotenv`
+ * left it, so what the environment says still wins — and reading the file costs nothing
+ * where there is none: a deployment has no `.env` to find.
  *
  * It used to be read only where `TOA_ENV` was unset, taking that one variable as proof the
  * environment had been injected. Setting it for any other reason then dropped the file
  * whole, and every variable in it with it.
  */
+export function load(path) {
+  environment.absorbEntries(dotenv.parse(readFileSync(path, 'utf8')))
+}
+
 const path = findUp('.env')
 
-if (path !== undefined) dotenv.config({ path })
+if (path !== undefined) load(path)

package/src/events.js

@@ -1,3 +1,5 @@
+import { environment } from '@toa.io/generic'
+
 /**
  * The events of this component that something consumes. An event nobody consumes is not
  * published, so it gets no emitter and no exchange, and a component none of whose events are
@@ -12,7 +14,7 @@
 export const events = (manifest) => {
   if (manifest.events === undefined) return
 
-  const value = process.env[VARIABLE + manifest.locator.uppercase]
+  const value = environment.get(VARIABLE + manifest.locator.uppercase)
 
   if (value === undefined) return manifest.events
 

package/src/index.js

@@ -1,6 +1,5 @@
 // the environment is read at module scope elsewhere, so it is loaded first
-// oxlint-disable-next-line import/no-unassigned-import
-import './env.js'
+import { load as env } from './env.js'
 
 import * as bindings from './bindings/index.js'
 import * as bridge from './bridge.js'
@@ -29,6 +28,7 @@ import { rc } from './rc.js'
 
 export {
   call,
+  env,
   cascade,
   component,
   composition,

package/src/span.js

@@ -1,6 +1,7 @@
 import { console, traces } from 'openspan'
+import { environment } from '@toa.io/generic'
 
-const enabled = process.env.TOA_BOOT_TRACE === '1'
+const enabled = environment.get('TOA_BOOT_TRACE') === '1'
 
 // Tracing is off until an exporter is configured, and the CLI opens its own span before
 // any extension gets to configure one — so asking for a boot trace turns the console

package/src/storage.js

@@ -20,8 +20,14 @@ export const storage = async (manifest, outbox) => {
   const factory = new Factory()
   const storage = factory.storage(manifest.locator, manifest.entity, { outbox })
 
-  // a component whose structure nothing will make must not start with the structure it lacks
-  if (manifest.entity.migrations?.length > 0 && storage.migrates !== true)
+  // a component whose structure nothing will make must not start with the structure it lacks;
+  // what it inherits was written for descendants that store, and one that stores nothing has
+  // nothing to convert
+  const own = manifest.entity.migrations?.some(
+    (migration) => migration.prototype === undefined
+  )
+
+  if (own === true && storage.migrates !== true)
     throw new Error(
       `Component '${manifest.locator.id}' declares migrations, ` +
         `which storage '${manifest.entity.storage}' does not apply`

package/src/storage.test.js

@@ -30,6 +30,16 @@ it('should refuse migrations a storage does not apply', async () => {
   )
 })
 
+it('should accept inherited migrations a storage does not apply', async () => {
+  const entity = {
+    schema,
+    storage: '@toa.io/storages.null',
+    migrations: [{ id: 'system:0001', steps: [], prototype: 'system' }]
+  }
+
+  assert.notEqual(await storage(manifest(entity), false), undefined)
+})
+
 it('should accept a storage with no migrations', async () => {
   const entity = { schema, storage: '@toa.io/storages.null' }