@toa.io/pointer 1.0.0-alpha.29 → 1.0.0-alpha.292

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Change Log
+
+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)
+
+**Note:** Version bump only for package @toa.io/pointer
+
+
+
+
+
+# [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/pointer
+
+
+
+
+
+# [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.287](https://github.com/toa-io/toa/compare/v1.0.0-alpha.286...v1.0.0-alpha.287) (2026-09-06)
+
+**Note:** Version bump only for package @toa.io/pointer

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@toa.io/pointer",
-  "version": "1.0.0-alpha.29",
+  "version": "1.0.0-alpha.292",
+  "type": "module",
   "description": "Toa Pointer",
   "homepage": "https://toa.io",
   "author": {
@@ -16,7 +17,7 @@
     "url": "https://github.com/toa-io/toa/issues"
   },
   "engines": {
-    "node": ">= 18.0.0"
+    "node": ">= 24.0.0"
   },
   "publishConfig": {
     "access": "public"
@@ -24,15 +25,11 @@
   "main": "transpiled/index.js",
   "types": "transpiled/index.d.ts",
   "dependencies": {
-    "@toa.io/generic": "1.0.0-alpha.29",
-    "@toa.io/schemas": "1.0.0-alpha.29"
+    "@toa.io/generic": "1.0.0-alpha.292",
+    "@toa.io/schemas": "1.0.0-alpha.292"
   },
   "scripts": {
     "transpile": "tsc"
   },
-  "jest": {
-    "preset": "ts-jest",
-    "testEnvironment": "node"
-  },
-  "gitHead": "186d0e17c12a9016b8076edf925963cbb32b9219"
+  "gitHead": "0f6aa3ad9dbec86bb632a7975ea61d1dde1d8fc5"
 }

package/readme.md

@@ -72,7 +72,7 @@ amqp:
 URL resolution for the example above is as follows:
 
 | Selector          | Result                               | Description        |
-|-------------------|--------------------------------------|--------------------|
+| ----------------- | ------------------------------------ | ------------------ |
 | `dummies.dummy`   | `amqp://d1.rmq.example.com`          | Exact match        |
 | `dummies.another` | `amqp://all-dummies.rmq.example.com` | Partial match      |
 | `what.ever`       | `amqp://default.rmq.example.com`     | No match (default) |

package/schemas/urimap.cos.yaml

@@ -1,2 +1,14 @@
-.: [uri]
-/^[a-zA-Z0-9]{1,32}(\.[a-zA-Z0-9]{1,32}){0,3}$/: [uri]
+properties:
+  .:
+    type: array
+    items:
+      type: string
+      format: uri
+additionalProperties: false
+type: object
+patternProperties:
+  ^[a-zA-Z0-9]{1,32}(\.[a-zA-Z0-9]{1,32}){0,3}$:
+    type: array
+    items:
+      type: string
+      format: uri

package/source/Deployment.ts

