@astrale-os/cli 0.4.0-alpha.13

package/src/commands/logs.ts

@@ -0,0 +1,347 @@
+import type { JournalEntry, JournalFilter } from '@astrale-os/kernel-core'
+
+/**
+ * `astrale logs` — tail the kernel event journal (Root.journal) for the target
+ * instance. Defaults to the kernel journal syscall
+ * `/kernel.astrale.ai/class.Root/journal`; `--service <name>` switches to the
+ * per-instance `services` domain log buffer (the historical behavior).
+ *
+ * Target the instance with `-i <instance>` (inherited from withKernelOptions).
+ */
+import chalk from 'chalk'
+
+import type { CommandDefinition } from '../command'
+import type { ClientContext, KernelCommandOpts } from '../kernel'
+import type { Column, ListProjection } from '../lib/output'
+
+import { runKernelCommand, withKernelClient } from '../kernel'
+import { fatal, withSpinner } from '../lib/log'
+import { isMachine, output, presentList } from '../lib/output'
+
+const ROOT_JOURNAL_PATH = '/kernel.astrale.ai/class.Root/journal'
+const DEFAULT_SERVICES_ORIGIN = 'services.astrale.ai'
+const DEFAULT_LIMIT = 200
+const FOLLOW_INTERVAL_MS = 2000
+// The journal-read syscall journals its own ops; hide them by default so polling
+// doesn't self-pollute the view. `--all` shows them.
+const SELF_READ_PREFIX = 'op:class.Root.method.journal:'
+
+// The published @astrale-os/kernel-core@0.5.0 JournalFilter has no `cursor` yet
+// (added on the kernel branch). Type against the augmented shape so the
+// incremental cursor compiles against the consumer dependency.
+type EventsParams = JournalFilter & { cursor?: number }
+
+type LogsOpts = KernelCommandOpts & {
+  since?: string
+  until?: string
+  topic?: string
+  principal?: string
+  limit?: string
+  cursor?: string
+  follow?: boolean
+  all?: boolean
+  timing?: boolean
+  // service mode
+  service?: string
+  tail?: string
+  servicesOrigin?: string
+}
+
+/**
+ * Kernel journal page. The Root.journal syscall returns a BARE `JournalEntry[]`;
+ * the client derives the next cursor from the max `seq`. We still model a
+ * `nextCursor` field so the TTY footer / incremental tail share one shape, and
+ * so a future paged kernel response degrades gracefully.
+ */
+type EventsPage = {
+  entries: JournalEntry[]
+  nextCursor?: number | null
+}
+
+// ── Root.journal (default) ───────────────────────────────────
+
+/** The highest `seq` across entries, or null when empty. */
+function maxSeq(entries: JournalEntry[]): number | null {
+  let max: number | null = null
+  for (const e of entries) {
+    if (typeof e.seq === 'number' && (max === null || e.seq > max)) max = e.seq
+  }
+  return max
+}
+
+/**
+ * Accept the bare `JournalEntry[]` the syscall returns (and tolerate a paged
+ * `{ entries, nextCursor }` shape if the kernel ever switches). `nextCursor` is
+ * the max `seq` — the client passes it back as `cursor` to tail incrementally.
+ */
+export function normalizePage(raw: unknown): EventsPage {
+  if (Array.isArray(raw)) {
+    const entries = raw as JournalEntry[]
+    return { entries, nextCursor: maxSeq(entries) }
+  }
+  const obj = (raw ?? {}) as { entries?: unknown; nextCursor?: unknown }
+  const entries = Array.isArray(obj.entries) ? (obj.entries as JournalEntry[]) : []
+  const nextCursor = typeof obj.nextCursor === 'number' ? obj.nextCursor : maxSeq(entries)
+  return { entries, nextCursor }
+}
+
+/** Build the JournalFilter (+ optional seq cursor) from typed flags. */
+export function buildEventsParams(opts: LogsOpts): EventsParams {
+  const params: EventsParams = {}
+  if (opts.topic) params.topic = opts.topic
+  if (opts.principal) params.principal = opts.principal as JournalFilter['principal']
+  if (opts.since !== undefined) params.since = parseTimeFlag('--since', opts.since)
+  if (opts.until !== undefined) params.until = parseTimeFlag('--until', opts.until)
+  params.limit = opts.limit !== undefined ? parsePositiveInt('--limit', opts.limit) : DEFAULT_LIMIT
+  if (opts.cursor !== undefined) params.cursor = parsePositiveInt('--cursor', opts.cursor)
+  return params
+}
+
+/** Accept epoch-ms or an ISO-8601 string → epoch ms. */
+export function parseTimeFlag(flag: string, raw: string): number {
+  if (/^-?\d+$/.test(raw)) return Number(raw)
+  const ms = Date.parse(raw)
+  if (Number.isNaN(ms)) throw new Error(`${flag} needs epoch-ms or ISO-8601, got "${raw}"`)
+  return ms
+}
+
+function parsePositiveInt(flag: string, raw: string): number {
+  const n = Number(raw)
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`${flag} needs a positive integer, got "${raw}"`)
+  }
+  return n
+}
+
+const TOPIC_COLOR = (s: string): string =>
+  s.startsWith('op:') ? chalk.cyan(s) : s.startsWith('sys:') ? chalk.magenta(s) : chalk.dim(s)
+
+/** op:*:completed|failed carry `durationMs` in their payload; started does not. */
+const latencyOf = (e: JournalEntry): string => {
+  const d = (e.event.payload as { durationMs?: number } | undefined)?.durationMs
+  return typeof d === 'number' ? `${d}ms` : ''
+}
+
+/** Highlight slow ops: green < 100ms, yellow < 500ms, red beyond. */
+const LATENCY_COLOR = (s: string): string => {
+  if (!s) return s
+  const ms = Number.parseInt(s, 10)
+  if (ms >= 500) return chalk.red(s)
+  if (ms >= 100) return chalk.yellow(s)
+  return chalk.green(s)
+}
+
+/** Short labels for the per-step dispatch timing (payload.timing). */
+const STEP_LABEL: Record<string, string> = {
+  authenticate: 'auth',
+  validateInput: 'in',
+  authorize: 'authz',
+  resolve: 'resolve',
+  invariants: 'inv',
+  execute: 'exec',
+  validateOutput: 'out',
+  effects: 'fx',
+}
+
+/** Compact per-step breakdown, non-zero steps only: e.g. "auth:7 authz:13 exec:12". */
+const timingOf = (e: JournalEntry): string => {
+  const t = (e.event.payload as { timing?: Record<string, number> } | undefined)?.timing
+  if (!t || typeof t !== 'object') return ''
+  return Object.entries(t)
+    .filter(([, ms]) => typeof ms === 'number' && ms > 0)
+    .map(([k, ms]) => `${STEP_LABEL[k] ?? k}:${ms}`)
+    .join(' ')
+}
+
+function eventsProjection(entries: JournalEntry[], showTiming = false): ListProjection {
+  const columns: Column[] = [
+    { key: 'seq', header: 'SEQ', color: chalk.dim },
+    { key: 'ts', header: 'TIME', color: chalk.dim },
+    { key: 'topic', header: 'TOPIC', color: TOPIC_COLOR },
+    { key: 'latency', header: 'LATENCY', color: LATENCY_COLOR },
+    ...(showTiming ? [{ key: 'steps', header: 'STEPS', color: chalk.dim } as Column] : []),
+    { key: 'principal', header: 'PRINCIPAL', color: chalk.dim },
+  ]
+  return {
+    columns,
+    rows: entries.map((e) => ({
+      seq: String(e.seq),
+      ts: new Date(e.event.metadata.timestamp).toISOString(),
+      topic: e.event.topic,
+      latency: latencyOf(e),
+      ...(showTiming ? { steps: timingOf(e) } : {}),
+      principal: String(e.event.metadata.principal),
+    })),
+    paths: entries.map((e) => String(e.seq)),
+  }
+}
+
+async function fetchEventsPage(ctx: ClientContext, opts: LogsOpts): Promise<EventsPage> {
+  const raw = await ctx.client.call(ROOT_JOURNAL_PATH, buildEventsParams(opts))
+  const page = normalizePage(raw)
+  // Strip the journal's own read ops by default (but keep nextCursor past them).
+  const entries = opts.all
+    ? page.entries
+    : page.entries.filter((e) => !e.event.topic.startsWith(SELF_READ_PREFIX))
+  return { entries, nextCursor: page.nextCursor }
+}
+
+function printEventLine(e: JournalEntry, showTiming = false): void {
+  const ts = new Date(e.event.metadata.timestamp).toISOString()
+  const lat = latencyOf(e)
+  const steps = showTiming ? timingOf(e) : ''
+  process.stdout.write(
+    `${chalk.dim(String(e.seq).padStart(6))} ${chalk.dim(ts)} ${TOPIC_COLOR(e.event.topic)} ${chalk.dim(String(e.event.metadata.principal))}${lat ? ` ${LATENCY_COLOR(lat)}` : ''}${steps ? ` ${chalk.dim(`[${steps}]`)}` : ''}\n`,
+  )
+}
+
+async function runEvents(opts: LogsOpts): Promise<void> {
+  if (opts.follow) return followEvents(opts)
+
+  await runKernelCommand<EventsPage>({
+    opts,
+    label: 'Kernel events',
+    fn: (ctx) => fetchEventsPage(ctx, opts),
+    format: (page, fmtOpts) => {
+      if (isMachine(fmtOpts) || fmtOpts.format) {
+        // Machine surface: the kernel's own entries array, no projection.
+        output(page.entries, fmtOpts)
+        return
+      }
+      presentList(page.entries, fmtOpts, (entries) => eventsProjection(entries, opts.timing))
+      if (typeof page.nextCursor === 'number') {
+        process.stdout.write(chalk.dim(`  tail: --follow  (or --cursor ${page.nextCursor})\n`))
+      }
+    },
+  })
+}
+
+/**
+ * Client-side polling follow (ctx.client exposes no stream transport). Take the
+ * max `seq` from each page and pass it back as `cursor` (exclusive cursor) so
+ * the next poll only returns new entries.
+ */
+async function followEvents(opts: LogsOpts): Promise<void> {
+  await withKernelClient(opts, async (ctx) => {
+    let cursor = opts.cursor !== undefined ? parsePositiveInt('--cursor', opts.cursor) : undefined
+    for (;;) {
+      const page = await fetchEventsPage(ctx, { ...opts, cursor: cursor?.toString() })
+      for (const e of page.entries) printEventLine(e, opts.timing)
+      if (typeof page.nextCursor === 'number') cursor = page.nextCursor
+      await new Promise((resolve) => setTimeout(resolve, FOLLOW_INTERVAL_MS))
+    }
+  })
+}
+
+// ── --service (legacy services-domain log buffer) ───────────
+
+type ServiceLogs = {
+  name: string
+  lines: Array<{ ts: number; level: string; line: string }>
+}
+
+const LEVEL_COLOR: Record<string, (s: string) => string> = {
+  error: chalk.red,
+  warn: chalk.yellow,
+  access: chalk.cyan,
+  debug: chalk.dim,
+}
+
+/** Accept a bare service name, a `<name>.…` host, or a full https URL → the service name. */
+export function parseServiceName(ref: string): string {
+  let host = ref.trim()
+  if (host.includes('://')) {
+    try {
+      host = new URL(host).hostname
+    } catch {
+      // keep the raw value — the call will fail loud with the name
+    }
+  }
+  return host.includes('.') ? (host.split('.')[0] ?? host) : host
+}
+
+async function runService(opts: LogsOpts): Promise<void> {
+  const name = parseServiceName(opts.service as string)
+  const origin = opts.servicesOrigin ?? DEFAULT_SERVICES_ORIGIN
+  const tail = opts.tail !== undefined ? Number(opts.tail) : undefined
+  if (tail !== undefined && (!Number.isInteger(tail) || tail <= 0)) {
+    throw new Error(`--tail needs a positive integer, got "${opts.tail}"`)
+  }
+  const result = await withSpinner(`Fetching logs for ${name}`, !isMachine(opts), () =>
+    withKernelClient(
+      opts,
+      async (ctx) =>
+        (await ctx.client.call(
+          `/${origin}/services/${name}::logs`,
+          tail !== undefined ? { tail } : {},
+        )) as ServiceLogs,
+    ),
+  )
+  if (isMachine(opts)) {
+    output(result, opts)
+    return
+  }
+  if (result.lines.length === 0) {
+    console.log(chalk.dim(`no log lines captured yet for ${result.name}`))
+    return
+  }
+  for (const entry of result.lines) {
+    const ts = new Date(entry.ts).toISOString()
+    const paint = LEVEL_COLOR[entry.level] ?? ((s: string) => s)
+    console.log(`${chalk.dim(ts)} ${paint(entry.level.padEnd(6))} ${entry.line}`)
+  }
+}
+
+export default {
+  name: 'logs',
+  description: 'Tail the kernel event journal (or a service log buffer with --service)',
+  options: [
+    { flags: '--since <t>', description: 'Events at/after this time (epoch-ms or ISO-8601)' },
+    { flags: '--until <t>', description: 'Events at/before this time (epoch-ms or ISO-8601)' },
+    { flags: '--topic <glob>', description: 'Topic glob (e.g. op:*:failed, graph:node:**)' },
+    { flags: '--principal <id>', description: 'Filter by the triggering identity' },
+    { flags: '--limit <n>', description: `Max entries (default ${DEFAULT_LIMIT})` },
+    { flags: '--cursor <n>', description: 'Start after this journal sequence number' },
+    { flags: '--follow', description: 'Poll for new events (Ctrl-C to stop)' },
+    { flags: '--all', description: 'Include the journal-read syscall ops (hidden by default)' },
+    { flags: '--timing', description: 'Show the per-step dispatch breakdown (auth/authz/exec/…)' },
+    { flags: '--service <name>', description: 'Tail a deployed service log buffer instead' },
+    { flags: '--tail <n>', description: '[--service] lines to return (default 200, max 500)' },
+    {
+      flags: '--services-origin <origin>',
+      description: `[--service] services-domain origin (default ${DEFAULT_SERVICES_ORIGIN})`,
+    },
+  ],
+  afterHelpText: `
+Default: tails the kernel event journal via ${ROOT_JOURNAL_PATH} on the target
+instance (-i <instance>). Topics use ':'-segmented globs ('*' one segment,
+'**' zero-or-more). Machine output (--json / pipe) emits the JournalEntry[]
+array; a TTY shows a SEQ/TIME/TOPIC/LATENCY/PRINCIPAL table (LATENCY is the
+op's durationMs, present on :completed/:failed). --timing adds a STEPS column
+with the per-step dispatch breakdown (auth/in/authz/resolve/inv/exec/out/fx,
+non-zero only). --follow polls for new entries (client-side, tailing by
+sequence number). The journal-read syscall's own ops are hidden unless --all.
+
+--service <name> switches to the per-instance 'services' domain log buffer
+(console output, 5xx accesses, uncaught exceptions). Requires the services
+domain installed on the target instance.
+
+Examples:
+  astrale logs -i staging
+  astrale logs -i staging --topic 'op:*:failed' --limit 50
+  astrale logs -i staging --topic 'op:*:completed' --timing
+  astrale logs -i staging --since 2026-06-20T00:00:00Z --follow
+  astrale logs --service my-notes -i staging --tail 50
+`,
+  action: async (opts: LogsOpts) => {
+    try {
+      if (opts.service) {
+        await runService(opts)
+      } else {
+        await runEvents(opts)
+      }
+    } catch (e) {
+      fatal(e)
+    }
+  },
+} satisfies CommandDefinition

