@astrale-os/cli 0.4.0-alpha.13 → 0.6.0-alpha.0

package/src/lib/__tests__/table.test.ts

@@ -15,7 +15,7 @@ describe('renderTable', () => {
     const out = strip(
       renderTable(
         [
-          { name: 'dist.astrale.ai', kind: 'Domain' },
+          { name: 'example.astrale.ai', kind: 'Domain' },
           { name: 'workspace', kind: 'Folder' },
         ],
         { columns: COLS },

package/src/lib/__tests__/view-open-intent.test.ts

@@ -0,0 +1,308 @@
+import type { IntentMessage, MountedWindow, ResolvedView, Shell } from '@astrale-os/shell'
+
+import { describe, expect, test } from 'bun:test'
+
+import {
+  handleOpenIntent,
+  installOpenIntentHandler,
+  mountWithHandshakeFallback,
+  type OpenIntentHost,
+} from '../view/open-intent'
+
+const profile: ResolvedView = {
+  id: 'profile-view',
+  path: '/shell/views/profile',
+  url: 'https://shell.test/profile',
+  origin: 'class',
+}
+const card: ResolvedView = {
+  id: 'card-view',
+  path: '/shell/views/card',
+  url: 'https://shell.test/card',
+  handshake: 'none',
+  origin: 'class',
+}
+
+function openMessage(viewId?: string, correlationId?: string): IntentMessage<'open'> {
+  return {
+    type: 'intent',
+    version: 1,
+    envelope: {
+      name: 'open',
+      payload: { nodeId: 'person-1', ...(viewId ? { viewId } : {}) },
+      sender: { windowId: 'old-window' },
+      ...(correlationId ? { correlationId } : {}),
+    },
+  }
+}
+
+function mounted(windowId: string, onClose?: () => void): MountedWindow {
+  return {
+    windowId,
+    window: {
+      windowId,
+      functionId: 'view',
+      isolation: 'shared',
+      state: 'active',
+      delegationToken: null,
+      capabilities: { intents: [] },
+    },
+    handle: { element: {} as HTMLElement },
+    close: async () => {
+      onClose?.()
+      return { kind: 'closed' }
+    },
+  }
+}
+
+function harness(views: readonly ResolvedView[] = [profile, card]) {
+  const events: string[] = []
+  const sent: { windowId: string; message: IntentMessage }[] = []
+  const old = mounted('old-window', () => events.push('close:old-window'))
+  let current: MountedWindow | null = old
+  const shell = {
+    views: {
+      resolve: async (node: string) => {
+        events.push(`resolve:${node}`)
+        return views
+      },
+    },
+  } as unknown as Pick<Shell, 'views'>
+  const host: OpenIntentHost = {
+    current: () => current,
+    setCurrent: (next) => {
+      events.push(`current:${next.windowId}`)
+      current = next
+    },
+    mount: async (view, nodeId) => {
+      events.push(`mount:${view.id}:${nodeId}`)
+      return mounted('new-window')
+    },
+    opened: (view, nodeId) => events.push(`opened:${view.path}:${nodeId}`),
+    failed: (error) => events.push(`failed:${error instanceof Error ? error.message : error}`),
+    reply: (message, windowId) => {
+      if (!message.envelope.correlationId) return
+      events.push(`reply:${message.envelope.sender.windowId}`)
+      sent.push({
+        windowId: message.envelope.sender.windowId,
+        message: {
+          type: 'intent',
+          version: 1,
+          envelope: {
+            name: 'intentReply',
+            payload: {
+              correlationId: message.envelope.correlationId,
+              result: { windowId },
+            },
+            sender: { windowId: 'root' },
+          },
+        },
+      })
+    },
+    reject: (message, error) => {
+      if (!message.envelope.correlationId) return
+      events.push(`reply:${message.envelope.sender.windowId}`)
+      sent.push({
+        windowId: message.envelope.sender.windowId,
+        message: {
+          type: 'intent',
+          version: 1,
+          envelope: {
+            name: 'intentReply',
+            payload: {
+              correlationId: message.envelope.correlationId,
+              error: { message: error instanceof Error ? error.message : String(error) },
+            },
+            sender: { windowId: 'root' },
+          },
+        },
+      })
+    },
+  }
+  return { events, sent, shell, host, current: () => current }
+}
+
+describe('open intent host', () => {
+  test('uses kernel preference and replies before retiring the requesting child', async () => {
+    const h = harness()
+    await handleOpenIntent(h.shell, h.host, openMessage(undefined, 'corr-1'))
+
+    expect(h.events).toEqual([
+      'resolve:person-1',
+      'mount:profile-view:person-1',
+      'current:new-window',
+      'opened:/shell/views/profile:person-1',
+      'reply:old-window',
+      'close:old-window',
+    ])
+    expect(h.current()?.windowId).toBe('new-window')
+    expect(h.sent).toEqual([
+      {
+        windowId: 'old-window',
+        message: {
+          type: 'intent',
+          version: 1,
+          envelope: {
+            name: 'intentReply',
+            payload: { correlationId: 'corr-1', result: { windowId: 'new-window' } },
+            sender: { windowId: 'root' },
+          },
+        },
+      },
+    ])
+  })
+
+  test('honors an explicit view and keeps fire-and-forget navigation reply-free', async () => {
+    const h = harness()
+    await handleOpenIntent(h.shell, h.host, openMessage('card-view'))
+
+    expect(h.events).toContain('mount:card-view:person-1')
+    expect(h.sent).toEqual([])
+  })
+
+  test('keeps the current view and rejects a correlated resolution failure', async () => {
+    const h = harness([])
+    await handleOpenIntent(h.shell, h.host, openMessage(undefined, 'corr-fail'))
+
+    expect(h.current()?.windowId).toBe('old-window')
+    expect(h.events).toEqual([
+      'resolve:person-1',
+      'reply:old-window',
+      'failed:No view resolves for this node',
+    ])
+    expect(h.sent[0]!.message.envelope).toEqual({
+      name: 'intentReply',
+      payload: {
+        correlationId: 'corr-fail',
+        error: { message: 'No view resolves for this node' },
+      },
+      sender: { windowId: 'root' },
+    })
+  })
+
+  test('keeps the current view when the replacement mount fails', async () => {
+    const h = harness([profile])
+    h.host.mount = async () => {
+      h.events.push('mount:failed')
+      throw new Error('replacement failed')
+    }
+
+    await handleOpenIntent(h.shell, h.host, openMessage(undefined, 'corr-mount'))
+
+    expect(h.current()?.windowId).toBe('old-window')
+    expect(h.events).toEqual([
+      'resolve:person-1',
+      'mount:failed',
+      'reply:old-window',
+      'failed:replacement failed',
+    ])
+    expect(h.sent[0]!.message.envelope.payload).toEqual({
+      correlationId: 'corr-mount',
+      error: { message: 'replacement failed' },
+    })
+  })
+
+  test('serializes overlapping opens', async () => {
+    let handler: ((message: IntentMessage<'open'>) => Promise<void>) | undefined
+    let releaseFirst!: () => void
+    const firstGate = new Promise<void>((resolve) => {
+      releaseFirst = resolve
+    })
+    let resolveCount = 0
+    const base = harness([profile])
+    const events = base.events
+    const shell = {
+      ...base.shell,
+      views: {
+        resolve: async () => {
+          resolveCount += 1
+          events.push(`resolve:${resolveCount}`)
+          if (resolveCount === 1) await firstGate
+          return [profile]
+        },
+      },
+      onIntent: (_name: 'open', next: typeof handler) => {
+        handler = next
+        return () => {}
+      },
+    } as unknown as Shell
+    const host = {
+      ...base.host,
+      mount: async () => {
+        const id = `new-${resolveCount}`
+        events.push(`mount:${id}`)
+        return mounted(id, () => events.push(`close:${id}`))
+      },
+    }
+    installOpenIntentHandler(shell, host)
+
+    const first = handler!(openMessage())
+    const second = handler!(openMessage())
+    await Promise.resolve()
+    expect(events).toEqual(['resolve:1'])
+    releaseFirst()
+    await Promise.all([first, second])
+    expect(events).toEqual([
+      'resolve:1',
+      'mount:new-1',
+      'current:new-1',
+      'opened:/shell/views/profile:person-1',
+      'close:old-window',
+      'resolve:2',
+      'mount:new-2',
+      'current:new-2',
+      'opened:/shell/views/profile:person-1',
+      'close:new-1',
+    ])
+    expect(base.current()?.windowId).toBe('new-2')
+  })
+})
+
+describe('mountWithHandshakeFallback', () => {
+  test('mounts a plain view once', async () => {
+    const attempts: string[] = []
+    const result = await mountWithHandshakeFallback({
+      handshake: 'none',
+      attempts: 2,
+      mount: async (handshake) => {
+        attempts.push(handshake)
+        return 'plain-window'
+      },
+      cleanupFailedAttempt: () => attempts.push('cleanup'),
+    })
+    expect(result).toEqual({ mounted: 'plain-window', handshake: 'none' })
+    expect(attempts).toEqual(['none'])
+  })
+
+  test('retries shell mounts, cleans each failure, then falls back to plain', async () => {
+    const attempts: string[] = []
+    const result = await mountWithHandshakeFallback({
+      handshake: 'shell',
+      attempts: 2,
+      mount: async (handshake) => {
+        attempts.push(handshake)
+        if (handshake === 'shell') throw new Error('handshake failed')
+        return 'plain-window'
+      },
+      cleanupFailedAttempt: () => attempts.push('cleanup'),
+    })
+    expect(result).toEqual({ mounted: 'plain-window', handshake: 'none' })
+    expect(attempts).toEqual(['shell', 'cleanup', 'shell', 'cleanup', 'none'])
+  })
+
+  test('cleans and surfaces the decisive plain fallback failure', async () => {
+    const attempts: string[] = []
+    const run = mountWithHandshakeFallback({
+      handshake: 'shell',
+      attempts: 2,
+      mount: async (handshake) => {
+        attempts.push(handshake)
+        throw new Error(handshake === 'shell' ? 'handshake failed' : 'plain failed')
+      },
+      cleanupFailedAttempt: () => attempts.push('cleanup'),
+    })
+
+    await expect(run).rejects.toThrow('plain failed')
+    expect(attempts).toEqual(['shell', 'cleanup', 'shell', 'cleanup', 'none', 'cleanup'])
+  })
+})

package/src/lib/__tests__/view-snapshot.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from 'bun:test'
+
+import type { AbResult } from '../browser'
+
+import { snapshotText, waitForSettledSnapshot } from '../view/snapshot'
+
+const pending = result('- paragraph\n  - StaticText "Opening integrations…"')
+const settled = result('- heading "Integrations" [level=1]\n- button "Connect Google" [ref=e4]')
+
+function result(snapshot: string): AbResult {
+  return { ok: true, data: { snapshot }, error: null }
+}
+
+function clock() {
+  let elapsed = 0
+  return {
+    now: () => elapsed,
+    sleep: async (ms: number) => {
+      elapsed += ms
+    },
+    elapsed: () => elapsed,
+  }
+}
+
+describe('view snapshot settling', () => {
+  test('waits through a late loading-to-content transition and a quiet window', async () => {
+    const fakeClock = clock()
+    let calls = 0
+    const takeSnapshot = async () => {
+      calls += 1
+      return fakeClock.elapsed() < 1_250 ? pending : settled
+    }
+
+    const snapshot = await waitForSettledSnapshot(takeSnapshot, fakeClock, {
+      timeoutMs: 4_000,
+      quietWindowMs: 750,
+      pollMs: 250,
+    })
+
+    expect(snapshotText(snapshot)).toContain('Connect Google')
+    expect(fakeClock.elapsed()).toBe(2_000)
+    expect(calls).toBe(10)
+  })
+
+  test('returns the latest permanently pending snapshot at the bound', async () => {
+    const fakeClock = clock()
+    let calls = 0
+    const takeSnapshot = async () => {
+      calls += 1
+      return pending
+    }
+
+    const snapshot = await waitForSettledSnapshot(takeSnapshot, fakeClock, {
+      timeoutMs: 1_000,
+      quietWindowMs: 500,
+      pollMs: 250,
+    })
+
+    expect(snapshot).toBe(pending)
+    expect(fakeClock.elapsed()).toBe(1_000)
+    expect(calls).toBe(6)
+  })
+
+  test('ignores changing agent-browser refs when measuring stability', async () => {
+    const fakeClock = clock()
+    let ref = 0
+
+    const snapshot = await waitForSettledSnapshot(
+      async () => result(`- button "Deploy" [ref=e${++ref}]`),
+      fakeClock,
+      { timeoutMs: 2_000, quietWindowMs: 500, pollMs: 250 },
+    )
+
+    expect(snapshotText(snapshot)).toContain('Deploy')
+    expect(fakeClock.elapsed()).toBe(500)
+  })
+})

package/src/lib/admin-domain.ts

@@ -7,16 +7,20 @@
  * mounting it on an instance is the separate `domain install` step (or the
  * admin's install-by-default policy).
  */
-export const ADMIN_DOMAIN = '/admin.astrale.ai/class.DomainEntry'
+export const ADMIN_DOMAIN = '/:admin.astrale.ai:class.DomainEntry'
+
+export function adminDomainMethod(method: 'info' | 'install' | 'list' | 'publish'): string {
+  return `${ADMIN_DOMAIN}:${method}`
+}
 
 /** Read shape returned by `DomainEntry.publish` / `info` / `list` (domain `DomainInfoSchema`). */
 export type DomainInfo = {
   id: string
-  /** dist.astrale.ai — the authority origin (== JWT aud + kernel path prefix). */
+  /** shell.astrale.ai — the authority origin (== JWT aud + kernel path prefix). */
   origin: string
-  /** 'distribution' — the node slug + the id used in install plans / the CLI. */
+  /** 'shell' — the node slug + the id used in install plans / the CLI. */
   name: string
-  /** https://dist.astrale.ai — the published worker URL the kernel installs from. */
+  /** https://shell.astrale.ai — the published worker URL the kernel installs from. */
   url?: string
   description?: string
   installByDefault?: boolean

package/src/lib/admin-instance.ts

@@ -3,7 +3,11 @@
  * list/status/create/delete`. The merged admin domain models instances as the
  * `Instance` class (provisioned via `Instance.init`); these commands target it.
  */
-export const ADMIN_INSTANCE = '/admin.astrale.ai/class.Instance'
+export const ADMIN_INSTANCE = '/:admin.astrale.ai:class.Instance'
+
+export function adminInstanceMethod(method: 'alphaCreate' | 'delete' | 'info' | 'list'): string {
+  return `${ADMIN_INSTANCE}:${method}`
+}
 
 /** Read shape returned by `Instance.list` / `info` / `delete` (domain `InstanceInfoSchema`). */
 export type InstanceInfo = {

package/src/lib/config.ts

@@ -9,6 +9,7 @@ import { CONFIG_PATH } from './paths'
 export const AstraleConfigSchema = z.object({
   issuer: z.string().url().default('https://unregistered.invalid'),
   admin: AdminTargetConfigSchema.default(DEFAULT_ADMIN_TARGET_CONFIG),
+  telemetry: z.object({ enabled: z.boolean().default(true) }).default({ enabled: true }),
 })
 
 export type AstraleConfig = z.infer<typeof AstraleConfigSchema>

package/src/lib/domain-identity.ts

@@ -10,7 +10,7 @@ export async function loadPrivateJwk(keyPath: string): Promise<Record<string, un
 }
 
 /**
- * True when the kernel rejected an `installDomain` call because the
+ * True when the kernel rejected a `Domain.install` call because the
  * identity binding's signature failed to verify — i.e. the private/public
  * JWK halves don't match. Callers re-throw with a regenerate-the-keypair
  * hint instead of leaking the raw `AuthenticationError`.

package/src/lib/instance-target.ts

@@ -172,6 +172,11 @@ export function adminTargetToInstance(target: ResolvedAdminTarget): ResolvedInst
 export function isManagedInstanceNotFound(error: unknown): boolean {
   if (!(error instanceof Error)) return false
   if (error.name === 'NotFoundError') return true
+  // The admin kernel reports a missing instance node as InternalKernelError
+  // with a NOT_FOUND-prefixed message. In this lookup that's an instance
+  // miss (config problem), not a kernel fault — map it so callers get the
+  // typed INSTANCE_NOT_FOUND with remediation instead of a raw kernel error.
+  if (error.name === 'InternalKernelError' && /^NOT_FOUND\b/.test(error.message)) return true
   const data = (error as Error & { data?: unknown }).data
   return (
     error.name === 'KernelError' &&

package/src/lib/instance.ts

@@ -113,6 +113,17 @@ export function sanitizeStore(store: InstanceStore): { store: InstanceStore; cha
 
 let instancesMemo: InstanceStore | null = null
 
+/**
+ * Drop the in-process bookmark cache so the next `readInstances` re-reads disk.
+ *
+ * A long-lived host (e.g. `@astrale-os/connect-host`) would otherwise serve a
+ * stale bookmark list after the user runs `astrale instance bookmark`. The CLI
+ * itself is one-shot, so this is a no-op for command usage.
+ */
+export function resetInstancesMemo(): void {
+  instancesMemo = null
+}
+
 export async function readInstances(
   _config?: AstraleConfig,
   opts: { persist?: boolean } = {},

package/src/lib/log.ts

@@ -3,6 +3,7 @@ import ora, { type Ora } from 'ora'
 
 import { AstraleError, NotImplementedError } from '../errors'
 import { formatElapsed } from './format'
+import { isMachine, type RawOutputOpts } from './output'
 
 export const log = {
   info: (msg: string) => console.log(chalk.blue('ℹ'), msg),
@@ -13,12 +14,21 @@ export const log = {
   dim: (msg: string) => console.log(chalk.dim(msg)),
 }
 
-/** Report an error with hint (when present) and exit. */
-export function fatal(e: unknown): never {
+/** Report an error with hint (when present) and exit. Commands that carry
+ *  RawOutputOpts should pass them so machine consumers (--json/--raw/piped)
+ *  get one structured JSON line on stderr instead of the pretty ✖ view. */
+export function fatal(e: unknown, opts?: RawOutputOpts): never {
   // Ctrl-C at an interactive (@inquirer/prompts) prompt — exit quietly with the
   // SIGINT convention, not a red error line.
   if (e instanceof Error && e.name === 'ExitPromptError') process.exit(130)
   const msg = e instanceof Error ? e.message : String(e)
+  if (opts && isMachine(opts)) {
+    const error = e instanceof AstraleError ? e.code : e instanceof Error ? e.name : 'Error'
+    const payload: Record<string, unknown> = { error, message: msg }
+    if (e instanceof AstraleError && e.hint) payload.hint = e.hint
+    process.stderr.write(JSON.stringify(payload) + '\n')
+    process.exit(1)
+  }
   log.error(msg)
   if (e instanceof AstraleError && e.hint) log.dim(`  hint: ${e.hint}`)
   process.exit(1)

package/src/lib/login-flow.ts

@@ -29,6 +29,27 @@ import { log } from './log'
  * behavior; presentation (the device URL is logged here; success lines are the
  * caller's) does not.
  */
+/**
+ * Interactive device-flow progress. Emitted once, when the device authorization
+ * has been requested and the user must approve it in a browser. The caller
+ * decides how to present it (the CLI logs it; the desktop opens the URL and
+ * pushes it to the renderer). Structurally identical to connect-host's wire
+ * `AuthVerificationEvent`, but declared here so the CLI carries no dependency on
+ * connect-host (which depends on the CLI, not the reverse).
+ */
+export type DeviceVerification = {
+  /** The base verification URL (fallback to the complete one when absent). */
+  verificationUri: string
+  /** Pre-filled verification URL (opens straight to the approval page). */
+  verificationUriComplete?: string
+  /** The short user code to confirm — a reassurance fallback when the URL is pre-filled. */
+  userCode?: string
+  /** Seconds until the device code expires. */
+  expiresIn?: number
+  /** Human-readable instruction from the IdP. */
+  message?: string
+}
+
 export type LoginFlowOpts = {
   idp?: string
   name?: string
@@ -42,6 +63,12 @@ export type LoginFlowOpts = {
   codeVerifier?: string
   /** Switch the default identity to the one we just logged in (default true). */
   use?: boolean
+  /**
+   * When set, receives the device-flow verification details and REPLACES the
+   * default `log.info` presentation (a headless/GUI caller drives the UI). The
+   * `auth login` command passes nothing, so its terminal output is unchanged.
+   */
+  onVerification?: (e: DeviceVerification) => void
 }
 
 export type LoginResult = {
@@ -148,10 +175,20 @@ async function obtainToken(
     scope,
     audience: opts.audience,
   })
-  if (device.verification_uri_complete) log.info(`Open: ${device.verification_uri_complete}`)
-  else if (device.verification_uri) log.info(`Open: ${device.verification_uri}`)
-  if (device.user_code) log.info(`Code: ${device.user_code}`)
-  if (device.message) log.dim(`  ${device.message}`)
+  if (opts.onVerification) {
+    opts.onVerification({
+      verificationUri: device.verification_uri ?? device.verification_uri_complete ?? '',
+      verificationUriComplete: device.verification_uri_complete,
+      userCode: device.user_code,
+      expiresIn: device.expires_in,
+      message: device.message,
+    })
+  } else {
+    if (device.verification_uri_complete) log.info(`Open: ${device.verification_uri_complete}`)
+    else if (device.verification_uri) log.info(`Open: ${device.verification_uri}`)
+    if (device.user_code) log.info(`Code: ${device.user_code}`)
+    if (device.message) log.dim(`  ${device.message}`)
+  }
 
   return pollDeviceToken({
     idp,

package/src/lib/provision-instance.ts

@@ -5,7 +5,7 @@ import type { AdminTargetCommandOpts } from './admin-target'
 
 import { AuthError } from '../errors'
 import { withAdminKernelClient } from '../kernel/client'
-import { ADMIN_INSTANCE } from './admin-instance'
+import { adminInstanceMethod } from './admin-instance'
 import { readIdentities, type IdentityStore } from './identity'
 import { setActive, upsertManagedBookmark } from './instance'
 import { withSpinner } from './log'
@@ -74,7 +74,7 @@ export async function provisionInstance(
         const created = await withAdminKernelClient(
           createOpts,
           async (ctx) =>
-            (await ctx.client.call(`${ADMIN_INSTANCE}/alphaCreate`, {
+            (await ctx.client.call(adminInstanceMethod('alphaCreate'), {
               slug,
               ...(hostId ? { host_id: hostId } : {}),
             })) as { url: string; organizationId?: string },

package/src/lib/self.ts

@@ -158,9 +158,7 @@ function refusalMessage(r: SelfRefusal): string {
     case 'idp-no-sub':
       return [
         `\`@self\` could not be resolved for IdP identity "${r.identityName}": no cached registration, and the automatic whoami lookup did not return a node id (offline, auth failure, or unprovisioned identity).`,
-        'Get your node id manually, then use it directly:',
-        '  astrale call "/:kernel.astrale.ai:interface.Identity:whoami" --json   # → { id: <nodeId> }',
-        'and address yourself as `@<nodeId>`.',
+        'The CLI resolves `@self` through the bound auth.whoami() flow; fix auth/registration and rerun, or pass a literal `@<nodeId>`.',
       ].join('\n  ')
   }
 }