@astrale-os/cli 0.8.1-alpha.6 → 1.0.0-beta.0

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

@@ -0,0 +1,78 @@
+import { describe, expect, test } from 'bun:test'
+
+import { functionInputIssues, queryInputRepair } from '../reasons'
+
+describe('public reason presentation admission', () => {
+  /** @evidence TEST-CLI-CONNECTION-ADMITS-BOUNDED-REASONS */
+  test('admits bounded public callable issues and filters unsafe additions', () => {
+    expect(
+      functionInputIssues({
+        code: 'FUNCTION_INPUT_INVALID',
+        details: {
+          issues: [
+            {
+              code: 'VALUE_SCHEMA_INSTANCE_INVALID',
+              path: '/issuer',
+              message: 'Object is missing required property issuer.',
+            },
+            {
+              code: 'VALUE_SCHEMA_INSTANCE_INVALID',
+              path: '/slug',
+              message: 'Object is missing required property slug.',
+            },
+            {
+              code: 'VALUE_SCHEMA_INSTANCE_INVALID',
+              path: '/unsafe',
+              message: 'private\ndiagnostic',
+            },
+          ],
+        },
+      }),
+    ).toEqual([
+      {
+        code: 'VALUE_SCHEMA_INSTANCE_INVALID',
+        path: '/issuer',
+        message: 'Object is missing required property issuer.',
+      },
+      {
+        code: 'VALUE_SCHEMA_INSTANCE_INVALID',
+        path: '/slug',
+        message: 'Object is missing required property slug.',
+      },
+    ])
+  })
+
+  test('admits exact Query repair variants and rejects unbounded additions', () => {
+    expect(
+      queryInputRepair({
+        code: 'QUERY_INPUT_INVALID',
+        details: {
+          phase: 'plan',
+          issue: 'QUERY_DEFINITION_NOT_EDGE',
+          path: '/steps/0/via/0',
+        },
+      }),
+    ).toEqual({
+      phase: 'plan',
+      issue: 'QUERY_DEFINITION_NOT_EDGE',
+      path: '/steps/0/via/0',
+    })
+    expect(
+      queryInputRepair({
+        code: 'QUERY_INPUT_INVALID',
+        details: { phase: 'limit', limit: 'steps', maximum: 4, actual: 5 },
+      }),
+    ).toEqual({ phase: 'limit', limit: 'steps', maximum: 4, actual: 5 })
+    expect(
+      queryInputRepair({
+        code: 'QUERY_INPUT_INVALID',
+        details: {
+          phase: 'plan',
+          issue: 'QUERY_DEFINITION_NOT_EDGE',
+          path: '/steps/0/via/0',
+          provider: 'private',
+        },
+      }),
+    ).toBeUndefined()
+  })
+})

package/src/connection/auth.ts

@@ -162,7 +162,7 @@ async function resolveIdpAccessToken(
       )
     }
     if (e instanceof IdpSessionNoRefreshTokenError) {
-      throw new Error(wrongAudienceHint(identityName, identity, audience))
+      throw classifyNoRefreshTokenError(audience, identity.audience, e)
     }
     // An audience mismatch means the session is healthy but the IdP won't
     // mint this audience — re-login is futile, so propagate it verbatim for
@@ -182,6 +182,16 @@ async function resolveIdpAccessToken(
   return token
 }
 
+export function classifyNoRefreshTokenError(
+  requestedAudience: string,
+  sourceAudience: string | undefined,
+  error: IdpSessionNoRefreshTokenError,
+): IdpSessionNoRefreshTokenError | IdpAudienceMismatchError {
+  return sourceAudience !== undefined && sourceAudience !== requestedAudience
+    ? new IdpAudienceMismatchError(requestedAudience, sourceAudience)
+    : error
+}
+
 /** A refresh attempt failed for a reason that re-login will NOT fix. */
 export class IdpRefreshTransientError extends Error {
   constructor(message: string) {
@@ -224,11 +234,3 @@ function refreshFailureError(identityName: string, identity: Identity, cause: un
       )
   }
 }
-
-function wrongAudienceHint(identityName: string, identity: Identity, audience: string): string {
-  return (
-    `IdP token for "${identityName}" was not minted for target audience ${audience}, ` +
-    'and the cached session cannot be refreshed. ' +
-    `Run: astrale auth login --name ${identityName} --idp ${identity.idp ?? '<idp>'} --audience ${audience}`
-  )
-}

package/src/connection/command.ts