@@ -1,17 +1,17 @@
-import { nameVariable, nameSecret } from './naming'
-import { resolveRecord } from './resolve'
+import { nameVariable, nameSecret } from './naming.js'
+import { resolveRecord } from './resolve.js'
 import type { Variables, Variable } from '@toa.io/operations'
 
 export class Deployment {
   private readonly id: string
   private readonly annotation: URIMap
 
-  public constructor (id: string, annotation: URIMap) {
+  public constructor(id: string, annotation: URIMap) {
     this.id = id
     this.annotation = annotation
   }
 
-  public export (requests: Request[]): Variables {
+  public export(requests: Request[]): Variables {
     const variables: Variables = {}
 
     for (const request of requests)
@@ -20,7 +20,7 @@ export class Deployment {
     return variables
   }
 
-  private createVariables (selectors: string[]): Variable[] {
+  private createVariables(selectors: string[]): Variable[] {
     const variables: Variable[] = []
 
     for (const selector of selectors) {
@@ -33,7 +33,7 @@ export class Deployment {
     return variables
   }
 
-  private createVariable (selector: string): Variable {
+  private createVariable(selector: string): Variable {
     const name = nameVariable(this.id, selector)
     const { references } = this.resolveRecord(selector)
     const value = references.join(' ')
@@ -41,17 +41,13 @@ export class Deployment {
     return { name, value }
   }
 
-  private createSecrets (selector: string): Variable[] {
+  private createSecrets(selector: string): Variable[] {
     const variables: Variable[] = []
     const { key, references } = this.resolveRecord(selector)
 
     const protocol = new URL(references[0]).protocol
 
-    if (insecureProtocols.includes(protocol))
-      return []
-
-    if (protocol in specialProtocols)
-      return specialProtocols[protocol](references)
+    if (insecureProtocols.includes(protocol)) return []
 
     for (const token of ['username', 'password']) {
       const varName = nameVariable(this.id, selector, token)
@@ -69,7 +65,7 @@ export class Deployment {
     return variables
   }
 
-  private resolveRecord (selector: string): AnnotationRecord {
+  private resolveRecord(selector: string): AnnotationRecord {
     return resolveRecord(this.annotation, selector)
   }
 }
@@ -86,21 +82,4 @@ export interface AnnotationRecord {
 
 const insecureProtocols = ['http:', 'https:', 'redis:']
 
-const specialProtocols: Record<string, (references: string[]) => Variable[]> = {
-  'pubsub:': (references: string[]) => {
-    const path = new URL(references[0]).pathname
-    const [, , project] = path.split('/')
-    const name = nameVariable('ORIGINS_PUBSUB_', project)
-
-    return [{
-      name,
-      secret: {
-        name: 'toa-origins-pubsub',
-        key: project,
-        optional: true
-      }
-    } satisfies Variable]
-  }
-}
-
 export type URIMap = Record<string, string[]>

package/source/annotation.test.ts

@@ -1,18 +1,20 @@
-import { normalize } from './annotation'
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { normalize } from './annotation.js'
 
 describe('normalize', () => {
   it('should expand default shards', async () => {
     const declaration = 'amqp://rmq{0-2}.example.com'
     const annotation = normalize(declaration)
 
-    expect(annotation)
-      .toStrictEqual({
-        '.': [
-          'amqp://rmq0.example.com',
-          'amqp://rmq1.example.com',
-          'amqp://rmq2.example.com'
-        ]
-      })
+    assert.deepStrictEqual(annotation, {
+      '.': [
+        'amqp://rmq0.example.com',
+        'amqp://rmq1.example.com',
+        'amqp://rmq2.example.com'
+      ]
+    })
   })
 
   it('should expand shards within array', async () => {
@@ -22,15 +24,14 @@ describe('normalize', () => {
 
     const annotation = normalize(declaration)
 
-    expect(annotation)
-      .toStrictEqual({
-        foo: [
-          'amqp://rmq.example.com',
-          'amqp://rmq0.example.com',
-          'amqp://rmq1.example.com',
-          'amqp://rmq2.example.com'
-        ]
-      })
+    assert.deepStrictEqual(annotation, {
+      foo: [
+        'amqp://rmq.example.com',
+        'amqp://rmq0.example.com',
+        'amqp://rmq1.example.com',
+        'amqp://rmq2.example.com'
+      ]
+    })
   })
 })
 
@@ -38,29 +39,34 @@ describe('validation', () => {
   it('should pass', async () => {
     const declaration = 'http://localhost'
 
-    expect(() => normalize(declaration))
-      .not.toThrow()
+    assert.doesNotThrow(() => normalize(declaration))
   })
 
   it('should throw if non-uri', async () => {
     const declaration = 'non uri'
 
-    expect(() => normalize(declaration))
-      .toThrow('must match format')
+    assert.throws(
+      () => normalize(declaration),
+      (error: any) => /must match format/.test(error.message)
+    )
   })
 
-  it.each(['user:pass', 'user', ':pass'])('should throw if uri has credentials',
-    async (credentials) => {
+  for (const credentials of ['user:pass', 'user', ':pass'])
+    it('should throw if uri has credentials', async () => {
       const declaration = `http://${credentials}@localhost`
 
-      expect(() => normalize(declaration))
-        .toThrow('must not contain credentials')
+      assert.throws(
+        () => normalize(declaration),
+        (error: any) => /must not contain credentials/.test(error.message)
+      )
     })
 
   it('should throw if key is not deployable', async () => {
     const declaration = { 'foo bar': 'http://localhost' }
 
-    expect(() => normalize(declaration))
-      .toThrow('not expected')
+    assert.throws(
+      () => normalize(declaration),
+      (error: any) => /not expected/.test(error.message)
+    )
   })
 })

package/source/annotation.ts

@@ -2,9 +2,9 @@ import { resolve } from 'node:path'
 import * as schemas from '@toa.io/schemas'
 import { shards } from '@toa.io/generic'
 import type { Schema } from '@toa.io/schemas'
-import type { URIMap } from './Deployment'
+import type { URIMap } from './Deployment.js'
 
-export function normalize (declaration: Declaration): URIMap {
+export function normalize(declaration: Declaration): URIMap {
   const map: URIMap = {}
 
   if (declaration === undefined) return map
@@ -21,27 +21,31 @@ export function normalize (declaration: Declaration): URIMap {
   return map
 }
 
-function format (values: string[]): string[] {
+function format(values: string[]): string[] {
   return values.map(shards).flat()
 }
 
-function validate (map: URIMap): void {
+function validate(map: URIMap): void {
   schema.validate(map)
 
-  for (const uris of Object.values(map))
-    for (const uri of uris)
-      checkCredentials(uri)
+  for (const uris of Object.values(map)) for (const uri of uris) checkCredentials(uri)
 }
 
-function checkCredentials (uri: string): void {
+function checkCredentials(uri: string): void {
   const url = new URL(uri)
 
   if (url.username !== '' || url.password !== '')
-    throw new Error(`Pointer URI '${uri}' must not contain credentials. ` +
-      'Please refer to the "Credentials" section of the documentation for more information.')
+    throw new Error(
+      `Pointer URI '${uri}' must not contain credentials. ` +
+        'Please refer to the "Credentials" section of the documentation for more information.'
+    )
 }
 
-const path = resolve(__dirname, '../schemas/urimap.cos.yaml')
+const path = resolve(import.meta.dirname, '../schemas/urimap.cos.yaml')
 const schema: Schema<URIMap> = schemas.schema(path)
 
-export type Declaration = string | string[] | Record<string, string | string[]> | undefined
+export type Declaration =
+  | string
+  | string[]
+  | Record<string, string | string[]>
+  | undefined

package/source/createVariables.test.ts

@@ -1,7 +1,11 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+import { isDeepStrictEqual } from 'node:util'
+
 import { generate } from 'randomstring'
-import { createVariables } from './createVariables'
+import { createVariables } from './createVariables.js'
 import type { Variable, Variables } from '@toa.io/operations'
-import type { Request } from './Deployment'
+import type { Request } from './Deployment.js'
 
 it('should create from selector', async () => {
   const id = generate()
@@ -11,14 +15,15 @@ it('should create from selector', async () => {
   const variables = createVariables(id, annotation, [request])
 
   const expectation: Variables = {
-    [request.group]: [{
-      name: `TOA_${id.toUpperCase()}_${selector.toUpperCase()}`,
-      value: annotation[selector]
-    }]
+    [request.group]: [
+      {
+        name: `TOA_${id.toUpperCase()}_${selector.toUpperCase()}`,
+        value: annotation[selector]
+      }
+    ]
   }
 
-  expect(variables)
-    .toStrictEqual(expectation)
+  assert.deepStrictEqual(variables, expectation)
 })
 
 it('should create from partial match', async () => {
@@ -30,18 +35,15 @@ it('should create from partial match', async () => {
   const variables = createVariables(id, annotation, [request])
 
   const expectation: Variables = {
-    [request.group]: [{
-      name: `TOA_${id.toUpperCase()}_${
-        selector
-          .replace('.', '_')
-          .toUpperCase()
-      }`,
-      value: annotation[key]
-    }]
+    [request.group]: [
+      {
+        name: `TOA_${id.toUpperCase()}_${selector.replace('.', '_').toUpperCase()}`,
+        value: annotation[key]
+      }
+    ]
   }
 
-  expect(variables)
-    .toStrictEqual(expectation)
+  assert.deepStrictEqual(variables, expectation)
 })
 
 it('should create from default', async () => {
@@ -52,14 +54,15 @@ it('should create from default', async () => {
   const variables = createVariables(id, annotation, [request])
 
   const expectation: Variables = {
-    [request.group]: [{
-      name: `TOA_${id.toUpperCase()}_${selector.toUpperCase()}`,
-      value: annotation
-    }]
+    [request.group]: [
+      {
+        name: `TOA_${id.toUpperCase()}_${selector.toUpperCase()}`,
+        value: annotation
+      }
+    ]
   }
 
-  expect(variables)
-    .toStrictEqual(expectation)
+  assert.deepStrictEqual(variables, expectation)
 })
 
 it('should create from array', async () => {
@@ -71,14 +74,15 @@ it('should create from array', async () => {
   const variables = createVariables(id, annotation, [request])
 
   const expectation: Variables = {
-    [request.group]: [{
-      name: `TOA_${id.toUpperCase()}_${selector.toUpperCase()}`,
-      value: values.join(' ')
-    }]
+    [request.group]: [
+      {
+        name: `TOA_${id.toUpperCase()}_${selector.toUpperCase()}`,
+        value: values.join(' ')
+      }
+    ]
   }
 
-  expect(variables)
-    .toStrictEqual(expectation)
+  assert.deepStrictEqual(variables, expectation)
 })
 
 it('should create from default array', async () => {
@@ -90,14 +94,15 @@ it('should create from default array', async () => {
   const variables = createVariables(id, annotation, [request])
 
   const expectation: Variables = {
-    [request.group]: [{
-      name: `TOA_${id.toUpperCase()}_${selector.toUpperCase()}`,
-      value: values.join(' ')
-    }]
+    [request.group]: [
+      {
+        name: `TOA_${id.toUpperCase()}_${selector.toUpperCase()}`,
+        value: values.join(' ')
+      }
+    ]
   }
 
-  expect(variables)
-    .toStrictEqual(expectation)
+  assert.deepStrictEqual(variables, expectation)
 })
 
 it('should throw if selector cannot be resolved', async () => {
@@ -106,8 +111,10 @@ it('should throw if selector cannot be resolved', async () => {
   const annotation = {}
   const request: Request = { group: generate(), selectors: [selector] }
 
-  expect(() => createVariables(id, annotation, [request]))
-    .toThrow('cannot be resolved.')
+  assert.throws(
+    () => createVariables(id, annotation, [request]),
+    (error: any) => /cannot be resolved\./.test(error.message)
+  )
 })
 
 it('should create credential secrets for annotation keys', async () => {
@@ -135,35 +142,30 @@ it('should create credential secrets for annotation keys', async () => {
   const secrets2 = createExpectedSecrets(id, namespace, selector2)
   const secrets3 = createExpectedSecrets(id, '.', selector3)
 
-  const expectation: Variables = {
-    [group]: expect.arrayContaining([
-      ...secrets1,
-      ...secrets2,
-      ...secrets3
-    ])
-  }
+  const expected = [...secrets1, ...secrets2, ...secrets3]
 
-  expect(variables).toStrictEqual(expectation)
+  // the group holds every expected secret, in whatever order it built them
+  for (const secret of expected)
+    assert.ok(variables[group].some((one: any) => isDeepStrictEqual(one, secret)))
 })
 
-it.each([
-  'http:', 'redis:'
-])('should not create credetial secrets for %s', async (protocol) => {
-  const id = generate()
-  const selector = generate()
-  const annotation = { [selector]: uri(protocol) }
-  const request: Request = { group: generate(), selectors: [selector] }
-  const variables = createVariables(id, annotation, [request])
+for (const protocol of ['http:', 'redis:'])
+  it(`should not create credetial secrets for ${protocol}`, async () => {
+    const id = generate()
+    const selector = generate()
+    const annotation = { [selector]: uri(protocol) }
+    const request: Request = { group: generate(), selectors: [selector] }
+    const variables = createVariables(id, annotation, [request])
 
-  for (const variable of variables[request.group])
-    expect(variable.secret).toBeUndefined()
-})
+    for (const variable of variables[request.group])
+      assert.strictEqual(variable.secret, undefined)
+  })
 
-function uri (protocol = 'http:'): string {
+function uri(protocol = 'http:'): string {
   return protocol + '//host-' + generate()
 }
 
-function createExpectedSecrets (id: string, key: string, selector: string): Variable[] {
+function createExpectedSecrets(id: string, key: string, selector: string): Variable[] {
   key = key === '.' ? '.default' : '-' + key.replaceAll('.', '-')
   selector = selector.replaceAll('.', '_').toUpperCase()
 

package/source/createVariables.ts

@@ -1,10 +1,13 @@
-import { Deployment, type Request } from './Deployment'
-import { normalize } from './annotation'
+import { Deployment, type Request } from './Deployment.js'
+import { normalize } from './annotation.js'
 import type { Variables } from '@toa.io/operations'
-import type { Declaration } from './annotation'
+import type { Declaration } from './annotation.js'
 
-export function createVariables
-(id: string, declaration: Declaration, requests: Request[]): Variables {
+export function createVariables(
+  id: string,
+  declaration: Declaration,
+  requests: Request[]
+): Variables {
   const annotation = normalize(declaration)
   const deployment = new Deployment(id, annotation)
 

package/source/index.ts

@@ -1,7 +1,7 @@
-export { createVariables } from './createVariables'
-export { resolve, resolveRecord } from './resolve'
-export { normalize } from './annotation'
-export * as naming from './naming'
+export { createVariables } from './createVariables.js'
+export { resolve, resolveRecord } from './resolve.js'
+export { normalize } from './annotation.js'
+export * as naming from './naming.js'
 
-export type { Declaration } from './annotation'
-export type { Request, URIMap } from './Deployment'
+export type { Declaration } from './annotation.js'
+export type { Request, URIMap } from './Deployment.js'

package/source/naming.ts

@@ -1,11 +1,7 @@
-export function nameVariable (...segments: string[]): string {
-  return 'TOA_' + segments.join('_')
-    .replaceAll(/[-.]/g, '_')
-    .toUpperCase()
+export function nameVariable(...segments: string[]): string {
+  return 'TOA_' + segments.join('_').replaceAll(/[-.]/g, '_').toUpperCase()
 }
 
-export function nameSecret (...segments: string[]): string {
-  return 'toa-' + segments.join('-')
-    .replaceAll('.', '-')
-    .replace(/--$/, '.default')
+export function nameSecret(...segments: string[]): string {
+  return 'toa-' + segments.join('-').replaceAll('.', '-').replace(/--$/, '.default')
 }

package/source/resolve.ts

@@ -1,21 +1,20 @@
-import { nameVariable } from './naming'
-import { type AnnotationRecord, type URIMap } from './Deployment'
+import { nameVariable } from './naming.js'
+import { type AnnotationRecord, type URIMap } from './Deployment.js'
+import { environment } from '@toa.io/generic'
 
-export function resolve (id: string, selector: string): string[] {
+export function resolve(id: string, selector: string): string[] {
   const variable = nameVariable(id, selector)
-  const value = process.env[variable]
+  const value = environment.get(variable)
 
-  if (value === undefined)
-    throw new Error(`${variable} is not set.`)
+  if (value === undefined) throw new Error(`${variable} is not set.`)
 
   const urls = value.split(' ')
 
   return withCredentials(variable, urls)
 }
 
-export function resolveRecord (uris: URIMap, selector: string): AnnotationRecord {
-  if (selector in uris)
-    return getRecord(uris, selector)
+export function resolveRecord(uris: URIMap, selector: string): AnnotationRecord {
+  if (selector in uris) return getRecord(uris, selector)
 
   const segments = selector.split('.')
 
@@ -25,20 +24,18 @@ export function resolveRecord (uris: URIMap, selector: string): AnnotationRecord
     if (current in uris) return getRecord(uris, current)
   }
 
-  if ('.' in uris)
-    return getRecord(uris, '.')
-  else
-    throw new Error(`Selector '${selector}' cannot be resolved.`)
+  if ('.' in uris) return getRecord(uris, '.')
+  else throw new Error(`Selector '${selector}' cannot be resolved.`)
 }
 
-function withCredentials (variable: string, urls: string[]): string[] {
-  const username = process.env[variable + '_USERNAME'] ?? ''
-  const password = process.env[variable + '_PASSWORD'] ?? ''
+function withCredentials(variable: string, urls: string[]): string[] {
+  const username = environment.get(variable + '_USERNAME') ?? ''
+  const password = environment.get(variable + '_PASSWORD') ?? ''
 
   return urls.map((url) => addCredentials(url, username, password))
 }
 
-function addCredentials (ref: string, username: string, password: string): string {
+function addCredentials(ref: string, username: string, password: string): string {
   const url = new URL(ref)
 
   url.username = username
@@ -47,7 +44,7 @@ function addCredentials (ref: string, username: string, password: string): strin
   return url.href
 }
 
-function getRecord (uris: URIMap, key: string): AnnotationRecord {
+function getRecord(uris: URIMap, key: string): AnnotationRecord {
   return {
     key,
     references: uris[key]