@astrale-os/cli 1.0.0-beta.32 → 1.0.0-beta.43

package/src/program/build.ts

@@ -1,205 +0,0 @@
-import { Command, Option } from 'commander'
-
-import pkg from '../../package.json' with { type: 'json' }
-import { withKernelOptions } from './options'
-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
- * `program/__tests__/program.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, '-V, --cli-version', 'output the CLI version (root alias: --version)')
-    .showSuggestionAfterError(true)
-    .addOption(new Option('--ci', 'Machine mode: no prompts, structured errors on stderr'))
-    .addOption(new Option('--no-prompt', 'Disable interactive prompts'))
-    .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()
-    })
-
-  // 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/mutate')).default))
-  registerCommand(program, withKernelOptions((await import('../commands/query')).default))
-  registerCommand(program, withKernelOptions((await import('../commands/introspect')).default))
-  registerCommand(program, withKernelOptions((await import('../commands/logs')).default))
-  registerCommand(program, withKernelOptions((await import('../commands/view')).default))
-  registerCommand(program, (await import('../commands/status')).default)
-  registerCommand(program, (await import('../commands/browser')).default)
-  registerCommand(program, (await import('../commands/view-serve')).default)
-  registerCommand(program, (await import('../commands/studio')).default)
-
-  registerGroup(program, {
-    name: 'ui',
-    description: 'Initialize and install Astrale UI in local applications',
-    commands: [
-      (await import('../commands/ui/init')).default,
-      (await import('../commands/ui/list')).default,
-      (await import('../commands/ui/add')).default,
-      (await import('../commands/ui/doctor')).default,
-    ],
-    subgroups: [
-      {
-        name: 'preset',
-        description: 'List and apply qualified Astrale UI presets',
-        commands: [
-          (await import('../commands/ui/preset-list')).default,
-          (await import('../commands/ui/preset-apply')).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, install, and uninstall domains',
-    commands: [
-      withKernelOptions((await import('../commands/domain/list')).default),
-      withKernelOptions((await import('../commands/domain/publish')).default),
-      withKernelOptions((await import('../commands/domain/install')).default),
-      withKernelOptions((await import('../commands/domain/uninstall')).default),
-    ],
-  })
-
-  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,
-      withKernelOptions((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: 'session',
-    description: 'Locally recorded work sessions: list and DX-analyze them',
-    commands: [
-      (await import('../commands/session/list')).default,
-      (await import('../commands/session/analyze')).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        get, mutate, call, query, introspect, logs, view, token
-  Management    admin, instance, domain, identity, auth, idp, update
-  Application   ui        (initialize, inspect, and install Astrale UI source)
-  Agent         browser   (drive the GUI via agent-browser)
-  Studio        studio    (launch the local Domain Studio GUI for a workspace)
-
-Path syntax:
-  /:origin                       Domain root
-  /:origin:class.Name            Class node
-  /:origin:class.Name:method     Static callable
-  <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 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 shell.astrale.ai
-  $ astrale query /:notes.example.dev:class.Note --limit 50
-  $ astrale introspect /:kernel.astrale.ai:class.Identity:whois
-  $ astrale query --file query.v6.json --cursor "$CURSOR"
-`,
-  )
-
-  return program
-}

package/src/program/command.ts

@@ -1,43 +0,0 @@
-export interface CommandArgument {
-  readonly name: string
-  readonly description: string
-  readonly required?: boolean
-  readonly variadic?: boolean
-}
-
-export interface CommandOption {
-  readonly flags: string
-  readonly description: string
-  readonly default?: string
-  readonly choices?: string[]
-}
-
-export interface CommandDefinition {
-  readonly name: string
-  readonly description: string
-  /** One-line summary shown in the parent's command list (Commander `.summary()`). */
-  readonly summary?: string
-  /** Hide from help listings (internal entries, e.g. `__view-serve`). */
-  readonly hidden?: boolean
-  readonly aliases?: string[]
-  readonly arguments?: CommandArgument[]
-  readonly options?: CommandOption[]
-  /**
-   * Free-form prose appended to `<cmd> --help` (Commander `addHelpText('after')`).
-   * Use for command-local behavior the flag list cannot express + canonical
-   * examples. Pre-wrap lines to ~78 cols — Commander prints it verbatim.
-   */
-  readonly afterHelpText?: string
-  /** Opaque Commander callback; each command module owns its concrete argument tuple. */
-  readonly action: (...args: never[]) => Promise<void>
-}
-
-export interface CommandGroup {
-  readonly name: string
-  readonly description: string
-  /** One-line summary shown in the program's command list (Commander `.summary()`). */
-  readonly summary?: string
-  readonly commands: CommandDefinition[]
-  /** Nested subgroups (one extra level of `astrale foo bar baz` nesting). */
-  readonly subgroups?: CommandGroup[]
-}

