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

package/src/lib/view/resolve.ts

@@ -1,111 +0,0 @@
-import type { ResolvedView as SessionResolvedView } from '@astrale-os/sdk/client/session'
-import type { ResolvedView } from '@astrale-os/shell'
-
-import { Path } from '@astrale-os/sdk/graph/path'
-
-import type { ConnectionContext } from '../../connection'
-
-import { AstraleError } from '../../errors'
-
-/**
- * View + target resolution for `astrale view`. Both spec shapes funnel through
- * the kernel's `View:resolve` syscall: a ViewPath resolves to the view node
- * itself (its class implements UI), a target path lists the views attached to
- * it via `view_for`.
- */
-
-const VIEW_PATH_RE = /^\/:[^\s/:@]+:view\.[a-z][a-z0-9-]*$/
-
-export type ViewSpec = { kind: 'view' | 'target'; path: string }
-
-export function parseViewSpec(spec: string): ViewSpec {
-  if (VIEW_PATH_RE.test(spec)) return { kind: 'view', path: spec }
-  if (spec.startsWith('/') || spec.startsWith('@')) return { kind: 'target', path: spec }
-  throw new AstraleError(
-    'INVALID_ARGUMENT',
-    `"${spec}" is neither a ViewPath (/:origin:view.slug) nor a node path (/… or @id)`,
-  )
-}
-
-/** The owning Domain principal used when an explicit ViewPath has no target override. */
-export function viewOwnerTarget(viewPath: string): string {
-  const parsed = Path.parse(viewPath)
-  if (parsed.ast.anchor.kind !== 'domain') {
-    throw new AstraleError('INVALID_ARGUMENT', `ViewPath has no Domain owner: ${viewPath}`)
-  }
-  return `/:${parsed.ast.anchor.origin}`
-}
-
-/** One exact Shell selection plus stable presentation fields for CLI output. */
-export type ViewCandidate = ResolvedView & {
-  id: string
-  path: string
-  url: string
-  name?: string
-  handshake: 'shell' | 'none'
-  origin: 'self' | 'class'
-  issuer: string
-  etag: string
-  revision: string
-}
-
-export async function resolveViewCandidates(
-  ctx: ConnectionContext,
-  nodePath: string,
-): Promise<ViewCandidate[]> {
-  const target = Path.parse(nodePath).raw
-  const catalog = await ctx.session.viewsFor(target)
-  return catalog.views.map((route) => toCandidate(target, route))
-}
-
-function toCandidate(target: ResolvedView['target'], route: SessionResolvedView): ViewCandidate {
-  const key = String(route.key)
-  return Object.freeze({
-    target,
-    route,
-    id: key,
-    path: `/:${key}`,
-    url: route.href,
-    name: key.slice(key.lastIndexOf(':view.') + ':view.'.length),
-    handshake: route.handshake,
-    origin: route.declaration.target.kind === 'domain' ? 'self' : 'class',
-    issuer: route.issuer,
-    etag: route.etag,
-    revision: route.revision,
-  })
-}
-
-/** Strip presentation aliases before crossing the Shell mount boundary. */
-export function selectedView(candidate: ViewCandidate): ResolvedView {
-  return Object.freeze({ target: candidate.target, route: candidate.route })
-}
-
-/** The slug tail of a candidate: `view.dashboard` → `dashboard`. */
-export function candidateSlug(candidate: ViewCandidate): string {
-  return candidate.name ?? candidate.id.slice(candidate.id.lastIndexOf(':view.') + ':view.'.length)
-}
-
-export function pickCandidate(
-  candidates: ViewCandidate[],
-  nodePath: string,
-  slug?: string,
-): ViewCandidate | 'ambiguous' {
-  if (slug) {
-    const match = candidates.find(
-      (candidate) =>
-        candidate.id === slug || candidate.path === slug || candidateSlug(candidate) === slug,
-    )
-    if (!match) {
-      throw new AstraleError(
-        'VIEW_NOT_FOUND',
-        `No view "${slug}" on ${nodePath} — available: ${candidates.map(candidateSlug).join(', ') || '(none)'}`,
-      )
-    }
-    return match
-  }
-  if (candidates.length === 0) {
-    throw new AstraleError('VIEW_NOT_FOUND', `No views resolve on ${nodePath}`)
-  }
-  if (candidates.length === 1) return candidates[0]
-  return 'ambiguous'
-}

