@astrale-os/cli 1.0.0-beta.17 → 1.0.0-beta.19

package/src/commands/domain/install.ts

@@ -1,11 +1,11 @@
-import { Path } from '@astrale-os/sdk/graph/path'
-import { K } from '@astrale-os/sdk/schema'
+import type { InstallRequest, InstallResult, OperationId } from '@astrale-os/sdk/client/schema'
+
 import chalk from 'chalk'
 
 import type { KernelCommandOpts } from '../../connection'
 import type { CommandDefinition } from '../../program/index'
 
-import { createPathCall, runKernelCommand, withAdminClientSession } from '../../connection'
+import { runKernelCommand, withAdminClientSession } from '../../connection'
 import { formatKernelError } from '../../connection/errors'
 import { AstraleError } from '../../errors'
 import {
@@ -23,35 +23,61 @@ import { confirmWithInput, promptText, selectFrom } from '../../lib/prompt'
 import { isHttpUrl } from '../../lib/validation'
 
 /** Public Kernel install syscall input for one remote URL. */
-export function directInstallCallInput(url: string, operation: string, token?: string) {
+export function directInstallCallInput(
+  url: string,
+  operation: string,
+  token?: string,
+): InstallRequest {
+  const domain = Object.freeze({
+    publication: Object.freeze({
+      url,
+      ...(token === undefined ? {} : { token }),
+    }),
+  })
   return Object.freeze({
-    operation,
-    domains: [
-      Object.freeze({
-        source: Object.freeze({
-          kind: 'remote' as const,
-          url,
-          ...(token === undefined ? {} : { token }),
-        }),
-      }),
-    ],
+    operation: acceptOperationId(operation),
+    domains: Object.freeze([domain] as const),
   })
 }
 
-type DirectInstallResult = {
+export interface DirectInstallPresentation {
   readonly operation: string
-  readonly transitions: readonly {
-    readonly intent: {
-      readonly origin: string
-      readonly target?: { readonly schemaRevision?: string } | null
+  readonly origin: string
+  readonly revision: string
+  readonly status: 'installed' | 'already current'
+}
+
+/** Stable CLI presentation derived from the canonical binary install result. */
+export function directInstallPresentation(
+  result: InstallResult,
+  requestedOperation: string,
+): DirectInstallPresentation {
+  if (result.changed) {
+    const installed = result.receipt.transitions[0]?.intent
+    if (!installed) throw new Error('Kernel install returned no committed Domain transition.')
+    if (!installed.generation) {
+      throw new Error('Kernel install returned a committed transition without a Domain generation.')
     }
-  }[]
+    return Object.freeze({
+      operation: result.receipt.operation,
+      origin: installed.origin,
+      revision: installed.generation.revision,
+      status: 'installed' as const,
+    })
+  }
+  const installed = result.domains[0]
+  return Object.freeze({
+    operation: requestedOperation,
+    origin: installed.origin,
+    revision: installed.revision,
+    status: 'already current' as const,
+  })
 }
 
 const OPERATION_ID_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u
 
-function acceptOperationId(input: unknown): string {
+function acceptOperationId(input: unknown): OperationId {
   if (typeof input !== 'string' || !OPERATION_ID_PATTERN.test(input)) {
     throw new AstraleError(
       'INVALID_FLAG',
@@ -59,10 +85,10 @@ function acceptOperationId(input: unknown): string {
       'Omit --operation for a fresh install; use it only with the exact UUID printed for recovery.',
     )
   }
-  return input
+  return input as OperationId
 }
 
-function createOperationId(): string {
+function createOperationId(): OperationId {
   return acceptOperationId(globalThis.crypto.randomUUID())
 }
 
@@ -407,27 +433,20 @@ export async function installDirect(
   const url = target as string
   const retry = directInstallRetry(url, operation, opts)
 
-  await direct.runKernelCommand<DirectInstallResult>({
+  await direct.runKernelCommand<InstallResult>({
     opts,
     label: `Installing domain from ${url} (operation ${operation})`,
     recovery: { operation, retry },
     fn: async ({ session }) =>
-      (await session.call(
-        createPathCall(
-          Path.project(K.functions.install.ref).raw,
-          directInstallCallInput(url, operation, opts.token),
-        ),
-      )) as DirectInstallResult,
+      session.schema.install(directInstallCallInput(url, operation, opts.token)),
     format: (result, fmtOpts, isRaw) => {
       if (isRaw) {
         output(result, fmtOpts)
         return
       }
-      const installed = result.transitions[0]?.intent
-      if (!installed) throw new Error('Kernel install returned no committed Domain transition.')
-      const revision = installed.target?.schemaRevision ?? result.operation
-      log.success(`Domain installed: ${installed.origin}@${revision}`)
-      log.dim(`  operation:   ${result.operation}`)
+      const installed = directInstallPresentation(result, operation)
+      log.success(`Domain ${installed.status}: ${installed.origin}@${installed.revision}`)
+      log.dim(`  operation:   ${installed.operation}`)
       // Belt-and-braces: the kernel-confirmed origin is authoritative. If it
       // aliases the host and the pre-install gate never consented to THAT
       // origin (lying or unavailable Publication), say so loudly after the fact.

package/src/commands/introspect.ts

@@ -1,3 +1,5 @@
+import type { DomainBundle, DomainInfo, SchemaApi } from '@astrale-os/sdk/client/schema'
+
 import { Path } from '@astrale-os/sdk/graph/path'
 
 import type { KernelCommandOpts } from '../connection'
@@ -11,7 +13,18 @@ import { describeCallableFromBundle, missingCallableDescription } from './call-d
 
 type IntrospectOpts = KernelCommandOpts & { bundle?: boolean }
 
-export async function introspectCommand(target: string, opts: IntrospectOpts): Promise<void> {
+interface IntrospectDependencies {
+  readonly runKernelCommand: typeof runKernelCommand
+}
+
+const defaultIntrospectDependencies = Object.freeze({ runKernelCommand })
+
+export async function introspectCommand(
+  target: string,
+  opts: IntrospectOpts,
+  dependencies: Partial<IntrospectDependencies> = {},
+): Promise<void> {
+  const introspect = { ...defaultIntrospectDependencies, ...dependencies }
   let origin: string
   let path: Path
   try {
@@ -21,30 +34,14 @@ export async function introspectCommand(target: string, opts: IntrospectOpts): P
   }
   const wantsCallable = isCallablePath(path)
 
-  await runKernelCommand({
+  await introspect.runKernelCommand({
     opts,
     label: `Introspect ${origin}`,
     fn: async ({ session }) => {
       const includeBundle = wantsCallable || opts.bundle === true
-      const result = await session.schema.introspect({
-        from: { kind: 'installation', origin },
-        select: {
-          state: true,
-          target: true,
-          source: true,
-          readiness: true,
-          capabilities: true,
-          ...(includeBundle ? { bundle: true as const } : {}),
-        },
-      })
-      if (result === null) {
-        throw new AstraleError(
-          'DOMAIN_NOT_INSTALLED',
-          `Domain ${origin} is not installed on this Kernel.`,
-        )
-      }
+      const result = await readInstalledDomain(session.schema, origin, includeBundle)
       if (wantsCallable) {
-        const described = describeCallableFromBundle(path, result.bundle)
+        const described = describeCallableFromBundle(path, (result as DomainBundle).bundle)
         if (described === undefined) throw missingCallableDescription(path.raw)
         return described
       }
@@ -54,6 +51,29 @@ export async function introspectCommand(target: string, opts: IntrospectOpts): P
   })
 }
 
+export function readInstalledDomain(
+  schema: Pick<SchemaApi, 'inspect' | 'bundle'>,
+  origin: string,
+  includeBundle: true,
+): Promise<DomainBundle>
+export function readInstalledDomain(
+  schema: Pick<SchemaApi, 'inspect' | 'bundle'>,
+  origin: string,
+  includeBundle: false,
+): Promise<DomainInfo>
+export function readInstalledDomain(
+  schema: Pick<SchemaApi, 'inspect' | 'bundle'>,
+  origin: string,
+  includeBundle: boolean,
+): Promise<DomainInfo | DomainBundle>
+export function readInstalledDomain(
+  schema: Pick<SchemaApi, 'inspect' | 'bundle'>,
+  origin: string,
+  includeBundle: boolean,
+): Promise<DomainInfo | DomainBundle> {
+  return includeBundle ? schema.bundle(origin) : schema.inspect(origin)
+}
+
 export function parseIntrospectTarget(target: string): { origin: string; path: Path } {
   if (target.startsWith('@')) {
     throw new AstraleError(

package/src/commands/logs.ts

@@ -33,10 +33,21 @@ export interface JournalRecord {
   readonly occurredAt?: string
   readonly committedAt?: string
   readonly principal?: string
+  readonly correlation?: JournalCorrelation
   readonly correlationId?: string
   readonly causationId?: string
 }
 
+export interface JournalCorrelation {
+  readonly operationId?: string
+  readonly parentOperationId?: string
+  readonly invocationId?: string
+  readonly rootInvocationId?: string
+  readonly parentInvocationId?: string
+  readonly traceId?: string
+  readonly spanId?: string
+}
+
 export interface JournalPage {
   readonly records: readonly JournalRecord[]
   readonly cursor?: string
@@ -133,8 +144,21 @@ async function runOnce(opts: LogsOpts): Promise<void> {
   })
 }
 
-async function follow(opts: LogsOpts): Promise<void> {
-  await runKernelCommand({
+type FollowDependencies = {
+  readonly run: typeof runKernelCommand
+  readonly pause: (milliseconds: number) => Promise<void>
+}
+
+/** Follow one admitted journal stream. Dependencies are explicit so routing is proven at the command boundary. */
+export async function followLogs(
+  opts: LogsOpts,
+  dependencies: FollowDependencies = {
+    run: runKernelCommand,
+    pause: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+  },
+): Promise<void> {
+  validateLogsOpts(opts)
+  await dependencies.run({
     opts,
     label: 'Kernel journal',
     fn: async (context): Promise<never> => {
@@ -142,9 +166,9 @@ async function follow(opts: LogsOpts): Promise<void> {
       let cursor = resolved.cursor
       for (;;) {
         const page = await fetchPage(context, { ...resolved, cursor })
-        for (const record of page.records) printRecord(record)
+        for (const record of page.records) printRecord(record, opts)
         cursor = page.cursor ?? cursor
-        await new Promise((resolve) => setTimeout(resolve, FOLLOW_INTERVAL_MS))
+        await dependencies.pause(FOLLOW_INTERVAL_MS)
       }
     },
   })
@@ -169,12 +193,28 @@ function journalProjection(records: JournalRecord[]): ListProjection {
   }
 }
 
-function printRecord(record: JournalRecord): void {
+function printRecord(record: JournalRecord, opts: LogsOpts): void {
+  if (isMachine(opts) || opts.format === 'json') {
+    process.stdout.write(formatFollowRecord(record))
+    return
+  }
   process.stdout.write(
     `${chalk.dim(String(record.sequence).padStart(6))} ${chalk.dim(record.timestamp)} ${chalk.cyan(record.topic)} ${chalk.dim(record.principal ?? '')}\n`,
   )
 }
 
+/** Machine follow is an NDJSON stream: one complete admitted record per line. */
+export function formatFollowRecord(record: JournalRecord): string {
+  return `${JSON.stringify(record)}\n`
+}
+
+export function validateLogsOpts(opts: LogsOpts): void {
+  buildJournalInput(opts)
+  if (opts.follow && opts.format === 'yaml' && !opts.json && !opts.raw) {
+    throw new TypeError('--follow does not support YAML; use --json for an NDJSON stream')
+  }
+}
+
 function acceptRecord(input: unknown, index: number): JournalRecord {
   if (
     !isRecord(input) ||
@@ -188,10 +228,17 @@ function acceptRecord(input: unknown, index: number): JournalRecord {
   if (timestamp === undefined) {
     throw new TypeError(`Kernel journal record ${index} is missing occurredAt/timestamp`)
   }
-  const correlation = isRecord(input.correlation) ? input.correlation : undefined
-  const correlationId =
-    optionalText(input.correlationId, index, 'correlationId') ??
-    optionalText(correlation?.invocationId, index, 'correlation.invocationId')
+  const correlation = acceptCorrelation(input.correlation, index)
+  const legacyCorrelationId = optionalIdentifier(input.correlationId, index, 'correlationId')
+  const structuredCorrelationId = correlation?.invocationId
+  if (
+    legacyCorrelationId !== undefined &&
+    structuredCorrelationId !== undefined &&
+    legacyCorrelationId !== structuredCorrelationId
+  ) {
+    throw new TypeError(`Kernel journal record ${index} has conflicting correlation identifiers`)
+  }
+  const correlationId = structuredCorrelationId ?? legacyCorrelationId
   const principal = optionalText(input.principal, index, 'principal')
   return Object.freeze({
     sequence: input.sequence as number,
@@ -203,13 +250,56 @@ function acceptRecord(input: unknown, index: number): JournalRecord {
       ? {}
       : { committedAt: input.committedAt as string }),
     ...(principal === undefined ? {} : { principal }),
+    ...(correlation === undefined ? {} : { correlation }),
     ...(correlationId === undefined ? {} : { correlationId }),
-    ...(optionalText(input.causationId, index, 'causationId') === undefined
+    ...(optionalIdentifier(input.causationId, index, 'causationId') === undefined
       ? {}
       : { causationId: input.causationId as string }),
   })
 }
 
+const correlationFields = [
+  'operationId',
+  'parentOperationId',
+  'invocationId',
+  'rootInvocationId',
+  'parentInvocationId',
+  'traceId',
+  'spanId',
+] as const
+
+function acceptCorrelation(input: unknown, index: number): JournalCorrelation | undefined {
+  if (input === undefined) return undefined
+  if (!isRecord(input)) {
+    throw new TypeError(`Kernel journal record ${index}.correlation must be an object`)
+  }
+  const unknown = Object.keys(input).find(
+    (field) => !correlationFields.includes(field as (typeof correlationFields)[number]),
+  )
+  if (unknown !== undefined) {
+    throw new TypeError(`Kernel journal record ${index}.correlation.${unknown} is unsupported`)
+  }
+  return Object.freeze(
+    Object.fromEntries(
+      correlationFields.flatMap((field) => {
+        const value = optionalIdentifier(input[field], index, `correlation.${field}`)
+        return value === undefined ? [] : [[field, value]]
+      }),
+    ),
+  )
+}
+
+function optionalIdentifier(input: unknown, index: number, field: string): string | undefined {
+  const value = optionalText(input, index, field)
+  if (value === undefined) return undefined
+  if (value.trim() === '' || new TextEncoder().encode(value).byteLength > 256) {
+    throw new TypeError(
+      `Kernel journal record ${index}.${field} must be non-empty and at most 256 UTF-8 bytes`,
+    )
+  }
+  return value
+}
+
 function optionalText(input: unknown, index: number, field: string): string | undefined {
   if (input === undefined) return undefined
   if (typeof input !== 'string') {
@@ -251,7 +341,8 @@ Behavior:
   Calls the public Kernel journal syscall and emits its { records, cursor }
   page. Topic selection is exact or prefix-based; cursors and timestamps are
   opaque strings owned by the journal backend. --follow reuses one Client Session
-  and advances only with the returned cursor.
+  and advances only with the returned cursor. Machine follow output is NDJSON:
+  one complete admitted record per line; YAML follow is unsupported.
 
   Historical event-glob lowering and the application-specific services-domain
   log buffer are not part of the Kernel V2 journal contract.
@@ -273,11 +364,11 @@ Examples:
   ],
   action: async (opts: LogsOpts) => {
     try {
-      buildJournalInput(opts)
+      validateLogsOpts(opts)
     } catch (error) {
       failInput(error, opts)
     }
-    if (opts.follow) await follow(opts)
+    if (opts.follow) await followLogs(opts)
     else await runOnce(opts)
   },
 } satisfies CommandDefinition

package/src/lib/output.ts

@@ -17,7 +17,7 @@ export type RawOutputOpts = Pick<OutputOpts, 'raw' | 'json'>
 export type MachineOpts = RawOutputOpts & { readonly ci?: boolean }
 
 export const RAW_OUTPUT_OPTIONS = [
-  { flags: '--json', description: 'Always-valid JSON (for jq)' },
+  { flags: '--json', description: 'JSON; streaming commands emit one JSON value per line' },
   { flags: '--raw', description: 'Unwrapped: bare scalar / raw bytes / JSON for objects' },
 ] as const
 

package/src/program/__tests__/program.test.ts

@@ -195,7 +195,7 @@ describe('program composition', () => {
       'whoami',
     ])
     expect(createHash('sha256').update(JSON.stringify(surface)).digest('hex')).toBe(
-      'd37c3d80b3067b3553b8527b10bf1c5632922d624b3d6072c3b03e7a507efc4f',
+      '958b54c4eeee1bab77efeac734bd11fe5a0b103aae69788de7db5418e5652f64',
     )
   })
 

package/studio/package.json

@@ -21,7 +21,7 @@
     "typecheck": "tsgo --noEmit"
   },
   "dependencies": {
-    "@astrale-os/sdk": "0.5.0-beta.38",
+    "@astrale-os/sdk": "0.5.0-beta.49",
     "@astrale-os/shell": "0.4.2-beta.3",
     "@dagrejs/dagre": "^3.0.0",
     "@radix-ui/react-collapsible": "^1.1.0",