@astrale-os/cli 0.4.0-alpha.13

package/src/program.ts

@@ -0,0 +1,200 @@
+import { Command, Option } from 'commander'
+
+import type { CommandDefinition } from './command'
+
+import pkg from '../package.json' with { type: 'json' }
+import { KERNEL_PASSTHROUGH_OPTIONS } from './kernel/options'
+import { RAW_OUTPUT_OPTIONS } from './lib/output'
+import { registerCommand, registerGroup } from './registry'
+
+/**
+ * Build the fully-wired Commander program (every command + group registered)
+ * WITHOUT parsing argv. `bin/astrale.ts` is a thin shim that calls this and
+ * `.parse()`; tests import it to walk the command tree (the `--help` surface
+ * is asserted to be the source of truth it claims to be — see
+ * `commands/__tests__/help-contract.test.ts`).
+ */
+export async function buildProgram(): Promise<Command> {
+  const program = new Command()
+
+  program
+    .name('astrale')
+    .description('Astrale CLI — connect to existing Astrale kernels')
+    // Single source of truth = package.json (bumped by release-please together
+    // with .release-please-manifest.json). Never hand-write a version literal.
+    .version(pkg.version)
+    .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.
+      if (process.stdin.isTTY && process.stdout.isTTY) {
+        const { shouldAutostartSetup } = await import('./setup/engine')
+        if (await shouldAutostartSetup()) {
+          await (await import('./commands/setup')).default.action(undefined, {})
+          return
+        }
+      }
+      program.help()
+    })
+
+  // Options shared by every kernel-touching command (call / token / get / ls /
+  // describe / query + `domain install`). Merged onto the command's own
+  // options at the registration site so the list stays single-sourced — the
+  // command-definition files only carry their command-specific options.
+  const kernelOptions = [
+    {
+      flags: '--format <type>',
+      description: 'Output format (default: yaml in TTY, json when piped)',
+      choices: ['yaml', 'json'],
+    },
+    ...RAW_OUTPUT_OPTIONS,
+    ...KERNEL_PASSTHROUGH_OPTIONS,
+  ]
+
+  const withKernelOptions = (def: CommandDefinition): CommandDefinition => ({
+    ...def,
+    options: [...(def.options ?? []), ...kernelOptions],
+  })
+
+  // Verbatim alias of `identity whoami` — defer to the command-definition
+  // module so options stay in sync.
+  const whoamiMod = await import('./commands/identity/whoami')
+  registerCommand(program, {
+    name: 'whoami',
+    description: 'Show the current default identity (alias for identity whoami)',
+    options: whoamiMod.default.options,
+    action: whoamiMod.default.action,
+  })
+  registerCommand(program, (await import('./commands/setup')).default)
+  registerCommand(program, (await import('./commands/use')).default)
+  registerCommand(program, (await import('./commands/update')).default)
+
+  // ── Graph / kernel ─────────────────────────────────────────────
+  registerCommand(program, withKernelOptions((await import('./commands/call')).default))
+  registerCommand(program, withKernelOptions((await import('./commands/token')).default))
+  registerCommand(program, withKernelOptions((await import('./commands/get')).default))
+  registerCommand(program, withKernelOptions((await import('./commands/ls')).default))
+  registerCommand(program, withKernelOptions((await import('./commands/describe')).default))
+  registerCommand(program, withKernelOptions((await import('./commands/query')).default))
+  registerCommand(program, withKernelOptions((await import('./commands/logs')).default))
+  registerCommand(program, (await import('./commands/status')).default)
+  registerCommand(program, (await import('./commands/browser')).default)
+  registerCommand(program, (await import('./commands/studio')).default)
+
+  registerGroup(program, {
+    name: 'instance',
+    description: 'Manage admin-provisioned instances and local bookmarks',
+    commands: [
+      withKernelOptions((await import('./commands/instance/list')).default),
+      (await import('./commands/instance/bookmark')).default,
+      (await import('./commands/instance/forget')).default,
+      withKernelOptions((await import('./commands/instance/create')).default),
+      withKernelOptions((await import('./commands/instance/delete')).default),
+      withKernelOptions((await import('./commands/instance/status')).default),
+      (await import('./commands/instance/active')).default,
+      (await import('./commands/instance/use')).default,
+    ],
+  })
+
+  registerGroup(program, {
+    name: 'domain',
+    description: 'List, publish, and install domains (admin catalog + per-instance install)',
+    commands: [
+      withKernelOptions((await import('./commands/domain/list')).default),
+      withKernelOptions((await import('./commands/domain/publish')).default),
+      withKernelOptions((await import('./commands/domain/install')).default),
+    ],
+  })
+
+  registerGroup(program, {
+    name: 'admin',
+    description: 'Configure the admin kernel',
+    commands: [
+      (await import('./commands/admin/status')).default,
+      (await import('./commands/admin/use')).default,
+    ],
+  })
+
+  registerGroup(program, {
+    name: 'identity',
+    description: 'Manage CLI identities & delegation keypairs',
+    commands: [
+      (await import('./commands/identity/create')).default,
+      (await import('./commands/identity/register')).default,
+      (await import('./commands/identity/list')).default,
+      (await import('./commands/identity/use')).default,
+      (await import('./commands/identity/whoami')).default,
+      (await import('./commands/identity/delete')).default,
+      (await import('./commands/identity/sync')).default,
+      (await import('./commands/identity/unsync')).default,
+      (await import('./commands/identity/export')).default,
+      (await import('./commands/identity/import')).default,
+    ],
+  })
+
+  registerGroup(program, {
+    name: 'auth',
+    description: 'Authenticate with configured identity providers',
+    commands: [
+      (await import('./commands/auth/login')).default,
+      (await import('./commands/auth/token')).default,
+      (await import('./commands/auth/logout')).default,
+      (await import('./commands/auth/status')).default,
+    ],
+  })
+
+  registerGroup(program, {
+    name: 'idp',
+    description: 'Manage OpenID Connect identity providers',
+    commands: [
+      (await import('./commands/idp/add')).default,
+      (await import('./commands/idp/list')).default,
+      (await import('./commands/idp/show')).default,
+      (await import('./commands/idp/refresh')).default,
+      (await import('./commands/idp/remove')).default,
+    ],
+  })
+
+  program.addHelpText(
+    'after',
+    `
+Command groups:
+  Getting started  setup     (sign in, pick an instance, equip your workspace)
+  Kernel        ls, get, call, query, describe, 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)
+
+Path syntax:
+  /domain                        Domain node
+  /domain/class.Name             Class node     (or /domain/interface.Name)
+  /domain/class.Name/method      Static method  — single slash
+                                 (interface-hosted static: /domain/interface.Name/method)
+  <nodePath>::method             Instance method dispatch — double colon ::
+  @nodeId                        Reference a node by its UID
+  @nodeId::method                Instance method on a node by UID
+
+Examples:
+  $ astrale ls /
+  $ astrale studio
+  $ astrale admin status
+  $ astrale update --check
+  $ astrale instance bookmark staging --url https://kernel.example.com
+  $ astrale instance create my-app
+  $ astrale instance status staging
+  $ astrale token --audience dist.astrale.ai --ttl 3600
+  $ astrale query 'MATCH (n) RETURN n LIMIT 5'
+`,
+  )
+
+  return program
+}