package/src/lib/view/server.ts

@@ -1,244 +0,0 @@
-import type { ReadableStream as WebReadableStream } from 'node:stream/web'
-
-import { readFile } from 'node:fs/promises'
-import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
-import { join } from 'node:path'
-import { Readable } from 'node:stream'
-
-import type { ViewServeConfig } from './session'
-
-import { withClientSession } from '../../connection'
-import { fetchWithCaFile } from '../ca-fetch'
-import { viewerDistDir } from './assets'
-import { removeSessionFiles } from './session'
-
-export { ensureViewerAssets, viewerDistDir } from './assets'
-
-/**
- * The view-session server: serves the host page, hands it config and fresh
- * credentials, receives its lifecycle reports, and proxies the view's kernel
- * calls (one mechanism for CORS, self-signed local CAs, and keeping the kernel
- * origin out of the page). Everything is nonce-scoped under `/s/<nonce>/`;
- * loopback-only. Exits after `idleMs` without a request — the host page's
- * heartbeat keeps a live session alive.
- */
-
-const TOKEN_REFRESH_MARGIN_MS = 5 * 60_000
-const FALLBACK_TOKEN_TTL_MS = 3600_000
-const IDLE_SWEEP_MS = 60_000
-
-export type PageStatus = { state: string; error?: string; at: string }
-
-type TokenGrant = { token: string; expiresAt: number; kind: 'minted' }
-
-export function startViewServer(config: ViewServeConfig): Server {
-  const { session, proxy } = config
-  const base = `/s/${session.nonce}`
-  const hostDir = viewerDistDir()
-  const proxyFetch = proxy.caFile ? fetchWithCaFile(proxy.caFile) : globalThis.fetch
-  let status: PageStatus = { state: 'waiting', at: new Date().toISOString() }
-  let grant: TokenGrant | null = null
-  let lastActivity = Date.now()
-
-  /** Mint one TTL-bound credential; raw CLI credentials never enter the browser session. */
-  async function freshGrant(): Promise<TokenGrant> {
-    if (grant && grant.expiresAt - Date.now() > TOKEN_REFRESH_MARGIN_MS) return grant
-    grant = await withClientSession(config.kernel, async ({ auth, target }) => {
-      const token = await auth.mint({ audience: target.kernelIssuer, ttlSeconds: 3_600 })
-      return {
-        token,
-        expiresAt: jwtExpiry(token) ?? Date.now() + FALLBACK_TOKEN_TTL_MS,
-        kind: 'minted' as const,
-      }
-    })
-    return grant
-  }
-
-  const server = createServer((req, res) => {
-    lastActivity = Date.now()
-    void route(req, res).catch((error: unknown) => {
-      const message = error instanceof Error ? error.message : String(error)
-      // CORS headers even on failures — the caller may be the cross-origin
-      // view iframe, and an opaque error reads as a network failure there.
-      if (!res.headersSent) {
-        res.writeHead(502, {
-          'content-type': 'application/json',
-          ...corsHeaders(req.headers.origin),
-        })
-      }
-      res.end(JSON.stringify({ error: message }))
-    })
-  })
-
-  async function route(req: IncomingMessage, res: ServerResponse): Promise<void> {
-    const url = new URL(req.url ?? '/', 'http://localhost')
-    if (!url.pathname.startsWith(`${base}/`) && url.pathname !== base) {
-      res.writeHead(404).end()
-      return
-    }
-    const sub = url.pathname.slice(base.length) || '/'
-
-    if (sub === '/k' || sub.startsWith('/k/')) {
-      await proxyKernel(req, res, sub.slice('/k'.length), url.search)
-      return
-    }
-    if (sub === '/' || sub === '/index.html') {
-      await serveAsset(res, join(hostDir, 'index.html'), 'text/html; charset=utf-8')
-      return
-    }
-    if (sub === '/main.js') {
-      await serveAsset(res, join(hostDir, 'main.js'), 'text/javascript; charset=utf-8')
-      return
-    }
-    if (sub === '/config.json' && req.method === 'GET') {
-      json(res, 200, {
-        view: session.view,
-        kernelUrl: proxy.direct ? proxy.kernelUrl : `${base}/k`,
-        kernelIssuer: proxy.issuer,
-        identity: session.identity ?? null,
-        instance: session.instance ?? null,
-        sessionId: session.id,
-      })
-      return
-    }
-    if (sub === '/token' && req.method === 'POST') {
-      if (session.view.route.handshake !== 'shell') {
-        json(res, 403, { error: 'plain views have no Astrale credential privilege' })
-        return
-      }
-      const fresh = await freshGrant()
-      json(res, 200, { token: fresh.token, expiresAt: fresh.expiresAt, kind: fresh.kind })
-      return
-    }
-    if (sub === '/status' && req.method === 'POST') {
-      const body = await readJson(req)
-      if (body && typeof body.state === 'string' && body.state !== 'alive') {
-        status = { state: body.state, error: asString(body.error), at: new Date().toISOString() }
-      }
-      res.writeHead(204).end()
-      return
-    }
-    if (sub === '/state' && req.method === 'GET') {
-      json(res, 200, status)
-      return
-    }
-    res.writeHead(404).end()
-  }
-
-  /** Forward a kernel call: verbatim headers/body both ways, CORS added. */
-  async function proxyKernel(
-    req: IncomingMessage,
-    res: ServerResponse,
-    suffix: string,
-    search: string,
-  ): Promise<void> {
-    const origin = req.headers.origin
-    if (req.method === 'OPTIONS') {
-      res.writeHead(204, corsHeaders(origin)).end()
-      return
-    }
-    const target = joinUrl(proxy.kernelUrl, suffix) + search
-    const headers: Record<string, string> = {}
-    for (const name of ['authorization', 'content-type', 'accept']) {
-      const value = req.headers[name]
-      if (typeof value === 'string') headers[name] = value
-    }
-    // Buffer the request body (envelope requests are small JSON): the caFile
-    // fetch path speaks node https and cannot consume a web-stream body.
-    // Response bodies still stream through.
-    const hasBody = req.method !== 'GET' && req.method !== 'HEAD'
-    const body = hasBody ? Buffer.concat(await collect(req)) : undefined
-    const upstream = await proxyFetch(target, {
-      method: req.method,
-      headers,
-      ...(body !== undefined ? { body } : {}),
-    } as RequestInit)
-    const responseHeaders: Record<string, string> = corsHeaders(origin)
-    const contentType = upstream.headers.get('content-type')
-    if (contentType) responseHeaders['content-type'] = contentType
-    res.writeHead(upstream.status, responseHeaders)
-    if (upstream.body) {
-      Readable.fromWeb(upstream.body as unknown as WebReadableStream).pipe(res)
-    } else {
-      res.end()
-    }
-  }
-
-  const idleTimer = setInterval(() => {
-    if (Date.now() - lastActivity > config.idleMs) void shutdown(0)
-  }, IDLE_SWEEP_MS)
-  idleTimer.unref()
-
-  async function shutdown(code: number): Promise<void> {
-    clearInterval(idleTimer)
-    server.close()
-    await removeSessionFiles(session.id)
-    process.exit(code)
-  }
-  process.on('SIGTERM', () => void shutdown(0))
-  process.on('SIGINT', () => void shutdown(0))
-
-  server.listen(session.port, '127.0.0.1')
-  return server
-}
-
-function jwtExpiry(token: string): number | null {
-  try {
-    const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString('utf8')) as {
-      exp?: number
-    }
-    return typeof payload.exp === 'number' ? payload.exp * 1000 : null
-  } catch {
-    return null
-  }
-}
-
-function corsHeaders(origin: string | undefined): Record<string, string> {
-  return {
-    'access-control-allow-origin': origin ?? '*',
-    'access-control-allow-methods': 'GET,POST,PUT,PATCH,DELETE,OPTIONS',
-    'access-control-allow-headers': 'authorization, content-type, accept',
-    // Chrome private-network-access preflight (public page → loopback proxy).
-    'access-control-allow-private-network': 'true',
-    'access-control-max-age': '600',
-    vary: 'origin',
-  }
-}
-
-function joinUrl(baseUrl: string, suffix: string): string {
-  if (!suffix) return baseUrl
-  return baseUrl.replace(/\/$/, '') + suffix
-}
-
-function json(res: ServerResponse, code: number, body: unknown): void {
-  res.writeHead(code, { 'content-type': 'application/json' })
-  res.end(JSON.stringify(body))
-}
-
-async function serveAsset(res: ServerResponse, file: string, contentType: string): Promise<void> {
-  try {
-    const content = await readFile(file)
-    res.writeHead(200, { 'content-type': contentType, 'cache-control': 'no-store' })
-    res.end(content)
-  } catch {
-    res.writeHead(404).end()
-  }
-}
-
-async function collect(req: IncomingMessage): Promise<Buffer[]> {
-  const chunks: Buffer[] = []
-  for await (const chunk of req) chunks.push(chunk as Buffer)
-  return chunks
-}
-
-async function readJson(req: IncomingMessage): Promise<Record<string, unknown> | null> {
-  try {
-    return JSON.parse(Buffer.concat(await collect(req)).toString('utf8')) as Record<string, unknown>
-  } catch {
-    return null
-  }
-}
-
-function asString(value: unknown): string | undefined {
-  return typeof value === 'string' ? value : undefined
-}