package/src/program/index.ts

@@ -1,3 +0,0 @@
-export { buildProgram } from './build.js'
-export { normalizeRootVersionArgv } from './argv.js'
-export type { CommandArgument, CommandDefinition, CommandGroup, CommandOption } from './command.js'

package/src/program/options.ts

@@ -1,41 +0,0 @@
-import type { CommandDefinition, CommandOption } from './command'
-
-import { RAW_OUTPUT_OPTIONS } from '../lib/output'
-
-const KERNEL_PASSTHROUGH_OPTIONS: readonly CommandOption[] = Object.freeze([
-  {
-    flags: '--url <url>',
-    description: 'Target a kernel URL directly (overrides instance resolution)',
-  },
-  {
-    flags: '-i, --instance <name>',
-    description: 'Target a specific instance (overrides active)',
-  },
-  { flags: '--timeout <ms>', description: 'Request timeout in ms (default: 30000)' },
-  { flags: '--as <identity>', description: 'Call as a specific identity' },
-  { flags: '--creds <token>', description: 'Use a pre-signed credential (e.g. delegation token)' },
-  {
-    flags: '--anonymous',
-    description:
-      'Send no credential (cannot be combined with --as or --creds; --as and --creds are mutually exclusive)',
-  },
-  { flags: '--debug', description: 'Print full error diagnostics on failure' },
-])
-
-const KERNEL_OPTIONS: readonly CommandOption[] = Object.freeze([
-  {
-    flags: '--format <type>',
-    description: 'Output format (default: yaml in TTY, json when piped)',
-    choices: ['yaml', 'json'],
-  },
-  ...RAW_OUTPUT_OPTIONS,
-  ...KERNEL_PASSTHROUGH_OPTIONS,
-])
-
-/** Attach the single canonical option set to one Kernel-touching command. */
-export function withKernelOptions(definition: CommandDefinition): CommandDefinition {
-  return {
-    ...definition,
-    options: [...(definition.options ?? []), ...KERNEL_OPTIONS],
-  }
-}

package/src/program/registry.ts

