@astrale-os/cli 0.4.0-alpha.13

package/src/commands/browser.ts

@@ -0,0 +1,207 @@
+import chalk from 'chalk'
+import { existsSync } from 'node:fs'
+
+import type { CommandDefinition } from '../command'
+
+import {
+  ab,
+  AGENT_BROWSER_REPO,
+  type BrowserSession,
+  findAgentBrowser,
+  navigateAndCheck,
+  pollAuth,
+  profileDirFor,
+  saveSession,
+} from '../lib/browser'
+import { readLocalStatus } from '../lib/local-status'
+import { fatal, log } from '../lib/log'
+import { isMachine, output, RAW_OUTPUT_OPTIONS, type RawOutputOpts } from '../lib/output'
+
+type BrowserOpts = RawOutputOpts & {
+  url?: string
+  cdp?: string
+  profile?: string
+  login?: boolean
+  check?: boolean
+}
+
+const LOGIN_TIMEOUT_MS = 180_000
+const POLL_INTERVAL_MS = 2500
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/** Resolve the GUI origin for the active instance (or an explicit --url). */
+async function resolveGuiOrigin(explicit?: string): Promise<string> {
+  let target = explicit
+  if (!target) {
+    const status = await readLocalStatus()
+    target = status.instance?.url ?? undefined
+  }
+  if (!target) {
+    fatal(
+      new Error(
+        'No target instance. Set one with `astrale instance use <name>`, or pass `--url <gui-url>`.',
+      ),
+    )
+  }
+  try {
+    return new URL(target).origin
+  } catch {
+    return fatal(new Error(`Invalid instance URL: ${target}`))
+  }
+}
+
+function requireAgentBrowser(machine: boolean, opts: RawOutputOpts): Promise<string> {
+  return findAgentBrowser().then((bin) => {
+    if (bin) return bin
+    if (machine) {
+      output({ error: 'agent-browser-not-installed', repo: AGENT_BROWSER_REPO }, opts)
+    } else {
+      log.error('agent-browser is not installed — it is the engine `astrale browser` drives.')
+      log.dim('  Install it:')
+      log.dim('    npm install -g agent-browser && agent-browser install')
+      log.dim('  Recommended — also install its agent skill so your coding agent knows it:')
+      log.dim(`    npx skills add ${AGENT_BROWSER_REPO}`)
+    }
+    process.exit(1)
+  })
+}
+
+function reportConnected(session: BrowserSession, machine: boolean, opts: RawOutputOpts): void {
+  if (machine) {
+    output({ connected: true, ...session }, opts)
+    return
+  }
+  const drive = session.profile ? `--profile ${session.profile}` : `--cdp ${session.cdp}`
+  log.success(
+    `Connected to ${chalk.bold(session.url)}${session.email ? ` as ${session.email}` : ''}`,
+  )
+  log.dim(`  session saved → ~/.astrale/browser.json (reused automatically next time)`)
+  console.log('')
+  console.log(chalk.bold('Drive it:'))
+  console.log(`  agent-browser ${drive} snapshot`)
+  console.log(`  agent-browser ${drive} open ${session.url}`)
+  console.log(`  agent-browser ${drive} click @e3`)
+}
+
+export default {
+  name: 'browser',
+  description: 'Open a reusable, authenticated browser session your agent can drive',
+  options: [
+    { flags: '--url <url>', description: 'GUI URL to connect (default: active instance)' },
+    {
+      flags: '--cdp <endpoint>',
+      description: 'Attach to a running Chrome (port or ws URL) instead of a profile',
+    },
+    { flags: '--profile <dir>', description: 'Override the persistent profile directory' },
+    { flags: '--login', description: 'Force interactive sign-in even if a session exists' },
+    { flags: '--check', description: 'Report session status only; never open a window' },
+    ...RAW_OUTPUT_OPTIONS,
+  ],
+  afterHelpText: `
+What it does:
+  Wires your coding agent to the live Astrale GUI. It owns the *session* — pins a
+  persistent per-instance profile, runs the one-time WorkOS sign-in, and verifies
+  auth. Driving the page is agent-browser's job: once connected, your agent runs
+  \`agent-browser --profile <dir> snapshot|open|click|eval\` directly.
+
+  The GUI session is an httpOnly cookie with no token-injection path, so "use my
+  session" means driving a browser whose profile holds the cookie. You sign in
+  once; the profile keeps it and every later run is silent.
+
+Requires agent-browser (https://github.com/${AGENT_BROWSER_REPO}):
+  npm install -g agent-browser && agent-browser install
+  npx skills add ${AGENT_BROWSER_REPO}     # recommended: teaches the agent its commands
+
+Examples:
+  $ astrale browser                  # connect the active instance (sign in once)
+  $ astrale browser --check          # is the saved session still authenticated?
+  $ astrale browser --login          # force a fresh sign-in
+  $ astrale browser --cdp 9222       # attach to a Chrome you already have open
+`,
+  action: async (opts: BrowserOpts) => {
+    const machine = isMachine(opts)
+    const gui = await resolveGuiOrigin(opts.url)
+    const host = new URL(gui).host
+    await requireAgentBrowser(machine, opts)
+
+    const usingCdp = !!opts.cdp
+    const profile = usingCdp ? null : (opts.profile ?? profileDirFor(host))
+    const target = usingCdp ? { cdp: opts.cdp } : { profile: profile! }
+
+    const persist = async (state: { email?: string }): Promise<BrowserSession> => {
+      const session: BrowserSession = {
+        url: gui,
+        host,
+        profile,
+        cdp: opts.cdp ?? null,
+        email: state.email,
+        updatedAt: new Date().toISOString(),
+      }
+      await saveSession(session)
+      return session
+    }
+
+    // Attach mode: the external Chrome is the user's — never drive its login.
+    if (usingCdp) {
+      const state = await navigateAndCheck(gui, target)
+      if (!state.authed) {
+        if (machine) output({ connected: false, url: gui, host, cdp: opts.cdp }, opts)
+        else {
+          log.warn(`Attached to Chrome on ${opts.cdp}, but not signed in to ${gui}.`)
+          log.dim('  Sign in in that browser window, then re-run `astrale browser --cdp ...`.')
+        }
+        process.exit(1)
+      }
+      reportConnected(await persist(state), machine, opts)
+      return
+    }
+
+    // Profile mode: silent (headless) reuse check when the profile may already
+    // hold a cookie. Skip for a brand-new profile — nothing to reuse, and it
+    // avoids a throwaway headless navigation before the sign-in window opens.
+    if (!opts.login && profile && existsSync(profile)) {
+      const reused = await navigateAndCheck(gui, target)
+      if (reused.authed) {
+        reportConnected(await persist(reused), machine, opts)
+        return
+      }
+    }
+
+    // Not authenticated. In check/machine mode we never pop a window.
+    if (opts.check || machine) {
+      if (machine) output({ connected: false, url: gui, host, profile }, opts)
+      else {
+        log.warn(`No authenticated session for ${gui}.`)
+        log.dim('  Run `astrale browser` (without --check) to sign in.')
+      }
+      process.exit(1)
+    }
+
+    // Interactive sign-in: open a HEADED window and poll until the router sets
+    // the cookie. Every command on this browser must carry `headed:true` —
+    // agent-browser defaults to headless, and an unflagged command flips the
+    // live window back to headless (closing it mid-login). Proven: a poll
+    // `eval` without --headed turns HEADED → HEADLESS on the next call.
+    const headedTarget = { ...target, headed: true }
+    log.step(`Opening ${chalk.bold(gui)} — sign in with your Astrale account in the window…`)
+    await ab(['close'], target) // release any stale browser on this profile
+    await ab(['open', gui], headedTarget)
+
+    const deadline = Date.now() + LOGIN_TIMEOUT_MS
+    let state = { authed: false } as { authed: boolean; email?: string }
+    while (Date.now() < deadline) {
+      await sleep(POLL_INTERVAL_MS)
+      state = await pollAuth(headedTarget)
+      if (state.authed) break
+    }
+    if (!state.authed) {
+      fatal(
+        new Error(
+          `Sign-in not detected within ${LOGIN_TIMEOUT_MS / 1000}s. Re-run \`astrale browser\`.`,
+        ),
+      )
+    }
+    reportConnected(await persist(state), machine, opts)
+  },
+} satisfies CommandDefinition

