@astrale-os/cli 1.0.0-beta.3 → 1.0.0-beta.31

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,7 @@
-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 type { SessionRouteStore } from '@astrale-os/sdk/client/session'
 
 import { issuer } from '@astrale-os/sdk/auth'
 import { describe, expect, test } from 'bun:test'
@@ -23,6 +24,7 @@ const config: AstraleConfig = {
     kernelIssuer: 'https://admin.example',
   },
   telemetry: { enabled: false },
+  browser: {},
 }
 
 const context: ConnectionContext = Object.freeze({
@@ -37,11 +39,13 @@ describe('connection session', () => {
   /** @evidence TEST-CLI-CONNECTION-PINS-SOURCE-ISSUER */
   test('pins the selected canonical Kernel issuer without a transport escape hatch', async () => {
     const auth = { ttlSeconds: 3_600, resolve: async () => ({ credential: 'credential' }) }
-    const options = createClientSessionOptions(target, globalThis.fetch, auth, 2_500)
+    const routeStore: SessionRouteStore = { read: () => undefined, write: () => undefined }
+    const options = createClientSessionOptions(target, globalThis.fetch, auth, 2_500, routeStore)
 
     expect(options.kernel).toBe(target.kernelIssuer)
     expect(options).not.toHaveProperty('url')
     expect(options).not.toHaveProperty('sourceIssuer')
+    expect(options.routeStore).toBe(routeStore)
   })
 
   /** @evidence TEST-CLI-CONNECTION-OMITS-EXPLICIT-ANONYMOUS-CREDENTIAL */

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

@@ -15,6 +15,7 @@ const config: AstraleConfig = {
     domainIssuer: 'https://admin-domain.example',
   },
   telemetry: { enabled: false },
+  browser: {},
 }
 
 const instances: InstanceStore = {
@@ -68,6 +69,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'
 

package/src/connection/errors.ts

@@ -1,355 +1 @@
-import chalk from 'chalk'
-
-import type { OperationRecovery } from './command'
-
-import { AstraleError } from '../errors'
-import { readLocalStatus, type LocalStatus } from '../lib/local-status'
-import { log } from '../lib/log'
-import {
-  functionInputIssues,
-  queryInputRepair,
-  reasonCode,
-  schemaUpgradeDetails,
-  schemaUpgradeHint,
-  type FunctionInputIssue,
-  type QueryInputRepair,
-} from './reasons'
-
-export { functionInputIssues, schemaUpgradeHint } from './reasons'
-
-/**
- * Format and display a kernel client error.
- *
- * Handles CLI-local errors plus the current Kernel Client public error families.
- *
- * When `debug` is true, additional diagnostic information (class name, full
- * error chain, attached url/details) is printed after the user-facing line.
- */
-export async function formatKernelError(
-  error: unknown,
-  isRaw: boolean,
-  urlArg = '',
-  debug = false,
-  opts: { recovery?: OperationRecovery } = {},
-): Promise<void> {
-  const url =
-    urlArg || (error instanceof Error ? ((error as Error & { url?: string }).url ?? '') : '')
-  const localContext = await contextForError(error)
-  // Handle AstraleError (AuthError, etc.) with structured hints
-  if (error instanceof AstraleError) {
-    if (isRaw) {
-      writeRaw({ error: error.code, message: error.message, hint: error.hint })
-    } else {
-      log.error(`${chalk.bold(error.code)}: ${error.message}`)
-      if (error.hint) log.dim(`  ${error.hint}`)
-    }
-    if (debug) printDebug(error, url)
-    return
-  }
-
-  if (!(error instanceof Error)) {
-    if (isRaw) writeRaw({ error: 'UNKNOWN', message: String(error) })
-    else log.error(String(error))
-    return
-  }
-
-  const name = error.name
-
-  switch (name) {
-    case 'TransportError':
-      presentTransportError(error, isRaw, url, localContext, opts.recovery)
-      break
-
-    case 'ResponseError': {
-      const code = (error as { readonly code?: unknown }).code
-      const reason = (error as { readonly reason?: unknown }).reason
-      const codeOfReason = reasonCode(reason)
-      const inputIssues = functionInputIssues(reason)
-      const queryRepair = queryInputRepair(reason)
-      const upgrade = schemaUpgradeDetails(reason)
-      const removalHint = schemaDataRemovalHint(reason)
-      const domainAddressNotPublic = codeOfReason === 'SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC'
-      const displayMessage = domainAddressNotPublic
-        ? 'Expose the Domain through a public HTTPS URL or public tunnel, then retry.'
-        : removalHint !== undefined && !isRaw
-          ? 'Existing business data still uses schema definitions being removed.'
-          : error.message
-      const hint =
-        codeOfReason === 'FUNCTION_INPUT_INVALID' && (isRaw || inputIssues.length === 0)
-          ? 'Use `astrale introspect <path>` to see the callable input.'
-          : (removalHint ?? (upgrade === undefined ? undefined : schemaUpgradeHint(upgrade)))
-      if (isRaw) {
-        writeRaw({
-          error: 'RESPONSE_ERROR',
-          ...(code === undefined ? {} : { code }),
-          message: displayMessage,
-          ...(reason === undefined ? {} : { reason }),
-          ...(hint === undefined ? {} : { hint }),
-        })
-      } else {
-        log.error(
-          domainAddressNotPublic
-            ? `${chalk.bold('SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC')}: ${displayMessage}`
-            : removalHint !== undefined
-              ? `${chalk.bold('DATA_MIGRATION_REQUIRED')}: ${displayMessage}`
-              : `${chalk.bold(code === undefined ? 'RESPONSE_ERROR' : `RESPONSE_ERROR(${String(code)})`)}: ${displayMessage}`,
-        )
-        if (codeOfReason !== undefined && !domainAddressNotPublic && removalHint === undefined) {
-          log.dim(`  reason: ${codeOfReason}`)
-        }
-        presentFunctionInputIssues(inputIssues)
-        if (queryRepair !== undefined) presentQueryInputRepair(queryRepair)
-        if (upgrade?.issue === 'issuer-changed') {
-          log.dim(`  installed issuer: ${upgrade.installedIssuer}`)
-          log.dim(`  replacement issuer: ${upgrade.replacementIssuer}`)
-        }
-        if (hint !== undefined) log.dim(`  ${hint}`)
-      }
-      break
-    }
-
-    default: {
-      const mapped = mapPublicError(error)
-      if (isRaw) {
-        writeRaw({
-          error: mapped.code,
-          message: mapped.message,
-          ...(mapped.hint === undefined ? {} : { hint: mapped.hint }),
-          ...(mapped.timeoutMs === undefined ? {} : { timeoutMs: mapped.timeoutMs }),
-        })
-      } else {
-        log.error(`${chalk.bold(mapped.code)}: ${mapped.message}`)
-        if (mapped.hint) log.dim(`  ${mapped.hint}`)
-      }
-    }
-  }
-
-  if (debug) printDebug(error, url)
-}
-
-function schemaDataRemovalHint(reason: unknown): string | undefined {
-  if (reason === null || typeof reason !== 'object') return undefined
-  const value = reason as { readonly code?: unknown; readonly details?: unknown }
-  if (value.code !== 'DATA_MIGRATION_REQUIRED') return undefined
-  if (value.details === null || typeof value.details !== 'object') return undefined
-
-  const requirements = (value.details as { readonly requirements?: unknown }).requirements
-  if (
-    !Array.isArray(requirements) ||
-    requirements.length === 0 ||
-    !requirements.every(
-      (requirement) =>
-        requirement !== null &&
-        typeof requirement === 'object' &&
-        (requirement as { readonly operation?: unknown }).operation === 'remove-facts' &&
-        (requirement as { readonly reason?: unknown }).reason === 'destructive-change',
-    )
-  ) {
-    return undefined
-  }
-
-  return 'Delete this data explicitly, then retry. No data was deleted.'
-}
-
-function mapPublicError(error: Error): {
-  code: string
-  message: string
-  hint?: string
-  timeoutMs?: number
-} {
-  const name = error.name
-  if (name === 'PathError') {
-    return { code: 'PATH_INVALID', message: error.message }
-  }
-  if (name === 'NodeUnavailableError') {
-    return {
-      code: 'NODE_UNAVAILABLE',
-      message: error.message,
-      hint: 'If this is a callable Path, use `astrale call` or `astrale introspect`.',
-    }
-  }
-  if (name === 'AuthValueError') {
-    return { code: 'AUTH_VALUE_INVALID', message: error.message }
-  }
-  if (name === 'ClientError' && /timed out/i.test(error.message)) {
-    const timeoutMs = (error as { timeoutMs?: number }).timeoutMs
-    return {
-      code: 'TIMEOUT',
-      message: error.message,
-      hint: 'Try increasing with --timeout',
-      ...(timeoutMs === undefined ? {} : { timeoutMs }),
-    }
-  }
-  if (name === 'ClientError' && /Publication discovery returned HTTP/i.test(error.message)) {
-    return {
-      code: 'KERNEL_DISCOVERY_FAILED',
-      message: error.message,
-      hint: 'Pass the Kernel issuer URL (no /invoke suffix), e.g. https://host/kernel/host',
-    }
-  }
-  return { code: name && name !== 'Error' ? name : 'UNKNOWN', message: error.message }
-}
-
-function presentTransportError(
-  error: Error,
-  isRaw: boolean,
-  url: string,
-  context: LocalStatus | undefined,
-  recovery: OperationRecovery | undefined,
-): void {
-  const phase = transportPhase(error)
-  const delivery = transportDelivery(error)
-  const code =
-    phase === 'connect'
-      ? 'CONNECTION_ERROR'
-      : phase === 'timeout'
-        ? 'TIMEOUT'
-        : phase === 'closed'
-          ? 'DISCONNECTED'
-          : 'TRANSPORT_ERROR'
-  if (isRaw) {
-    writeRaw({
-      error: code,
-      message: error.message,
-      ...(url === '' ? {} : { url }),
-      ...(phase === undefined ? {} : { phase }),
-      ...(delivery === undefined ? {} : { delivery }),
-      ...(context === undefined ? {} : { context }),
-      ...(delivery === 'unknown' && recovery !== undefined ? recovery : {}),
-    })
-    return
-  }
-  log.error(`${chalk.bold(code)}: ${error.message}`)
-  if (url !== '') log.dim(`  target: ${url}`)
-  if (phase !== undefined) log.dim(`  phase: ${phase}`)
-  if (phase === 'connect') log.dim('  Check the target and run `astrale status`.')
-  else if (phase === 'timeout') log.dim('  Try increasing `--timeout`.')
-  else if (delivery === 'unknown') printOperationRecovery(recovery)
-  printLocalContext(context)
-}
-
-function printOperationRecovery(recovery: OperationRecovery | undefined): void {
-  if (recovery === undefined) {
-    log.dim('  Delivery is unknown; do not automatically retry a mutating call.')
-    return
-  }
-  log.dim('  Delivery is unknown; retry with the same operation id:')
-  log.dim(`  operation: ${recovery.operation}`)
-  log.dim(`  ${recovery.retry}`)
-}
-
-function presentFunctionInputIssues(issues: readonly FunctionInputIssue[]): void {
-  for (const issue of issues) {
-    const location = issue.path === undefined || issue.path === '' ? '<input>' : issue.path
-    console.log(chalk.red(`  ${location}: ${issue.message} (${chalk.dim(issue.code)})`))
-  }
-}
-
-function presentQueryInputRepair(repair: QueryInputRepair): void {
-  if (repair.phase === 'plan') {
-    log.dim(`  ${repair.path ?? '/'}  ${repair.issue}`)
-    return
-  }
-  if (repair.phase === 'limit') {
-    log.dim(`  ${repair.path ?? '/'}  ${repair.limit} limit ${repair.actual}/${repair.maximum}`)
-    return
-  }
-  log.dim(`  ${repair.path}  ${repair.phase} input`)
-}
-
-function transportPhase(error: Error): string | undefined {
-  const phase = (error as Error & { readonly phase?: unknown }).phase
-  return phase === 'connect' ||
-    phase === 'send' ||
-    phase === 'receive' ||
-    phase === 'timeout' ||
-    phase === 'closed'
-    ? phase
-    : undefined
-}
-
-function transportDelivery(error: Error): string | undefined {
-  const delivery = (error as Error & { readonly delivery?: unknown }).delivery
-  return delivery === 'not-sent' || delivery === 'unknown' ? delivery : undefined
-}
-
-function writeRaw(payload: Record<string, unknown>): void {
-  process.stderr.write(JSON.stringify(payload) + '\n')
-}
-
-async function contextForError(error: unknown): Promise<LocalStatus | undefined> {
-  if (!(error instanceof Error)) return undefined
-  if (error.name !== 'TransportError') return undefined
-  return readLocalStatus().catch(() => undefined)
-}
-
-function printLocalContext(context: LocalStatus | undefined): void {
-  if (!context) return
-  process.stderr.write(chalk.dim('\nContext:\n'))
-  if ('error' in context.admin) {
-    process.stderr.write(chalk.dim(`  admin: invalid (${context.admin.error})\n`))
-  } else {
-    process.stderr.write(chalk.dim(`  admin: ${context.admin.name} -> ${context.admin.url}\n`))
-  }
-  if (context.instance) {
-    process.stderr.write(
-      chalk.dim(`  instance: ${context.instance.active} -> ${context.instance.url}\n`),
-    )
-  } else {
-    process.stderr.write(chalk.dim('  instance: none\n'))
-  }
-  if (context.identity) {
-    const source =
-      context.identity.source === 'idp'
-        ? `idp:${context.identity.idp ?? 'unknown'}`
-        : context.identity.source
-    process.stderr.write(chalk.dim(`  identity: ${context.identity.name} [${source}]\n`))
-    if (context.identity.session?.cached) {
-      const state = context.identity.session.requiresLogin ? 'login required' : 'ready'
-      process.stderr.write(chalk.dim(`  session: ${state}\n`))
-    } else if (context.identity.source === 'idp') {
-      process.stderr.write(chalk.dim('  session: not cached\n'))
-    }
-  } else {
-    process.stderr.write(chalk.dim('  identity: none\n'))
-  }
-}
-
-function printDebug(error: unknown, url: string): void {
-  process.stderr.write('\n' + chalk.dim('── debug ─────────────────') + '\n')
-  if (url) process.stderr.write(chalk.dim(`url:   ${url}`) + '\n')
-  if (error instanceof Error) {
-    process.stderr.write(chalk.dim(`class: ${error.constructor.name}`) + '\n')
-    if (error.stack) process.stderr.write(chalk.dim(error.stack) + '\n')
-    // Walk cause chain
-    let cause = (error as Error & { cause?: unknown }).cause
-    while (cause instanceof Error) {
-      process.stderr.write(
-        chalk.dim(`caused by: ${cause.constructor.name}: ${cause.message}`) + '\n',
-      )
-      if (cause.stack) process.stderr.write(chalk.dim(cause.stack) + '\n')
-      cause = (cause as Error & { cause?: unknown }).cause
-    }
-    // Any attached fields (code, details, etc.)
-    const extras: Record<string, unknown> = {}
-    const bag = error as unknown as Record<string, unknown>
-    for (const key of [
-      'code',
-      'type',
-      'reason',
-      'details',
-      'errors',
-      'data',
-      'timeoutMs',
-      'requestId',
-    ]) {
-      const v = bag[key]
-      if (v !== undefined) extras[key] = v
-    }
-    if (Object.keys(extras).length > 0) {
-      process.stderr.write(chalk.dim(`extras: ${JSON.stringify(extras, null, 2)}`) + '\n')
-    }
-  } else {
-    process.stderr.write(chalk.dim(String(error)) + '\n')
-  }
-}
+export { formatKernelError, functionInputIssues, schemaUpgradeHint } from './failure'