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

package/src/connection/.spec/layout.ts

@@ -10,6 +10,7 @@ export default defineLayout({
     'errors.ts',
     'exchange.ts',
     'index.ts',
+    'reasons.ts',
     'self.ts',
     'session.ts',
     'target.ts',

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

@@ -3,7 +3,9 @@ import { describe, expect, test } from 'bun:test'
 import type { Identity } from '../../identity/index'
 import type { AstraleConfig } from '../../lib/config'
 
-import { resolveKeyIdentityAuthOptions } from '../auth'
+import { IdpAudienceMismatchError } from '../../lib/idp'
+import { IdpSessionNoRefreshTokenError } from '../../lib/idp-session'
+import { classifyNoRefreshTokenError, resolveKeyIdentityAuthOptions } from '../auth'
 
 const config: AstraleConfig = {
   issuer: 'https://unregistered.invalid',
@@ -100,3 +102,27 @@ describe('resolveKeyIdentityAuthOptions', () => {
     })
   })
 })
+
+describe('classifyNoRefreshTokenError', () => {
+  test('preserves expiry when the non-refreshable session already targets the required audience', () => {
+    const expired = new IdpSessionNoRefreshTokenError('alice')
+
+    expect(
+      classifyNoRefreshTokenError('https://kernel.example', 'https://kernel.example', expired),
+    ).toBe(expired)
+  })
+
+  test('reports a real audience mismatch when the source audience differs', () => {
+    const result = classifyNoRefreshTokenError(
+      'https://child.example',
+      'https://manager.example',
+      new IdpSessionNoRefreshTokenError('alice'),
+    )
+
+    expect(result).toBeInstanceOf(IdpAudienceMismatchError)
+    expect(result).toMatchObject({
+      requested: 'https://child.example',
+      actual: 'https://manager.example',
+    })
+  })
+})

package/src/connection/__tests__/ca-fetch.test.ts

@@ -29,7 +29,10 @@ describe('connection CA fetch', () => {
       hostname: '127.0.0.1',
       port: 0,
       tls: { cert: certificate, key },
-      fetch: () => new Response('trusted'),
+      fetch: (request) =>
+        new URL(request.url).pathname === '/cached'
+          ? new Response(null, { status: 304, headers: { etag: 'retained' } })
+          : new Response('trusted'),
     })
 
     const requests: Array<{ input: RequestInfo | URL; init?: RequestInit }> = []