package/src/commands/call.ts

@@ -0,0 +1,300 @@
+import { K } from '@astrale-os/kernel-core'
+
+import type { CommandDefinition } from '../command'
+import type { CallCommandOpts, ClientContext, SelfExpansionMeta } from '../kernel'
+
+import { buildSelfContext, resolveSelfIdLazy, runKernelCommand, withSelfHint } from '../kernel'
+import { presentBinary, type BinaryLike } from '../lib/binary'
+import { log } from '../lib/log'
+import { output, present } from '../lib/output'
+import { containsSelfRef, expandSelfReferences } from '../lib/self'
+
+type CallOpts = CallCommandOpts & { describe?: boolean; dryRun?: boolean; output?: string }
+
+/** A call resolves to either a JSON value or a binary response. */
+type CallResult = { kind: 'binary'; response: BinaryLike } | { kind: 'value'; value: unknown }
+
+export async function callCommand(
+  path: string,
+  rawParams: string[],
+  opts: CallOpts,
+): Promise<void> {
+  // ── Expand `@self` in path + raw param strings ──────────
+  // Local resolution, with ONE lazy whoami round-trip for IdP identities
+  // missing a cached registration (persisted, so it's local afterwards).
+  // Throws a typed SelfRefusalError (manager, instance-signed, …) which we
+  // surface as a fatal CLI error. Runs BEFORE `--describe` so users get the
+  // typed refusal instead of a generic NotFoundError from the kernel.
+  let expandedPath = path
+  let expandedRaw = rawParams
+  let selfMeta: SelfExpansionMeta | undefined
+  const inputsHaveSelf = containsSelfRef(path) || rawParams.some(containsSelfRef)
+  if (inputsHaveSelf) {
+    try {
+      const selfCtx = await buildSelfContext(opts)
+      const selfId = await resolveSelfIdLazy(selfCtx, opts)
+      expandedPath = expandSelfReferences(path, selfId)
+      expandedRaw = rawParams.map((p) => expandSelfReferences(p, selfId))
+      // Stamp metadata whenever ANY input mutated — the stale-registration
+      // hint in `formatKernelError` is just as useful when `@self` lived in
+      // a param (`node=@self`) as when it was in the path head.
+      const rawMutated = expandedRaw.some((p, i) => p !== rawParams[i])
+      if (expandedPath !== path || rawMutated) {
+        selfMeta = {
+          original: path,
+          expanded: expandedPath,
+          selfId,
+          identity: selfCtx.identity?.name,
+          slug: selfCtx.instanceSlug,
+        }
+      }
+    } catch (e) {
+      log.error(e instanceof Error ? e.message : 'Invalid @self expansion')
+      process.exit(1)
+    }
+  }
+
+  // ── Describe mode: show schema without executing ────────
+  // Runs AFTER expansion so `astrale call @self::m --describe` works.
+  if (opts.describe) {
+    return describeOperation(expandedPath, opts)
+  }
+
+  // ── Parse params ────────────────────────────────────────
+  let params: Record<string, unknown>
+  try {
+    params = await parseParams(expandedRaw, opts.data)
+  } catch (e) {
+    log.error(e instanceof Error ? e.message : 'Invalid params')
+    process.exit(1)
+  }
+
+  // ── Dry-run: show what would be sent ─────────────────────
+  if (opts.dryRun) {
+    output({ method: expandedPath, params }, opts)
+    return
+  }
+
+  // ── Execute ────────────────────────────────────────────
+  await runKernelCommand<CallResult>({
+    opts,
+    label: expandedPath,
+    fn: async (ctx): Promise<CallResult> => {
+      // Remote-bound functions live on an external worker. The kernel resolves
+      // the call to a redirect carrying the worker's URL + `iss`; the session
+      // follows it, minting a worker-scoped delegation for that `iss` (the
+      // delegation cache wired in `client.ts`). No client-side binding lookup.
+      //
+      // The one thing the reactive path can't discover after dispatch is a
+      // binary output mode (a JSON decode would corrupt the bytes), so detect
+      // it up front and route to the binary transport — which also auto-follows.
+      if (await isBinaryOutput(ctx, expandedPath)) {
+        const response = await withSelfHint(() => ctx.client.binary(expandedPath, params), selfMeta)
+        return { kind: 'binary', response }
+      }
+      const value = await withSelfHint(() => ctx.client.call(expandedPath, params), selfMeta)
+      return { kind: 'value', value }
+    },
+    format: async (result, fmtOpts) => {
+      if (result.kind === 'binary') {
+        await presentBinary(result.response, fmtOpts, { outFile: opts.output })
+        return
+      }
+      present(result.value, fmtOpts)
+    },
+  })
+}
+
+/**
+ * Best-effort pre-flight: does the target Function declare a binary output?
+ * A binary method must use the binary transport (the value path would JSON-
+ * decode and corrupt the bytes), and the client can't discover that after
+ * dispatch. For a static path the path IS the Function node — read `output`
+ * off it via `::get`. For an instance-method path (`<node>::method`) the
+ * Function node isn't addressable that way: resolve the instance's class
+ * first, then probe the class's method node (`<classPath>:method`). An
+ * interface-hosted instance method still escapes the probe (its Function node
+ * hangs off the interface, not the class) — that and any other failure returns
+ * false and falls through to the value path, letting the kernel surface the
+ * real error. `::get` is a kernel syscall (same origin) so it neither
+ * redirects nor triggers delegation.
+ */
+async function isBinaryOutput(ctx: ClientContext, path: string): Promise<boolean> {
+  try {
+    const target = path.includes('::') ? await instanceMethodNodePath(ctx, path) : path
+    if (!target) return false
+    const node = (await ctx.client.call(`${target}::get`, {})) as {
+      props?: Record<string, unknown>
+    } | null
+    return node?.props?.[K.$.i('Function').output.key] === 'binary'
+  } catch {
+    return false
+  }
+}
+
+/** `<node>::method` → the method's Function-node MethodPath, via the node's class. */
+async function instanceMethodNodePath(
+  ctx: ClientContext,
+  path: string,
+): Promise<string | undefined> {
+  const sep = path.lastIndexOf('::')
+  const source = path.slice(0, sep)
+  const method = path.slice(sep + 2)
+  if (!source || !method) return undefined
+  const node = (await ctx.client.call(`${source}::get`, {})) as { class?: string } | null
+  // node.class is a ClassPath (`/:domain:class.Name`); appending `:<method>`
+  // forms the MethodPath of the class-owned Function node.
+  return node?.class ? `${node.class}:${method}` : undefined
+}
+
+async function describeOperation(path: string, opts: CallOpts): Promise<void> {
+  await runKernelCommand<Record<string, unknown>>({
+    opts,
+    label: `Schema for ${path}`,
+    fn: (ctx) => ctx.client.call(`${path}::get`, {}) as Promise<Record<string, unknown>>,
+    format: (node, fmtOpts) => {
+      const props = (node.properties ?? node) as Record<string, unknown>
+      const schema: Record<string, unknown> = {}
+      if (props.inputSchema) schema.input = tryParseJson(props.inputSchema)
+      if (props.outputSchema) schema.output = tryParseJson(props.outputSchema)
+      output(Object.keys(schema).length > 0 ? schema : node, fmtOpts)
+    },
+  })
+}
+
+function tryParseJson(value: unknown): unknown {
+  if (typeof value !== 'string') return value
+  try {
+    return JSON.parse(value)
+  } catch {
+    return value
+  }
+}
+
+// ── Param parsing ───────────────────────────────────────────
+
+export async function parseParams(
+  rawParams: string[],
+  dataFlag?: string,
+): Promise<Record<string, unknown>> {
+  if (dataFlag) {
+    if (rawParams.length > 0) {
+      log.warn('--data provided, ignoring key=value params')
+    }
+    try {
+      return JSON.parse(dataFlag)
+    } catch {
+      throw new Error(`Invalid JSON in --data: ${dataFlag}`)
+    }
+  }
+
+  const stdin = await readStdin()
+  if (stdin) {
+    try {
+      return JSON.parse(stdin)
+    } catch {
+      throw new Error('Invalid JSON from stdin')
+    }
+  }
+
+  if (rawParams.length > 0) {
+    return parseKeyValue(rawParams)
+  }
+
+  return {}
+}
+
+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)
+  }
+  const text = Buffer.concat(chunks).toString('utf-8').trim()
+  return text || null
+}
+
+// Top-level param keys are identifier-shaped: letters, digits, underscore,
+// hyphen. No `:` (would catch httpie's `key:=value` syntax — not supported,
+// use `--data '{...}'` instead) and no `.` (qualified prop keys appear
+// inside nested objects, never as top-level CLI params).
+const PARAM_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/
+
+export function parseKeyValue(pairs: string[]): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  for (const pair of pairs) {
+    const eqIdx = pair.indexOf('=')
+    if (eqIdx === -1) {
+      throw new Error(`Invalid param "${pair}" — expected key=value format`)
+    }
+    const key = pair.slice(0, eqIdx)
+    const raw = pair.slice(eqIdx + 1)
+    if (!PARAM_KEY_RE.test(key)) {
+      const hint = key.endsWith(':')
+        ? ` (looks like httpie's "key:=value" syntax — Astrale CLI doesn't support it; use --data '{"${key.slice(0, -1)}":<value>}' for nested values)`
+        : ` (keys must be identifier-shaped: letters, digits, underscore, hyphen)`
+      throw new Error(`Invalid param key "${key}" in "${pair}"${hint}`)
+    }
+    result[key] = coerceValue(raw)
+  }
+  return result
+}
+
+export function coerceValue(raw: string): unknown {
+  if ((raw.startsWith('{') && raw.endsWith('}')) || (raw.startsWith('[') && raw.endsWith(']'))) {
+    try {
+      return JSON.parse(raw)
+    } catch {
+      /* fall through */
+    }
+  }
+  if (raw === 'true') return true
+  if (raw === 'false') return false
+  if (raw === 'null') return null
+  if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw)
+  return raw
+}
+
+export default {
+  name: 'call',
+  description: 'Call a kernel operation',
+  afterHelpText: `
+Behavior:
+  Param priority (highest wins): --data > stdin > key=value > {}. If
+  both --data and key=value are given, key=value is ignored (warned).
+  Stdin is read only when piped (ignored on a TTY). --describe and
+  --dry-run short-circuit (no execution). Remote-bound functions
+  auto-mint a worker-scoped credential; --creds overrides it.
+
+Self-reference:
+  @self expands to your nodeId on the active instance (path head or
+  bare param value, e.g. node=@self). --data and stdin payloads are
+  sent verbatim — pre-resolve manually to a literal @<nodeId> there
+  (e.g. via 'astrale describe @self -q', or shell-substituted from the
+  registration record in ~/.astrale/identities.json).
+
+Examples:
+  $ astrale call /:host.astrale.ai:class.KernelInstance:list
+  $ astrale call /:blog.acme.com:class.Author:list limit=10
+  $ astrale call '@self::deactivate'
+  $ astrale call /:dist.astrale.ai:class.Domain:install --creds "$TOKEN" \\
+      -d "$(cat spec.json)"
+`,
+  arguments: [
+    {
+      name: 'path',
+      description:
+        'Operation path (e.g., /:host.astrale.ai:class.KernelInstance:list or /node::method)',
+    },
+    { name: 'params...', description: 'Params as key=value pairs', required: false },
+  ],
+  options: [
+    { flags: '-d, --data <json>', description: 'Params as JSON string' },
+    { flags: '-o, --output <file>', description: 'Write binary/raw output to a file' },
+    { flags: '--describe', description: 'Show operation schema without executing' },
+    { flags: '--dry-run', description: 'Show what would be sent without executing' },
+  ],
+  action: async (path, params, opts) => {
+    await callCommand(path as string, params as string[], opts)
+  },
+} satisfies CommandDefinition