package/src/commands/ls.ts

@@ -0,0 +1,229 @@
+import chalk from 'chalk'
+
+import type { CommandDefinition } from '../command'
+import type { KernelCommandOpts, ClientContext, SelfExpansionMeta } from '../kernel'
+import type { ListProjection } from '../lib/output'
+
+import {
+  expandSelfInPath,
+  extractItems,
+  formatKernelError,
+  runKernelCommand,
+  withKernelClient,
+  withSelfHint,
+} from '../kernel'
+import { spinner } from '../lib/log'
+import { isMachine, output, presentList } from '../lib/output'
+
+type LsOpts = KernelCommandOpts & {
+  long?: boolean
+  quiet?: boolean
+  recursive?: boolean
+  count?: boolean
+  filter?: string
+}
+
+/** A child node as returned by `::listChildren`. */
+type Item = {
+  id?: string
+  class?: string
+  path?: string
+  props?: Record<string, unknown>
+  __labels?: string[]
+}
+
+// ── Display projection ──────────────────────────────────────
+
+/** `/dist.astrale.ai` → `dist.astrale.ai`; `/` stays `/`. */
+export function basename(path?: string): string {
+  if (!path || path === '/') return path ?? ''
+  return path.slice(path.lastIndexOf('/') + 1)
+}
+
+/** `/:kernel.astrale.ai:class.Domain` → `Domain`; falls back to the most specific label. */
+export function classNameOf(item: Item): string {
+  const tail = item.class?.split(/[/:.]/).pop()
+  return tail || item.__labels?.[item.__labels.length - 1] || '?'
+}
+
+/** The addressable path of a child (for `-q` / tree descent). */
+function itemPath(item: Item): string {
+  return item.path ?? (item.id ? `@${item.id}` : '')
+}
+
+function lsProjection(items: Item[]): ListProjection {
+  return {
+    columns: [
+      { key: 'name', header: 'NAME', color: chalk.cyan },
+      { key: 'kind', header: 'KIND', color: chalk.dim },
+      { key: 'id', header: 'ID', color: chalk.dim },
+    ],
+    rows: items.map((i) => ({ name: basename(i.path), kind: classNameOf(i), id: i.id ?? '' })),
+    paths: items.map(itemPath),
+  }
+}
+
+function applyFilter(items: Item[], filter: string | undefined): Item[] {
+  if (!filter) return items
+  const f = filter.toLowerCase()
+  return items.filter((i) => {
+    const kindMatch = classNameOf(i).toLowerCase() === f
+    const labelMatch = i.__labels?.some((l) => l.toLowerCase() === f) ?? false
+    return kindMatch || labelMatch
+  })
+}
+
+// ── Command ─────────────────────────────────────────────────
+
+export async function lsCommand(path: string, opts: LsOpts): Promise<void> {
+  let expandedPath: string
+  let meta
+  try {
+    ;({ path: expandedPath, meta } = await expandSelfInPath(path, opts))
+  } catch (e) {
+    process.stderr.write((e instanceof Error ? e.message : 'Invalid @self expansion') + '\n')
+    process.exit(1)
+  }
+
+  if (opts.recursive) {
+    return recursiveLs(expandedPath, opts, meta)
+  }
+
+  await runKernelCommand({
+    opts,
+    label: `Children of ${expandedPath}`,
+    fn: (ctx) => withSelfHint(() => ctx.client.call(`${expandedPath}::listChildren`, {}), meta),
+    format: (result, fmtOpts) => {
+      const items = applyFilter(extractItems<Item>(result), opts.filter)
+      presentList(
+        items,
+        { ...fmtOpts, quiet: opts.quiet, count: opts.count, long: opts.long },
+        lsProjection,
+      )
+    },
+  })
+}
+
+// ── Recursive tree ──────────────────────────────────────────
+
+const MAX_DEPTH = 5
+const MAX_NODES = 200
+
+type TreeNode = Item & { children?: TreeNode[] }
+
+async function recursiveLs(
+  path: string,
+  opts: LsOpts,
+  meta: SelfExpansionMeta | undefined,
+): Promise<void> {
+  const machine = isMachine(opts)
+  const spin = !machine ? spinner(`Listing ${path} recursively...`) : null
+
+  try {
+    await withKernelClient(opts, async (ctx) => {
+      const counter = { count: 0 }
+      const tree = await withSelfHint(() => buildTree(ctx, path, 0, counter), meta)
+      spin?.succeed(`Tree of ${path}`)
+      if (!machine) console.log('')
+
+      if (machine || opts.format) {
+        output(tree, opts)
+      } else if (opts.quiet) {
+        printTreeQuiet(tree)
+      } else {
+        printTree(tree, '')
+      }
+    })
+  } catch (error) {
+    if (!machine && spin) spin.fail('Failed')
+    await formatKernelError(error, machine, undefined, opts.debug, { credential: opts.creds })
+    process.exit(1)
+  }
+}
+
+async function buildTree(
+  ctx: ClientContext,
+  path: string,
+  depth: number,
+  counter: { count: number },
+): Promise<TreeNode[]> {
+  if (depth >= MAX_DEPTH || counter.count >= MAX_NODES) return []
+  try {
+    const result = await ctx.client.call(`${path}::listChildren`, {})
+    const items = extractItems<Item>(result)
+
+    const nodes: TreeNode[] = []
+    for (const item of items) {
+      if (counter.count >= MAX_NODES) break
+      counter.count++
+      const node: TreeNode = { ...item }
+      // Descend by the child's absolute path (the kernel returns `path`, not `slug`).
+      if (item.path && item.path !== '/') {
+        node.children = await buildTree(ctx, item.path, depth + 1, counter)
+      }
+      nodes.push(node)
+    }
+    return nodes
+  } catch {
+    return []
+  }
+}
+
+function printTree(nodes: TreeNode[], prefix: string): void {
+  for (let i = 0; i < nodes.length; i++) {
+    const node = nodes[i]
+    const isLast = i === nodes.length - 1
+    const connector = isLast ? '└── ' : '├── '
+    const childPrefix = isLast ? '    ' : '│   '
+
+    const name = basename(node.path) || node.id || '?'
+    console.log(`${prefix}${connector}${chalk.cyan(name)}  ${chalk.dim(classNameOf(node))}`)
+
+    if (node.children && node.children.length > 0) {
+      printTree(node.children, prefix + childPrefix)
+    }
+  }
+}
+
+function printTreeQuiet(nodes: TreeNode[]): void {
+  for (const node of nodes) {
+    process.stdout.write(itemPath(node) + '\n')
+    if (node.children) printTreeQuiet(node.children)
+  }
+}
+
+export default {
+  name: 'ls',
+  description: 'List children of a node',
+  afterHelpText: `
+Behavior:
+  Default output is a NAME/KIND/ID table on a TTY, JSON when piped. --filter
+  matches a node KIND or label: Folder, Method, Domain. At a domain's tree
+  position the children are Folder nodes (class.X), not Class — so --filter
+  Class returns nothing; use --filter Folder, or descend into class.<X> and
+  --filter Method. -R tree view is TTY-only (raw/JSON emits the nested tree).
+  -q prints one absolute path per line (pipeable). Note: ls /<domain> may
+  report NOT_FOUND even when it exists — use describe, or ls one of its children.
+
+Examples:
+  $ astrale ls /
+  $ astrale ls /kernel.astrale.ai --filter Folder
+  $ astrale ls / -q | xargs -I{} astrale describe {}
+`,
+  arguments: [
+    { name: 'path', description: 'Node path (/domain/Class) or ID (@nodeId)', required: false },
+  ],
+  options: [
+    { flags: '-l, --long', description: 'Full node dump (default: compact)' },
+    { flags: '-q, --quiet', description: 'One path per line (unix-pipeable)' },
+    { flags: '-R, --recursive', description: 'List recursively (tree view)' },
+    { flags: '--count', description: 'Print only the number of children' },
+    {
+      flags: '--filter <kind>',
+      description: 'Filter children by kind or label (e.g., Folder, Method, Domain)',
+    },
+  ],
+  action: async (path, opts) => {
+    await lsCommand((path as string | undefined) ?? '/', opts as Parameters<typeof lsCommand>[1])
+  },
+} satisfies CommandDefinition

