@astrale-os/cli 1.0.0-beta.2 → 1.0.0-beta.20

package/src/commands/__tests__/install-direct.test.ts

@@ -1,21 +1,128 @@
+import type { InstallResult } from '@astrale-os/sdk/client/schema'
+
+import { defineSchema, schema } from '@astrale-os/sdk/schema'
 import { describe, expect, test } from 'bun:test'
 
-import { directInstallCallInput } from '../domain/install'
+import { directInstallCallInput, directInstallPresentation } from '../domain/install'
+
+const currentRevision = schema.revision(defineSchema('tasks.astrale.ai', {}))
 
 describe('directInstallCallInput', () => {
   test('sends the current remote install syscall, not a legacy url list', () => {
     const operation = '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8'
-    expect(directInstallCallInput('https://tasks.example.test', operation, 'secret')).toEqual({
-      operation,
+    const input = directInstallCallInput('https://tasks.example.test', operation, 'secret')
+
+    expect(String(input.operation)).toBe(operation)
+    expect(input.domains).toEqual([
+      {
+        publication: {
+          url: 'https://tasks.example.test',
+          token: 'secret',
+        },
+      },
+    ])
+  })
+
+  test('presents a committed install from its receipt', () => {
+    const operation = directInstallCallInput(
+      'https://tasks.example.test',
+      '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
+    ).operation
+    const result = {
+      changed: true,
+      receipt: {
+        operation,
+        transitions: [
+          {
+            intent: {
+              transition: 'transition-1',
+              operation,
+              origin: 'tasks.astrale.ai',
+              previous: null,
+              generation: {
+                origin: 'tasks.astrale.ai',
+                revision: currentRevision,
+                generation: 'sha256:generation',
+              },
+            },
+            phase: 'cutover',
+            state: 'committed',
+          },
+        ],
+      },
+    } satisfies InstallResult
+
+    expect(directInstallPresentation(result, 'ignored')).toEqual({
+      operation: '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
+      origin: 'tasks.astrale.ai',
+      revision: currentRevision,
+      status: 'installed',
+    })
+  })
+
+  test('presents an idempotent install from the current Domain observation', () => {
+    const operation = '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8'
+    const result = {
+      changed: false,
       domains: [
         {
-          source: {
-            kind: 'remote',
-            url: 'https://tasks.example.test',
-            token: 'secret',
-          },
+          origin: 'tasks.astrale.ai',
+          revision: currentRevision,
+          generation: 'sha256:generation',
+          publication: null,
+          readiness: 'sha256:readiness',
+          capabilities: { requested: {}, materialized: {} },
+          bindings: { callables: [], views: [] },
         },
       ],
+    } satisfies InstallResult
+
+    expect(directInstallPresentation(result, operation)).toEqual({
+      operation,
+      origin: 'tasks.astrale.ai',
+      revision: currentRevision,
+      status: 'already current',
     })
   })
+
+  test('rejects a changed result without a committed transition', () => {
+    const result = {
+      changed: true,
+      receipt: { operation: '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8', transitions: [] },
+    } as unknown as InstallResult
+
+    expect(() => directInstallPresentation(result, 'ignored')).toThrow(
+      'Kernel install returned no committed Domain transition.',
+    )
+  })
+
+  test('rejects a committed transition without an installed generation', () => {
+    const operation = directInstallCallInput(
+      'https://tasks.example.test',
+      '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
+    ).operation
+    const result = {
+      changed: true,
+      receipt: {
+        operation,
+        transitions: [
+          {
+            intent: {
+              transition: 'transition-1',
+              operation,
+              origin: 'tasks.astrale.ai',
+              previous: null,
+              generation: null,
+            },
+            phase: 'cutover',
+            state: 'committed',
+          },
+        ],
+      },
+    } satisfies InstallResult
+
+    expect(() => directInstallPresentation(result, 'ignored')).toThrow(
+      'Kernel install returned a committed transition without a Domain generation.',
+    )
+  })
 })

package/src/commands/__tests__/install-identity-override.test.ts

@@ -1,9 +1,7 @@
-import { defineDomain } from '@astrale-os/sdk'
-import { issuer } from '@astrale-os/sdk/auth'
-import { createDeployment } from '@astrale-os/sdk/deployment'
-import { defineSchema } from '@astrale-os/sdk/schema/v1'
+import { defineSchema } from '@astrale-os/sdk/schema'
 import { afterAll, describe, expect, test } from 'bun:test'
 
+import { releaseFor } from '../../__tests__/fixtures/publication'
 import { domainRefFromTarget, isIdentityOverride, probeDeclaredOrigin } from '../domain/install'
 
 describe('admin-path target classification', () => {
@@ -47,16 +45,7 @@ describe('declared-origin Publication probe', () => {
 
   test('reads origin from a well-formed canonical Publication', async () => {
     const schema = defineSchema('crm.acme.dev', {})
-    const definition = defineDomain({
-      schema,
-      handlers: { functions: {}, classes: {}, interfaces: {} },
-    })
-    const deployed = createDeployment({
-      definition,
-      issuer: issuer.accept('https://crm.acme.dev'),
-      bundleHref: 'https://crm.acme.dev/domain.bundle.json',
-      bindings: { callables: [] },
-    }).publication
+    const deployed = releaseFor(schema, 'https://crm.acme.dev').publication
     const url = servePublication((req) =>
       new URL(req.url).pathname === '/.well-known/astrale/domain.json'
         ? Response.json(deployed)

package/src/commands/__tests__/instance-list-rows.test.ts

@@ -5,7 +5,7 @@ import type { InstanceInfo } from '../../lib/admin-instance'
 import { buildInstanceRows, type Bookmark } from '../instance/list'
 
 const managed: InstanceInfo[] = [
-  { id: 'demo', slug: 'demo', url: 'https://demo.eu.astrale.ai', region: 'eu' },
+  { id: 'demo', slug: 'demo', url: 'https://demo.eu.astrale.ai', state: 'ready' },
 ]
 
 function bookmark(overrides: Partial<Bookmark> = {}): Bookmark {

package/src/commands/__tests__/instance-status.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { InstanceInfo } from '../../lib/admin-instance'
+import type { ResolvedInstance } from '../../lib/instance'
+
+import { resolveStatus, type StatusDependencies } from '../instance/status'
+
+const cliRoot = join(import.meta.dir, '../../..')
+
+let home: string
+let server: ReturnType<typeof Bun.serve>
+
+beforeEach(async () => {
+  home = await mkdtemp(join(tmpdir(), 'astrale-instance-status-'))
+  server = Bun.serve({
+    port: 0,
+    fetch(request) {
+      const url = new URL(request.url)
+      const issuer = `http://127.0.0.1:${server.port}`
+      if (url.pathname === '/.well-known/openid-configuration') {
+        return Response.json({ issuer, jwks_uri: `${issuer}/.well-known/jwks.json` })
+      }
+      if (url.pathname === '/.well-known/jwks.json') {
+        return Response.json({ keys: [{ kid: 'status-test' }] })
+      }
+      return new Response('Not found', { status: 404 })
+    },
+  })
+})
+
+afterEach(async () => {
+  server.stop(true)
+  await rm(home, { recursive: true, force: true })
+})
+
+describe('instance status', () => {
+  test('keeps managed lifecycle authoritative when the slug is also bookmarked', async () => {
+    const managed: InstanceInfo = {
+      id: '@managed',
+      slug: 'shared',
+      url: 'https://managed.example.com',
+      state: 'provisioning',
+      phase: 'bootstrap',
+    }
+    const statusOwnedInstance: StatusDependencies['statusOwnedInstance'] = mock(async () => managed)
+    const resolveInstance: StatusDependencies['resolveInstance'] = mock(async () => {
+      throw new Error('bookmark resolution must not run')
+    })
+    const probeBookmark: StatusDependencies['probeBookmark'] = mock(async () => {
+      throw new Error('bookmark probe must not run')
+    })
+
+    await expect(
+      resolveStatus('shared', {}, { statusOwnedInstance, resolveInstance, probeBookmark }),
+    ).resolves.toEqual(managed)
+    expect(statusOwnedInstance).toHaveBeenCalledWith({}, 'shared')
+    expect(resolveInstance).not.toHaveBeenCalled()
+    expect(probeBookmark).not.toHaveBeenCalled()
+  })
+
+  test('probes only an explicitly selected bookmark and rejects mixed source flags', async () => {
+    const bookmark: ResolvedInstance = {
+      name: 'local',
+      kind: 'bookmark',
+      url: 'https://local.example.com',
+      issuer: 'https://issuer.example.com',
+    }
+    const statusOwnedInstance: StatusDependencies['statusOwnedInstance'] = mock(async () => {
+      throw new Error('managed status must not run')
+    })
+    const resolveInstance: StatusDependencies['resolveInstance'] = mock(async () => bookmark)
+    const probeBookmark: StatusDependencies['probeBookmark'] = mock(async () => undefined)
+    const dependencies = { statusOwnedInstance, resolveInstance, probeBookmark }
+
+    await expect(resolveStatus('local', { bookmarked: true }, dependencies)).resolves.toEqual({
+      slug: 'local',
+      url: bookmark.url,
+      issuer: 'https://issuer.example.com',
+      kind: 'bookmark',
+      state: 'ready',
+    })
+    expect(resolveInstance).toHaveBeenCalledWith('local', undefined, { persist: false })
+    expect(probeBookmark).toHaveBeenCalledWith(bookmark)
+    expect(statusOwnedInstance).not.toHaveBeenCalled()
+
+    await expect(
+      resolveStatus('local', { bookmarked: true, admin: 'admin' }, dependencies),
+    ).rejects.toMatchObject({ code: 'INVALID_FLAG' })
+  })
+
+  test('probes an explicit local bookmark without rewriting its registry', async () => {
+    const issuer = `http://127.0.0.1:${server.port}`
+    const registry = `${JSON.stringify({
+      active: 'local',
+      instances: {
+        local: {
+          url: issuer,
+          issuer,
+          mode: 'remote',
+        },
+      },
+    })}\n`
+    const path = join(home, 'instances.json')
+    await writeFile(path, registry)
+
+    const process = Bun.spawn({
+      cmd: [
+        'bun',
+        join(cliRoot, 'bin/astrale.ts'),
+        'instance',
+        'status',
+        'local',
+        '--bookmarked',
+        '--json',
+      ],
+      env: { ...Bun.env, ASTRALE_HOME: home },
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(process.stdout).text(),
+      new Response(process.stderr).text(),
+      process.exited,
+    ])
+
+    expect(exitCode, stderr).toBe(0)
+    expect(JSON.parse(stdout)).toEqual({
+      slug: 'local',
+      url: issuer,
+      issuer,
+      kind: 'bookmark',
+      state: 'ready',
+    })
+    expect(await readFile(path, 'utf8')).toBe(registry)
+  })
+})

package/src/commands/__tests__/introspect-parse.test.ts

@@ -1,6 +1,44 @@
+import type { DomainBundle, DomainInfo } from '@astrale-os/sdk/client/schema'
+
+import { bundle, defineSchema, func, method, nodeClass, schema } from '@astrale-os/sdk/schema'
 import { describe, expect, test } from 'bun:test'
 
-import { parseIntrospectTarget } from '../introspect'
+import { introspectCommand, parseIntrospectTarget } from '../introspect'
+
+const source = defineSchema('host.astrale.ai', {
+  classes: {
+    Manager: nodeClass({
+      methods: {
+        createInstance: method({
+          auth: 'authenticated',
+          input: { type: 'object', properties: {}, additionalProperties: false },
+          output: { type: 'object', additionalProperties: true },
+          static: true,
+        }),
+      },
+    }),
+  },
+  functions: {
+    journal: func({
+      auth: 'authenticated',
+      input: { type: 'object', properties: {}, additionalProperties: false },
+      output: { type: 'object', additionalProperties: true },
+    }),
+  },
+})
+
+const info = {
+  origin: source.origin,
+  revision: schema.revision(source),
+  generation: 'sha256:generation',
+  publication: null,
+  readiness: 'sha256:readiness',
+  capabilities: { requested: {}, materialized: {} },
+  bindings: { callables: [], views: [] },
+} satisfies DomainInfo
+
+const installed = bundle.create(source)
+const bundled = { domain: info, bundle: installed } satisfies DomainBundle
 
 describe('parseIntrospectTarget', () => {
   test('accepts a bare origin', () => {
@@ -18,4 +56,45 @@ describe('parseIntrospectTarget', () => {
   test('rejects an @id', () => {
     expect(() => parseIntrospectTarget('@abc')).toThrow('not an @id')
   })
+
+  test('routes bare, bundle, Method, and Function commands through the current Schema API', async () => {
+    const calls: string[] = []
+    const schema = {
+      inspect: async (origin: string) => {
+        calls.push(`inspect:${origin}`)
+        return info
+      },
+      bundle: async (origin: string) => {
+        calls.push(`bundle:${origin}`)
+        return bundled
+      },
+    }
+    const results: unknown[] = []
+    const runKernelCommand = async (input: {
+      fn: (context: unknown) => Promise<unknown>
+    }): Promise<void> => {
+      results.push(await input.fn({ session: { schema } }))
+    }
+    const dependencies = { runKernelCommand: runKernelCommand as never }
+
+    await introspectCommand('host.astrale.ai', { json: true }, dependencies)
+    await introspectCommand('host.astrale.ai', { bundle: true, json: true }, dependencies)
+    await introspectCommand(
+      '/:host.astrale.ai:class.Manager:createInstance',
+      { json: true },
+      dependencies,
+    )
+    await introspectCommand('/:host.astrale.ai:function.journal', { json: true }, dependencies)
+
+    expect(results[0]).toBe(info)
+    expect(results[1]).toBe(bundled)
+    expect(results[2]).toMatchObject({ class: 'Manager', method: 'createInstance' })
+    expect(results[3]).toMatchObject({ function: 'journal' })
+    expect(calls).toEqual([
+      'inspect:host.astrale.ai',
+      'bundle:host.astrale.ai',
+      'bundle:host.astrale.ai',
+      'bundle:host.astrale.ai',
+    ])
+  })
 })

package/src/commands/__tests__/logs.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, test } from 'bun:test'
 
-import { acceptJournalPage, buildJournalInput } from '../logs'
+import logsCommand, {
+  acceptJournalPage,
+  buildJournalInput,
+  followLogs,
+  formatFollowRecord,
+} from '../logs'
 
 describe('buildJournalInput', () => {
   /** @evidence TEST-CLI-LOGS-MAPS-EXACT-JOURNAL-INPUT */
@@ -81,7 +86,15 @@ describe('acceptJournalPage', () => {
           occurredAt: '2026-08-19T16:51:10.049Z',
           committedAt: '2026-08-19T16:51:10.070Z',
           payload: { outcome: 'rejected' },
-          correlation: { invocationId: 'cf862a64-3aa1-4343-ba86-f9b516c4ff95' },
+          correlation: {
+            operationId: 'operation-child',
+            parentOperationId: 'operation-parent',
+            invocationId: 'cf862a64-3aa1-4343-ba86-f9b516c4ff95',
+            rootInvocationId: 'invocation-root',
+            parentInvocationId: 'invocation-parent',
+            traceId: 'trace-1',
+            spanId: 'span-1',
+          },
         },
       ],
     })
@@ -91,7 +104,242 @@ describe('acceptJournalPage', () => {
       timestamp: '2026-08-19T16:51:10.049Z',
       occurredAt: '2026-08-19T16:51:10.049Z',
       committedAt: '2026-08-19T16:51:10.070Z',
+      correlation: {
+        operationId: 'operation-child',
+        parentOperationId: 'operation-parent',
+        invocationId: 'cf862a64-3aa1-4343-ba86-f9b516c4ff95',
+        rootInvocationId: 'invocation-root',
+        parentInvocationId: 'invocation-parent',
+        traceId: 'trace-1',
+        spanId: 'span-1',
+      },
       correlationId: 'cf862a64-3aa1-4343-ba86-f9b516c4ff95',
     })
   })
+
+  test('rejects malformed or invented structured correlation fields', () => {
+    const record = {
+      sequence: 1,
+      topic: 'function.invoke',
+      occurredAt: '2026-08-19T16:51:10.049Z',
+      payload: {},
+    }
+    expect(() => acceptJournalPage({ records: [{ ...record, correlation: 'opaque' }] })).toThrow(
+      'correlation must be an object',
+    )
+    expect(() =>
+      acceptJournalPage({ records: [{ ...record, correlation: { authority: 'forged' } }] }),
+    ).toThrow('correlation.authority is unsupported')
+    for (const field of [
+      'operationId',
+      'parentOperationId',
+      'invocationId',
+      'rootInvocationId',
+      'parentInvocationId',
+      'traceId',
+      'spanId',
+    ]) {
+      expect(() =>
+        acceptJournalPage({ records: [{ ...record, correlation: { [field]: 7 } }] }),
+      ).toThrow(`correlation.${field}`)
+    }
+    expect(() =>
+      acceptJournalPage({ records: [{ ...record, correlation: { invocationId: '   ' } }] }),
+    ).toThrow('must be non-empty')
+    expect(() =>
+      acceptJournalPage({
+        records: [{ ...record, correlation: { invocationId: 'x'.repeat(257) } }],
+      }),
+    ).toThrow('at most 256 UTF-8 bytes')
+    expect(
+      acceptJournalPage({
+        records: [{ ...record, correlation: { invocationId: 'x'.repeat(256) } }],
+      }).records[0].correlation?.invocationId,
+    ).toHaveLength(256)
+    expect(
+      acceptJournalPage({
+        records: [{ ...record, correlation: { invocationId: 'é'.repeat(128) } }],
+      }).records[0].correlation?.invocationId,
+    ).toHaveLength(128)
+    expect(() =>
+      acceptJournalPage({
+        records: [{ ...record, correlation: { invocationId: `${'é'.repeat(127)}€` } }],
+      }),
+    ).toThrow('at most 256 UTF-8 bytes')
+  })
+
+  test('keeps legacy identity compatibility coherent with structured correlation', () => {
+    const record = {
+      sequence: 1,
+      topic: 'function.invoke',
+      occurredAt: '2026-08-19T16:51:10.049Z',
+      payload: {},
+    }
+    expect(
+      acceptJournalPage({
+        records: [{ ...record, correlationId: 'legacy-only', causationId: 'legacy-cause' }],
+      }).records[0],
+    ).toMatchObject({ correlationId: 'legacy-only', causationId: 'legacy-cause' })
+    expect(
+      acceptJournalPage({
+        records: [
+          {
+            ...record,
+            correlationId: 'same',
+            correlation: { invocationId: 'same' },
+          },
+        ],
+      }).records[0],
+    ).toMatchObject({ correlationId: 'same', correlation: { invocationId: 'same' } })
+    expect(() =>
+      acceptJournalPage({
+        records: [
+          {
+            ...record,
+            correlationId: 'legacy',
+            correlation: { invocationId: 'structured' },
+          },
+        ],
+      }),
+    ).toThrow('conflicting correlation identifiers')
+  })
+
+  test('serializes one complete structured record per machine-follow line', () => {
+    const record = acceptJournalPage({
+      records: [
+        {
+          sequence: 2,
+          topic: 'function.invoke',
+          occurredAt: '2026-08-19T16:51:10.049Z',
+          payload: { outcome: 'completed' },
+          correlation: {
+            operationId: 'operation-child',
+            parentOperationId: 'operation-parent',
+            invocationId: 'invocation-child',
+            rootInvocationId: 'invocation-root',
+            parentInvocationId: 'invocation-parent',
+            traceId: 'trace-1',
+            spanId: 'span-1',
+          },
+        },
+      ],
+    }).records[0]
+    expect(formatFollowRecord(record).endsWith('\n')).toBe(true)
+    expect(JSON.parse(formatFollowRecord(record))).toEqual(record)
+  })
+})
+
+describe('follow output routing', () => {
+  const inputRecord = {
+    sequence: 2,
+    topic: 'function.invoke',
+    occurredAt: '2026-08-19T16:51:10.049Z',
+    payload: { outcome: 'completed' },
+    principal: 'principal-1',
+    correlation: {
+      invocationId: 'invocation-child',
+      rootInvocationId: 'invocation-root',
+      parentInvocationId: 'invocation-parent',
+    },
+  }
+  const admittedRecord = acceptJournalPage({ records: [inputRecord] }).records[0]
+
+  test('routes every effective machine mode through complete NDJSON records', async () => {
+    for (const { opts, tty } of [
+      { opts: { json: true }, tty: true },
+      { opts: { raw: true }, tty: true },
+      { opts: { format: 'json' as const }, tty: true },
+      { opts: { ci: true }, tty: true },
+      { opts: {}, tty: false },
+      { opts: { format: 'yaml' as const, json: true }, tty: true },
+      { opts: { format: 'yaml' as const, raw: true }, tty: true },
+    ]) {
+      const stdout = await captureFollowOutput({ ...opts, follow: true }, tty)
+      expect(stdout.endsWith('\n')).toBe(true)
+      expect(JSON.parse(stdout)).toEqual(admittedRecord)
+    }
+  })
+
+  test('keeps an unflagged TTY human-readable', async () => {
+    const stdout = await captureFollowOutput({ follow: true }, true)
+    expect(stdout).toContain('function.invoke')
+    expect(stdout).toContain('principal-1')
+    expect(stdout).not.toContain('invocation-child')
+    expect(() => JSON.parse(stdout)).toThrow()
+  })
+
+  test('rejects effective YAML before opening a Kernel session with INVALID_INPUT', async () => {
+    let runCalls = 0
+    await expect(
+      followLogs(
+        { follow: true, format: 'yaml' },
+        {
+          run: async () => {
+            runCalls += 1
+          },
+          pause: async () => {},
+        },
+      ),
+    ).rejects.toThrow('--follow does not support YAML')
+    expect(runCalls).toBe(0)
+
+    const originalExit = process.exit
+    const originalStderrWrite = process.stderr.write
+    let stderr = ''
+    process.stderr.write = ((chunk: string | Uint8Array) => {
+      stderr += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8')
+      return true
+    }) as typeof process.stderr.write
+    process.exit = ((code?: string | number | null) => {
+      throw new Error(`exit:${String(code)}`)
+    }) as typeof process.exit
+    try {
+      await expect(logsCommand.action({ follow: true, format: 'yaml' })).rejects.toThrow('exit:1')
+      expect(JSON.parse(stderr)).toEqual({
+        error: 'INVALID_INPUT',
+        message: '--follow does not support YAML; use --json for an NDJSON stream',
+      })
+    } finally {
+      process.exit = originalExit
+      process.stderr.write = originalStderrWrite
+    }
+  })
+
+  async function captureFollowOutput(
+    opts: Parameters<typeof followLogs>[0],
+    tty: boolean,
+  ): Promise<string> {
+    const originalWrite = process.stdout.write
+    const originalTty = Object.getOwnPropertyDescriptor(process.stdout, 'isTTY')
+    let stdout = ''
+    let pages = 0
+    process.stdout.write = ((chunk: string | Uint8Array) => {
+      stdout += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8')
+      return true
+    }) as typeof process.stdout.write
+    Object.defineProperty(process.stdout, 'isTTY', { configurable: true, value: tty })
+    try {
+      await expect(
+        followLogs(opts, {
+          run: async (input) => {
+            await input.fn({
+              session: {
+                call: async () => {
+                  pages += 1
+                  if (pages === 1) return { records: [inputRecord] }
+                  throw new Error('end of controlled stream')
+                },
+              },
+            } as never)
+          },
+          pause: async () => {},
+        }),
+      ).rejects.toThrow('end of controlled stream')
+      return stdout
+    } finally {
+      process.stdout.write = originalWrite
+      if (originalTty === undefined) delete (process.stdout as { isTTY?: boolean }).isTTY
+      else Object.defineProperty(process.stdout, 'isTTY', originalTty)
+    }
+  }
 })