@astrale-os/cli 1.0.0-beta.8 → 1.0.0-npm-deprecated.0

package/src/program/.spec/architecture.md

@@ -1,18 +0,0 @@
-# CLI program architecture
-
-The program module owns Commander composition, not command effects or process lifecycle. It loads
-the existing command definitions only when `buildProgram` runs, attaches the single shared Kernel
-option set, and returns a fresh unparsed tree. Command modules own their actions; the binary owns
-argv, telemetry, signal, error, and exit handling.
-
-```mermaid
-flowchart LR
-  B[Binary entrypoint] --> P[buildProgram]
-  D[Command definitions] --> P
-  O[Shared Kernel options] --> P
-  P --> C[Fresh Commander tree]
-  C --> B
-```
-
-The module is private to the CLI package. The exhaustive user-facing grammar remains the generated
-Commander inventory rather than a duplicate declaration tree.

package/src/program/.spec/laws/program.ts

@@ -1,29 +0,0 @@
-import { defineLaw } from '@astrale-os/spec/authoring'
-
-export const CLI_PROGRAM_LEDGERED_SURFACE = defineLaw({
-  id: 'CLI-PROGRAM-LEDGERED-SURFACE',
-  statement:
-    'Program composition exposes one exact root and nested command surface; metadata, options, aliases, visibility, Commander behavior, rendered help, and package-derived version change only through a deliberate compatibility-ledger entry.',
-  tests: [
-    {
-      file: '__tests__/program.test.ts',
-      id: 'TEST-CLI-PROGRAM-MATCHES-LEDGERED-SURFACE',
-    },
-    {
-      file: '__tests__/program.test.ts',
-      id: 'TEST-CLI-PROGRAM-VERSION-SINGLE-SOURCE',
-    },
-  ],
-})
-
-export const CLI_PROGRAM_FRESH_ROOT = defineLaw({
-  id: 'CLI-PROGRAM-FRESH-ROOT',
-  statement:
-    'Each build produces an independent unparsed Commander root; mutation by one consumer cannot alter a later build.',
-  tests: [
-    {
-      file: '__tests__/program.test.ts',
-      id: 'TEST-CLI-PROGRAM-BUILDS-ISOLATED-ROOTS',
-    },
-  ],
-})

package/src/program/.spec/layout.ts

@@ -1,14 +0,0 @@
-import { defineLayout } from '@astrale-os/spec/authoring'
-
-export default defineLayout({
-  entries: [
-    '__tests__/',
-    'build.ts',
-    'command.ts',
-    'index.ts',
-    'options.ts',
-    'registry.ts',
-    'tsconfig.json',
-  ],
-  exact: true,
-})

package/src/program/__tests__/program.test.ts