package/src/commands/query.ts

@@ -0,0 +1,32 @@
+import { K } from '@astrale-os/kernel-core'
+
+import type { CommandDefinition } from '../command'
+import type { KernelCommandOpts } from '../kernel'
+
+import { runKernelCommand } from '../kernel'
+
+export async function queryCommand(cypher: string, opts: KernelCommandOpts): Promise<void> {
+  await runKernelCommand({
+    opts,
+    label: 'Query',
+    fn: (ctx) => ctx.client.call(K.Root.query.path.method.raw, { cypher }),
+  })
+}
+
+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)
+  },
+} satisfies CommandDefinition

package/src/commands/setup.ts

@@ -0,0 +1,54 @@
+import type { CommandDefinition } from '../command'
+
+import { ADMIN_TARGET_OPTIONS } from '../lib/admin-target'
+import { fatal } from '../lib/log'
+import { RAW_OUTPUT_OPTIONS } from '../lib/output'
+import { runSetup, type SetupOpts } from '../setup/engine'
+
+export default {
+  name: 'setup',
+  description: 'Guided first run: sign in, pick an instance, and equip your workspace',
+  arguments: [
+    {
+      name: 'slug',
+      description: 'Instance slug to provision when none is active',
+      required: false,
+    },
+  ],
+  options: [
+    { flags: '--plan', description: 'Print what setup would do (read-only) and exit' },
+    ...ADMIN_TARGET_OPTIONS,
+    ...RAW_OUTPUT_OPTIONS,
+  ],
+  afterHelpText: `
+What it does:
+  Walks you from zero to a working instance, then offers to equip your agent:
+    1. Connect    sign in (WorkOS), confirm the admin control plane, pick or
+                  provision an instance — ending on your live instance URL.
+    2. Equip      the astrale agent skills (cli + domain), agent-browser, and a
+                  first domain (a pre-checked multi-select — toggle off any).
+
+  Idempotent: re-run it anytime; satisfied steps are skipped. Bare \`astrale\`
+  in a terminal launches this when you have no active instance yet.
+
+Agents / CI:
+  Piped, --ci, or --plan → read-only. \`astrale setup --plan --json\` prints each
+  step's state and the exact command to fix it; run those granular commands
+  (auth login / instance create / …) rather than the interactive wizard.
+
+Examples:
+  $ astrale setup                 # the guided flow
+  $ astrale setup my-app          # pre-fill the instance slug
+  $ astrale setup --plan          # what's left to do (no changes)
+  $ astrale setup --plan --json   # machine-readable plan for an agent
+`,
+  action: async (slug: string | undefined, opts: SetupOpts) => {
+    try {
+      await runSetup(opts, slug)
+    } catch (e) {
+      // fatal() exits 130 quietly on Ctrl-C (ExitPromptError); each step's
+      // writes are atomic + idempotent, so nothing half-applied matters.
+      fatal(e)
+    }
+  },
+} satisfies CommandDefinition