@@ -45,6 +48,10 @@ describe('connection CA fetch', () => {
     expect(await httpsResponse.text()).toBe('trusted')
     expect(httpsResponse.url).toBe(httpsUrl)
     expect(httpsResponse.redirected).toBe(false)
+    const cachedResponse = await scoped(`https://127.0.0.1:${server.port}/cached`)
+    expect(cachedResponse.status).toBe(304)
+    expect(cachedResponse.body).toBeNull()
+    expect(cachedResponse.headers.get('etag')).toBe('retained')
     await expect(
       scoped('http://localhost:8080/invoke', init).then((value) => value.text()),
     ).resolves.toBe('fallback')

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

@@ -1,47 +1,82 @@
-import { ResponseError } from '@astrale-os/kernel-client'
+import { ResponseError, TransportError } from '@astrale-os/kernel-client'
 import { describe, expect, test } from 'bun:test'
 
-import { formatKernelError, stripMethodSuffix } from '../errors'
+import { formatKernelError, functionInputIssues, schemaUpgradeHint } from '../errors'
 
 const CONFLICT = 4001
+const VALIDATION = 1003
 
-describe('stripMethodSuffix', () => {
-  test('strips ::listChildren from path', () => {
-    expect(stripMethodSuffix('Path not found: "/nonexistent::listChildren"')).toBe(
-      'Path not found: "/nonexistent"',
-    )
-  })
-
-  test('strips ::get from path', () => {
-    expect(stripMethodSuffix('Path not found: "/some/path::get"')).toBe(
-      'Path not found: "/some/path"',
-    )
-  })
-
-  test('strips any method name', () => {
-    expect(stripMethodSuffix('"/kernel.astrale.ai/Root::describe"')).toBe(
-      '"/kernel.astrale.ai/Root"',
-    )
-  })
-
-  test('does not strip from non-path strings', () => {
-    expect(stripMethodSuffix('regular::text')).toBe('regular::text')
-  })
+describe('formatKernelError', () => {
+  /** @evidence TEST-CLI-CONNECTION-MAPS-TYPED-TRANSPORT */
+  test('maps typed discovery transport evidence without inspecting its cause message', async () => {
+    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
+    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'
+    try {
+      await formatKernelError(error, true)
+    } finally {
+      process.stderr.write = original
+    }
 
-  test('handles multiple paths in one message', () => {
-    expect(stripMethodSuffix('"/a/b::get" and "/c/d::list"')).toBe('"/a/b" and "/c/d"')
+    expect(JSON.parse(writes[0]!)).toMatchObject({
+      error: 'CONNECTION_ERROR',
+      message: 'Publication discovery request failed.',
+      url: 'https://localhost:8443/kernel/host',
+      phase: 'connect',
+      delivery: 'unknown',
+    })
+    expect(writes[0]).not.toContain('ECONNREFUSED')
   })
 
-  test('preserves messages without method suffixes', () => {
-    expect(stripMethodSuffix('No path found')).toBe('No path found')
-  })
+  test('retains operation recovery only for outcome-unknown transport failure', async () => {
+    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 formatKernelError(
+        new TransportError('Request timed out.', {
+          cause: new Error('timeout'),
+          phase: 'timeout',
+          delivery: 'unknown',
+        }),
+        true,
+        undefined,
+        false,
+        {
+          recovery: {
+            operation: '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
+            retry:
+              'astrale domain install https://crm.test --direct --operation 4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
+          },
+        },
+      )
+    } finally {
+      process.stderr.write = original
+    }
 
-  test('does not strip single colon (not a method dispatch)', () => {
-    expect(stripMethodSuffix('"/a/b:notMethod"')).toBe('"/a/b:notMethod"')
+    expect(writes).toHaveLength(1)
+    expect(JSON.parse(writes[0]!)).toMatchObject({
+      error: 'TIMEOUT',
+      phase: 'timeout',
+      delivery: 'unknown',
+      operation: '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
+      retry:
+        'astrale domain install https://crm.test --direct --operation 4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
+    })
   })
-})
 
-describe('formatKernelError', () => {
   /** @evidence TEST-CLI-CONNECTION-PRESERVES-PUBLIC-SEMANTIC-REASON */
   test('preserves a Kernel-admitted semantic reason in machine output', async () => {
     const writes: string[] = []
@@ -94,6 +129,102 @@ describe('formatKernelError', () => {
     })
   })
 
+  test('explains deletion-only schema work without changing the Kernel reason', async () => {
+    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 formatKernelError(
+        new ResponseError(CONFLICT, 'Schema change requires migration.', {
+          code: 'DATA_MIGRATION_REQUIRED',
+          details: {
+            requirements: [
+              {
+                operation: 'remove-facts',
+                reason: 'destructive-change',
+                subject: {
+                  kind: 'definition',
+                  ref: { origin: 'x.test', kind: 'class', name: 'X' },
+                },
+                work: { observedFacts: 1 },
+              },
+            ],
+          },
+        }),
+        true,
+      )
+    } finally {
+      process.stderr.write = original
+    }
+
+    expect(JSON.parse(writes[0]!)).toEqual({
+      error: 'RESPONSE_ERROR',
+      code: CONFLICT,
+      message: 'Schema change requires migration.',
+      reason: {
+        code: 'DATA_MIGRATION_REQUIRED',
+        details: {
+          requirements: [
+            {
+              operation: 'remove-facts',
+              reason: 'destructive-change',
+              subject: {
+                kind: 'definition',
+                ref: { origin: 'x.test', kind: 'class', name: 'X' },
+              },
+              work: { observedFacts: 1 },
+            },
+          ],
+        },
+      },
+      hint: 'Delete this data explicitly, then retry. No data was deleted.',
+    })
+  })
+
+  test('prints an actionable message for deletion-only schema work', async () => {
+    const errors: string[] = []
+    const hints: string[] = []
+    const originalError = console.error
+    const originalLog = console.log
+    console.error = (...values: unknown[]) => errors.push(values.map(String).join(' '))
+    console.log = (...values: unknown[]) => hints.push(values.map(String).join(' '))
+    try {
+      await formatKernelError(
+        new ResponseError(CONFLICT, 'Schema change requires migration.', {
+          code: 'DATA_MIGRATION_REQUIRED',
+          details: {
+            requirements: [
+              {
+                operation: 'remove-facts',
+                reason: 'destructive-change',
+                subject: {
+                  kind: 'definition',
+                  ref: { origin: 'x.test', kind: 'class', name: 'X' },
+                },
+                work: { observedFacts: 1 },
+              },
+            ],
+          },
+        }),
+        false,
+      )
+    } finally {
+      console.error = originalError
+      console.log = originalLog
+    }
+
+    expect(errors.join('\n')).toContain('DATA_MIGRATION_REQUIRED')
+    expect(errors.join('\n')).toContain(
+      'Existing business data still uses schema definitions being removed.',
+    )
+    expect(hints.join('\n')).toContain(
+      'Delete this data explicitly, then retry. No data was deleted.',
+    )
+  })
+
   test('maps SDK class names to stable CLI error codes', async () => {
     const writes: string[] = []
     const original = process.stderr.write
@@ -113,4 +244,323 @@ describe('formatKernelError', () => {
       message: 'Path must have an Id or Domain anchor.',
     })
   })
+
+  /** @evidence TEST-CLI-CONNECTION-PRESENTS-BOUNDED-REPAIRS */
+  test('renders callable and Query repair coordinates for humans', async () => {
+    const lines: string[] = []
+    const originalError = console.error
+    const originalLog = console.log
+    console.error = (...values: unknown[]) => lines.push(values.join(' '))
+    console.log = (...values: unknown[]) => lines.push(values.join(' '))
+    try {
+      await formatKernelError(
+        new ResponseError(VALIDATION, 'Function input is invalid.', {
+          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: '/operationId',
+                message: 'Object is missing required property operationId.',
+              },
+              {
+                code: 'VALUE_SCHEMA_INSTANCE_INVALID',
+                path: '/slug',
+                message: 'Object is missing required property slug.',
+              },
+            ],
+          },
+        }),
+        false,
+      )
+      await formatKernelError(
+        new ResponseError(VALIDATION, 'Query input is invalid.', {
+          code: 'QUERY_INPUT_INVALID',
+          details: {
+            phase: 'plan',
+            issue: 'QUERY_DEFINITION_NOT_EDGE',
+            path: '/steps/0/via/0',
+          },
+        }),
+        false,
+      )
+    } finally {
+      console.error = originalError
+      console.log = originalLog
+    }
+
+    const rendered = lines.join('\n')
+    expect(rendered).toContain('/issuer: Object is missing required property issuer.')
+    expect(rendered).toContain('/operationId: Object is missing required property operationId.')
+    expect(rendered).toContain('/slug: Object is missing required property slug.')
+    expect(rendered).toContain('/steps/0/via/0  QUERY_DEFINITION_NOT_EDGE')
+  })
+
+  test('explains immutable issuer replacements and preserves the Kernel reason', async () => {
+    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 formatKernelError(
+        new ResponseError(5001, 'Schema operation is not supported.', {
+          code: 'SCHEMA_UPGRADE_INCOMPATIBLE',
+          details: {
+            phase: 'upgrade',
+            origin: 'grc.example',
+            issue: 'issuer-changed',
+            installedIssuer: 'https://old.example',
+            replacementIssuer: 'https://new.example',
+          },
+        }),
+        true,
+      )
+    } finally {
+      process.stderr.write = original
+    }
+
+    expect(JSON.parse(writes[0]!)).toEqual({
+      error: 'RESPONSE_ERROR',
+      code: 5001,
+      message: 'Schema operation is not supported.',
+      reason: {
+        code: 'SCHEMA_UPGRADE_INCOMPATIBLE',
+        details: {
+          phase: 'upgrade',
+          origin: 'grc.example',
+          issue: 'issuer-changed',
+          installedIssuer: 'https://old.example',
+          replacementIssuer: 'https://new.example',
+        },
+      },
+      hint: schemaUpgradeHint({
+        origin: 'grc.example',
+        issue: 'issuer-changed',
+        installedIssuer: 'https://old.example',
+        replacementIssuer: 'https://new.example',
+      }),
+    })
+  })
+
+  test('prints both issuers and the recovery command for an incompatible replacement', async () => {
+    const errors: string[] = []
+    const details: string[] = []
+    const originalError = console.error
+    const originalLog = console.log
+    console.error = (...values: unknown[]) => errors.push(values.map(String).join(' '))
+    console.log = (...values: unknown[]) => details.push(values.map(String).join(' '))
+    try {
+      await formatKernelError(
+        new ResponseError(5001, 'Schema operation is not supported.', {
+          code: 'SCHEMA_UPGRADE_INCOMPATIBLE',
+          details: {
+            phase: 'upgrade',
+            origin: 'grc.example',
+            issue: 'issuer-changed',
+            installedIssuer: 'https://old.example',
+            replacementIssuer: 'https://new.example',
+          },
+        }),
+        false,
+      )
+    } finally {
+      console.error = originalError
+      console.log = originalLog
+    }
+
+    expect(errors.join('\n')).toContain('RESPONSE_ERROR(5001)')
+    expect(details.join('\n')).toContain('reason: SCHEMA_UPGRADE_INCOMPATIBLE')
+    expect(details.join('\n')).toContain('installed issuer: https://old.example')
+    expect(details.join('\n')).toContain('replacement issuer: https://new.example')
+    expect(details.join('\n')).toContain('astrale domain uninstall grc.example')
+  })
+
+  test('explains a private Domain source without exposing transport diagnostics', async () => {
+    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 formatKernelError(
+        new ResponseError(1003, 'Function input is invalid.', {
+          code: 'SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC',
+          details: { phase: 'publication', requiredScope: 'public' },
+        }),
+        true,
+      )
+    } finally {
+      process.stderr.write = original
+    }
+
+    expect(JSON.parse(writes[0]!)).toEqual({
+      error: 'RESPONSE_ERROR',
+      code: 1003,
+      message: 'Expose the Domain through a public HTTPS URL or public tunnel, then retry.',
+      reason: {
+        code: 'SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC',
+        details: { phase: 'publication', requiredScope: 'public' },
+      },
+    })
+  })
+
+  test('prints the actionable private-source message in interactive output', async () => {
+    const errors: string[] = []
+    const hints: string[] = []
+    const originalError = console.error
+    const originalLog = console.log
+    console.error = (...values: unknown[]) => errors.push(values.map(String).join(' '))
+    console.log = (...values: unknown[]) => hints.push(values.map(String).join(' '))
+    try {
+      await formatKernelError(
+        new ResponseError(1003, 'Function input is invalid.', {
+          code: 'SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC',
+          details: { phase: 'publication', requiredScope: 'public' },
+        }),
+        false,
+      )
+    } finally {
+      console.error = originalError
+      console.log = originalLog
+    }
+
+    expect(errors.join('\n')).toContain('SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC')
+    expect(errors.join('\n')).toContain(
+      'Expose the Domain through a public HTTPS URL or public tunnel, then retry.',
+    )
+    expect(hints).toEqual([])
+  })
+
+  test('preserves structured Function input issues in machine output', async () => {
+    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 formatKernelError(
+        new ResponseError(1003, 'Function input is invalid.', {
+          code: 'FUNCTION_INPUT_INVALID',
+          details: {
+            issues: [
+              {
+                code: 'INVALID_FORMAT',
+                path: '/customer/email',
+                message: 'Must be a valid email address.',
+              },
+            ],
+          },
+        }),
+        true,
+      )
+    } finally {
+      process.stderr.write = original
+    }
+
+    expect(JSON.parse(writes[0]!)).toEqual({
+      error: 'RESPONSE_ERROR',
+      code: 1003,
+      message: 'Function input is invalid.',
+      reason: {
+        code: 'FUNCTION_INPUT_INVALID',
+        details: {
+          issues: [
+            {
+              code: 'INVALID_FORMAT',
+              path: '/customer/email',
+              message: 'Must be a valid email address.',
+            },
+          ],
+        },
+      },
+      hint: 'Use `astrale introspect <path>` to see the callable input.',
+    })
+  })
+
+  test('prints Kernel-provided Function input messages in interactive output', async () => {
+    const errors: string[] = []
+    const details: string[] = []
+    const originalError = console.error
+    const originalLog = console.log
+    console.error = (...values: unknown[]) => errors.push(values.map(String).join(' '))
+    console.log = (...values: unknown[]) => details.push(values.map(String).join(' '))
+    try {
+      await formatKernelError(
+        new ResponseError(1003, 'Function input is invalid.', {
+          code: 'FUNCTION_INPUT_INVALID',
+          details: {
+            issues: [
+              {
+                code: 'INVALID_FORMAT',
+                path: '/customer/email',
+                message: 'Must be a valid email address.',
+              },
+            ],
+          },
+        }),
+        false,
+      )
+    } finally {
+      console.error = originalError
+      console.log = originalLog
+    }
+
+    expect(errors.join('\n')).toContain('Function input is invalid.')
+    expect(details.join('\n')).toContain(
+      '/customer/email: Must be a valid email address. (INVALID_FORMAT)',
+    )
+    expect(details.join('\n')).not.toContain('astrale introspect')
+  })
+
+  test('keeps the introspection fallback for legacy Function input issues', async () => {
+    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 formatKernelError(
+        new ResponseError(1003, 'Function input is invalid.', {
+          code: 'FUNCTION_INPUT_INVALID',
+          details: { issues: [{ code: 'INVALID_FORMAT', path: '/customer/email' }] },
+        }),
+        true,
+      )
+    } finally {
+      process.stderr.write = original
+    }
+
+    expect(JSON.parse(writes[0]!)).toMatchObject({
+      reason: {
+        code: 'FUNCTION_INPUT_INVALID',
+        details: { issues: [{ code: 'INVALID_FORMAT', path: '/customer/email' }] },
+      },
+      hint: 'Use `astrale introspect <path>` to see the callable input.',
+    })
+  })
+
+  test('rejects malformed public Function issue messages', () => {
+    expect(
+      functionInputIssues({
+        code: 'FUNCTION_INPUT_INVALID',
+        details: {
+          issues: [
+            { code: 'INVALID_FORMAT', path: '/safe', message: 'Safe message.' },
+            { code: 'INVALID_FORMAT', path: 'not-a-pointer', message: 'Unsafe path.' },
+            { code: 'INVALID_FORMAT', path: '/unsafe', message: 'Unsafe\nmessage.' },
+          ],
+        },
+      }),
+    ).toEqual([{ code: 'INVALID_FORMAT', path: '/safe', message: 'Safe message.' }])
+  })
 })

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