@@ -1,64 +0,0 @@
-import { type Command, Option } from 'commander'
-
-import type { CommandDefinition, CommandGroup } from './command'
-
-type CommanderAction = Parameters<Command['action']>[0]
-
-/**
- * Register a single command on a Commander program or subcommand.
- */
-export function registerCommand(parent: Command, def: CommandDefinition): void {
-  const cmd = parent.command(def.name, { hidden: def.hidden ?? false }).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 name = arg.variadic ? `${arg.name}...` : arg.name
-      const bracket = arg.required !== false ? `<${name}>` : `[${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)
-      }
-    }
-  }
-
-  // CommandDefinition keeps each callback tuple opaque; Commander materializes
-  // that tuple only after this definition has registered its arguments/options.
-  cmd.action(def.action as CommanderAction)
-
-  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/program/tsconfig.json

@@ -1,6 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": { "types": ["@types/node"] },
-  "include": ["*.ts"],
-  "exclude": ["__tests__"]
-}

package/src/setup/__tests__/instance-step.test.ts

@@ -1,256 +0,0 @@
-import { describe, expect, mock, test } from 'bun:test'
-
-import type { OwnedInstanceInfo } from '../../lib/admin-instance'
-import type { SetupContext } from '../types'
-
-import { AstraleError } from '../../errors'
-import {
-  adoptOwnedInstance,
-  ensureOwnedInstance,
-  type InstanceSetupDependencies,
-} from '../steps/instance'
-
-const ctx: SetupContext = {
-  interactive: true,
-  machine: true,
-  opts: {},
-  slug: 'new-instance',
-}
-
-function instance(slug: string, state: OwnedInstanceInfo['state'] = 'ready'): OwnedInstanceInfo {
-  return {
-    id: `${slug}-id`,
-    slug,
-    url: `https://${slug}.eu.astrale.ai`,
-    state,
-    organizationId: `org_${slug}`,
-  }
-}
-
-function inventory(instances: OwnedInstanceInfo[], identity?: string) {
-  return { instances, ...(identity ? { identity } : {}) }
-}
-
-function dependencies(
-  overrides: Partial<InstanceSetupDependencies> = {},
-): InstanceSetupDependencies {
-  return {
-    fetchOwned: mock(async () => inventory([])),
-    adopt: mock(async () => {}),
-    selectReady: mock(async (instances) => instances[0] ?? null),
-    confirmCreate: mock(async () => true),
-    promptSlug: mock(async () => 'new-instance'),
-    provision: mock(async (slug) => ({
-      created: { url: `https://${slug}.eu.astrale.ai`, organizationId: `org_${slug}` },
-      slug,
-    })),
-    ...overrides,
-  }
-}
-
-describe('setup owned-instance reconciliation', () => {
-  test('silently adopts the sole owned ready instance', async () => {
-    const ready = instance('only')
-    const failed = instance('old-attempt', 'failed')
-    const deps = dependencies({
-      fetchOwned: mock(async () => inventory([failed, ready], 'manager')),
-    })
-
-    await expect(ensureOwnedInstance(ctx, deps)).resolves.toBe('fixed')
-
-    expect(deps.adopt).toHaveBeenCalledTimes(1)
-    expect(deps.adopt).toHaveBeenCalledWith(ready, 'manager')
-    expect(deps.selectReady).not.toHaveBeenCalled()
-    expect(deps.confirmCreate).not.toHaveBeenCalled()
-    expect(deps.provision).not.toHaveBeenCalled()
-  })
-
-  test('asks the user to pick when several owned instances are ready', async () => {
-    const first = instance('first')
-    const second = instance('second')
-    const pending = instance('pending', 'provisioning')
-    const deps = dependencies({
-      fetchOwned: mock(async () => inventory([first, pending, second], 'manager')),
-      selectReady: mock(async (instances) => instances[1] ?? null),
-    })
-
-    await expect(ensureOwnedInstance(ctx, deps)).resolves.toBe('fixed')
-
-    expect(deps.selectReady).toHaveBeenCalledWith([first, second])
-    expect(deps.adopt).toHaveBeenCalledWith(second, 'manager')
-    expect(deps.confirmCreate).not.toHaveBeenCalled()
-    expect(deps.provision).not.toHaveBeenCalled()
-  })
-
-  test('leaves setup skipped when the ready-instance picker is cancelled', async () => {
-    const first = instance('first')
-    const second = instance('second')
-    const deps = dependencies({
-      fetchOwned: mock(async () => inventory([first, second])),
-      selectReady: mock(async () => null),
-    })
-
-    await expect(ensureOwnedInstance(ctx, deps)).resolves.toBe('skipped')
-
-    expect(deps.selectReady).toHaveBeenCalledWith([first, second])
-    expect(deps.adopt).not.toHaveBeenCalled()
-    expect(deps.confirmCreate).not.toHaveBeenCalled()
-    expect(deps.provision).not.toHaveBeenCalled()
-  })
-
-  test('offers first-instance creation only after a confirmed empty owner list', async () => {
-    const deps = dependencies()
-    const original = console.log
-    console.log = mock(() => {})
-
-    try {
-      await expect(ensureOwnedInstance(ctx, deps)).resolves.toBe('fixed')
-    } finally {
-      console.log = original
-    }
-
-    expect(deps.confirmCreate).toHaveBeenCalledTimes(1)
-    expect(deps.promptSlug).toHaveBeenCalledTimes(1)
-    expect(deps.provision).toHaveBeenCalledWith('new-instance')
-    expect(deps.adopt).not.toHaveBeenCalled()
-  })
-
-  test('does not provision when first-instance creation is declined', async () => {
-    const deps = dependencies({ confirmCreate: mock(async () => false) })
-
-    await expect(ensureOwnedInstance(ctx, deps)).resolves.toBe('skipped')
-
-    expect(deps.confirmCreate).toHaveBeenCalledTimes(1)
-    expect(deps.promptSlug).not.toHaveBeenCalled()
-    expect(deps.provision).not.toHaveBeenCalled()
-  })
-
-  test('does not provision when the slug prompt is cancelled', async () => {
-    const deps = dependencies({ promptSlug: mock(async () => undefined) })
-
-    await expect(ensureOwnedInstance(ctx, deps)).resolves.toBe('skipped')
-
-    expect(deps.confirmCreate).toHaveBeenCalledTimes(1)
-    expect(deps.promptSlug).toHaveBeenCalledTimes(1)
-    expect(deps.provision).not.toHaveBeenCalled()
-  })
-
-  test('does not report setup fixed when provisioning could not select the instance', async () => {
-    const deps = dependencies({
-      provision: mock(async (slug) => ({
-        created: { url: `https://${slug}.eu.astrale.ai`, organizationId: `org_${slug}` },
-        slug,
-        selectionError: new Error('instances.json is read-only'),
-      })),
-    })
-    const logged: string[] = []
-    const original = console.log
-    console.log = mock((...args: unknown[]) => {
-      logged.push(args.map(String).join(' '))
-    })
-
-    let caught: unknown
-    try {
-      await ensureOwnedInstance(ctx, deps)
-    } catch (error) {
-      caught = error
-    } finally {
-      console.log = original
-    }
-
-    expect(caught).toBeInstanceOf(AstraleError)
-    expect((caught as AstraleError).code).toBe('INSTANCE_SELECTION_FAILED')
-    expect((caught as AstraleError).message).toContain('instances.json is read-only')
-    expect((caught as AstraleError).hint).toContain('astrale instance use new-instance')
-    expect(logged.join('\n')).not.toContain('https://new-instance.eu.astrale.ai')
-  })
-
-  test('does not create a duplicate while an owned instance is provisioning or failed', async () => {
-    const provisioning = {
-      ...instance('pending', 'provisioning'),
-      phase: 'installing:default-domains',
-    }
-    const failed = { ...instance('broken', 'failed'), error: 'postInstall failed' }
-    const deps = dependencies({
-      fetchOwned: mock(async () => inventory([provisioning, failed])),
-    })
-    const logged: string[] = []
-    const original = console.log
-    console.log = mock((...args: unknown[]) => {
-      logged.push(args.map(String).join(' '))
-    })
-
-    try {
-      await expect(ensureOwnedInstance(ctx, deps)).resolves.toBe('skipped')
-    } finally {
-      console.log = original
-    }
-
-    expect(deps.selectReady).not.toHaveBeenCalled()
-    expect(deps.confirmCreate).not.toHaveBeenCalled()
-    expect(deps.promptSlug).not.toHaveBeenCalled()
-    expect(deps.provision).not.toHaveBeenCalled()
-    expect(logged.join('\n')).toContain('pending: provisioning (installing:default-domains)')
-    expect(logged.join('\n')).toContain('broken: failed')
-    expect(logged.join('\n')).toContain('postInstall failed')
-    expect(logged.join('\n')).toContain('astrale instance status')
-  })
-
-  test('does not treat owner-discovery failure as an empty account', async () => {
-    const deps = dependencies({
-      fetchOwned: mock(async () => {
-        throw new Error('admin unavailable')
-      }),
-    })
-
-    let caught: unknown
-    try {
-      await ensureOwnedInstance(ctx, deps)
-    } catch (error) {
-      caught = error
-    }
-
-    expect(caught).toBeInstanceOf(AstraleError)
-    expect((caught as AstraleError).code).toBe('INSTANCE_DISCOVERY_FAILED')
-    expect((caught as AstraleError).hint).toContain('No instance was created')
-    expect(deps.confirmCreate).not.toHaveBeenCalled()
-    expect(deps.provision).not.toHaveBeenCalled()
-  })
-})
-
-describe('owned-instance adoption', () => {
-  test('persists the owner organization before activating the bookmark', async () => {
-    const owned = instance('existing')
-    const calls: unknown[][] = []
-    const original = console.log
-    console.log = mock(() => {})
-
-    try {
-      await adoptOwnedInstance(owned, 'manager', {
-        upsert: mock(async (...args) => {
-          calls.push(['upsert', ...args])
-          return { entry: {} }
-        }),
-        activate: mock(async (...args) => {
-          calls.push(['activate', ...args])
-        }),
-      })
-    } finally {
-      console.log = original
-    }
-
-    expect(calls).toEqual([
-      [
-        'upsert',
-        {
-          key: 'existing',
-          slug: 'existing',
-          url: 'https://existing.eu.astrale.ai',
-          organizationId: 'org_existing',
-          defaultIdentity: 'manager',
-        },
-      ],
-      ['activate', 'existing'],
-    ])
-  })
-})

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

@@ -1,29 +0,0 @@
-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')
-  })
-})