package/src/registry.ts

@@ -0,0 +1,59 @@
+import { type Command, Option } from 'commander'
+
+import type { CommandDefinition, CommandGroup } from './command'
+
+/**
+ * Register a single command on a Commander program or subcommand.
+ */
+export function registerCommand(parent: Command, def: CommandDefinition): void {
+  const cmd = parent.command(def.name).description(def.description)
+
+  if (def.summary) cmd.summary(def.summary)
+
+  if (def.aliases) {
+    for (const alias of def.aliases) cmd.alias(alias)
+  }
+
+  if (def.arguments) {
+    for (const arg of def.arguments) {
+      const bracket = arg.required !== false ? `<${arg.name}>` : `[${arg.name}]`
+      cmd.argument(bracket, arg.description)
+    }
+  }
+
+  if (def.options) {
+    for (const opt of def.options) {
+      if (opt.choices) {
+        const o = new Option(opt.flags, opt.description)
+        o.choices(opt.choices)
+        if (opt.default !== undefined) o.default(opt.default)
+        cmd.addOption(o)
+      } else if (opt.default !== undefined) {
+        cmd.option(opt.flags, opt.description, opt.default)
+      } else {
+        cmd.option(opt.flags, opt.description)
+      }
+    }
+  }
+
+  cmd.action(def.action)
+
+  if (def.afterHelpText) cmd.addHelpText('after', def.afterHelpText)
+}
+
+/**
+ * Register a command group (subcommand with nested commands). Supports
+ * one level of nested subgroups via `group.subgroups`.
+ */
+export function registerGroup(parent: Command, group: CommandGroup): void {
+  const sub = parent.command(group.name).description(group.description)
+  if (group.summary) sub.summary(group.summary)
+  for (const def of group.commands) {
+    registerCommand(sub, def)
+  }
+  if (group.subgroups) {
+    for (const nested of group.subgroups) {
+      registerGroup(sub, nested)
+    }
+  }
+}