package/src/lib/view/session.ts

@@ -1,152 +0,0 @@
-import type { ResolvedView } from '@astrale-os/shell'
-
-import { closeSync, fchmodSync, openSync } from 'node:fs'
-import { chmod, mkdir, readdir, readFile, rm } from 'node:fs/promises'
-import { join } from 'node:path'
-
-import { atomicWrite, paths } from '../../state/index'
-
-/**
- * View-session records: one detached server process per open view, tracked as
- * `~/.astrale/view/<id>.json` (+ `<id>.log`, `<id>.config.json`). Records are
- * garbage-collected on every `astrale view` invocation by probing the pid.
- */
-
-export const VIEW_DIR = join(paths.home, 'view')
-
-export type ViewSessionRecord = {
-  id: string
-  pid: number
-  port: number
-  nonce: string
-  /** Host page URL, nonce-scoped: `http://127.0.0.1:<port>/s/<nonce>/`. */
-  pageUrl: string
-  /** Exact verified View placement passed to Shell without split aliases. */
-  view: ResolvedView
-  instance?: string
-  identity?: string
-  createdAt: string
-}
-
-/** Everything the detached `view __serve` process needs, written before spawn. */
-export type ViewServeConfig = {
-  session: ViewSessionRecord
-  /** Kernel passthrough opts, re-resolved server-side for token mints. */
-  kernel: { url?: string; instance?: string; as?: string; creds?: string; timeout?: string }
-  /**
-   * Kernel the view dispatches to. `direct: true` hands the child the kernel
-   * URL itself (public https kernels — the router serves CORS, and Chrome's
-   * local-network-access rules forbid a public view origin fetching our
-   * loopback proxy). Otherwise the child gets the nonce-scoped proxy, which
-   * handles CORS and self-signed local CAs.
-   */
-  proxy: { kernelUrl: string; issuer: string; caFile?: string; direct: boolean }
-  idleMs: number
-}
-
-export const recordPath = (id: string, directory = VIEW_DIR): string =>
-  join(directory, `${id}.json`)
-export const logPath = (id: string, directory = VIEW_DIR): string => join(directory, `${id}.log`)
-export const configPath = (id: string, directory = VIEW_DIR): string =>
-  join(directory, `${id}.config.json`)
-
-/** Create or repair the credential-bearing session directory as owner-only. */
-export async function ensureViewDirectory(directory = VIEW_DIR): Promise<void> {
-  await mkdir(directory, { recursive: true, mode: 0o700 })
-  await chmod(directory, 0o700)
-}
-
-export async function saveRecord(record: ViewSessionRecord, directory = VIEW_DIR): Promise<void> {
-  await ensureViewDirectory(directory)
-  await atomicWrite(recordPath(record.id, directory), `${JSON.stringify(record, null, 2)}\n`)
-}
-
-/** Atomically publish the detached process config; it may contain raw `--creds`. */
-export async function saveServeConfig(
-  config: ViewServeConfig,
-  directory = VIEW_DIR,
-): Promise<void> {
-  await ensureViewDirectory(directory)
-  await atomicWrite(
-    configPath(config.session.id, directory),
-    `${JSON.stringify(config, null, 2)}\n`,
-  )
-}
-
-/** Open or repair a session log as owner-only and return its descriptor. */
-export async function openSessionLog(id: string, directory = VIEW_DIR): Promise<number> {
-  await ensureViewDirectory(directory)
-  const descriptor = openSync(logPath(id, directory), 'a', 0o600)
-  try {
-    fchmodSync(descriptor, 0o600)
-    return descriptor
-  } catch (error) {
-    closeSync(descriptor)
-    throw error
-  }
-}
-
-export async function removeSessionFiles(id: string, directory = VIEW_DIR): Promise<void> {
-  await Promise.all([
-    rm(recordPath(id, directory), { force: true }),
-    rm(configPath(id, directory), { force: true }),
-    rm(logPath(id, directory), { force: true }),
-  ])
-}
-
-export function isAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0)
-    return true
-  } catch {
-    return false
-  }
-}
-
-/** List live sessions, removing records whose server process is gone. */
-export async function listSessions(): Promise<ViewSessionRecord[]> {
-  let entries: string[]
-  try {
-    entries = await readdir(VIEW_DIR)
-  } catch {
-    return []
-  }
-  const live: ViewSessionRecord[] = []
-  for (const entry of entries) {
-    if (!/^v-[0-9a-f]+\.json$/.test(entry)) continue
-    let record: ViewSessionRecord
-    try {
-      record = JSON.parse(await readFile(join(VIEW_DIR, entry), 'utf8')) as ViewSessionRecord
-    } catch {
-      continue
-    }
-    if (isAlive(record.pid)) live.push(record)
-    else await removeSessionFiles(record.id)
-  }
-  return live.sort((a, b) => a.createdAt.localeCompare(b.createdAt))
-}
-
-const CLOSE_GRACE_MS = 2000
-
-/** SIGTERM the session server (SIGKILL after a grace period), drop its files. */
-export async function closeSession(record: ViewSessionRecord): Promise<void> {
-  if (isAlive(record.pid)) {
-    try {
-      process.kill(record.pid, 'SIGTERM')
-    } catch {
-      // already gone
-    }
-    const deadline = Date.now() + CLOSE_GRACE_MS
-    while (isAlive(record.pid) && Date.now() < deadline) {
-      await new Promise((resolve) => setTimeout(resolve, 100))
-    }
-    if (isAlive(record.pid)) {
-      try {
-        process.kill(record.pid, 'SIGKILL')
-      } catch {
-        // already gone
-      }
-    }
-  }
-  await removeSessionFiles(record.id)
-}

