@astrale-os/cli 1.0.0-beta.1 → 1.0.0-beta.11

package/src/connection/__tests__/credential.test.ts

@@ -1,4 +1,4 @@
-import type { SessionAuth } from '@astrale-os/kernel-client/session'
+import type { SessionAuth } from '@astrale-os/sdk/client/session'
 
 import { issuer, type IssuerId } from '@astrale-os/sdk/auth'
 import { Path } from '@astrale-os/sdk/graph/path'
@@ -6,6 +6,7 @@ import { describe, expect, test } from 'bun:test'
 
 import type { AstraleConfig } from '../../lib/config'
 
+import { bindCredentialIdentity } from '../auth'
 import { createCliCredential, createConnectionCredential } from '../credential'
 
 const SOURCE = issuer.accept('https://kernel.example')
@@ -20,6 +21,24 @@ const config: AstraleConfig = {
 }
 
 describe('connection credential', () => {
+  test('pins the bookmark identity while leaving explicit credentials unnamed', async () => {
+    const target = {
+      url: `${SOURCE}/invoke`,
+      kernelIssuer: SOURCE,
+      defaultIdentity: 'bookmark-owner',
+    }
+
+    await expect(bindCredentialIdentity({}, target)).resolves.toMatchObject({
+      as: 'bookmark-owner',
+    })
+    await expect(bindCredentialIdentity({ as: 'explicit-owner' }, target)).resolves.toEqual({
+      as: 'explicit-owner',
+    })
+    await expect(bindCredentialIdentity({ creds: 'opaque' }, target)).resolves.toEqual({
+      creds: 'opaque',
+    })
+  })
+
   /** @evidence TEST-CLI-CONNECTION-RESOLVES-SOURCE-AUTH-BEFORE-ROUTING */
   test('resolves source authority without destination knowledge', async () => {
     const audiences: IssuerId[] = []

package/src/connection/__tests__/errors.test.ts

@@ -1,10 +1,16 @@
-import { ResponseError, TransportError } from '@astrale-os/kernel-client'
+import { ResponseError } from '@astrale-os/sdk/client'
+import { Path } from '@astrale-os/sdk/graph/path'
 import { describe, expect, test } from 'bun:test'
 
 import { formatKernelError, functionInputIssues, schemaUpgradeHint } from '../errors'
+import { transportFailure } from './failure-fixtures'
 
 const CONFLICT = 4001
 const VALIDATION = 1003
+const TEST_INVOCATION = {
+  source: 'https://kernel.test',
+  id: 'connection-errors',
+} as ConstructorParameters<typeof ResponseError>[2]
 
 describe('formatKernelError', () => {
   /** @evidence TEST-CLI-CONNECTION-MAPS-TYPED-TRANSPORT */
@@ -15,24 +21,28 @@ describe('formatKernelError', () => {
       writes.push(typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk))
       return true
     }) as typeof process.stderr.write
-    const error = new TransportError('Publication discovery request failed.', {
-      cause: Object.assign(new Error('connect ECONNREFUSED'), { code: 'ECONNREFUSED' }),
-      phase: 'connect',
-      delivery: 'unknown',
-    }) as TransportError & { url?: string }
-    error.url = 'https://localhost:8443/kernel/host'
+    const error = Object.assign(
+      transportFailure('Publication discovery request failed.', 'unknown', {
+        kind: 'acquisition',
+        resource: 'publication',
+      }),
+      {
+        url: 'https://localhost:8443/kernel/host',
+        cause: Object.assign(new Error('connect ECONNREFUSED'), { code: 'ECONNREFUSED' }),
+      },
+    )
     try {
-      await formatKernelError(error, true)
+      await formatKernelError(error, true, 'https://localhost:8443/kernel/host')
     } finally {
       process.stderr.write = original
     }
 
     expect(JSON.parse(writes[0]!)).toMatchObject({
-      error: 'CONNECTION_ERROR',
+      error: 'TRANSPORT_ERROR',
       message: 'Publication discovery request failed.',
       url: 'https://localhost:8443/kernel/host',
-      phase: 'connect',
-      delivery: 'unknown',
+      phase: 'unknown',
+      transport: { kind: 'acquisition', resource: 'publication' },
     })
     expect(writes[0]).not.toContain('ECONNREFUSED')
   })
@@ -46,9 +56,8 @@ describe('formatKernelError', () => {
     }) as typeof process.stderr.write
     try {
       await formatKernelError(
-        new TransportError('Request timed out.', {
-          cause: new Error('timeout'),
-          phase: 'timeout',
+        transportFailure('Request timed out.', 'timeout', {
+          kind: 'invocation',
           delivery: 'unknown',
         }),
         true,
@@ -70,7 +79,7 @@ describe('formatKernelError', () => {
     expect(JSON.parse(writes[0]!)).toMatchObject({
       error: 'TIMEOUT',
       phase: 'timeout',
-      delivery: 'unknown',
+      transport: { kind: 'invocation', delivery: 'unknown' },
       operation: '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
       retry:
         'astrale domain install https://crm.test --direct --operation 4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
@@ -87,7 +96,7 @@ describe('formatKernelError', () => {
     }) as typeof process.stderr.write
     try {
       await formatKernelError(
-        new ResponseError(CONFLICT, 'Schema change requires migration.', {
+        new ResponseError(CONFLICT, 'Schema change requires migration.', TEST_INVOCATION, {
           code: 'DATA_MIGRATION_REQUIRED',
           details: {
             requirements: [
@@ -138,7 +147,7 @@ describe('formatKernelError', () => {
     }) as typeof process.stderr.write
     try {
       await formatKernelError(
-        new ResponseError(CONFLICT, 'Schema change requires migration.', {
+        new ResponseError(CONFLICT, 'Schema change requires migration.', TEST_INVOCATION, {
           code: 'DATA_MIGRATION_REQUIRED',
           details: {
             requirements: [
@@ -193,7 +202,7 @@ describe('formatKernelError', () => {
     console.log = (...values: unknown[]) => hints.push(values.map(String).join(' '))
     try {
       await formatKernelError(
-        new ResponseError(CONFLICT, 'Schema change requires migration.', {
+        new ResponseError(CONFLICT, 'Schema change requires migration.', TEST_INVOCATION, {
           code: 'DATA_MIGRATION_REQUIRED',
           details: {
             requirements: [
@@ -225,7 +234,7 @@ describe('formatKernelError', () => {
     )
   })
 
-  test('maps SDK class names to stable CLI error codes', async () => {
+  test('maps SDK error identities to stable CLI error codes', async () => {
     const writes: string[] = []
     const original = process.stderr.write
     process.stderr.write = ((chunk: string | Uint8Array) => {
@@ -233,15 +242,17 @@ describe('formatKernelError', () => {
       return true
     }) as typeof process.stderr.write
     try {
-      const pathError = new Error('Path must have an Id or Domain anchor.')
-      pathError.name = 'PathError'
-      await formatKernelError(pathError, true)
+      try {
+        Path.parse('not-a-path')
+      } catch (error) {
+        await formatKernelError(error, true)
+      }
     } finally {
       process.stderr.write = original
     }
     expect(JSON.parse(writes[0]!)).toEqual({
       error: 'PATH_INVALID',
-      message: 'Path must have an Id or Domain anchor.',
+      message: expect.any(String),
     })
   })
 
@@ -254,7 +265,7 @@ describe('formatKernelError', () => {
     console.log = (...values: unknown[]) => lines.push(values.join(' '))
     try {
       await formatKernelError(
-        new ResponseError(VALIDATION, 'Function input is invalid.', {
+        new ResponseError(VALIDATION, 'Function input is invalid.', TEST_INVOCATION, {
           code: 'FUNCTION_INPUT_INVALID',
           details: {
             issues: [
@@ -279,7 +290,7 @@ describe('formatKernelError', () => {
         false,
       )
       await formatKernelError(
-        new ResponseError(VALIDATION, 'Query input is invalid.', {
+        new ResponseError(VALIDATION, 'Query input is invalid.', TEST_INVOCATION, {
           code: 'QUERY_INPUT_INVALID',
           details: {
             phase: 'plan',
@@ -310,7 +321,7 @@ describe('formatKernelError', () => {
     }) as typeof process.stderr.write
     try {
       await formatKernelError(
-        new ResponseError(5001, 'Schema operation is not supported.', {
+        new ResponseError(5001, 'Schema operation is not supported.', TEST_INVOCATION, {
           code: 'SCHEMA_UPGRADE_INCOMPATIBLE',
           details: {
             phase: 'upgrade',
@@ -358,7 +369,7 @@ describe('formatKernelError', () => {
     console.log = (...values: unknown[]) => details.push(values.map(String).join(' '))
     try {
       await formatKernelError(
-        new ResponseError(5001, 'Schema operation is not supported.', {
+        new ResponseError(5001, 'Schema operation is not supported.', TEST_INVOCATION, {
           code: 'SCHEMA_UPGRADE_INCOMPATIBLE',
           details: {
             phase: 'upgrade',
@@ -391,7 +402,7 @@ describe('formatKernelError', () => {
     }) as typeof process.stderr.write
     try {
       await formatKernelError(
-        new ResponseError(1003, 'Function input is invalid.', {
+        new ResponseError(1003, 'Function input is invalid.', TEST_INVOCATION, {
           code: 'SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC',
           details: { phase: 'publication', requiredScope: 'public' },
         }),
@@ -421,7 +432,7 @@ describe('formatKernelError', () => {
     console.log = (...values: unknown[]) => hints.push(values.map(String).join(' '))
     try {
       await formatKernelError(
-        new ResponseError(1003, 'Function input is invalid.', {
+        new ResponseError(1003, 'Function input is invalid.', TEST_INVOCATION, {
           code: 'SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC',
           details: { phase: 'publication', requiredScope: 'public' },
         }),
@@ -448,7 +459,7 @@ describe('formatKernelError', () => {
     }) as typeof process.stderr.write
     try {
       await formatKernelError(
-        new ResponseError(1003, 'Function input is invalid.', {
+        new ResponseError(1003, 'Function input is invalid.', TEST_INVOCATION, {
           code: 'FUNCTION_INPUT_INVALID',
           details: {
             issues: [
@@ -495,7 +506,7 @@ describe('formatKernelError', () => {
     console.log = (...values: unknown[]) => details.push(values.map(String).join(' '))
     try {
       await formatKernelError(
-        new ResponseError(1003, 'Function input is invalid.', {
+        new ResponseError(1003, 'Function input is invalid.', TEST_INVOCATION, {
           code: 'FUNCTION_INPUT_INVALID',
           details: {
             issues: [
@@ -530,7 +541,7 @@ describe('formatKernelError', () => {
     }) as typeof process.stderr.write
     try {
       await formatKernelError(
-        new ResponseError(1003, 'Function input is invalid.', {
+        new ResponseError(1003, 'Function input is invalid.', TEST_INVOCATION, {
           code: 'FUNCTION_INPUT_INVALID',
           details: { issues: [{ code: 'INVALID_FORMAT', path: '/customer/email' }] },
         }),

package/src/connection/__tests__/exchange.test.ts

@@ -1,4 +1,4 @@
-import type { Fetch } from '@astrale-os/kernel-client'
+import type { Fetch } from '@astrale-os/sdk/client'
 
 import { issuer } from '@astrale-os/sdk/auth'
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
@@ -47,7 +47,7 @@ describe('Domain token exchange', () => {
         observed.push({ url, init, body })
         const index = observed.filter((entry) => entry.url === INVOCATION).length
         return invocationResponse(
-          body.id,
+          body.requestId,
           index === 1
             ? { id: 'user-1' }
             : index === 2
@@ -121,7 +121,7 @@ describe('Domain token exchange', () => {
       if (url === INVOCATION) {
         const body = JSON.parse(await new Response(init?.body).text()) as Record<string, any>
         return invocationResponse(
-          body.id,
+          body.requestId,
           body.call.input && Object.keys(body.call.input).length === 0
             ? { id: 'user-1' }
             : 'kernel-destination-envelope',
@@ -190,6 +190,35 @@ describe('Domain token exchange', () => {
       message: 'Token exchange returned an invalid success response.',
     })
   })
+
+  test('normalizes native issuer Fetch failures without exposing their message', async () => {
+    const native = new AggregateError([new Error('private DNS state')], '')
+    const resolver = createExchangeCredentialResolver(
+      TARGET,
+      { resolve: async () => SOURCE_TOKEN },
+      async (input, init) => {
+        if (String(input) === INVOCATION) {
+          const body = JSON.parse(await new Response(init?.body).text()) as Record<string, any>
+          return invocationResponse(
+            body.requestId,
+            body.call.input && Object.keys(body.call.input).length === 0
+              ? { id: 'user-1' }
+              : 'kernel-destination-envelope',
+            new Headers(init?.headers).get('accept')!,
+          )
+        }
+        throw native
+      },
+      5_000,
+      new ExchangeCredentialCache(join(directory, 'native-failure.json')),
+    )
+
+    await expect(resolver.resolve(KERNEL, new AbortController().signal)).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_UNAVAILABLE',
+      message: 'Domain issuer discovery could not be reached.',
+      cause: native,
+    })
+  })
 })
 
 function exchangeFetch(
@@ -201,7 +230,7 @@ function exchangeFetch(
     if (url === INVOCATION) {
       const body = JSON.parse(await new Response(init?.body).text()) as Record<string, any>
       return invocationResponse(
-        body.id,
+        body.requestId,
         body.call.input && Object.keys(body.call.input).length === 0
           ? { id: 'user-1' }
           : 'kernel-destination-envelope',
@@ -233,8 +262,9 @@ function configuration(enabled: boolean) {
   }
 }
 
-function invocationResponse(id: number, result: unknown, contentType: string): Response {
-  return new Response(JSON.stringify({ id, result }), {
+function invocationResponse(requestId: unknown, result: unknown, contentType: string): Response {
+  const invocation = { source: KERNEL, id: `exchange-${String(requestId)}` }
+  return new Response(JSON.stringify({ requestId, invocation, result }), {
     headers: { 'content-type': contentType, 'cache-control': 'no-store' },
   })
 }

package/src/connection/__tests__/failure-fixtures.ts

@@ -0,0 +1,39 @@
+import { ClientError, TransportError } from '@astrale-os/sdk/client'
+
+import type { TransportDiagnosticContext } from '../failure/model'
+
+type CompatibleTransportPhase = TransportError['phase'] | 'unknown'
+
+export function transportFailure(
+  message: string,
+  phase: CompatibleTransportPhase,
+  context: TransportDiagnosticContext,
+): TransportError {
+  const error = new Error(message) as TransportError & {
+    context: TransportDiagnosticContext
+  }
+  Object.setPrototypeOf(error, TransportError.prototype)
+  Object.assign(error, { name: 'TransportError', phase, context })
+  return error
+}
+
+export function legacyTransportFailure(
+  message: string,
+  phase: CompatibleTransportPhase,
+  delivery: 'not-sent' | 'unknown',
+): TransportError {
+  const error = new Error(message) as TransportError & { delivery: typeof delivery }
+  Object.setPrototypeOf(error, TransportError.prototype)
+  Object.assign(error, { name: 'TransportError', phase, delivery })
+  return error
+}
+
+export function sessionFailure(
+  message: string,
+  failure: 'cancelled' | 'closed' | 'timeout',
+): ClientError {
+  const error = new Error(message) as ClientError & { failure: typeof failure }
+  Object.setPrototypeOf(error, ClientError.prototype)
+  Object.assign(error, { name: 'SessionError', failure })
+  return error
+}

package/src/connection/__tests__/failure-safety.test.ts

@@ -0,0 +1,75 @@
+import { expect, test } from 'bun:test'
+
+import { formatKernelError } from '../errors'
+import { legacyTransportFailure, sessionFailure, transportFailure } from './failure-fixtures'
+
+/** @evidence TEST-CLI-CONNECTION-FAILURE-SAFETY */
+test('unknown and empty native failures never become ordinary diagnostics', async () => {
+  for (const failure of [new Error('private provider detail'), new Error(''), { secret: true }]) {
+    const output = await capture(() => formatKernelError(failure, true))
+    expect(JSON.parse(output)).toEqual({
+      error: 'UNEXPECTED_ERROR',
+      message: 'The CLI encountered an unexpected internal failure.',
+    })
+    expect(output).not.toContain('private provider detail')
+  }
+})
+
+test('Aggregate children are available only under explicit debug output', async () => {
+  const failure = new AggregateError([new Error('first private'), new Error('second private')], '')
+  const ordinary = await capture(() => formatKernelError(failure, true))
+  expect(ordinary).not.toContain('first private')
+  expect(ordinary).not.toContain('second private')
+
+  const debug = await capture(() => formatKernelError(failure, true, '', true))
+  expect(debug).toContain('aggregate: Error: first private')
+  expect(debug).toContain('aggregate: Error: second private')
+})
+
+test('Session and acquisition failures remain typed without unsafe recovery advice', async () => {
+  const session = await capture(() =>
+    formatKernelError(sessionFailure('Session operation timed out.', 'timeout'), true),
+  )
+  expect(JSON.parse(session)).toEqual({ error: 'TIMEOUT', message: 'Session operation timed out.' })
+
+  const acquisition = await capture(() =>
+    formatKernelError(
+      transportFailure('Publication failed.', 'unknown', {
+        kind: 'acquisition',
+        resource: 'publication',
+      }),
+      true,
+      '',
+      false,
+      { recovery: { operation: 'must-not-leak', retry: 'must-not-leak' } },
+    ),
+  )
+  expect(JSON.parse(acquisition)).toMatchObject({
+    error: 'TRANSPORT_ERROR',
+    transport: { kind: 'acquisition', resource: 'publication' },
+  })
+  expect(acquisition).not.toContain('must-not-leak')
+
+  const legacy = await capture(() =>
+    formatKernelError(legacyTransportFailure('Legacy send failed.', 'send', 'not-sent'), true),
+  )
+  expect(JSON.parse(legacy)).toMatchObject({
+    error: 'TRANSPORT_ERROR',
+    transport: { kind: 'invocation', delivery: 'not-sent' },
+  })
+})
+
+async function capture(action: () => Promise<void>): Promise<string> {
+  const writes: string[] = []
+  const original = process.stderr.write
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    writes.push(typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk))
+    return true
+  }) as typeof process.stderr.write
+  try {
+    await action()
+    return writes.join('')
+  } finally {
+    process.stderr.write = original
+  }
+}

package/src/connection/__tests__/self.test.ts

@@ -2,7 +2,11 @@ import { describe, expect, test } from 'bun:test'
 import { SignJWT } from 'jose'
 import { webcrypto } from 'node:crypto'
 
-import { resolveSelfIdAuthenticated } from '../self'
+import type { ConnectionContext } from '../session'
+
+import { expandSelfInCall, resolveSelfIdAuthenticated } from '../self'
+
+const context = Object.freeze({}) as ConnectionContext
 
 describe('resolveSelfIdAuthenticated', () => {
   /** @evidence TEST-CLI-SELF-USES-AUTHENTICATED-EFFECTIVE-PRINCIPAL */
@@ -14,11 +18,9 @@ describe('resolveSelfIdAuthenticated', () => {
       .setSubject('manager-principal')
       .setAudience('https://child.example')
       .sign(key)
-    const opts = { creds: credential, url: 'https://manager.example/children/child/invoke' }
-
-    const resolved = await resolveSelfIdAuthenticated(opts, {
+    const resolved = await resolveSelfIdAuthenticated(context, {
       whoami: async (received) => {
-        expect(received).toBe(opts)
+        expect(received).toBe(context)
         return { id: 'child-kernel-principal', slug: 'child' }
       },
     })
@@ -28,17 +30,35 @@ describe('resolveSelfIdAuthenticated', () => {
 
   test('resolves an imported root without requiring a local registration', async () => {
     await expect(
-      resolveSelfIdAuthenticated(
-        { as: 'platform-root', url: 'https://manager.example/invoke' },
-        { whoami: async () => ({ id: 'manager-kernel-principal' }) },
-      ),
+      resolveSelfIdAuthenticated(context, {
+        whoami: async () => ({ id: 'manager-kernel-principal' }),
+      }),
     ).resolves.toEqual({ id: 'manager-kernel-principal' })
   })
 
   test('fails closed when authenticated whoami returns no NodeId', async () => {
     await expect(
-      resolveSelfIdAuthenticated({}, { whoami: async () => ({ id: '   ' }) }),
-    ).rejects.toMatchObject({ name: 'SelfResolutionError' })
+      resolveSelfIdAuthenticated(context, { whoami: async () => ({ id: '   ' }) }),
+    ).rejects.toMatchObject({ code: 'SELF_RESOLUTION_FAILED' })
+  })
+})
+
+describe('expandSelfInCall', () => {
+  test('expands only top-level string values after local parameter admission', async () => {
+    const callContext = {
+      auth: { whoami: async () => ({ id: 'caller-id' }) },
+      target: {},
+    } as ConnectionContext
+    const expanded = await expandSelfInCall(
+      '/:people.example.dev:class.Person:get',
+      { owner: '@self', count: 2, nested: { owner: '@self' } },
+      callContext,
+    )
+    expect(expanded.parameters).toEqual({
+      owner: '@caller-id',
+      count: 2,
+      nested: { owner: '@self' },
+    })
   })
 })
 

package/src/connection/__tests__/session.test.ts

@@ -1,6 +1,6 @@
-import type { AuthApi } from '@astrale-os/kernel-client/auth'
-import type { GraphApi } from '@astrale-os/kernel-client/graph'
-import type { ClientSession } from '@astrale-os/kernel-client/session'
+import type { AuthApi } from '@astrale-os/sdk/auth'
+import type { GraphApi } from '@astrale-os/sdk/client'
+import type { ClientSession } from '@astrale-os/sdk/client/session'
 
 import { issuer } from '@astrale-os/sdk/auth'
 import { describe, expect, test } from 'bun:test'

package/src/connection/__tests__/target.test.ts

@@ -68,6 +68,7 @@ describe('connection target', () => {
           id: 'managed-id',
           slug,
           url: 'https://managed.example',
+          state: 'ready',
         }),
       }),
     ).toEqual({

package/src/connection/auth.ts

@@ -1,4 +1,5 @@
 import type { AstraleConfig } from '../lib/config'
+import type { ConnectionOptions, ConnectionTarget } from './target'
 
 import { AuthError } from '../errors'
 import { getDefault, getIdentity, type Identity } from '../identity/registry'
@@ -21,6 +22,18 @@ export type KeyIdentityAuthOptions = {
   audience: string
 }
 
+/** Pin the local identity label before a session performs any authenticated effect. */
+export async function bindCredentialIdentity<Options extends ConnectionOptions>(
+  options: Options,
+  target: ConnectionTarget,
+): Promise<Options> {
+  if (options.anonymous === true || options.creds !== undefined || options.as !== undefined) {
+    return options
+  }
+  const identity = target.defaultIdentity ?? (await getDefault()).name
+  return Object.freeze({ ...options, as: identity })
+}
+
 /**
  * Resolve a signed JWT credential from CLI options.
  *

package/src/connection/call.ts

@@ -1,4 +1,4 @@
-import { call, type Call } from '@astrale-os/kernel-client'
+import { call, type Call } from '@astrale-os/sdk/client'
 import { Path } from '@astrale-os/sdk/graph/path'
 
 /** Convert the CLI's untrusted text/JSON boundary into the one public Call representation. */

package/src/connection/credential.ts

@@ -1,5 +1,5 @@
-import type { Fetch } from '@astrale-os/kernel-client'
-import type { SessionAuth } from '@astrale-os/kernel-client/session'
+import type { Fetch } from '@astrale-os/sdk/client'
+import type { SessionAuth } from '@astrale-os/sdk/client/session'
 
 import { credential, type IssuerId } from '@astrale-os/sdk/auth'