@@ -158,9 +158,44 @@ describe('Domain token exchange', () => {
       code: 'TOKEN_EXCHANGE_PROTOCOL_ERROR',
     })
   })
+
+  test('rejects success responses without no-store or with malformed fields', async () => {
+    const exchanged = token(DOMAIN, KERNEL, 'user-1', EXPIRES_AT)
+    const cache = () => new ExchangeCredentialCache(join(directory, crypto.randomUUID()))
+    const resolver = (fetch: Fetch) =>
+      createExchangeCredentialResolver(
+        TARGET,
+        { resolve: async () => SOURCE_TOKEN },
+        fetch,
+        5_000,
+        cache(),
+      )
+
+    await expect(
+      resolver(exchangeFetch(exchanged, { cacheControl: false })).resolve(
+        KERNEL,
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+      message: 'Token exchange response is missing Cache-Control: no-store.',
+    })
+    await expect(
+      resolver(exchangeFetch(exchanged, { body: { token: 7, expiresAt: 'soon' } })).resolve(
+        KERNEL,
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+      message: 'Token exchange returned an invalid success response.',
+    })
+  })
 })
 
-function exchangeFetch(exchanged: string): Fetch {
+function exchangeFetch(
+  exchanged: string,
+  options: { readonly body?: unknown; readonly cacheControl?: boolean } = {},
+): Fetch {
   return async (input, init) => {
     const url = String(input)
     if (url === INVOCATION) {
@@ -174,11 +209,17 @@ function exchangeFetch(exchanged: string): Fetch {
       )
     }
     if (url.endsWith('/.well-known/openid-configuration')) return jsonResponse(configuration(true))
-    return jsonResponse(
-      { token: exchanged, expiresAt: EXPIRES_AT },
-      200,
-      'application/vnd.astrale+json',
+    const response = new Response(
+      JSON.stringify(options.body ?? { token: exchanged, expiresAt: EXPIRES_AT }),
+      {
+        status: 200,
+        headers: {
+          'content-type': 'application/vnd.astrale+json',
+          ...(options.cacheControl === false ? {} : { 'cache-control': 'no-store' }),
+        },
+      },
     )
+    return response
   }
 }