package/src/lib/view/snapshot.ts

@@ -1,101 +0,0 @@
-import type { AbResult } from '../browser'
-
-const SETTLE_TIMEOUT_MS = 8_000
-const QUIET_WINDOW_MS = 750
-const POLL_MS = 250
-
-type SettleClock = {
-  now(): number
-  sleep(ms: number): Promise<void>
-}
-
-type SettlePolicy = {
-  timeoutMs: number
-  quietWindowMs: number
-  pollMs: number
-}
-
-const realClock: SettleClock = {
-  now: Date.now,
-  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-}
-
-const defaultPolicy: SettlePolicy = {
-  timeoutMs: SETTLE_TIMEOUT_MS,
-  quietWindowMs: QUIET_WINDOW_MS,
-  pollMs: POLL_MS,
-}
-
-export function snapshotText(result: AbResult): string | null {
-  const data = result.data as { snapshot?: unknown } | string | null
-  if (typeof data === 'string') return data
-  return typeof data?.snapshot === 'string' ? data.snapshot : null
-}
-
-function isMeaningfulSnapshot(text: string): boolean {
-  return /"[^"\n]+"/.test(text)
-}
-
-function isPendingSnapshot(text: string): boolean {
-  if (/\[[^\]]*\bbusy\b[^\]]*\]/i.test(text)) return true
-  if (/^\s*-\s*progressbar\b/im.test(text)) return true
-
-  // Views often render loading text without aria-busy. The timeout still
-  // returns that snapshot when a view never leaves its loading state.
-  return /"(?:loading|opening|connecting|initializing|preparing|starting|fetching|refreshing|please wait)(?:\b[^"\n]{0,100})?"/i.test(
-    text,
-  )
-}
-
-function fingerprint(text: string): string {
-  return text
-    .replace(/\bref=e\d+\b/g, 'ref')
-    .replace(/\s+/g, ' ')
-    .trim()
-}
-
-/**
- * Warm the cross-origin accessibility tree, then wait for a meaningful view
- * snapshot to remain unchanged briefly. Loading/busy states never settle
- * early, but the timeout returns their latest snapshot for diagnosis.
- */
-export async function waitForSettledSnapshot(
-  takeSnapshot: () => Promise<AbResult>,
-  clock: SettleClock = realClock,
-  policy: SettlePolicy = defaultPolicy,
-): Promise<AbResult> {
-  let lastAttempt = await takeSnapshot()
-  let lastSuccess = lastAttempt.ok ? lastAttempt : null
-  let stableFingerprint: string | null = null
-  let stableSince = clock.now()
-  const deadline = clock.now() + policy.timeoutMs
-
-  while (true) {
-    lastAttempt = await takeSnapshot()
-    const sampledAt = clock.now()
-
-    if (lastAttempt.ok) {
-      lastSuccess = lastAttempt
-      const text = snapshotText(lastAttempt)
-      if (text && isMeaningfulSnapshot(text)) {
-        const nextFingerprint = fingerprint(text)
-        if (nextFingerprint !== stableFingerprint) {
-          stableFingerprint = nextFingerprint
-          stableSince = sampledAt
-        } else if (!isPendingSnapshot(text) && sampledAt - stableSince >= policy.quietWindowMs) {
-          return lastAttempt
-        }
-      } else {
-        stableFingerprint = null
-        stableSince = sampledAt
-      }
-    } else {
-      stableFingerprint = null
-      stableSince = sampledAt
-    }
-
-    const remaining = deadline - clock.now()
-    if (remaining <= 0) return lastSuccess ?? lastAttempt
-    await clock.sleep(Math.min(policy.pollMs, remaining))
-  }
-}

