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

package/src/commands/mutate.ts

@@ -0,0 +1,191 @@
+import type { PatchInput } from '@astrale-os/kernel-client/graph'
+
+import { patchDataSchema } from '@astrale-os/kernel-core'
+import chalk from 'chalk'
+import { readFile } from 'node:fs/promises'
+
+import type { CommandDefinition } from '../command'
+import type { KernelCommandOpts } from '../kernel'
+import type { MutationResultWire } from '../kernel'
+
+import { bindGraph, runKernelCommand } from '../kernel'
+import { log } from '../lib/log'
+import { output } from '../lib/output'
+import { renderTable } from '../lib/table'
+
+type MutateOpts = KernelCommandOpts & { data?: string; file?: string; dry?: boolean }
+
+export async function mutateCommand(opts: MutateOpts): Promise<void> {
+  let raw: unknown
+  try {
+    raw = await readPatch(opts)
+  } catch (e) {
+    log.error(e instanceof Error ? e.message : 'Invalid patch')
+    process.exit(1)
+    return
+  }
+
+  // --dry: validate the patch locally against the kernel's own schema and print
+  // the normalized form (every arm defaulted to []). No kernel round-trip.
+  if (opts.dry) {
+    const parsed = patchDataSchema.safeParse(raw)
+    if (!parsed.success) {
+      log.error('Patch failed local validation:')
+      for (const issue of parsed.error.issues) {
+        log.dim(`  ${issue.path.join('.') || '(root)'}: ${issue.message}`)
+      }
+      process.exit(1)
+    }
+    output(parsed.data, opts)
+    return
+  }
+
+  await runKernelCommand<MutationResultWire>({
+    opts,
+    label: 'Mutate',
+    fn: (ctx) => bindGraph(ctx).mutate(raw as PatchInput),
+    format: (result, fmtOpts, isRaw) => {
+      if (isRaw) {
+        output(result, fmtOpts)
+        return
+      }
+      printResult(result)
+    },
+  })
+}
+
+/** Patch source ladder (highest wins): --data > --file > stdin. */
+async function readPatch(opts: MutateOpts): Promise<unknown> {
+  if (opts.data) {
+    try {
+      return JSON.parse(opts.data)
+    } catch {
+      throw new Error(`Invalid JSON in --data: ${opts.data}`)
+    }
+  }
+  if (opts.file) {
+    let text: string
+    try {
+      text = await readFile(opts.file, 'utf-8')
+    } catch (e) {
+      throw new Error(`Cannot read --file ${opts.file}: ${e instanceof Error ? e.message : e}`)
+    }
+    try {
+      return JSON.parse(text)
+    } catch {
+      throw new Error(`Invalid JSON in ${opts.file}`)
+    }
+  }
+  const stdin = await readStdin()
+  if (stdin) {
+    try {
+      return JSON.parse(stdin)
+    } catch {
+      throw new Error('Invalid JSON from stdin')
+    }
+  }
+  throw new Error(
+    'No patch provided — pass --data <json>, --file <path>, or pipe a PatchData JSON on stdin',
+  )
+}
+
+async function readStdin(): Promise<string | null> {
+  if (process.stdin.isTTY) return null
+  const chunks: Buffer[] = []
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer)
+  }
+  const text = Buffer.concat(chunks).toString('utf-8').trim()
+  return text || null
+}
+
+function printResult(result: MutationResultWire): void {
+  const nodeRows = Object.entries(result.createdNodes ?? {})
+  const edgeRows = Object.entries(result.createdEdges ?? {})
+
+  if (nodeRows.length === 0 && edgeRows.length === 0) {
+    console.log(chalk.dim('  applied — no nodes or edges minted (updates/deletes only)'))
+    return
+  }
+
+  if (nodeRows.length > 0) {
+    console.log(`  ${chalk.bold('Created nodes:')}`)
+    console.log(
+      renderTable(
+        nodeRows.map(([at, id]) => ({ at, id })),
+        {
+          columns: [
+            { key: 'at', header: 'AT', color: chalk.cyan },
+            { key: 'id', header: 'ID', color: chalk.dim },
+          ],
+          showHeader: true,
+        },
+      ),
+    )
+    console.log('')
+  }
+
+  if (edgeRows.length > 0) {
+    console.log(`  ${chalk.bold('Created edges:')}`)
+    console.log(
+      renderTable(
+        edgeRows.map(([tuple, id]) => ({ tuple, id })),
+        {
+          columns: [
+            { key: 'tuple', header: 'CLASS|SOURCE|SLUG|TARGET', color: chalk.cyan },
+            { key: 'id', header: 'ID', color: chalk.dim },
+          ],
+          showHeader: true,
+        },
+      ),
+    )
+    console.log('')
+  }
+}
+
+export default {
+  name: 'mutate',
+  description: 'Apply a batch graph write (create/update/delete nodes & edges) via function.mutate',
+  afterHelpText: `
+Behavior:
+  Sends a PatchData patch through the kernel's function.mutate door — a
+  single all-or-nothing write. Patch source (highest wins): --data > --file
+  > stdin. Prints the minted id maps (createdNodes: at→id, createdEdges:
+  class|source|slug|target → id); --json emits the raw MutationResult.
+
+  Authorization is per-arm: a create needs USE on the class and EDIT on the
+  parent, an update/delete needs EDIT on the target. A denied arm fails the
+  whole patch. --dry validates the patch locally (kernel patchDataSchema) and
+  prints the normalized form without touching the kernel.
+
+PatchData shape:
+  {
+    "nodes": {
+      "create": [{ "class": "/:d:class.X", "at": "/d/x", "props": {} }],
+      "update": [{ "class": "/:d:class.X", "path": "/d/x", "props": {} }],
+      "delete": [{ "class": "/:d:class.X", "path": "/d/x" }]
+    },
+    "edges": {
+      "create": [{ "class": "/:d:class.e", "source": "/a", "target": "/b", "props": {} }],
+      "delete": [{ "class": "/:d:class.e", "source": "/a", "target": "/b" }]
+    }
+  }
+
+Examples:
+  $ astrale mutate --data '{"nodes":{"create":[{"class":"/:blog.acme.com:class.Author","at":"/blog.acme.com/authors/ada","props":{}}]}}'
+  $ astrale mutate --file patch.json
+  $ echo '{"nodes":{"delete":[{"class":"/:d:class.X","path":"/d/x"}]}}' | astrale mutate
+  $ astrale mutate --file patch.json --dry
+`,
+  options: [
+    { flags: '-d, --data <json>', description: 'PatchData as a JSON string' },
+    { flags: '-f, --file <path>', description: 'Read PatchData JSON from a file' },
+    {
+      flags: '--dry',
+      description: 'Validate locally (no kernel call) and print the normalized patch',
+    },
+  ],
+  action: async (opts) => {
+    await mutateCommand(opts as MutateOpts)
+  },
+} satisfies CommandDefinition