package/src/setup/__tests__/util.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from 'bun:test'
+
+import { guiOrigin, slugError, urlError } from '../util'
+
+describe('guiOrigin — the clickable instance URL', () => {
+  test('strips the /api path bookmarks carry', () => {
+    expect(guiOrigin('https://my-app.eu.astrale.ai/api')).toBe('https://my-app.eu.astrale.ai')
+  })
+
+  test('leaves a bare origin untouched', () => {
+    expect(guiOrigin('https://my-app.eu.astrale.ai')).toBe('https://my-app.eu.astrale.ai')
+  })
+
+  test('returns the input verbatim when it is not a URL', () => {
+    expect(guiOrigin('not a url')).toBe('not a url')
+  })
+})
+
+describe('inquirer validators', () => {
+  test('slugError accepts a DNS-label slug and rejects junk', () => {
+    expect(slugError('my-app')).toBe(true)
+    expect(typeof slugError('Not A Slug')).toBe('string')
+  })
+
+  test('urlError accepts http(s) and rejects junk', () => {
+    expect(urlError('https://admin.eu.astrale.ai/api')).toBe(true)
+    expect(typeof urlError('ftp://nope')).toBe('string')
+  })
+})

package/src/setup/engine.ts

@@ -0,0 +1,83 @@
+import chalk from 'chalk'
+
+import type { SetupContext, SetupOpts } from './types'
+
+import { readLocalStatus } from '../lib/local-status'
+import { isMachine } from '../lib/output'
+import { promptMultiSelect } from '../lib/prompt'
+import { type Detected, phaseHeader, renderFinale, renderIntro, renderPlan } from './render'
+import { ALL_STEPS, CONNECT_STEPS, EQUIP_STEPS } from './steps'
+
+export type { SetupOpts } from './types'
+
+/**
+ * Run the setup reconciler. Two modes, one set of steps:
+ *  - interactive (TTY): hand-hold each Connect step, then offer the unsatisfied
+ *    Equip steps as a pre-checked multi-select.
+ *  - --plan / non-interactive: detect everything and report (machine JSON or a
+ *    human checklist), mutating nothing. This is the agent-facing contract.
+ */
+export async function runSetup(opts: SetupOpts, slug?: string): Promise<void> {
+  const machine = isMachine(opts)
+  const interactive = !!process.stdin.isTTY && !(opts.ci || opts.noPrompt || process.env.CI)
+  const ctx: SetupContext = { interactive, machine, opts, slug }
+
+  if (opts.plan || !interactive) {
+    renderPlan(await detectAll(ctx), ctx)
+    return
+  }
+
+  renderIntro()
+
+  // Connect: required prerequisites, walked in order. Each ensure() re-detects
+  // and is a no-op (a ✔ line) when already satisfied, so this resumes cleanly.
+  phaseHeader(1, 'Connect to Astrale')
+  for (const step of CONNECT_STEPS) {
+    await step.ensure(ctx)
+  }
+
+  // Equip: optional. Offer only the unsatisfied ones, pre-checked.
+  const equipGaps: Detected[] = []
+  for (const step of EQUIP_STEPS) {
+    const detection = await step.detect(ctx)
+    if (detection.state !== 'satisfied') equipGaps.push({ step, detection })
+  }
+  if (equipGaps.length > 0) {
+    phaseHeader(2, 'Equip your workspace & agents')
+    const chosen =
+      (await promptMultiSelect(
+        'Select what to set up — space toggles, enter confirms:',
+        equipGaps.map(({ step, detection }) => ({
+          name: `${step.title} ${chalk.dim(`— ${detection.summary}`)}`,
+          value: step.id,
+          checked: true,
+        })),
+      )) ?? []
+    for (const { step } of equipGaps) {
+      if (chosen.includes(step.id)) await step.ensure(ctx)
+    }
+  }
+
+  await renderFinale()
+}
+
+async function detectAll(ctx: SetupContext): Promise<Detected[]> {
+  const detected: Detected[] = []
+  for (const step of ALL_STEPS) {
+    detected.push({ step, detection: await step.detect(ctx) })
+  }
+  return detected
+}
+
+/**
+ * Should a bare `astrale` (no args, interactive terminal) launch setup instead
+ * of printing help? Yes only when the user has no active instance — i.e. not
+ * yet set up. A configured user gets help.
+ */
+export async function shouldAutostartSetup(): Promise<boolean> {
+  try {
+    return (await readLocalStatus()).instance === null
+  } catch {
+    return false
+  }
+}

