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

package/src/lib/command-dx.ts

@@ -2,6 +2,8 @@ import type { Command, CommanderError } from 'commander'
 
 import chalk from 'chalk'
 
+import { isMachine } from './output'
+
 export type CommandCatalogEntry = {
   path: string[]
   usage: string
@@ -34,42 +36,48 @@ export function renderCommanderError(
   const matched = matchRegisteredPrefix(program, tokens)
 
   if (matched.path.length === 0 && tokens.length > 0) {
-    return renderUnknownCommand(tokens, catalog)
+    return maybeMachine(renderUnknownCommand(tokens, catalog))
   }
 
   if (error.code === 'commander.missingArgument') {
     const usage = usageFor(matched.path, matched.command)
     const argName = error.message.match(/'([^']+)'/)?.[1]
-    return [
-      `Missing required argument${argName ? ` ${chalk.bold(`<${argName}>`)}` : ''} for ${chalk.bold(
-        `astrale ${matched.path.join(' ')}`,
-      )}`,
-      '',
-      'Usage:',
-      `  astrale ${usage}`,
-    ].join('\n')
+    return maybeMachine(
+      [
+        `Missing required argument${argName ? ` ${chalk.bold(`<${argName}>`)}` : ''} for ${chalk.bold(
+          `astrale ${matched.path.join(' ')}`,
+        )}`,
+        '',
+        'Usage:',
+        `  astrale ${usage}`,
+      ].join('\n'),
+    )
   }
 
   if (error.code === 'commander.excessArguments') {
     const usage = usageFor(matched.path, matched.command)
     const extra = tokens.slice(matched.path.length).join(' ')
-    return [
-      `Unexpected argument${extra.includes(' ') ? 's' : ''} for ${chalk.bold(
-        `astrale ${matched.path.join(' ')}`,
-      )}${extra ? `: ${extra}` : ''}`,
-      '',
-      'Usage:',
-      `  astrale ${usage}`,
-    ].join('\n')
+    return maybeMachine(
+      [
+        `Unexpected argument${extra.includes(' ') ? 's' : ''} for ${chalk.bold(
+          `astrale ${matched.path.join(' ')}`,
+        )}${extra ? `: ${extra}` : ''}`,
+        '',
+        'Usage:',
+        `  astrale ${usage}`,
+      ].join('\n'),
+    )
   }
 
   const suggestions = nearestCommands(tokens.join(' '), catalog)
-  return [
-    error.message,
-    ...(suggestions.length > 0
-      ? ['', 'Did you mean:', ...suggestions.map((s) => `  astrale ${s}`)]
-      : []),
-  ].join('\n')
+  return maybeMachine(
+    [
+      error.message,
+      ...(suggestions.length > 0
+        ? ['', 'Did you mean:', ...suggestions.map((s) => `  astrale ${s}`)]
+        : []),
+    ].join('\n'),
+  )
 }
 
 const RETIRED_COMMANDS: Record<string, string> = {
@@ -133,6 +141,15 @@ function usageFor(path: string[], command: Command): string {
   return [path.join(' '), suffix].filter(Boolean).join(' ')
 }
 
+const ANSI_RE = new RegExp(String.fromCharCode(27) + '\\[[0-9;]*m', 'g')
+
+function maybeMachine(text: string): string {
+  if (!isMachine()) return text
+  const plain = text.replace(ANSI_RE, '')
+  const first = plain.split('\n').find((line) => line.trim().length > 0) ?? plain
+  return JSON.stringify({ error: 'USAGE_ERROR', message: first, detail: plain })
+}
+
 function stripOptions(argv: string[]): string[] {
   const out: string[] = []
   for (const token of argv) {

package/src/lib/instance-target.ts

@@ -94,8 +94,8 @@ async function resolveNamedInstanceTarget(
   try {
     managed = await opts.managed(identifier)
   } catch (e) {
-    if (!isManagedInstanceNotFound(e)) throw e
-    throw notFound
+    if (isManagedInstanceNotFound(e) || isAdminDiscoveryFailure(e)) throw notFound
+    throw e
   }
 
   const url = normalizeInstanceKernelUrl(managed.url)
@@ -173,6 +173,22 @@ export function adminTargetToInstance(target: ResolvedAdminTarget): ResolvedInst
   }
 }
 
+const ADMIN_DISCOVERY_CODES = new Set([
+  'TOKEN_EXCHANGE_SOURCE_INVALID',
+  'TOKEN_EXCHANGE_SOURCE_EXPIRED',
+  'TOKEN_EXCHANGE_UNSUPPORTED',
+  'TOKEN_EXCHANGE_DISCOVERY_FAILED',
+  'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+  'TOKEN_EXCHANGE_INSECURE',
+  'ADMIN_DOMAIN_ISSUER_MISSING',
+  'ADMIN_INVENTORY_UNAVAILABLE',
+])
+
+/** Admin lookup failed before it could say whether the slug exists. */
+export function isAdminDiscoveryFailure(error: unknown): boolean {
+  return error instanceof AstraleError && ADMIN_DISCOVERY_CODES.has(error.code)
+}
+
 export function isManagedInstanceNotFound(error: unknown): boolean {
   if (error instanceof AstraleError && error.code === 'INSTANCE_NOT_FOUND') return true
   if (!(error instanceof Error)) return false

package/src/lib/instance.ts

@@ -68,6 +68,11 @@ export type ResolvedInstance = {
   status?: string
 }
 
+export type BookmarkTrustConflict = {
+  readonly name: string
+  readonly caFile: string | null
+}
+
 function seed(): InstanceStore {
   return { active: '', instances: {} }
 }
@@ -198,6 +203,32 @@ export function resolveInstanceKey(store: InstanceStore, identifier: string): st
   return null
 }
 
+/**
+ * Find other bookmarks for the same normalized Kernel URL whose TLS trust
+ * configuration differs. System trust (`undefined`) is a configuration too:
+ * mixing it with a custom CA is exactly as significant as mixing two CA files.
+ */
+export function findBookmarkTrustConflicts(
+  store: InstanceStore,
+  name: string,
+  url: string,
+  caFile?: string,
+): BookmarkTrustConflict[] {
+  const normalizedUrl = normalizeInstanceKernelUrl(url)
+  const configuredCa = caFile ?? null
+  return Object.entries(store.instances).flatMap(([candidateName, entry]) => {
+    if (
+      candidateName === name ||
+      entry.url === undefined ||
+      normalizeInstanceKernelUrl(entry.url) !== normalizedUrl ||
+      (entry.caFile ?? null) === configuredCa
+    ) {
+      return []
+    }
+    return [{ name: candidateName, caFile: entry.caFile ?? null }]
+  })
+}
+
 export async function addInstance(key: string, opts: AddInstanceOpts = {}): Promise<InstanceEntry> {
   validateName(key, 'Instance')
   if (RESERVED_SLUGS.has(key)) throw new ReservedSlugError(key)

package/src/lib/invocation.ts

@@ -0,0 +1,11 @@
+/** Process-wide machine mode from argv (`--json` / `--raw` / `--ci`). */
+
+let argvMachine = false
+
+export function configureInvocation(argv: readonly string[]): void {
+  argvMachine = argv.some((token) => token === '--json' || token === '--raw' || token === '--ci')
+}
+
+export function invocationWantsMachine(): boolean {
+  return argvMachine
+}

package/src/lib/log.ts

@@ -3,7 +3,7 @@ import ora, { type Ora } from 'ora'
 
 import { AstraleError, NotImplementedError } from '../errors'
 import { formatElapsed } from './format'
-import { isMachine, type RawOutputOpts } from './output'
+import { isMachine, type MachineOpts } from './output'
 
 export const log = {
   info: (msg: string) => console.log(chalk.blue('ℹ'), msg),
@@ -16,26 +16,34 @@ export const log = {
   dim: (msg: string) => console.log(chalk.dim(msg)),
 }
 
-/** 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 {
+/** Report an error with hint (when present) and exit. `--json` / `--ci` / a
+ *  non-TTY stdout always get one structured JSON line on stderr. */
+export function fatal(e: unknown, opts?: MachineOpts): 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 }
+  const code = e instanceof AstraleError ? e.code : e instanceof Error ? e.name : 'Error'
+  if (isMachine(opts)) {
+    const payload: Record<string, unknown> = { error: code, 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)
+  log.error(e instanceof AstraleError ? `${code}: ${msg}` : msg)
   if (e instanceof AstraleError && e.hint) log.dim(`  hint: ${e.hint}`)
   process.exit(1)
 }
 
+/** Admit expected invalid input and exit through {@link fatal}. */
+export function failClosed(error: unknown, opts?: MachineOpts): never {
+  if (error instanceof AstraleError) fatal(error, opts)
+  fatal(
+    new AstraleError('INVALID_INPUT', error instanceof Error ? error.message : String(error)),
+    opts,
+  )
+}
+
 /** Shortcut for stub commands that aren't wired in v1 (§15). */
 export function fatalNotImplemented(feature: string, hint?: string): never {
   fatal(new NotImplementedError(feature, hint))

package/src/lib/output.ts

@@ -1,6 +1,7 @@
 import chalk from 'chalk'
 import { stringify as yamlStringify } from 'yaml'
 
+import { invocationWantsMachine } from './invocation'
 import { renderTable, type Column } from './table'
 
 export type { Column } from './table'
@@ -13,6 +14,8 @@ export type OutputOpts = {
 
 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: '--raw', description: 'Unwrapped: bare scalar / raw bytes / JSON for objects' },
@@ -20,10 +23,15 @@ export const RAW_OUTPUT_OPTIONS = [
 
 /**
  * Is the consumer a machine (emit structured data, not a pretty view)?
- * True for `--json`, `--raw`, or any non-TTY stdout (pipe, redirect, CI, agent).
+ * True for `--json`, `--raw`, `--ci`, a process-wide `--ci/--json/--raw` on argv,
+ * or any non-TTY stdout (pipe, redirect, agent).
  */
-export function isMachine(opts?: RawOutputOpts): boolean {
-  return !!(opts?.raw || opts?.json) || !(process.stdout.isTTY ?? false)
+export function isMachine(opts?: MachineOpts): boolean {
+  return (
+    !!(opts?.raw || opts?.json || opts?.ci) ||
+    invocationWantsMachine() ||
+    !(process.stdout.isTTY ?? false)
+  )
 }
 
 /**
@@ -132,6 +140,14 @@ export type ListOpts = OutputOpts & {
 
 const NOISE_KEYS = new Set(['schema', 'icon', 'code', 'inputSchema', 'outputSchema'])
 
+function isNoiseKey(key: string): boolean {
+  if (NOISE_KEYS.has(key)) return true
+  const dot = key.lastIndexOf('.')
+  const colon = key.lastIndexOf(':')
+  const split = Math.max(dot, colon)
+  return split >= 0 && NOISE_KEYS.has(key.slice(split + 1))
+}
+
 /**
  * Strip heavy, low-signal keys (serialized schema blobs, SVG icons, code) at any
  * depth — so machine output is the kernel's data minus the noise, never a wall.
@@ -141,7 +157,7 @@ export function denoise(value: unknown): unknown {
   if (value && typeof value === 'object') {
     const out: Record<string, unknown> = {}
     for (const [k, v] of Object.entries(value)) {
-      if (NOISE_KEYS.has(k)) continue
+      if (isNoiseKey(k)) continue
       out[k] = v && typeof v === 'object' ? denoise(v) : v
     }
     return out

package/src/lib/view/assets.ts

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs'
+import { existsSync, statSync } from 'node:fs'
 import { copyFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -34,8 +34,8 @@ export async function ensureViewerAssets(
   entry = process.argv[1] ?? '.',
 ): Promise<string> {
   const dist = viewerDistDir(moduleUrl, entry)
-  if (hasViewerBundle(dist)) return dist
   const srcDir = join(dist, '..')
+  if (hasViewerBundle(dist) && !viewerSourceIsNewer(srcDir, dist)) return dist
   const bun = (
     globalThis as { Bun?: { build: (o: object) => Promise<{ success: boolean; logs: unknown[] }> } }
   ).Bun
@@ -62,3 +62,17 @@ function hasViewerBundle(directory: string): boolean {
 function hasViewerSource(directory: string): boolean {
   return existsSync(join(directory, 'main.ts')) && existsSync(join(directory, 'index.html'))
 }
+
+function viewerSourceIsNewer(source: string, dist: string): boolean {
+  if (!hasViewerSource(source)) return false
+  if (!hasViewerBundle(dist)) return true
+  const newestSource = Math.max(
+    statSync(join(source, 'main.ts')).mtimeMs,
+    statSync(join(source, 'index.html')).mtimeMs,
+  )
+  const oldestOutput = Math.min(
+    statSync(join(dist, 'main.js')).mtimeMs,
+    statSync(join(dist, 'index.html')).mtimeMs,
+  )
+  return newestSource > oldestOutput
+}

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

@@ -142,6 +142,7 @@ describe('program composition', () => {
       'domain install',
       'domain list',
       'domain publish',
+      'domain uninstall',
       'get',
       'identity',
       'identity create',
@@ -169,6 +170,7 @@ describe('program composition', () => {
       'instance list',
       'instance status',
       'instance use',
+      'introspect',
       'logs',
       'mutate',
       'query',
@@ -185,7 +187,7 @@ describe('program composition', () => {
       'whoami',
     ])
     expect(createHash('sha256').update(JSON.stringify(surface)).digest('hex')).toBe(
-      '369e7d1d51871f0ca1c6007d2a5c45023d093e70b85db07c1f58b06b7a0b17d4',
+      '73c4dc12159039257a1847701b16ef963f5c96a188f3656604dd2770e74c116e',
     )
   })
 
@@ -334,6 +336,7 @@ describe('help contract — payload sources', () => {
 
     expect(callHelp).toContain('--data <json>')
     expect(callHelp).not.toContain('--file <path>')
+    expect(callHelp).not.toContain('--describe')
     expect(mutateHelp).toContain('--data <json>')
     expect(mutateHelp).toContain('--file <path>')
   })

package/src/program/build.ts

@@ -23,13 +23,6 @@ export async function buildProgram(): Promise<Command> {
     .showSuggestionAfterError(true)
     .addOption(new Option('--ci', 'Machine mode: no prompts, structured errors on stderr'))
     .addOption(new Option('--no-prompt', 'Disable interactive prompts'))
-    .addOption(
-      new Option('--offline-ok', 'Tolerate offline state for commands that can operate locally'),
-    )
-    .addOption(
-      new Option('--log-level <level>', 'Log level').choices(['debug', 'info', 'warn', 'error']),
-    )
-    .addOption(new Option('--log-format <format>', 'Log output format').choices(['text', 'json']))
     .action(async () => {
       // Bare `astrale` in an interactive terminal with nothing connected yet →
       // launch the guided setup. Otherwise (configured, piped, or CI) show help.
@@ -62,6 +55,7 @@ export async function buildProgram(): Promise<Command> {
   registerCommand(program, withKernelOptions((await import('../commands/get')).default))
   registerCommand(program, withKernelOptions((await import('../commands/mutate')).default))
   registerCommand(program, withKernelOptions((await import('../commands/query')).default))
+  registerCommand(program, withKernelOptions((await import('../commands/introspect')).default))
   registerCommand(program, withKernelOptions((await import('../commands/logs')).default))
   registerCommand(program, withKernelOptions((await import('../commands/view')).default))
   registerCommand(program, (await import('../commands/status')).default)
@@ -86,11 +80,12 @@ export async function buildProgram(): Promise<Command> {
 
   registerGroup(program, {
     name: 'domain',
-    description: 'List, publish, and install domains (admin catalog + per-instance install)',
+    description: 'List, publish, install, and uninstall domains',
     commands: [
       withKernelOptions((await import('../commands/domain/list')).default),
       withKernelOptions((await import('../commands/domain/publish')).default),
       withKernelOptions((await import('../commands/domain/install')).default),
+      withKernelOptions((await import('../commands/domain/uninstall')).default),
     ],
   })
 
@@ -157,7 +152,7 @@ export async function buildProgram(): Promise<Command> {
     `
 Command groups:
   Getting started  setup     (sign in, pick an instance, equip your workspace)
-  Kernel        get, mutate, call, query, token
+  Kernel        get, mutate, call, query, introspect, logs, view, token
   Management    admin, instance, domain, identity, auth, idp, update
   Agent         browser   (drive the GUI via agent-browser)
   Studio        studio    (launch the local Domain Studio GUI for a workspace)
@@ -179,6 +174,7 @@ Examples:
   $ astrale instance status staging
   $ astrale token --audience shell.astrale.ai --ttl 3600
   $ astrale query /:notes.example.dev:class.Note --limit 50
+  $ astrale introspect /:host.astrale.ai:class.Manager:createInstance
   $ astrale query --file query.v6.json --cursor "$CURSOR"
 `,
   )

package/src/program/options.ts

@@ -16,7 +16,8 @@ const KERNEL_PASSTHROUGH_OPTIONS: readonly CommandOption[] = Object.freeze([
   { flags: '--creds <token>', description: 'Use a pre-signed credential (e.g. delegation token)' },
   {
     flags: '--anonymous',
-    description: 'Send no credential (cannot be combined with --as or --creds)',
+    description:
+      'Send no credential (cannot be combined with --as or --creds; --as and --creds are mutually exclusive)',
   },
   { flags: '--debug', description: 'Print full error diagnostics on failure' },
 ])

package/src/state/__tests__/identities.test.ts

@@ -46,7 +46,7 @@ describe('identity state', () => {
       path,
       now: () => new Date('2025-01-01T00:00:00.000Z'),
     })
-    expect(missing.identities.manager.createdAt).toBe('2025-01-01T00:00:00.000Z')
+    expect(missing).toEqual({ default: '', identities: {} })
     await expect(readFile(path, 'utf-8')).rejects.toThrow()
 
     await writeFile(path, legacy)
@@ -56,7 +56,7 @@ describe('identity state', () => {
 
     const current = `${JSON.stringify({ version: IDENTITY_STORE_VERSION, ...missing })}\n`
     await writeFile(path, current)
-    expect((await readIdentityStore({ path })).identities.manager.subject).toBe('manager')
+    expect((await readIdentityStore({ path })).identities).toEqual({})
     expect(await readFile(path, 'utf-8')).toBe(current)
   })
 

package/src/state/identities.ts

@@ -183,17 +183,10 @@ function hasVersion(input: unknown): input is { readonly version: unknown } {
   return typeof input === 'object' && input !== null && Object.hasOwn(input, 'version')
 }
 
-function seed(now: Date): IdentityStore {
+function seed(_now: Date): IdentityStore {
   return {
-    default: 'manager',
-    identities: {
-      manager: {
-        subject: 'manager',
-        createdAt: now.toISOString(),
-        source: 'key',
-        mode: 'local',
-      },
-    },
+    default: '',
+    identities: {},
   }
 }
 

package/studio/package.json

@@ -19,7 +19,7 @@
     "typecheck": "tsgo --noEmit"
   },
   "dependencies": {
-    "@astrale-os/shell": "file:../vendor/astrale-os-shell-0.3.8-beta.1.tgz",
+    "@astrale-os/shell": "file:../vendor/astrale-os-shell-0.3.8-beta.2.tgz",
     "@dagrejs/dagre": "^3.0.0",
     "@radix-ui/react-collapsible": "^1.1.0",
     "@radix-ui/react-dialog": "^1.1.6",
@@ -60,12 +60,11 @@
     "vite": "^7.0.0"
   },
   "overrides": {
-    "@astrale-os/kernel-client": "file:../vendor/kernel/astrale-os-kernel-client-0.6.0-beta.1.tgz",
-    "@astrale-os/kernel-core": "file:../vendor/kernel/astrale-os-kernel-core-0.9.0-beta.1.tgz",
-    "@astrale-os/kernel-dsl": "file:../vendor/kernel/astrale-os-kernel-dsl-0.2.0-beta.1.tgz",
-    "@astrale-os/kernel-ports": "file:../vendor/kernel/astrale-os-kernel-ports-0.6.0-beta.1.tgz",
-    "@astrale-os/kernel-protocol": "file:../vendor/kernel/astrale-os-kernel-protocol-0.5.0-beta.1.tgz",
-    "@astrale-os/kernel-server": "file:../vendor/kernel/astrale-os-kernel-server-0.5.0-beta.1.tgz",
-    "@astrale-os/sdk": "file:../vendor/astrale-os-sdk-0.5.0-beta.1.tgz"
+    "@astrale-os/kernel-client": "file:../vendor/kernel/astrale-os-kernel-client-0.6.0-beta.3.tgz",
+    "@astrale-os/kernel-core": "file:../vendor/kernel/astrale-os-kernel-core-0.9.0-beta.2.tgz",
+    "@astrale-os/kernel-dsl": "file:../vendor/kernel/astrale-os-kernel-dsl-0.2.0-beta.2.tgz",
+    "@astrale-os/kernel-protocol": "file:../vendor/kernel/astrale-os-kernel-protocol-0.5.0-beta.2.tgz",
+    "@astrale-os/kernel-server": "file:../vendor/kernel/astrale-os-kernel-server-0.5.0-beta.3.tgz",
+    "@astrale-os/sdk": "file:../vendor/astrale-os-sdk-0.5.0-beta.3.tgz"
   }
 }