@@ -1,362 +0,0 @@
-import type { Command } from 'commander'
-
-import { describe, expect, test } from 'bun:test'
-import { createHash } from 'node:crypto'
-import { existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
-
-import { buildProgram } from '../index'
-
-// Help output is the public CLI contract: version, spec anchors, and skill mirror stay in sync.
-
-const cliRoot = join(import.meta.dir, '../../..')
-
-/** Every command in the tree (root + groups + nested subgroups), depth-first. */
-function allCommands(cmd: Command): Command[] {
-  return [cmd, ...cmd.commands.flatMap(allCommands)]
-}
-
-describe('help contract — version is single-sourced', () => {
-  /** @evidence TEST-CLI-PROGRAM-VERSION-SINGLE-SOURCE */
-  test('program version === package.json === release-please manifest', async () => {
-    const program = await buildProgram()
-    const pkg = JSON.parse(readFileSync(join(cliRoot, 'package.json'), 'utf8')) as {
-      version: string
-    }
-    const manifest = JSON.parse(
-      readFileSync(join(cliRoot, '.release-please-manifest.json'), 'utf8'),
-    ) as Record<string, string>
-
-    // Program version must follow both package.json and release-please metadata.
-    expect(program.version()).toBe(pkg.version)
-    expect(manifest['.']).toBe(pkg.version)
-  })
-})
-
-type InspectedCommand = Command & {
-  readonly _allowExcessArguments?: boolean
-  readonly _allowUnknownOption?: boolean
-  readonly _combineFlagAndOptionalValue?: boolean
-  readonly _enablePositionalOptions?: boolean
-  readonly _hidden?: boolean
-  readonly _passThroughOptions?: boolean
-  readonly _showHelpAfterError?: boolean
-  readonly _showSuggestionAfterError?: boolean
-  readonly _storeOptionsAsProperties?: boolean
-}
-
-type InspectedArgument = Command['registeredArguments'][number] & {
-  readonly parseArg?: unknown
-}
-
-type InspectedOption = Command['options'][number] & {
-  readonly conflictsWith?: readonly string[]
-  readonly implied?: Readonly<Record<string, unknown>>
-}
-
-function ledgeredSurface(root: Command): readonly object[] {
-  const rows: object[] = []
-  const visit = (command: Command, parents: readonly string[]): void => {
-    const inspected = command as InspectedCommand
-    rows.push({
-      command: parents.join(' '),
-      aliases: command.aliases(),
-      description: command.description(),
-      summary: command.summary(),
-      arguments: command.registeredArguments.map((argument) => {
-        const inspectedArgument = argument as InspectedArgument
-        return {
-          name: argument.name(),
-          description: argument.description,
-          required: Boolean(argument.required),
-          variadic: Boolean(argument.variadic),
-          defaultValue: argument.defaultValue ?? null,
-          choices: argument.argChoices ?? null,
-          hasParser: typeof inspectedArgument.parseArg === 'function',
-        }
-      }),
-      options: command.options.map((option) => {
-        const inspectedOption = option as InspectedOption
-        return {
-          flags: option.flags,
-          attribute: option.attributeName(),
-          description: option.description,
-          required: Boolean(option.required),
-          optional: Boolean(option.optional),
-          variadic: Boolean(option.variadic),
-          mandatory: Boolean(option.mandatory),
-          negate: Boolean(option.negate),
-          hidden: Boolean(option.hidden),
-          defaultValue: option.defaultValue ?? null,
-          presetArg: option.presetArg ?? null,
-          envVar: option.envVar ?? null,
-          choices: option.argChoices ?? null,
-          conflictsWith: inspectedOption.conflictsWith ?? [],
-          implied: inspectedOption.implied ?? null,
-          hasParser: typeof option.parseArg === 'function',
-        }
-      }),
-      behavior: {
-        allowExcessArguments: Boolean(inspected._allowExcessArguments),
-        allowUnknownOption: Boolean(inspected._allowUnknownOption),
-        combineFlagAndOptionalValue: Boolean(inspected._combineFlagAndOptionalValue),
-        enablePositionalOptions: Boolean(inspected._enablePositionalOptions),
-        passThroughOptions: Boolean(inspected._passThroughOptions),
-        showHelpAfterError: Boolean(inspected._showHelpAfterError),
-        showSuggestionAfterError: Boolean(inspected._showSuggestionAfterError),
-        storeOptionsAsProperties: Boolean(inspected._storeOptionsAsProperties),
-      },
-      hidden: Boolean(inspected._hidden),
-      help: command.helpInformation(),
-    })
-    for (const child of command.commands) visit(child, [...parents, child.name()])
-  }
-  visit(root, [])
-  return rows.sort((left, right) => {
-    const leftName = (left as { command: string }).command
-    const rightName = (right as { command: string }).command
-    return leftName.localeCompare(rightName)
-  })
-}
-
-describe('program composition', () => {
-  /** @evidence TEST-CLI-PROGRAM-MATCHES-LEDGERED-SURFACE */
-  test('matches the complete ledgered command and help surface', async () => {
-    const surface = ledgeredSurface(await buildProgram())
-    const paths = surface.map((entry) => (entry as { command: string }).command)
-
-    expect(paths).toEqual([
-      '',
-      '__view-serve',
-      'admin',
-      'admin status',
-      'admin use',
-      'auth',
-      'auth login',
-      'auth logout',
-      'auth status',
-      'auth token',
-      'browser',
-      'call',
-      'domain',
-      'domain install',
-      'domain list',
-      'domain publish',
-      'domain uninstall',
-      'get',
-      'identity',
-      'identity create',
-      'identity delete',
-      'identity export',
-      'identity import',
-      'identity list',
-      'identity register',
-      'identity sync',
-      'identity unsync',
-      'identity use',
-      'identity whoami',
-      'idp',
-      'idp add',
-      'idp list',
-      'idp refresh',
-      'idp remove',
-      'idp show',
-      'instance',
-      'instance active',
-      'instance bookmark',
-      'instance create',
-      'instance delete',
-      'instance forget',
-      'instance list',
-      'instance status',
-      'instance use',
-      'introspect',
-      'logs',
-      'mutate',
-      'query',
-      'session',
-      'session analyze',
-      'session list',
-      'setup',
-      'status',
-      'studio',
-      'token',
-      'update',
-      'use',
-      'view',
-      'whoami',
-    ])
-    expect(createHash('sha256').update(JSON.stringify(surface)).digest('hex')).toBe(
-      '42b4812abbbca3d54289a16d0b066dfb3b1caaf1df6597a425c675744466a728',
-    )
-  })
-
-  /** @evidence TEST-CLI-PROGRAM-BUILDS-ISOLATED-ROOTS */
-  test('builds a fresh Commander root for each consumer', async () => {
-    const first = await buildProgram()
-    first.command('__temporary-test-command')
-
-    const second = await buildProgram()
-    expect(second).not.toBe(first)
-    expect(second.commands.some((command) => command.name() === '__temporary-test-command')).toBe(
-      false,
-    )
-  })
-})
-
-describe('help contract — no internal SPEC anchors leak to users', () => {
-  test('no rendered --help text contains a § section anchor', async () => {
-    const program = await buildProgram()
-    const offenders = allCommands(program)
-      .filter((c) => c.helpInformation().includes('§'))
-      .map((c) => c.name() || '<root>')
-
-    expect(offenders).toEqual([])
-  })
-})
-
-describe('help contract — IdP/auth surface is registered', () => {
-  test('idp group and auth commands are visible in --help tree', async () => {
-    const program = await buildProgram()
-    const names = allCommands(program).map((command) => command.name())
-
-    expect(names).toContain('idp')
-    expect(names).toContain('add')
-    expect(names).toContain('login')
-    expect(names).toContain('token')
-    expect(names).toContain('update')
-    expect(program.helpInformation()).toContain('idp')
-    expect(program.helpInformation()).toContain('update')
-  })
-})
-
-describe('help contract — admin target surface is registered', () => {
-  test('admin group and admin-target flags are visible', async () => {
-    const program = await buildProgram()
-    const names = allCommands(program).map((command) => command.name())
-    const instanceCreate = allCommands(program).find((command) => command.name() === 'create')
-
-    expect(names).toContain('admin')
-    expect(names).toContain('status')
-    expect(names).toContain('use')
-    expect(program.helpInformation()).toContain('admin')
-    expect(instanceCreate?.helpInformation()).toContain('--admin <name>')
-    expect(instanceCreate?.helpInformation()).toContain('--admin-url <url>')
-
-    const adminUse = program.commands
-      .find((command) => command.name() === 'admin')
-      ?.commands.find((command) => command.name() === 'use')
-    expect(adminUse?.helpInformation()).toContain('--kernel-issuer <url>')
-    expect(adminUse?.helpInformation()).toContain('--domain-issuer <url>')
-    expect(adminUse?.helpInformation()).not.toContain('--issuer <url>')
-  })
-
-  test('instance create is the alphaCreate flow, not legacy Instance.init DX', async () => {
-    const program = await buildProgram()
-    const instanceCreate = allCommands(program).find((command) => command.name() === 'create')
-    const help = instanceCreate?.helpInformation() ?? ''
-
-    expect(help).toContain('Instance.alphaCreate')
-    expect(help).not.toContain('--no-use')
-    expect(help).not.toContain('Instance.init requires --host-id')
-  })
-})
-
-describe('help contract — connect-only command surface', () => {
-  test('runtime management commands are not registered', async () => {
-    const program = await buildProgram()
-    const names = allCommands(program).map((command) => command.name())
-
-    // `logs` and `domain` have managed/admin meanings, so only retired verbs are absent.
-    for (const removed of [
-      'init',
-      'start',
-      'stop',
-      'restart',
-      'reset',
-      'bootstrap',
-      'tunnel',
-      'graph',
-      'server',
-      'env',
-      'ls',
-      'describe',
-    ]) {
-      expect(names).not.toContain(removed)
-    }
-  })
-})
-
-describe('help contract — read command split', () => {
-  test('get is point-read only and query owns structured read flags', async () => {
-    const program = await buildProgram()
-    const get = allCommands(program).find((command) => command.name() === 'get')
-    const query = allCommands(program).find((command) => command.name() === 'query')
-    const getHelp = get?.helpInformation() ?? ''
-    const queryHelp = query?.helpInformation() ?? ''
-
-    expect(getHelp).toContain('Usage: astrale get [options] <target>')
-    expect(getHelp).not.toContain('-l, --long')
-    expect(getHelp).not.toContain('--depth')
-    expect(getHelp).not.toContain('--children')
-    expect(getHelp).not.toContain('--edges')
-    expect(getHelp).not.toContain('--graph')
-
-    expect(queryHelp).toContain('Usage: astrale query [options] [sources...]')
-    expect(queryHelp).not.toContain('--depth <n>')
-    expect(queryHelp).not.toContain('--children <json>')
-    expect(queryHelp).not.toContain('--edges <json>')
-    expect(queryHelp).toContain('--ast <json>')
-    expect(queryHelp).toContain('--definition <path>')
-    expect(queryHelp).toContain('--edge <class>')
-    expect(queryHelp).toContain('--direction <direction>')
-    expect(queryHelp).toContain('--limit <n>')
-    expect(queryHelp).toContain('--cursor <token>')
-    expect(queryHelp).not.toContain('--cypher <query>')
-  })
-})
-
-describe('help contract — explicit anonymous authentication', () => {
-  test('kernel commands expose the credential-less session flag', async () => {
-    const program = await buildProgram()
-    const call = allCommands(program).find((command) => command.name() === 'call')
-
-    expect(call?.helpInformation()).toContain('--anonymous')
-    expect(call?.helpInformation()).toContain('Send no credential')
-  })
-})
-
-describe('help contract — payload sources', () => {
-  test('call excludes --file while mutate supports it', async () => {
-    const program = await buildProgram()
-    const call = allCommands(program).find((command) => command.name() === 'call')
-    const mutate = allCommands(program).find((command) => command.name() === 'mutate')
-    const callHelp = call?.helpInformation() ?? ''
-    const mutateHelp = mutate?.helpInformation() ?? ''
-
-    expect(callHelp).toContain('--data <json>')
-    expect(callHelp).not.toContain('--file <path>')
-    expect(callHelp).not.toContain('--describe')
-    expect(mutateHelp).toContain('--data <json>')
-    expect(mutateHelp).toContain('--file <path>')
-  })
-})
-
-describe('help contract — skill is single-source, not duplicated', () => {
-  const canonical = join(cliRoot, 'skills/astrale-cli/SKILL.md')
-  // Workspace mirror lives in the superrepo, outside this submodule. Absent
-  // when the CLI repo is tested standalone — only assert parity when present.
-  const mirror = join(cliRoot, '../.agents/skills/astrale-cli/SKILL.md')
-
-  test('canonical skill file exists and is non-empty', () => {
-    expect(existsSync(canonical)).toBe(true)
-    expect(readFileSync(canonical, 'utf8').length).toBeGreaterThan(0)
-  })
-
-  test.skipIf(!existsSync(mirror))(
-    'workspace mirror is byte-identical to the canonical skill',
-    () => {
-      expect(readFileSync(mirror, 'utf8')).toBe(readFileSync(canonical, 'utf8'))
-    },
-  )
-})

package/src/program/build.ts

@@ -1,183 +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)
-    .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: '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
-  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     (or /:origin:interface.Name)
-  /: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 --ttl 3600
-  $ astrale query /:notes.example.dev:class.Note --limit 50
-  $ astrale introspect /:host.astrale.ai:class.Manager:createInstance
-  $ astrale query --file query.v6.json --cursor "$CURSOR"
-`,
-  )
-
-  return program
-}

package/src/program/command.ts

@@ -1,42 +0,0 @@
-export interface CommandArgument {
-  readonly name: string
-  readonly description: string
-  readonly required?: 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,2 +0,0 @@
-export { buildProgram } from './build.js'
-export type { CommandArgument, CommandDefinition, CommandGroup, CommandOption } from './command.js'