@astrale-os/cli 0.8.1-alpha.6 → 0.8.1-alpha.7

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

@@ -1,47 +1,42 @@
-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')
-  })
-
-  test('handles multiple paths in one message', () => {
-    expect(stripMethodSuffix('"/a/b::get" and "/c/d::list"')).toBe('"/a/b" and "/c/d"')
-  })
-
-  test('preserves messages without method suffixes', () => {
-    expect(stripMethodSuffix('No path found')).toBe('No path found')
-  })
+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('does not strip single colon (not a method dispatch)', () => {
-    expect(stripMethodSuffix('"/a/b:notMethod"')).toBe('"/a/b:notMethod"')
+    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')
   })
-})
 
-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 +89,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 +204,287 @@ 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',
+            expected: 'https://old.example',
+            actual: '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',
+          expected: 'https://old.example',
+          actual: 'https://new.example',
+        },
+      },
+      hint: schemaUpgradeHint({
+        origin: 'grc.example',
+        expected: 'https://old.example',
+        actual: 'https://new.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
   }
 }
 

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

@@ -53,7 +53,7 @@ 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)
     process.exit(1)
   }
 }