package/src/commands/query.ts

@@ -1,32 +1,319 @@
-import { K } from '@astrale-os/kernel-core'
+import { getInputSchema, K } from '@astrale-os/kernel-core'
+import chalk from 'chalk'
 
 import type { CommandDefinition } from '../command'
-import type { KernelCommandOpts } from '../kernel'
+import type { GetResultWire, KernelCommandOpts, QueryASTInput, SelfExpansionMeta } from '../kernel'
 
-import { runKernelCommand } from '../kernel'
+import { bindGraph, expandSelfInPath, runKernelCommand, withSelfHint } from '../kernel'
+import { log } from '../lib/log'
+import { isMachine, output } from '../lib/output'
 
-export async function queryCommand(cypher: string, opts: KernelCommandOpts): Promise<void> {
-  await runKernelCommand({
+type QueryOpts = KernelCommandOpts & {
+  depth?: string
+  children?: string
+  edges?: string
+  ast?: string
+  cypher?: string
+}
+
+type QueryMode =
+  | { kind: 'cypher'; cypher: string }
+  | { kind: 'ast'; ast: QueryASTInput }
+  | { kind: 'roots'; roots: string[]; meta: SelfExpansionMeta | undefined; query: BuiltQuery }
+
+export async function queryCommand(paths: string[], opts: QueryOpts): Promise<void> {
+  let mode: QueryMode
+  try {
+    mode = await parseMode(paths, opts)
+  } catch (e) {
+    log.error(e instanceof Error ? e.message : 'Invalid arguments')
+    process.exit(1)
+    return
+  }
+
+  if (mode.kind === 'cypher') {
+    await runKernelCommand({
+      opts,
+      label: 'Query',
+      fn: (ctx) => ctx.client.call(K.$.f('query').path.domain.raw, { cypher: mode.cypher }),
+      format: (result, fmtOpts) => output(result, fmtOpts),
+    })
+    return
+  }
+
+  await runKernelCommand<GetResultWire>({
     opts,
-    label: 'Query',
-    fn: (ctx) => ctx.client.call(K.Root.query.path.method.raw, { cypher }),
+    label: mode.kind === 'roots' ? 'Query ' + mode.roots.join(' ') : 'Query',
+    fn: async (ctx) => {
+      const read = () => bindGraph(ctx).query(mode.kind === 'roots' ? mode.query.ast : mode.ast)
+      const result = mode.kind === 'roots' ? await withSelfHint(read, mode.meta) : await read()
+      return result.wire
+    },
+    format: (result, fmtOpts) => {
+      output(result, fmtOpts)
+      if (result.next && !isMachine(fmtOpts)) printCursorFooter(result.next)
+    },
+  })
+}
+
+async function parseMode(paths: string[], opts: QueryOpts): Promise<QueryMode> {
+  const rootsInput = paths ?? []
+  const hasRoots = rootsInput.length > 0
+  const hasAst = opts.ast !== undefined
+  const hasCypher = opts.cypher !== undefined
+  const hasSelectors =
+    opts.depth !== undefined || opts.children !== undefined || opts.edges !== undefined
+
+  if (hasCypher) {
+    if (hasAst || hasRoots || hasSelectors) {
+      throw new Error('--cypher cannot be used with roots, --ast, --depth, --children, or --edges')
+    }
+    return { kind: 'cypher', cypher: opts.cypher as string }
+  }
+
+  if (hasAst) {
+    if (hasRoots || hasSelectors) {
+      throw new Error('--ast cannot be used with positional roots or --depth/--children/--edges')
+    }
+    return { kind: 'ast', ast: parseAst(opts.ast as string) }
+  }
+
+  if (!hasRoots) {
+    throw new Error(
+      'Usage: astrale query <paths...> [--depth <n>] [--children <json>] [--edges <json>] | --ast <json> | --cypher <query>',
+    )
+  }
+
+  const { roots, meta } = await expandRoots(rootsInput, opts)
+  return { kind: 'roots', roots, meta, query: buildQuery(roots, opts) }
+}
+
+function parseAst(raw: string): QueryASTInput {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error('--ast must be JSON: ' + raw)
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('--ast must be a JSON object')
+  }
+  return parsed as QueryASTInput
+}
+
+async function expandRoots(
+  paths: string[],
+  opts: QueryOpts,
+): Promise<{ roots: string[]; meta: SelfExpansionMeta | undefined }> {
+  const roots: string[] = []
+  let meta: SelfExpansionMeta | undefined
+  for (const p of paths) {
+    const expanded = await expandSelfInPath(p, opts)
+    roots.push(expanded.path)
+    if (!meta && expanded.meta) meta = expanded.meta
+  }
+  return { roots, meta }
+}
+
+type QueryDir = 'in' | 'out' | 'both'
+type QueryOrder = { by: string; dir: 'asc' | 'desc' }
+type ChildrenSelector = { classes?: string[]; limit?: number; cursor?: string; order?: QueryOrder }
+type EdgeSelector = {
+  as?: string
+  classes?: string[]
+  direction?: QueryDir
+  limit?: number
+  cursor?: string
+  order?: QueryOrder
+}
+type BuiltQuery = { ast: QueryASTInput; depth: number; hasEdges: boolean }
+
+function buildQuery(roots: string[], opts: QueryOpts): BuiltQuery {
+  const depth = opts.depth !== undefined ? parseRange('--depth', opts.depth, 0, 5) : 0
+  const children =
+    opts.children !== undefined
+      ? parseSelector<ChildrenSelector>('--children', opts.children, getInputSchema.shape.children)
+      : undefined
+  const edges =
+    opts.edges !== undefined
+      ? parseSelector<EdgeSelector | EdgeSelector[]>(
+          '--edges',
+          opts.edges,
+          getInputSchema.shape.edges,
+        )
+      : undefined
+
+  const steps: NonNullable<QueryASTInput['steps']> = []
+  if (depth > 0) steps.push({ expand: childExpand(depth, children) })
+  edgeSelectors(edges).forEach((selector, index) => {
+    steps.push({ expand: edgeExpand(selector, index) })
   })
+
+  return {
+    ast: { version: 1, from: roots, ...(steps.length > 0 ? { steps } : {}) },
+    depth,
+    hasEdges: edges !== undefined,
+  }
+}
+
+function childExpand(depth: number, children: ChildrenSelector | undefined) {
+  return {
+    edge: 'has_parent',
+    dir: 'in' as const,
+    depth,
+    ...(children?.classes !== undefined ? { filter: { class: children.classes } } : {}),
+    ...pageFields(children),
+    ...(children?.order !== undefined ? { order: children.order } : {}),
+  }
+}
+
+function edgeExpand(selector: EdgeSelector, index: number) {
+  return {
+    ...(selector.classes !== undefined ? { edge: selector.classes } : {}),
+    dir: selector.direction ?? 'both',
+    as: selector.as ?? 'e' + index,
+    ...pageFields(selector),
+    ...(selector.order !== undefined ? { order: selector.order } : {}),
+  }
+}
+
+function pageFields(selector: { limit?: number; cursor?: string } | undefined) {
+  if (selector?.limit === undefined && selector?.cursor === undefined) return {}
+  return {
+    page: {
+      ...(selector.limit !== undefined ? { limit: selector.limit } : {}),
+      ...(selector.cursor !== undefined ? { cursor: selector.cursor } : {}),
+    },
+  }
+}
+
+function edgeSelectors(edges: EdgeSelector | EdgeSelector[] | undefined): EdgeSelector[] {
+  if (edges === undefined) return []
+  return Array.isArray(edges) ? edges : [edges]
+}
+
+function parseRange(flag: string, raw: string, min: number, max: number): number {
+  const n = Number(raw)
+  if (!Number.isInteger(n) || n < min || n > max) {
+    throw new Error(flag + ' needs an integer in [' + min + ', ' + max + '], got "' + raw + '"')
+  }
+  return n
+}
+
+type SelectorIssue = { readonly path: readonly PropertyKey[]; readonly message: string }
+type SelectorSchema = {
+  safeParse(
+    value: unknown,
+  ): { success: true } | { success: false; error: { issues: readonly SelectorIssue[] } }
+}
+
+function parseSelector<T>(flag: string, raw: string, schema: SelectorSchema): T {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error(flag + ' must be JSON: ' + raw)
+  }
+  if (parsed === null || typeof parsed !== 'object') {
+    throw new Error(
+      flag + ' must be a JSON selector object' + (flag === '--edges' ? ' or array' : ''),
+    )
+  }
+  const check = schema.safeParse(parsed)
+  if (!check.success) {
+    const detail = check.error.issues
+      .map((i) => (i.path.join('.') || '(root)') + ': ' + i.message)
+      .join('; ')
+    throw new Error(flag + ' invalid selector: ' + detail)
+  }
+  return parsed as T
+}
+
+function printCursorFooter(next: NonNullable<GetResultWire['next']>): void {
+  const entries = Object.entries(next)
+  if (entries.length === 1) {
+    const cursors = entries[0]?.[1]
+    if (cursors?.children) {
+      process.stdout.write(
+        chalk.dim('  more: --children \'{"cursor":"' + cursors.children + '"}\'\n'),
+      )
+    }
+    for (const [alias, cursor] of Object.entries(cursors?.edges ?? {})) {
+      process.stdout.write(
+        chalk.dim(
+          '  more edges[' +
+            alias +
+            ']: --edges \'{"as":"' +
+            alias +
+            '","cursor":"' +
+            cursor +
+            '"}\'\n',
+        ),
+      )
+    }
+    return
+  }
+  process.stdout.write(
+    chalk.dim('  more results - per-root cursors in .next (page each root by --cursor)\n'),
+  )
 }
 
 export default {
   name: 'query',
-  description: 'Run a read-only Cypher query against the kernel graph',
-  afterHelpText: `
-Behavior:
-  Read-only. The kernel rejects write keywords (CREATE, DELETE, SET,
-  MERGE, REMOVE, DETACH); enforcement is kernel-side.
-
-Examples:
-  $ astrale query 'MATCH (n) RETURN count(n) AS total'
-  $ astrale query 'MATCH (n:Domain) RETURN n.slug, n.id'
-`,
-  arguments: [{ name: 'cypher', description: 'Cypher query string' }],
-  action: async (cypher, opts) => {
-    await queryCommand(cypher as string, opts as KernelCommandOpts)
+  description: 'Run a structured graph read',
+  afterHelpText: [
+    '',
+    'Behavior:',
+    '  Structured read door for the query AST. Positional roots build a v1 AST',
+    '  with optional child and edge expansion, then lower through function.get',
+    '  today. A true query syscall may back this command later.',
+    '',
+    '  Output is always the full GraphData envelope { nodes, edges, aliases }',
+    '  with .roots and .next when returned. On a TTY, cursor footers are printed',
+    '  when .next has more pages.',
+    '',
+    '  --children takes { classes?, limit?, cursor?, order? } and shapes the',
+    '  depth-1 children page (needs --depth >= 1 to bite). --edges takes an edge',
+    '  selector, or a JSON array of selectors.',
+    '',
+    '  --ast (experimental) accepts a raw QueryASTInput JSON object. The AST shape',
+    '  is not a stable contract yet — prefer the flags above. @self is not expanded',
+    '  inside --ast JSON.',
+    '',
+    '  --cypher is a read-only escape hatch. The kernel rejects write keywords',
+    '  such as CREATE, DELETE, SET, MERGE, REMOVE, and DETACH.',
+    '',
+    'Examples:',
+    '  $ astrale query / --depth 1',
+    '  $ astrale query /a /b --edges \'{"direction":"both"}\'',
+    '  $ astrale query /kernel.astrale.ai --depth 2 --children \'{"classes":["/:kernel.astrale.ai:class.Folder"]}\'',
+    "  $ astrale query --cypher 'MATCH (n) RETURN count(n) AS total'",
+    '',
+  ].join('\n'),
+  arguments: [
+    {
+      name: 'paths...',
+      description: 'One or more root paths (/domain/Class) or IDs (@nodeId)',
+      required: false,
+    },
+  ],
+  options: [
+    { flags: '--depth <n>', description: 'Subtree depth to fetch (0-5, default 0)' },
+    {
+      flags: '--children <json>',
+      description: 'Children selector { classes?, limit?, cursor?, order? } (needs --depth >= 1)',
+    },
+    {
+      flags: '--edges <json>',
+      description: 'Edge selector (or JSON array of selectors) to include',
+    },
+    {
+      flags: '--ast <json>',
+      description: 'Raw QueryASTInput JSON object (experimental, unstable shape)',
+    },
+    { flags: '--cypher <query>', description: 'Read-only Cypher escape hatch' },
+  ],
+  action: async (paths, opts) => {
+    await queryCommand(Array.isArray(paths) ? paths : [], opts as QueryOpts)
   },
 } satisfies CommandDefinition

package/src/commands/session/analyze.ts

@@ -0,0 +1,50 @@
+import chalk from 'chalk'
+
+import type { CommandDefinition } from '../../command'
+
+import { log } from '../../lib/log'
+import { analyzeSession } from '../../telemetry/analyze'
+import { listSessions } from '../../telemetry/store'
+import { restampLock, releaseLock } from '../../telemetry/trigger'
+
+export default {
+  name: 'analyze',
+  description: 'Analyze a recorded session for DX frictions (dry-run: writes report.md)',
+  arguments: [{ name: 'id', description: 'Session id (default: most recent closed, unanalyzed)' }],
+  options: [
+    { flags: '--file', description: 'File cleared findings as issues on the admin tracker' },
+    { flags: '--model <model>', description: 'Model for the analyzer pass' },
+    { flags: '--force', description: 'Re-analyze even if already analyzed' },
+    { flags: '--auto', description: 'Triggered mode: quiet, used by the opportunistic trigger' },
+  ],
+  action: async (
+    id: string | undefined,
+    opts: { file?: boolean; model?: string; force?: boolean; auto?: boolean },
+  ) => {
+    if (opts.auto) restampLock()
+    try {
+      let target = id
+      if (!target) {
+        const candidate = listSessions().find((s) => s.closed && (opts.force || !s.analyzed))
+        if (!candidate) {
+          if (!opts.auto) log.dim('Nothing to analyze — no closed, unanalyzed session.')
+          return
+        }
+        target = candidate.id
+      }
+      if (!opts.auto) log.step(`analyzing session ${target} …`)
+      const outcome = await analyzeSession(target, opts)
+      if (opts.auto) return
+      if (outcome.outcome === 'skipped-quiet') {
+        log.dim(`quiet session (${outcome.note}) — nothing to analyze`)
+      } else if (outcome.outcome === 'error') {
+        log.error(`analyzer failed: ${outcome.note ?? 'unknown'}`)
+      } else {
+        log.success(`${outcome.outcome} (${outcome.note ?? ''})`)
+        if (outcome.reportPath) console.log(chalk.dim(`  ${outcome.reportPath}`))
+      }
+    } finally {
+      if (opts.auto) releaseLock()
+    }
+  },
+} satisfies CommandDefinition

package/src/commands/session/list.ts

@@ -0,0 +1,36 @@
+import chalk from 'chalk'
+
+import type { CommandDefinition } from '../../command'
+
+import { log } from '../../lib/log'
+import { isMachine, output, RAW_OUTPUT_OPTIONS } from '../../lib/output'
+import { listSessions } from '../../telemetry/store'
+
+export default {
+  name: 'list',
+  description: 'List locally recorded work sessions and their analysis state',
+  options: [...RAW_OUTPUT_OPTIONS],
+  action: async (opts: { raw?: boolean; json?: boolean }) => {
+    const sessions = listSessions()
+    if (isMachine(opts)) {
+      output(sessions, opts)
+      return
+    }
+    if (sessions.length === 0) {
+      log.dim('No sessions recorded yet. Run any astrale command in a workspace to start one.')
+      return
+    }
+    for (const s of sessions) {
+      const state = s.analyzed
+        ? s.analyzed.outcome === 'error'
+          ? chalk.red(s.analyzed.outcome)
+          : chalk.green(s.analyzed.outcome)
+        : s.closed
+          ? chalk.yellow('closed, unanalyzed')
+          : chalk.cyan('open')
+      const when = s.lastEventAt ? s.lastEventAt.toISOString().slice(0, 16) : 'no events'
+      console.log(`${chalk.bold(s.id)}  ${state}`)
+      console.log(chalk.dim(`  ${s.meta?.root ?? '(unknown root)'} — last activity ${when}`))
+    }
+  },
+} satisfies CommandDefinition

package/src/commands/token.ts

@@ -2,12 +2,11 @@ import type { CommandDefinition } from '../command'
 import type { KernelCommandOpts } from '../kernel'
 
 import { runKernelCommand } from '../kernel'
-import { mintDelegationPath } from '../kernel/remote-routing'
 import { log } from '../lib/log'
 
 /**
  * `astrale token` — mint a fresh delegation token for the active instance
- * + active identity (§2.5). Shortcut over the mintDelegationCredential call.
+ * + active identity through the bound AuthApi.
  */
 export type TokenOpts = KernelCommandOpts & {
   audience?: string
@@ -26,12 +25,10 @@ export async function tokenCommand(opts: TokenOpts): Promise<void> {
       const audience = opts.audience ?? ''
       const parsedTtl = Number(opts.ttl)
       const ttl = Number.isFinite(parsedTtl) && parsedTtl > 0 ? parsedTtl : 3600
-      const mintPath = await mintDelegationPath(ctx.client, ctx.credential)
-      const result = (await ctx.client.call(mintPath, {
+      const result = await ctx.client.as(ctx.credential).auth.delegate({
         audience,
-        delegation: { kind: 'identity', self: true },
         ttl,
-      })) as string
+      })
       return result
     },
     format: (token, fmtOpts, isRaw) => {
@@ -63,7 +60,7 @@ What this token is FOR — worker-direct HTTP calls:
   use 'astrale call' (which signs per-call) instead.
 
 Examples:
-  $ export TOKEN=$(astrale token --audience dist.astrale.ai --raw)
+  $ export TOKEN=$(astrale token --audience shell.astrale.ai --raw)
   $ astrale token --audience worker.example.com --for alice -i staging
 `,
   options: [

package/src/commands/view-serve.ts

@@ -0,0 +1,26 @@
+import { readFile } from 'node:fs/promises'
+
+import type { CommandDefinition } from '../command'
+import type { ViewServeConfig } from '../lib/view/session'
+
+import { startViewServer } from '../lib/view/server'
+
+/**
+ * Internal (hidden) entry for the detached view-session server: `astrale view`
+ * re-invokes the CLI with `__view-serve --config <file>` so the server runs
+ * under the same runtime and codebase as the CLI itself.
+ */
+export default {
+  name: '__view-serve',
+  hidden: true,
+  description: 'Internal: run a view-session server from a config file',
+  options: [{ flags: '--config <path>', description: 'ViewServeConfig JSON path' }],
+  action: async (opts: { config?: string }) => {
+    if (!opts.config) throw new Error('--config is required')
+    const config = JSON.parse(await readFile(opts.config, 'utf8')) as ViewServeConfig
+    startViewServer(config)
+    console.log(`view session ${config.session.id} listening on ${config.session.pageUrl}`)
+    // Keep the process alive; startViewServer owns shutdown (signals + idle).
+    await new Promise(() => {})
+  },
+} satisfies CommandDefinition