@astrale-os/cli 0.8.1-alpha.0 → 0.8.1-alpha.2

package/src/command.ts

@@ -1,42 +0,0 @@
-export type CommandArgument = {
-  name: string
-  description: string
-  required?: boolean
-}
-
-export type CommandOption = {
-  flags: string
-  description: string
-  default?: string
-  choices?: string[]
-}
-
-export type CommandDefinition = {
-  name: string
-  description: string
-  /** One-line summary shown in the parent's command list (Commander `.summary()`). */
-  summary?: string
-  /** Hide from help listings (internal entries, e.g. `__view-serve`). */
-  hidden?: boolean
-  aliases?: string[]
-  arguments?: CommandArgument[]
-  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.
-   */
-  afterHelpText?: string
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Commander passes typed args at runtime
-  action: (...args: any[]) => Promise<void>
-}
-
-export type CommandGroup = {
-  name: string
-  description: string
-  /** One-line summary shown in the program's command list (Commander `.summary()`). */
-  summary?: string
-  commands: CommandDefinition[]
-  /** Nested subgroups (one extra level of `astrale foo bar baz` nesting). */
-  subgroups?: CommandGroup[]
-}

package/src/commands/__tests__/help-contract.test.ts

@@ -1,164 +0,0 @@
-import type { Command } from 'commander'
-
-import { describe, expect, test } from 'bun:test'
-import { existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
-
-import { buildProgram } from '../../program'
-
-// 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', () => {
-  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)
-  })
-})
-
-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>')
-  })
-
-  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 local-runtime verbs are absent.
-    for (const removed of [
-      'init',
-      'start',
-      'stop',
-      'restart',
-      'reset',
-      'bootstrap',
-      'tunnel',
-      'graph',
-      'server',
-      'env',
-    ]) {
-      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] <path>')
-    expect(getHelp).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] [paths...]')
-    expect(queryHelp).toContain('--depth <n>')
-    expect(queryHelp).toContain('--children <json>')
-    expect(queryHelp).toContain('--edges <json>')
-    expect(queryHelp).toContain('--ast <json>')
-    expect(queryHelp).toContain('--cypher <query>')
-  })
-})
-
-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(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/kernel/__tests__/client-owned-lookup.test.ts

@@ -1,51 +0,0 @@
-import { describe, expect, mock, test } from 'bun:test'
-
-import type { OwnedInstanceInfo } from '../../lib/admin-instance'
-import type { AdminTargetCommandOpts } from '../../lib/admin-target'
-import type { KernelCommandOpts } from '../types'
-
-import { lookupImplicitOwnedInstance } from '../client'
-
-describe('implicit managed target owner discovery', () => {
-  test('keeps target credentials out of the admin inventory lookup', async () => {
-    const owned: OwnedInstanceInfo = {
-      id: 'owned-id',
-      slug: 'owned',
-      url: 'https://owned.eu.astrale.ai',
-      state: 'ready',
-    }
-    let captured:
-      | {
-          slug: string
-          opts: KernelCommandOpts & AdminTargetCommandOpts
-        }
-      | undefined
-    const lookupOwned = mock(
-      async (slug: string, opts: KernelCommandOpts & AdminTargetCommandOpts) => {
-        captured = { slug, opts }
-        return owned
-      },
-    )
-
-    await lookupImplicitOwnedInstance(
-      'owned',
-      {
-        as: 'target-identity',
-        creds: 'target-delegation',
-        timeout: '45000',
-        debug: true,
-      },
-      { lookupOwned },
-    )
-
-    expect(captured).toEqual({
-      slug: 'owned',
-      opts: {
-        timeout: '45000',
-        debug: true,
-      },
-    })
-    expect(captured?.opts).not.toHaveProperty('as')
-    expect(captured?.opts).not.toHaveProperty('creds')
-  })
-})

package/src/kernel/__tests__/errors.test.ts

@@ -1,43 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-
-// We test the stripMethodSuffix behavior indirectly through the module's exports.
-// Since stripMethodSuffix is private, we test the pattern directly.
-const stripMethodSuffix = (msg: string): string => {
-  return msg.replace(/(\/[^"\s:]+)::([a-zA-Z]\w*)/g, '$1')
-}
-
-describe('stripMethodSuffix', () => {
-  test('strips ::listChildren from path', () => {
-    expect(stripMethodSuffix('Path not found: "/nonexistent::listChildren"')).toBe(
-      'Path not found: "/nonexistent"',
-    )
-  })
-
-  test('strips ::get from path', () => {
-    expect(stripMethodSuffix('Path not found: "/some/path::get"')).toBe(
-      'Path not found: "/some/path"',
-    )
-  })
-
-  test('strips any method name', () => {
-    expect(stripMethodSuffix('"/kernel.astrale.ai/Root::describe"')).toBe(
-      '"/kernel.astrale.ai/Root"',
-    )
-  })
-
-  test('does not strip from non-path strings', () => {
-    expect(stripMethodSuffix('regular::text')).toBe('regular::text')
-  })
-
-  test('handles multiple paths in one message', () => {
-    expect(stripMethodSuffix('"/a/b::get" and "/c/d::list"')).toBe('"/a/b" and "/c/d"')
-  })
-
-  test('preserves messages without method suffixes', () => {
-    expect(stripMethodSuffix('No path found')).toBe('No path found')
-  })
-
-  test('does not strip single colon (not a method dispatch)', () => {
-    expect(stripMethodSuffix('"/a/b:notMethod"')).toBe('"/a/b:notMethod"')
-  })
-})

package/src/kernel/__tests__/expand.test.ts

@@ -1,123 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-
-import type { SelfResolverContext } from '../../lib/self'
-
-import { resolveSelfIdLazy } from '../expand'
-
-describe('resolveSelfIdLazy', () => {
-  test('refreshes a cached IdP @self registration via whoami', async () => {
-    const writes: unknown[][] = []
-    const ctx: SelfResolverContext = {
-      identity: {
-        name: 'bryan',
-        subject: 'user_01KC9MW1M6S5J6V9ERSRJ8RDYF',
-        createdAt: '2026-06-25T08:00:00.000Z',
-        source: 'idp',
-        registrations: {
-          bryan: {
-            iss: 'https://old.example',
-            sub: '4ad8e4ce-5cf7-4c2e-ab29-5549023dc8bf',
-            registeredAt: '2026-06-25T08:00:00.000Z',
-          },
-        },
-      },
-      instanceSlug: 'bryan',
-      instanceSigned: false,
-    }
-
-    const id = await resolveSelfIdLazy(
-      ctx,
-      {},
-      {
-        whoami: async () => ({
-          id: 'f011538e-9edc-4c29-92ce-9b81b6c1b6c7',
-          kernelUrl: 'https://bryan.example',
-        }),
-        setRegistration: async (...args) => {
-          writes.push(args)
-        },
-        now: () => new Date('2026-06-25T08:15:00.000Z'),
-      },
-    )
-
-    expect(id).toBe('f011538e-9edc-4c29-92ce-9b81b6c1b6c7')
-    expect(writes).toEqual([
-      [
-        'bryan',
-        'bryan',
-        {
-          iss: 'https://bryan.example',
-          sub: 'f011538e-9edc-4c29-92ce-9b81b6c1b6c7',
-          registeredAt: '2026-06-25T08:15:00.000Z',
-        },
-      ],
-    ])
-  })
-
-  test('keeps the cached IdP id when whoami is temporarily unavailable', async () => {
-    const ctx: SelfResolverContext = {
-      identity: {
-        name: 'bryan',
-        subject: 'user_01KC9MW1M6S5J6V9ERSRJ8RDYF',
-        createdAt: '2026-06-25T08:00:00.000Z',
-        source: 'idp',
-        registrations: {
-          bryan: {
-            iss: 'https://bryan.example',
-            sub: 'cached-id',
-            registeredAt: '2026-06-25T08:00:00.000Z',
-          },
-        },
-      },
-      instanceSlug: 'bryan',
-      instanceSigned: false,
-    }
-
-    await expect(
-      resolveSelfIdLazy(
-        ctx,
-        {},
-        {
-          whoami: async () => {
-            throw new Error('network down')
-          },
-        },
-      ),
-    ).resolves.toBe('cached-id')
-  })
-
-  test('does not run whoami for key-backed registrations', async () => {
-    const ctx: SelfResolverContext = {
-      identity: {
-        name: 'alice',
-        subject: 'alice',
-        createdAt: '2026-06-25T08:00:00.000Z',
-        source: 'key',
-        registrations: {
-          bryan: {
-            iss: 'https://bryan.example',
-            sub: 'key-node-id',
-            registeredAt: '2026-06-25T08:00:00.000Z',
-          },
-        },
-      },
-      instanceSlug: 'bryan',
-      instanceSigned: false,
-    }
-    let called = false
-
-    const id = await resolveSelfIdLazy(
-      ctx,
-      {},
-      {
-        whoami: async () => {
-          called = true
-          return { id: 'should-not-be-used', kernelUrl: 'https://bryan.example' }
-        },
-      },
-    )
-
-    expect(id).toBe('key-node-id')
-    expect(called).toBe(false)
-  })
-})

package/src/kernel/client.ts

@@ -1,214 +0,0 @@
-import { KernelClient, type FnMap } from '@astrale-os/kernel-client'
-import { ClientSession, delegationMintVia } from '@astrale-os/kernel-client/session'
-
-import type { AdminTargetCommandOpts } from '../lib/admin-target'
-import type { KernelCommandOpts } from './types'
-
-import { AstraleError } from '../errors'
-import {
-  callOwnedInstances,
-  findOwnedInstance,
-  type InstanceInfo,
-  type OwnedInstanceInfo,
-} from '../lib/admin-instance'
-import { readConfig } from '../lib/config'
-import { resolveInstanceTarget, type ResolvedInstanceTarget } from '../lib/instance-target'
-import { resolveCredential } from './auth'
-import { fetchWithCaFile } from './ca-fetch'
-
-const DEFAULT_TIMEOUT_MS = 30_000
-
-export type ClientContext = {
-  /** High-level call surface — bound to `credential` via ClientSession.identity. */
-  client: ClientSession<FnMap>
-  credential: string
-  url: string
-  config: Awaited<ReturnType<typeof readConfig>>
-}
-
-export type ResolvedKernelTarget = {
-  url: string
-  audience: string
-  slug?: string
-  defaultIdentity?: string
-  caFile?: string
-}
-
-/** Resolve the kernel a command targets (`--url` / `-i` / active instance). */
-export async function resolveKernelTarget(
-  opts: KernelCommandOpts,
-  config: Awaited<ReturnType<typeof readConfig>>,
-): Promise<ResolvedKernelTarget> {
-  // Ad-hoc `--url` — unknown kernel. Stamp the URL itself as audience,
-  // no slug for per-instance signing.
-  if (opts.url && !opts.instance) {
-    const resolved = await resolveInstanceTarget({ source: 'url', url: opts.url }, { config })
-    return resolvedToKernelTarget(resolved)
-  }
-  const resolved = await resolveInstanceTarget(
-    opts.instance ? { source: 'name', name: opts.instance } : { source: 'active' },
-    {
-      config,
-      admin: {},
-      managed: (slug) => lookupImplicitOwnedInstance(slug, opts),
-    },
-  )
-  return resolvedToKernelTarget(resolved, opts.url)
-}
-
-/**
- * Connect to a kernel instance, run `fn`, then disconnect.
- * The new client is lazy: construction does no I/O. We only need to
- * release sockets on the way out.
- */
-export async function withKernelClient<T>(
-  opts: KernelCommandOpts,
-  fn: (ctx: ClientContext) => Promise<T>,
-): Promise<T> {
-  const config = await readConfig()
-  const target = await resolveKernelTarget(opts, config)
-  return withResolvedKernelClient(opts, config, target, fn)
-}
-
-export async function listOwnedInstances(
-  opts: KernelCommandOpts & AdminTargetCommandOpts,
-): Promise<OwnedInstanceInfo[]> {
-  return await withAdminKernelClient(opts, async (ctx) => callOwnedInstances(ctx.client))
-}
-
-export async function lookupOwnedInstance(
-  slug: string,
-  opts: KernelCommandOpts & AdminTargetCommandOpts,
-): Promise<OwnedInstanceInfo> {
-  const instance = findOwnedInstance(await listOwnedInstances(opts), slug)
-  if (instance) return instance
-  throw new AstraleError('INSTANCE_NOT_FOUND', `No owned instance matches "${slug}".`)
-}
-
-export type ImplicitOwnedInstanceLookupDependencies = {
-  lookupOwned: (
-    slug: string,
-    opts: KernelCommandOpts & AdminTargetCommandOpts,
-  ) => Promise<OwnedInstanceInfo>
-}
-
-/**
- * Resolve an implicit managed target through the caller's owner inventory.
- *
- * Target `--as` / `--creds` belong to the eventual child-kernel call. They
- * must not authenticate the admin discovery request: leaving them out lets
- * `withAdminKernelClient` use the admin bookmark's default WorkOS identity.
- */
-export async function lookupImplicitOwnedInstance(
-  slug: string,
-  targetOpts: KernelCommandOpts,
-  deps: ImplicitOwnedInstanceLookupDependencies = {
-    lookupOwned: lookupOwnedInstance,
-  },
-): Promise<InstanceInfo> {
-  return await deps.lookupOwned(slug, {
-    timeout: targetOpts.timeout,
-    debug: targetOpts.debug,
-  })
-}
-
-function resolvedToKernelTarget(
-  target: ResolvedInstanceTarget,
-  urlOverride?: string,
-): ResolvedKernelTarget {
-  return {
-    url: urlOverride ?? target.url,
-    audience: target.issuer,
-    slug: target.name,
-    defaultIdentity: target.defaultIdentity,
-    caFile: target.caFile,
-  }
-}
-
-export async function withAdminKernelClient<T>(
-  opts: KernelCommandOpts & AdminTargetCommandOpts,
-  fn: (ctx: ClientContext) => Promise<T>,
-): Promise<T> {
-  const config = await readConfig()
-  const target = await resolveInstanceTarget({ source: 'admin' }, { config, admin: opts })
-  return withResolvedKernelClient(
-    opts,
-    config,
-    {
-      url: target.url,
-      audience: target.issuer,
-      slug: target.name,
-      defaultIdentity: target.defaultIdentity,
-      caFile: target.caFile,
-    },
-    fn,
-  )
-}
-
-async function withResolvedKernelClient<T>(
-  opts: KernelCommandOpts,
-  config: Awaited<ReturnType<typeof readConfig>>,
-  target: ResolvedKernelTarget,
-  fn: (ctx: ClientContext) => Promise<T>,
-): Promise<T> {
-  const credential = await resolveCredential(
-    { ...opts, defaultIdentity: target.defaultIdentity },
-    config,
-    target.audience,
-    target.slug,
-  )
-
-  // CLI is short-lived and one-shot per command. Skip the WS upgrade
-  // (saves up to 5s on hangs) and disable HTTP retries (saves ~7s of
-  // exponential backoff on ECONNREFUSED / 5xx). The user can re-run.
-  const requestTimeout = resolveTimeoutMs(opts.timeout)
-  const fetchImpl = target.caFile ? fetchWithCaFile(target.caFile) : undefined
-  const client: ClientSession<FnMap> = new ClientSession<FnMap>({
-    default: target.url,
-    identity: credential,
-    delegation: {
-      // Resolve lazily: the session must exist before the cache mints.
-      mint: delegationMintVia(() => client, credential),
-      ttl: 3600,
-    },
-    pool: {
-      clientFactory: (u) =>
-        new KernelClient<FnMap>({
-          url: u,
-          requestTimeout,
-          defaultTransport: 'http',
-          retry: { maxAttempts: 1 },
-          ...(fetchImpl ? { fetch: fetchImpl } : {}),
-        }),
-    },
-  })
-  await client.ready()
-
-  try {
-    return await fn({ client, credential, url: target.url, config })
-  } catch (error) {
-    // Attach url so formatKernelError can display it in connection errors
-    if (error instanceof Error) (error as Error & { url?: string }).url = target.url
-    throw error
-  } finally {
-    client.disconnect()
-  }
-}
-
-function resolveTimeoutMs(raw: string | undefined): number {
-  if (raw === undefined) return DEFAULT_TIMEOUT_MS
-  if (!/^\d+$/.test(raw)) {
-    throw new AstraleError(
-      'INVALID_FLAG',
-      `Invalid --timeout value "${raw}" — expected a positive integer (milliseconds)`,
-    )
-  }
-  const n = Number.parseInt(raw, 10)
-  if (!Number.isFinite(n) || n <= 0) {
-    throw new AstraleError(
-      'INVALID_FLAG',
-      `Invalid --timeout value "${raw}" — must be a positive integer`,
-    )
-  }
-  return n
-}