package/src/setup/render.ts

@@ -0,0 +1,109 @@
+import chalk from 'chalk'
+
+import type { SetupContext, SetupStep, StepDetection, StepState } from './types'
+
+import { readLocalStatus } from '../lib/local-status'
+import { output } from '../lib/output'
+import { panel } from '../lib/panel'
+import { guiOrigin } from './util'
+
+export type Detected = { step: SetupStep; detection: StepDetection }
+
+const MARK: Record<StepState, () => string> = {
+  satisfied: () => chalk.green('✔'),
+  gap: () => chalk.yellow('○'),
+  broken: () => chalk.red('✖'),
+}
+
+export function renderIntro(): void {
+  console.log('')
+  console.log(`${chalk.bold.cyan('astrale setup')} ${chalk.dim('· get connected and equipped')}`)
+}
+
+export function phaseHeader(n: number, title: string): void {
+  console.log('')
+  console.log(chalk.bold(`${n} · ${title}`))
+}
+
+/**
+ * The read-only report for `--plan` and non-interactive runs: machine-readable
+ * JSON (the agent's contract — each gap carries the command to fix it) or a
+ * human checklist mirroring `astrale status`.
+ */
+export function renderPlan(detected: Detected[], ctx: SetupContext): void {
+  const connected = detected
+    .filter((d) => d.step.group === 'connect')
+    .every((d) => d.detection.state === 'satisfied')
+
+  if (ctx.machine) {
+    output(
+      {
+        connected,
+        steps: detected.map(({ step, detection }) => ({
+          id: step.id,
+          title: step.title,
+          group: step.group,
+          state: detection.state,
+          summary: detection.summary,
+          ...(detection.fixHint ? { fix: detection.fixHint } : {}),
+        })),
+      },
+      ctx.opts,
+    )
+    return
+  }
+
+  console.log('')
+  console.log(chalk.bold('Astrale setup — status'))
+  for (const group of ['connect', 'equip'] as const) {
+    const rows = detected.filter((d) => d.step.group === group)
+    if (rows.length === 0) continue
+    console.log('')
+    console.log(chalk.bold(group === 'connect' ? 'Connect' : 'Equip'))
+    for (const { detection } of rows) {
+      const hint =
+        detection.state === 'satisfied' || !detection.fixHint
+          ? ''
+          : `  ${chalk.dim(`→ ${detection.fixHint}`)}`
+      console.log(`  ${MARK[detection.state]()} ${detection.summary}${hint}`)
+    }
+  }
+  console.log('')
+  console.log(
+    chalk.dim(
+      connected
+        ? 'Connected. Run `astrale setup` to equip your workspace.'
+        : 'Run `astrale setup` in a terminal to fix these interactively.',
+    ),
+  )
+}
+
+/** Closing recap: the active-instance hero (again) plus the obvious next moves. */
+export async function renderFinale(): Promise<void> {
+  const { instance } = await readLocalStatus()
+  console.log('')
+  if (instance) {
+    console.log(
+      panel(
+        [
+          `${chalk.green('✔')}  ${chalk.bold("You're all set")}`,
+          '',
+          `   ${chalk.cyan('Instance')}  ${chalk.bold(guiOrigin(instance.url))}`,
+        ],
+        { borderColor: chalk.green },
+      ),
+    )
+  } else {
+    console.log(
+      chalk.yellow('⚠'),
+      'Setup finished without an active instance — run `astrale setup` again when ready.',
+    )
+  }
+  console.log('')
+  console.log(chalk.bold('Next'))
+  console.log(
+    `  ${chalk.cyan('astrale call /:dist.astrale.ai:class.Echo:echo message=hello')}  ${chalk.dim('— smoke test')}`,
+  )
+  console.log(`  ${chalk.cyan('astrale browser')}  ${chalk.dim('— drive the GUI as your agent')}`)
+  console.log(`  ${chalk.cyan('astrale --help')}  ${chalk.dim('— everything else')}`)
+}