@@ -16,6 +16,11 @@ export interface KernelCommandOpts extends ConnectionOptions {
   readonly debug?: boolean
 }
 
+export interface OperationRecovery {
+  readonly operation: string
+  readonly retry: string
+}
+
 /**
  * Encapsulates the standard kernel command lifecycle:
  * spinner → connect → call → timing → output → error handling.
@@ -27,6 +32,7 @@ export interface KernelCommandOpts extends ConnectionOptions {
 export async function runKernelCommand<T>(input: {
   readonly opts: KernelCommandOpts
   readonly label: string
+  readonly recovery?: OperationRecovery
   readonly fn: (context: ConnectionContext) => Promise<T>
   readonly format?: (
     result: T,
@@ -53,7 +59,9 @@ export async function runKernelCommand<T>(input: {
     }
   } catch (error) {
     if (!isRaw && spin) spin.fail(`${label} failed`)
-    await formatKernelError(error, isRaw, undefined, opts.debug, { credential: opts.creds })
+    await formatKernelError(error, isRaw, undefined, opts.debug, {
+      recovery: input.recovery,
+    })
     process.exit(1)
   }
 }

package/src/connection/errors.ts

@@ -1,21 +1,26 @@
 import chalk from 'chalk'
 
-import type { SelfExpansionMeta } from './self'
+import type { OperationRecovery } from './command'
 
 import { AstraleError } from '../errors'
-import { decodeJwtExpiration, readLocalStatus, type LocalStatus } from '../lib/local-status'
+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'
 
-type FieldError = { path: string[]; code: string; message: string }
-type InvariantError = { code: string; message: string; context?: unknown }
+export { functionInputIssues, schemaUpgradeHint } from './reasons'
 
 /**
  * Format and display a kernel client error.
  *
- * Handles AstraleError (CLI-local) and every error class exported by
- * @astrale-os/kernel-client: ConnectionError, DisconnectedError,
- * TimeoutError, AuthenticationError, PermissionDeniedError, NotFoundError,
- * KernelError and its subclasses (ValidationError, InvariantViolationError).
+ * 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.
@@ -25,12 +30,11 @@ export async function formatKernelError(
   isRaw: boolean,
   urlArg = '',
   debug = false,
-  opts: { credential?: string } = {},
+  opts: { recovery?: OperationRecovery } = {},
 ): Promise<void> {
   const url =
     urlArg || (error instanceof Error ? ((error as Error & { url?: string }).url ?? '') : '')
   const localContext = await contextForError(error)
-  const credentialExpiration = opts.credential ? decodeJwtExpiration(opts.credential) : null
   // Handle AstraleError (AuthError, etc.) with structured hints
   if (error instanceof AstraleError) {
     if (isRaw) {
@@ -52,167 +56,58 @@ export async function formatKernelError(
   const name = error.name
 
   switch (name) {
-    case 'ConnectionError':
-      if (isRaw)
-        writeRaw({ error: 'CONNECTION_ERROR', message: error.message, url, context: localContext })
-      else {
-        log.error(`Could not connect to ${chalk.bold(url || 'kernel')}`)
-        log.dim(`  ${error.message}`)
-        log.dim('  Is the kernel running? Try: astrale status')
-        printLocalContext(localContext)
-      }
-      break
-
-    case 'DisconnectedError':
-      if (isRaw) writeRaw({ error: 'DISCONNECTED', message: error.message })
-      else {
-        log.error('Connection closed while request was pending')
-        log.dim('  The kernel may have been stopped or restarted. Retry the command.')
-      }
-      break
-
-    case 'TimeoutError': {
-      const timeoutMs = (error as { timeoutMs?: number }).timeoutMs
-      if (isRaw) writeRaw({ error: 'TIMEOUT', message: error.message, timeoutMs })
-      else {
-        log.error(`Request timed out after ${timeoutMs ?? '?'}ms`)
-        log.dim('  Try increasing with --timeout')
-      }
-      break
-    }
-
-    case 'AuthenticationError': {
-      const reason = (error as { reason?: string }).reason ?? 'unknown'
-      if (isRaw)
-        writeRaw({
-          error: 'AUTH_ERROR',
-          reason,
-          message: error.message,
-          credential: credentialExpiration,
-          context: localContext,
-        })
-      else {
-        log.error(`Authentication failed: ${error.message}`)
-        if (reason === 'missing')
-          log.dim('  No credential was sent. Run: astrale identity create <name>')
-        else if (reason === 'invalid')
-          log.dim('  Credential is invalid — check issuer/keypair. Try: astrale identity whoami')
-        else if (reason === 'expired') log.dim('  Credential expired — sign a fresh one')
-        if (credentialExpiration) {
-          const state = credentialExpiration.expired ? 'expired' : 'expires'
-          log.dim(`  Credential ${state} at ${credentialExpiration.expiresAt}`)
-        }
-        printLocalContext(localContext)
-      }
-      break
-    }
-
-    case 'PermissionDeniedError':
-      if (isRaw) writeRaw({ error: 'PERMISSION_DENIED', message: error.message })
-      else {
-        log.error(`Permission denied: ${error.message}`)
-        log.dim('  Your identity does not have the required permissions for this operation')
-      }
+    case 'TransportError':
+      presentTransportError(error, isRaw, url, localContext, opts.recovery)
       break
 
-    case 'NotFoundError': {
-      const cleanMsg = stripMethodSuffix(error.message)
-      const selfMeta = (error as Error & { expandedFromSelf?: SelfExpansionMeta }).expandedFromSelf
-      // kernel-client maps both NOT_FOUND (the node doesn't exist) and
-      // METHOD_NOT_FOUND (the method doesn't exist on a real node) to
-      // `NotFoundError`. Firing the authenticated-principal hint for the
-      // method case is misleading. Gate on the message referencing the
-      // expanded id — node lookup errors mention `@<id>` whereas method
-      // errors mention the method path.
-      const selfHintApplies = selfMeta && error.message.includes(`@${selfMeta.selfId}`)
-      if (isRaw) {
-        const payload: Record<string, unknown> = { error: 'NOT_FOUND', message: cleanMsg }
-        if (selfHintApplies) payload.expandedFromSelf = selfMeta
-        writeRaw(payload)
-      } else {
-        log.error(`Not found: ${cleanMsg}`)
-        log.dim('  Check the path/ID and that the instance is booted')
-        if (selfHintApplies && selfMeta) {
-          const where = selfMeta.slug ? ` on "${selfMeta.slug}"` : ''
-          log.dim(
-            `  @self resolved through authenticated Identity.whoami to @${selfMeta.selfId}${where}.`,
-          )
-          log.dim('  Check that the requested node path still exists for that principal.')
-        }
-      }
-      break
-    }
-
-    case 'ValidationError': {
-      const errors = (error as { errors?: FieldError[] }).errors ?? []
-      if (isRaw) writeRaw({ error: 'VALIDATION_ERROR', message: error.message, details: errors })
-      else {
-        log.error('Validation Error')
-        if (errors.length > 0) {
-          for (const e of errors) {
-            console.log(chalk.red(`  ${e.path.join('.')}: ${e.message} (${chalk.dim(e.code)})`))
-          }
-        } else {
-          // Server often sends details in message but empty errors array
-          console.log(chalk.red(`  ${error.message}`))
-        }
-        log.dim('  Use `astrale introspect <path>` to see the expected schema')
-      }
-      break
-    }
-
-    case 'InvariantViolationError': {
-      const errors = (error as { errors?: InvariantError[] }).errors ?? []
-      if (isRaw) writeRaw({ error: 'INVARIANT_VIOLATION', message: error.message, details: errors })
-      else {
-        log.error('Invariant Violation')
-        for (const e of errors) {
-          console.log(chalk.red(`  ${e.code}: ${e.message}`))
-          if (e.context) console.log(chalk.dim(`    ${JSON.stringify(e.context)}`))
-        }
-      }
-      break
-    }
-
     case 'ResponseError': {
       const code = (error as { readonly code?: unknown }).code
       const reason = (error as { readonly reason?: unknown }).reason
-      const reasonCode =
-        reason !== null &&
-        typeof reason === 'object' &&
-        typeof (reason as { readonly code?: unknown }).code === 'string'
-          ? (reason as { readonly code: string }).code
-          : undefined
+      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 =
-        reasonCode === 'FUNCTION_INPUT_INVALID'
+        codeOfReason === 'FUNCTION_INPUT_INVALID' && (isRaw || inputIssues.length === 0)
           ? 'Use `astrale introspect <path>` to see the callable input.'
-          : undefined
+          : (removalHint ?? (upgrade === undefined ? undefined : schemaUpgradeHint(upgrade)))
       if (isRaw) {
         writeRaw({
           error: 'RESPONSE_ERROR',
           ...(code === undefined ? {} : { code }),
-          message: error.message,
+          message: displayMessage,
           ...(reason === undefined ? {} : { reason }),
           ...(hint === undefined ? {} : { hint }),
         })
       } else {
         log.error(
-          `${chalk.bold(code === undefined ? 'RESPONSE_ERROR' : `RESPONSE_ERROR(${String(code)})`)}: ${error.message}`,
+          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 (reasonCode !== undefined) log.dim(`  reason: ${reasonCode}`)
+        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
     }
 
-    case 'KernelError': {
-      const code = (error as { code?: number | string }).code ?? 'UNKNOWN'
-      const type = (error as { type?: string }).type ?? 'KERNEL_ERROR'
-      if (isRaw) writeRaw({ error: type, code, message: error.message })
-      else log.error(`${chalk.bold(`${type}(${code})`)}: ${error.message}`)
-      break
-    }
-
     default: {
       const mapped = mapPublicError(error)
       if (isRaw) {
@@ -232,9 +127,28 @@ export async function formatKernelError(
   if (debug) printDebug(error, url)
 }
 
-/** Strip internal `::methodName` suffixes from paths in error messages (e.g., "/path::listChildren" → "/path") */
-export function stripMethodSuffix(msg: string): string {
-  return msg.replace(/(\/[^"\s:]+)::([a-zA-Z]\w*)/g, '$1')
+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): {
@@ -273,14 +187,90 @@ function mapPublicError(error: Error): {
       hint: 'Pass the Kernel issuer URL (no /invoke suffix), e.g. https://host/kernel/host',
     }
   }
-  if (name === 'Error' && /unable to connect/i.test(error.message)) {
-    return {
-      code: 'CONNECTION_ERROR',
+  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,
-      hint: 'Check --url / -i and that the Kernel is reachable. Try: astrale status',
-    }
+      ...(url === '' ? {} : { url }),
+      ...(phase === undefined ? {} : { phase }),
+      ...(delivery === undefined ? {} : { delivery }),
+      ...(context === undefined ? {} : { context }),
+      ...(delivery === 'unknown' && recovery !== undefined ? recovery : {}),
+    })
+    return
   }
-  return { code: name && name !== 'Error' ? name : 'UNKNOWN', message: error.message }
+  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 {
@@ -289,7 +279,7 @@ function writeRaw(payload: Record<string, unknown>): void {
 
 async function contextForError(error: unknown): Promise<LocalStatus | undefined> {
   if (!(error instanceof Error)) return undefined
-  if (error.name !== 'AuthenticationError' && error.name !== 'ConnectionError') return undefined
+  if (error.name !== 'TransportError') return undefined
   return readLocalStatus().catch(() => undefined)
 }
 

package/src/connection/exchange.ts

@@ -156,6 +156,7 @@ async function exchange(
     try {
       admitted = exchangeProtocol.acceptErrorResponse(body)
     } catch (cause) {
+      if (!(cause instanceof TypeError)) throw cause
       throw new AstraleError(
         'TOKEN_EXCHANGE_PROTOCOL_ERROR',
         `Token exchange failed with HTTP ${response.status} and an invalid error response.`,
@@ -165,8 +166,19 @@ async function exchange(
     throw new AstraleError(String(admitted.error.code), admitted.error.message)
   }
   requireExchangeResponseHeaders(response)
-  const exchanged = exchangeProtocol.acceptResponse(body)
-  const inspected = credential.inspect(exchanged.token)
+  let exchanged: exchangeProtocol.Response
+  let inspected: ReturnType<typeof credential.inspect>
+  try {
+    exchanged = exchangeProtocol.acceptResponse(body)
+    inspected = credential.inspect(exchanged.token)
+  } catch (cause) {
+    if (!(cause instanceof TypeError)) throw cause
+    throw new AstraleError(
+      'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+      'Token exchange returned an invalid success response.',
+      cause.message,
+    )
+  }
   if (
     inspected.iss !== domainIssuer ||
     inspected.aud !== kernelIssuer ||

package/src/connection/index.ts

@@ -1,6 +1,6 @@
 export { createPathCall } from './call'
 export { runKernelCommand } from './command'
-export type { KernelCommandOpts } from './command'
+export type { KernelCommandOpts, OperationRecovery } from './command'
 export { expandSelfInCall, expandSelfInPath, withSelfHint } from './self'
 export type { SelfExpansionMeta } from './self'
 export { withAdminClientSession, withClientSession, type ConnectionContext } from './session'