package/src/paths/.spec/api.d.ts

@@ -1,13 +0,0 @@
-export {
-  ASTRALE_HOME,
-  CONFIG_PATH,
-  DATA_DIR,
-  IDENTITIES_PATH,
-  IDPS_PATH,
-  IDP_SESSIONS_DIR,
-  INSTALL_PATH,
-  INSTANCES_PATH,
-  KEYS_DIR,
-  createPaths,
-} from '../../state/.spec/api.js'
-export type { PathEnvironment, Paths } from '../../state/.spec/api.js'

package/src/paths/.spec/architecture.md

@@ -1,5 +0,0 @@
-# CLI paths facade
-
-This independently consumed Node facade exposes only the CLI state coordinates retained by
-`@astrale-os/cli/paths`. The State module remains their semantic owner; this facade adds no mutable
-configuration or filesystem behavior.

package/src/paths/.spec/layout.ts

@@ -1,3 +0,0 @@
-import { defineLayout } from '@astrale-os/spec/authoring'
-
-export default defineLayout({ entries: ['index.ts'], exact: true })

package/src/paths/index.ts

@@ -1,13 +0,0 @@
-export {
-  ASTRALE_HOME,
-  CONFIG_PATH,
-  DATA_DIR,
-  IDENTITIES_PATH,
-  IDPS_PATH,
-  IDP_SESSIONS_DIR,
-  INSTALL_PATH,
-  INSTANCES_PATH,
-  KEYS_DIR,
-  createPaths,
-} from '../state/index'
-export type { PathEnvironment, Paths } from '../state/index'