package/src/setup/steps/admin.ts

@@ -0,0 +1,78 @@
+import type { SetupContext, SetupStep } from '../types'
+
+import { AdminTargetConfigSchema, DEFAULT_ADMIN_TARGET_NAME } from '../../lib/admin-target'
+import { readConfig, writeConfig } from '../../lib/config'
+import { readLocalStatus } from '../../lib/local-status'
+import { log } from '../../lib/log'
+import { promptText } from '../../lib/prompt'
+import { urlError } from '../util'
+
+const FIX = 'astrale admin use --url <admin-url>'
+
+async function setAdminUrl(url: string): Promise<void> {
+  const config = await readConfig()
+  await writeConfig({
+    ...config,
+    admin: AdminTargetConfigSchema.parse({ name: DEFAULT_ADMIN_TARGET_NAME, url, issuer: url }),
+  })
+}
+
+async function setAdminBookmark(bookmark: string): Promise<void> {
+  const config = await readConfig()
+  await writeConfig({ ...config, admin: AdminTargetConfigSchema.parse({ instance: bookmark }) })
+}
+
+/**
+ * Step 2 — the admin control plane. There's always a default (admin.eu), so the
+ * checklist shows it as satisfied and setup just confirms it with a ✔ line — no
+ * prompt, since the default is right for nearly everyone and asking only confused
+ * first-run users. Explicit --admin-url / --admin flags still persist immediately,
+ * and power users repoint later with `astrale admin use <bookmark>|--url <url>`.
+ * The only prompt left is the recovery path when the configured target is broken.
+ */
+export const adminStep: SetupStep = {
+  id: 'admin',
+  title: 'Admin control plane',
+  group: 'connect',
+
+  async detect() {
+    const { admin } = await readLocalStatus()
+    if ('error' in admin) {
+      return { state: 'broken', summary: `Admin target invalid: ${admin.error}`, fixHint: FIX }
+    }
+    return {
+      state: 'satisfied',
+      summary: `${admin.name} (${admin.url})`,
+      detail: `source: ${admin.source}`,
+    }
+  },
+
+  async ensure(ctx: SetupContext) {
+    // Explicit overrides win and persist, no prompt.
+    if (ctx.opts.adminUrl) {
+      await setAdminUrl(ctx.opts.adminUrl)
+      log.success(`Admin control plane set: ${ctx.opts.adminUrl}`)
+      return 'fixed'
+    }
+    if (ctx.opts.admin) {
+      await setAdminBookmark(ctx.opts.admin)
+      log.success(`Admin control plane set: bookmark "${ctx.opts.admin}"`)
+      return 'fixed'
+    }
+
+    const { admin } = await readLocalStatus()
+    if ('error' in admin) {
+      log.warn(`Admin target invalid: ${admin.error}`)
+      const url = await promptText('Admin kernel URL', { validate: urlError })
+      if (!url) return 'skipped'
+      await setAdminUrl(url)
+      log.success(`Admin control plane set: ${url}`)
+      return 'fixed'
+    }
+
+    // Configured or baked default: accept it silently — no prompt. Power users
+    // repoint with `astrale admin use` (or the --admin-url / --admin flags above).
+    log.success(`Admin control plane: ${admin.name} (${admin.url})`)
+    return 'unchanged'
+  },
+}