package/src/commands/describe.ts

@@ -0,0 +1,182 @@
+import { ClassPath } from '@astrale-os/kernel-core/domain'
+import chalk from 'chalk'
+
+import type { CommandDefinition } from '../command'
+import type { KernelCommandOpts } from '../kernel'
+
+import { expandSelfInPath, extractItems, runKernelCommand, withSelfHint } from '../kernel'
+import { log } from '../lib/log'
+import { output } from '../lib/output'
+
+type NodeItem = {
+  id?: string
+  slug?: string
+  class?: string
+  properties?: Record<string, unknown>
+}
+
+type DescribeResult = { node: NodeItem; children: NodeItem[] }
+
+// Commander turns `--no-schema` into `schema: false`.
+type DescribeOpts = KernelCommandOpts & { schema?: boolean }
+
+export async function describeCommand(path: string, opts: DescribeOpts): Promise<void> {
+  let expandedPath: string
+  let meta
+  try {
+    ;({ path: expandedPath, meta } = await expandSelfInPath(path, opts))
+  } catch (e) {
+    log.error(e instanceof Error ? e.message : 'Invalid @self expansion')
+    process.exit(1)
+  }
+  await runKernelCommand<DescribeResult>({
+    opts,
+    label: expandedPath,
+    fn: async (ctx) => {
+      const node = (await withSelfHint(
+        () => ctx.client.call(`${expandedPath}::get`, {}),
+        meta,
+      )) as NodeItem
+
+      let children: NodeItem[] = []
+      try {
+        const result = await withSelfHint(
+          () => ctx.client.call(`${expandedPath}::listChildren`, {}),
+          meta,
+        )
+        children = extractItems<NodeItem>(result)
+      } catch {
+        // Node may have no children (leaf node)
+      }
+
+      return { node, children }
+    },
+    format: (result, fmtOpts, isRaw) => {
+      const shown = opts.schema === false ? stripSchemaProp(result) : result
+      if (isRaw) {
+        output(shown, fmtOpts)
+        return
+      }
+      printDescribe(shown, expandedPath)
+    },
+  })
+}
+
+function stripSchemaProp(result: DescribeResult): DescribeResult {
+  const props = result.node.properties
+  if (!props || !('schema' in props)) return result
+  const { schema: _omitted, ...rest } = props
+  return { ...result, node: { ...result.node, properties: rest } }
+}
+
+// ── Pretty-print ────────────────────────────────────────────
+
+function printDescribe({ node, children }: DescribeResult, path: string): void {
+  const kind = classNameOf(node) ?? 'Node'
+  const slug = node.properties?.slug ?? node.slug ?? path.split('/').pop()
+  console.log(`  ${chalk.bold.cyan(String(slug))} ${chalk.dim(`(${kind})`)}`)
+
+  if (node.properties?.description) {
+    console.log(`  ${chalk.dim(String(node.properties.description))}`)
+  }
+  console.log('')
+
+  const operations = children.filter(isFunction)
+  const otherChildren = children.filter((c) => !isFunction(c))
+
+  if (operations.length > 0) {
+    console.log(`  ${chalk.bold('Operations:')}`)
+    const slugW = Math.max(4, ...operations.map((o) => (o.slug ?? '').length))
+    for (const op of operations) {
+      const opSlug = (op.slug ?? '?').padEnd(slugW)
+      const schema = formatInputSchema(op.properties)
+      console.log(`    ${chalk.green(opSlug)}  ${chalk.dim(schema)}`)
+    }
+    console.log('')
+  }
+
+  if (otherChildren.length > 0) {
+    console.log(`  ${chalk.bold('Children:')}`)
+    for (const child of otherChildren) {
+      const childKind = classNameOf(child) ?? '?'
+      console.log(`    ${chalk.cyan(child.slug ?? '?')}  ${chalk.dim(childKind)}`)
+    }
+    console.log('')
+  }
+
+  if (children.length === 0) {
+    printProperties(node)
+  }
+}
+
+/** Short class name from the contract field `class` (a serialized ClassPath). */
+function classNameOf(item: NodeItem): string | undefined {
+  return item.class ? (ClassPath.tryParse(item.class)?.className ?? undefined) : undefined
+}
+
+function isFunction(item: NodeItem): boolean {
+  return classNameOf(item) === 'Function'
+}
+
+function printProperties(node: NodeItem): void {
+  const props = node.properties ?? (node as Record<string, unknown>)
+  const entries = Object.entries(props).filter(([k]) => k !== '__labels' && k !== 'id')
+  if (entries.length === 0) return
+
+  console.log(`  ${chalk.bold('Properties:')}`)
+  for (const [k, v] of entries) {
+    const val = typeof v === 'string' && v.length > 80 ? v.slice(0, 80) + '...' : String(v)
+    console.log(`    ${chalk.cyan(k)}: ${chalk.dim(val)}`)
+  }
+}
+
+function formatInputSchema(properties?: Record<string, unknown>): string {
+  if (!properties) return '{}'
+  const raw = properties.inputSchema
+  if (!raw) return '{}'
+
+  try {
+    const schema = typeof raw === 'string' ? JSON.parse(raw) : raw
+    if (typeof schema !== 'object' || schema === null) return '{}'
+
+    const props = (schema as { properties?: Record<string, { type?: string }> }).properties
+    if (!props || Object.keys(props).length === 0) return '{}'
+
+    const required = new Set((schema as { required?: string[] }).required ?? [])
+
+    const fields = Object.entries(props).map(([name, def]) => {
+      const type = def?.type ?? '?'
+      return required.has(name) ? `${name}: ${type}` : `${name}?: ${type}`
+    })
+
+    return `{ ${fields.join(', ')} }`
+  } catch {
+    return '{...}'
+  }
+}
+
+export default {
+  name: 'describe',
+  description: 'Describe a node: its kind, operations, children, and schemas',
+  afterHelpText: `
+Behavior:
+  Raw node dump: full properties + children. For Domain nodes this
+  includes a multi-kB serialized 'schema' — use --no-schema, and pipe
+  to jq rather than reading by eye (it is not a curated summary).
+
+Examples:
+  $ astrale describe /kernel.astrale.ai
+  $ astrale describe /host.astrale.ai --no-schema | jq .
+`,
+  arguments: [{ name: 'path', description: 'Node path (/domain/Class) or ID (@nodeId)' }],
+  options: [
+    {
+      flags: '--no-schema',
+      description:
+        'Omit the serialized `schema` property (useful for Domain nodes, where it is multi-kB)',
+    },
+  ],
+  action: async (path, opts) => {
+    await describeCommand(path as string, opts as Parameters<typeof describeCommand>[1])
+  },
+} satisfies CommandDefinition