package/src/program/.spec/api.d.ts

@@ -1,42 +0,0 @@
-import type { Command } from 'commander'
-
-/** One positional argument in a CLI command definition. */
-export interface CommandArgument {
-  readonly name: string
-  readonly description: string
-  readonly required?: boolean
-}
-
-/** One Commander-compatible option in a CLI command definition. */
-export interface CommandOption {
-  readonly flags: string
-  readonly description: string
-  readonly default?: string
-  readonly choices?: string[]
-}
-
-/** Internal authoring shape implemented by each command module. */
-export interface CommandDefinition {
-  readonly name: string
-  readonly description: string
-  readonly summary?: string
-  readonly hidden?: boolean
-  readonly aliases?: string[]
-  readonly arguments?: CommandArgument[]
-  readonly options?: CommandOption[]
-  readonly afterHelpText?: string
-  /** Opaque Commander callback; each command module owns its concrete argument tuple. */
-  readonly action: (...args: never[]) => Promise<void>
-}
-
-/** Internal composition shape for one group of commands. */
-export interface CommandGroup {
-  readonly name: string
-  readonly description: string
-  readonly summary?: string
-  readonly commands: CommandDefinition[]
-  readonly subgroups?: CommandGroup[]
-}
-
-/** Build a fresh, complete Commander tree without parsing process arguments. */
-export function buildProgram(): Promise<Command>