package/src/setup/steps/agent-browser.ts

@@ -0,0 +1,81 @@
+import type { SetupStep } from '../types'
+
+import { AGENT_BROWSER_REPO } from '../../lib/browser'
+import { log } from '../../lib/log'
+import { runInherit } from '../../lib/proc'
+import { confirmDefaultYes } from '../../lib/prompt'
+import { AGENT_BROWSER_SKILL, detectAgentBrowser, detectSkill } from '../../lib/skills'
+
+const FIX = 'npm install -g agent-browser && agent-browser install'
+const SKILL_FIX = `npx skills add ${AGENT_BROWSER_REPO} -g`
+
+/**
+ * Equip — agent-browser, the tool `astrale browser` drives. Two halves: the
+ * third-party binary (a global npm install + one-time engine download, so opt-in
+ * and confirmed) and its agent skill (so the harness knows the commands). We
+ * track BOTH: a skill that the harness can't load is as broken as a missing
+ * binary, so detection requires both, and `ensure` wires a missing skill even
+ * when the binary is already present (the "installed but not loaded" gap).
+ */
+export const agentBrowserStep: SetupStep = {
+  id: 'agent-browser',
+  title: 'agent-browser',
+  group: 'equip',
+
+  async detect() {
+    const haveBin = await detectAgentBrowser()
+    const haveSkill = detectSkill(AGENT_BROWSER_SKILL).installed
+    if (haveBin && haveSkill)
+      return { state: 'satisfied', summary: 'agent-browser + skill installed' }
+    if (haveBin && !haveSkill) {
+      return {
+        state: 'gap',
+        summary: 'agent-browser installed, but its skill is not loaded by the harness',
+        fixHint: SKILL_FIX,
+      }
+    }
+    return { state: 'gap', summary: 'agent-browser not installed', fixHint: FIX }
+  },
+
+  async ensure() {
+    const haveSkill = () => detectSkill(AGENT_BROWSER_SKILL).installed
+    if ((await detectAgentBrowser()) && haveSkill()) {
+      log.success('agent-browser already installed')
+      return 'unchanged'
+    }
+
+    // 1) The binary — third-party global npm + engine download, so confirm it.
+    if (!(await detectAgentBrowser())) {
+      log.warn(`agent-browser is a third-party global npm package (${AGENT_BROWSER_REPO}).`)
+      if (!(await confirmDefaultYes('Install agent-browser globally now?'))) {
+        log.dim(`  Skipped — install later: ${FIX} && ${SKILL_FIX}`)
+        return 'skipped'
+      }
+
+      log.step('npm install -g agent-browser')
+      if ((await runInherit('npm', ['install', '-g', 'agent-browser'])) !== 0) {
+        log.warn('npm install failed — see the output above.')
+        return 'failed'
+      }
+
+      log.step('agent-browser install  (downloading the browser engine)')
+      if ((await runInherit('agent-browser', ['install'])) !== 0) {
+        log.warn('`agent-browser install` failed — re-run it manually.')
+        return 'failed'
+      }
+    }
+
+    // 2) The skill — wire it into the harness so the agent can load it. Runs even
+    //    when the binary was already present (the installed-but-not-loaded gap).
+    if (!haveSkill()) {
+      log.step(`${SKILL_FIX}  (teaches your agent its commands)`)
+      if ((await runInherit('npx', ['skills', 'add', AGENT_BROWSER_REPO, '-g', '-y'])) !== 0) {
+        log.warn(`Skill install did not complete — run it later: ${SKILL_FIX}`)
+        return 'failed'
+      }
+    }
+
+    log.success('agent-browser ready — drive the GUI with `astrale browser`')
+    return 'fixed'
+  },
+}