@astrale-os/cli 0.4.0-alpha.13

package/src/lib/binary.ts

@@ -0,0 +1,131 @@
+import chalk from 'chalk'
+import { writeFile } from 'node:fs/promises'
+
+import type { OutputOpts } from './output'
+
+import { output } from './output'
+
+/** A binary kernel result: bytes (or a stream of them) plus its content-type. */
+export type BinaryLike = {
+  status: number
+  contentType: string
+  body: Uint8Array | ReadableStream<Uint8Array>
+}
+
+/** Collapse a (possibly streamed) binary body into a single byte array. */
+export async function readBinaryBody(
+  body: Uint8Array | ReadableStream<Uint8Array>,
+): Promise<Uint8Array> {
+  if (body instanceof Uint8Array) return body
+
+  const chunks: Uint8Array[] = []
+  const reader = body.getReader()
+  let total = 0
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    if (!value) continue
+    chunks.push(value)
+    total += value.byteLength
+  }
+
+  const out = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    out.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return out
+}
+
+function isTextLike(contentType: string): boolean {
+  const ct = contentType.toLowerCase()
+  return (
+    ct.startsWith('text/') ||
+    ct.includes('json') ||
+    ct.includes('xml') ||
+    ct.includes('event-stream')
+  )
+}
+
+function humanSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  const units = ['kB', 'MB', 'GB']
+  let v = bytes / 1024
+  let i = 0
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024
+    i++
+  }
+  return `${v.toFixed(1)} ${units[i]}`
+}
+
+/** The `--json` envelope: text-like inlines decoded text, otherwise base64. */
+function jsonEnvelope(resp: BinaryLike, bytes: Uint8Array): Record<string, unknown> {
+  if (isTextLike(resp.contentType)) {
+    return {
+      status: resp.status,
+      contentType: resp.contentType,
+      body: new TextDecoder().decode(bytes),
+    }
+  }
+  return {
+    status: resp.status,
+    contentType: resp.contentType,
+    bodyBase64: Buffer.from(bytes).toString('base64'),
+  }
+}
+
+/**
+ * Present a binary kind result.
+ *
+ * Precedence:
+ *   -o <file>       → write raw bytes to a file (+ a dim summary on stderr)
+ *   --raw           → raw bytes to stdout
+ *   --json          → base64/text-wrapped JSON object (jq-friendly)
+ *   non-TTY (pipe)  → raw bytes to stdout (`astrale call … > out.png`)
+ *   TTY, text-like  → decode and print the text
+ *   TTY, otherwise  → a one-line summary (don't spew binary at a terminal)
+ */
+export async function presentBinary(
+  resp: BinaryLike,
+  opts: OutputOpts,
+  io?: { outFile?: string },
+): Promise<void> {
+  const bytes = await readBinaryBody(resp.body)
+
+  if (io?.outFile) {
+    await writeFile(io.outFile, bytes)
+    process.stderr.write(
+      chalk.dim(`  wrote ${humanSize(bytes.length)} (${resp.contentType}) → ${io.outFile}\n`),
+    )
+    return
+  }
+
+  if (opts.raw) {
+    process.stdout.write(bytes)
+    return
+  }
+
+  if (opts.json) {
+    output(jsonEnvelope(resp, bytes), opts)
+    return
+  }
+
+  if (!(process.stdout.isTTY ?? false)) {
+    process.stdout.write(bytes)
+    return
+  }
+
+  if (isTextLike(resp.contentType)) {
+    const text = new TextDecoder().decode(bytes)
+    process.stdout.write(text.endsWith('\n') ? text : text + '\n')
+    return
+  }
+
+  process.stdout.write(
+    chalk.dim(
+      `  <binary · ${resp.contentType} · ${humanSize(bytes.length)}> — pipe or use -o <file> to save\n`,
+    ),
+  )
+}

package/src/lib/browser.ts

@@ -0,0 +1,150 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { paths } from './env'
+import { run } from './proc'
+
+/**
+ * `astrale browser` is a thin orchestrator over `agent-browser`
+ * (https://github.com/vercel-labs/agent-browser) — the Rust browser-automation
+ * CLI that AI agents drive. We own only the *session*: resolve the active
+ * instance's GUI origin, pin a persistent per-instance profile so the WorkOS
+ * login cookie survives across runs, and verify auth. Driving (snapshot/click/
+ * eval/…) is agent-browser's job, invoked directly by the agent afterward.
+ *
+ * Why a profile and not an injected token: the GUI session is an httpOnly
+ * sealed cookie (`astrale_router_session`) with no token-injection path, so the
+ * only way to "use my session" is to drive a browser whose profile already
+ * holds the cookie — minted once via interactive login, reused thereafter.
+ */
+
+export const BROWSER_DIR = join(paths.home, 'browser')
+export const BROWSER_SESSION_PATH = join(paths.home, 'browser.json')
+export const AGENT_BROWSER_REPO = 'vercel-labs/agent-browser'
+
+/** Per-instance persistent profile dir handed to `agent-browser --profile`. */
+export function profileDirFor(host: string): string {
+  return join(BROWSER_DIR, host)
+}
+
+/** The last-connected browser session, read by agents to know how to drive. */
+export type BrowserSession = {
+  /** GUI origin, e.g. `https://alpha1.eu.astrale.ai`. */
+  url: string
+  host: string
+  /** Profile dir, or null when attached to an external Chrome over CDP. */
+  profile: string | null
+  /** CDP endpoint (`9222` or a ws URL) when in attach mode. */
+  cdp: string | null
+  email?: string
+  updatedAt: string
+}
+
+export async function readSession(): Promise<BrowserSession | null> {
+  try {
+    return JSON.parse(await readFile(BROWSER_SESSION_PATH, 'utf8')) as BrowserSession
+  } catch {
+    return null
+  }
+}
+
+export async function saveSession(session: BrowserSession): Promise<void> {
+  await mkdir(paths.home, { recursive: true })
+  await writeFile(BROWSER_SESSION_PATH, `${JSON.stringify(session, null, 2)}\n`)
+}
+
+/** Resolve `agent-browser` on PATH; null when not installed. */
+export async function findAgentBrowser(): Promise<string | null> {
+  // `command -v` is a POSIX shell builtin (no `command` executable exists on
+  // Windows), so resolve via `where` on Windows and a shell on Unix.
+  const lookup =
+    process.platform === 'win32'
+      ? run('where', ['agent-browser'])
+      : run('sh', ['-c', 'command -v agent-browser'])
+  const res = await lookup.catch(() => null)
+  if (!res || res.code !== 0) return null
+  const path = res.stdout.split(/\r?\n/)[0]?.trim()
+  return path || null
+}
+
+export type AbResult = {
+  ok: boolean
+  data: unknown
+  error: string | null
+}
+
+/**
+ * Connection target for an agent-browser invocation: either a persistent
+ * profile dir or a CDP endpoint (mutually exclusive).
+ */
+export type AbTarget = { profile?: string; cdp?: string }
+
+/**
+ * Run an `agent-browser` command with `--json` and parse its envelope
+ * (`{success, data, error}`). Global flags (`--profile`/`--cdp`/`--headed`)
+ * precede the subcommand; `--json` trails the args, matching the CLI's parser.
+ */
+export async function ab(
+  args: string[],
+  opts: AbTarget & { headed?: boolean } = {},
+): Promise<AbResult> {
+  const argv = ['agent-browser']
+  if (opts.profile) argv.push('--profile', opts.profile)
+  if (opts.cdp) argv.push('--cdp', opts.cdp)
+  if (opts.headed) argv.push('--headed')
+  argv.push(...args, '--json')
+
+  const { code, stdout, stderr } = await run(argv[0], argv.slice(1))
+
+  try {
+    const parsed = JSON.parse(stdout) as { success?: boolean; data?: unknown; error?: string }
+    if (parsed && typeof parsed === 'object' && 'success' in parsed) {
+      return { ok: !!parsed.success, data: parsed.data ?? null, error: parsed.error ?? null }
+    }
+  } catch {
+    // fall through to exit-code interpretation
+  }
+  return { ok: code === 0, data: null, error: stderr.trim() || null }
+}
+
+// Reads the GUI session from whatever origin the page currently sits on. During
+// an interactive login the page is on the IdP origin, where `/auth/me` 404s and
+// the fetch rejects → {authed:false}; once the router redirects back to the GUI
+// it resolves to the authenticated user. Returned as a value (not top-level
+// await — agent-browser's `eval` forbids it) so page.evaluate auto-resolves it.
+const AUTH_EVAL =
+  "fetch('/auth/me',{credentials:'include'})" +
+  '.then(r=>r.json())' +
+  '.then(j=>({authed:!!j.authenticated,email:j.user&&j.user.email}))' +
+  '.catch(()=>({authed:false}))'
+
+export type AuthState = { authed: boolean; email?: string }
+
+function readAuthResult(res: AbResult): AuthState {
+  const result = (res.data as { result?: unknown } | null)?.result
+  if (result && typeof result === 'object') {
+    const r = result as { authed?: boolean; email?: string }
+    return { authed: !!r.authed, email: r.email }
+  }
+  return { authed: false }
+}
+
+/**
+ * Poll auth on the current page (no navigation — safe during login redirects).
+ * Pass `headed:true` while a sign-in window is open: agent-browser defaults to
+ * headless, so an unflagged command flips the live window back to headless and
+ * closes it.
+ */
+export async function pollAuth(target: AbTarget & { headed?: boolean }): Promise<AuthState> {
+  return readAuthResult(await ab(['eval', AUTH_EVAL], target))
+}
+
+/** Navigate to the GUI, then read auth (used for the silent reuse check). */
+export async function navigateAndCheck(
+  url: string,
+  target: AbTarget & { headed?: boolean },
+): Promise<AuthState> {
+  const opened = await ab(['open', url], target)
+  if (!opened.ok) return { authed: false }
+  return pollAuth(target)
+}

package/src/lib/command-dx.ts

@@ -0,0 +1,161 @@
+import type { Command, CommanderError } from 'commander'
+
+import chalk from 'chalk'
+
+export type CommandCatalogEntry = {
+  path: string[]
+  usage: string
+}
+
+export function collectCommandCatalog(program: Command): CommandCatalogEntry[] {
+  const out: CommandCatalogEntry[] = []
+
+  function walk(command: Command, path: string[]): void {
+    for (const child of command.commands) {
+      const childPath = [...path, child.name()]
+      if (child.commands.length === 0) {
+        out.push({ path: childPath, usage: usageFor(childPath, child) })
+      }
+      walk(child, childPath)
+    }
+  }
+
+  walk(program, [])
+  return out
+}
+
+export function renderCommanderError(
+  program: Command,
+  error: CommanderError,
+  argv = process.argv.slice(2),
+): string {
+  const tokens = stripOptions(argv)
+  const catalog = collectCommandCatalog(program)
+  const matched = matchRegisteredPrefix(program, tokens)
+
+  if (matched.path.length === 0 && tokens.length > 0) {
+    return renderUnknownCommand(tokens, catalog)
+  }
+
+  if (error.code === 'commander.missingArgument') {
+    const usage = usageFor(matched.path, matched.command)
+    const argName = error.message.match(/'([^']+)'/)?.[1]
+    return [
+      `Missing required argument${argName ? ` ${chalk.bold(`<${argName}>`)}` : ''} for ${chalk.bold(
+        `astrale ${matched.path.join(' ')}`,
+      )}`,
+      '',
+      'Usage:',
+      `  astrale ${usage}`,
+    ].join('\n')
+  }
+
+  if (error.code === 'commander.excessArguments') {
+    const usage = usageFor(matched.path, matched.command)
+    const extra = tokens.slice(matched.path.length).join(' ')
+    return [
+      `Unexpected argument${extra.includes(' ') ? 's' : ''} for ${chalk.bold(
+        `astrale ${matched.path.join(' ')}`,
+      )}${extra ? `: ${extra}` : ''}`,
+      '',
+      'Usage:',
+      `  astrale ${usage}`,
+    ].join('\n')
+  }
+
+  const suggestions = nearestCommands(tokens.join(' '), catalog)
+  return [
+    error.message,
+    ...(suggestions.length > 0
+      ? ['', 'Did you mean:', ...suggestions.map((s) => `  astrale ${s}`)]
+      : []),
+  ].join('\n')
+}
+
+function renderUnknownCommand(tokens: string[], catalog: CommandCatalogEntry[]): string {
+  const command = tokens.join(' ')
+  const first = tokens[0]
+  const namespaceMatches = catalog.filter((entry) => entry.path.at(-1) === first)
+  if (namespaceMatches.length > 0) {
+    return [
+      `Unknown command: ${chalk.bold(`astrale ${command}`)}`,
+      '',
+      `"${first}" is available under:`,
+      ...namespaceMatches.map((entry) => `  astrale ${entry.usage}`),
+    ].join('\n')
+  }
+
+  const suggestions = nearestCommands(command, catalog)
+  return [
+    `Unknown command: ${chalk.bold(`astrale ${command}`)}`,
+    ...(suggestions.length > 0
+      ? ['', 'Did you mean:', ...suggestions.map((s) => `  astrale ${s}`)]
+      : []),
+  ].join('\n')
+}
+
+function matchRegisteredPrefix(
+  program: Command,
+  tokens: string[],
+): { command: Command; path: string[] } {
+  let current = program
+  const path: string[] = []
+  for (const token of tokens) {
+    const next = current.commands.find(
+      (cmd) => cmd.name() === token || cmd.aliases().includes(token),
+    )
+    if (!next) break
+    current = next
+    path.push(current.name())
+  }
+  return { command: current, path }
+}
+
+function usageFor(path: string[], command: Command): string {
+  const suffix = command
+    .usage()
+    .replace(/\[options\]\s*/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return [path.join(' '), suffix].filter(Boolean).join(' ')
+}
+
+function stripOptions(argv: string[]): string[] {
+  const out: string[] = []
+  for (const token of argv) {
+    if (token === '--') break
+    if (token.startsWith('-')) continue
+    out.push(token)
+  }
+  return out
+}
+
+function nearestCommands(input: string, catalog: CommandCatalogEntry[]): string[] {
+  if (!input) return []
+  return catalog
+    .map((entry) => ({ usage: entry.usage, score: similarity(input, entry.path.join(' ')) }))
+    .filter((entry) => entry.score >= 0.45)
+    .sort((a, b) => b.score - a.score || a.usage.localeCompare(b.usage))
+    .slice(0, 3)
+    .map((entry) => entry.usage)
+}
+
+function similarity(a: string, b: string): number {
+  const max = Math.max(a.length, b.length)
+  if (max === 0) return 1
+  return 1 - levenshtein(a, b) / max
+}
+
+function levenshtein(a: string, b: string): number {
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+  const curr = Array.from({ length: b.length + 1 }, () => 0)
+  for (let i = 1; i <= a.length; i += 1) {
+    curr[0] = i
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost)
+    }
+    prev.splice(0, prev.length, ...curr)
+  }
+  return prev[b.length] ?? 0
+}

package/src/lib/concurrency.ts

@@ -0,0 +1,31 @@
+/**
+ * Minimal bounded-concurrency map. No external dependency (the repo
+ * hand-rolls with `Promise.all`); a tiny worker pool is enough for the
+ * `domain dev up` fan-out.
+ */
+
+/**
+ * Run `fn` over `items` with at most `limit` in flight at once. Results
+ * are returned in input order regardless of completion order. The first
+ * rejection rejects the returned promise (in-flight work still settles).
+ */
+export async function mapBounded<T, R>(
+  items: readonly T[],
+  limit: number,
+  fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = []
+  const bound = Math.max(1, Math.min(limit, items.length))
+  let next = 0
+
+  async function worker(): Promise<void> {
+    while (true) {
+      const i = next++
+      if (i >= items.length) return
+      results[i] = await fn(items[i] as T, i)
+    }
+  }
+
+  await Promise.all(Array.from({ length: bound }, () => worker()))
+  return results
+}

package/src/lib/config.ts

@@ -0,0 +1,45 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { z } from 'zod'
+
+import { AdminTargetConfigSchema, DEFAULT_ADMIN_TARGET_CONFIG } from './admin-target'
+import { log } from './log'
+import { CONFIG_PATH } from './paths'
+
+export const AstraleConfigSchema = z.object({
+  issuer: z.string().url().default('https://unregistered.invalid'),
+  admin: AdminTargetConfigSchema.default(DEFAULT_ADMIN_TARGET_CONFIG),
+})
+
+export type AstraleConfig = z.infer<typeof AstraleConfigSchema>
+
+export const DEFAULT_CONFIG: AstraleConfig = AstraleConfigSchema.parse({})
+
+export async function readConfig(): Promise<AstraleConfig> {
+  try {
+    const raw = await readFile(CONFIG_PATH, 'utf-8')
+    return AstraleConfigSchema.parse(JSON.parse(raw))
+  } catch (e) {
+    // A present-but-broken config (invalid JSON or failed validation) should
+    // surface; a missing file (readFile ENOENT) stays silent — that's the
+    // normal first-run case and defaults are expected.
+    if (e instanceof z.ZodError || e instanceof SyntaxError) {
+      log.warn(`Invalid config at ${CONFIG_PATH} — using defaults`)
+    }
+    return DEFAULT_CONFIG
+  }
+}
+
+export async function writeConfig(config: AstraleConfig): Promise<void> {
+  await mkdir(dirname(CONFIG_PATH), { recursive: true })
+  await writeFile(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n')
+}
+
+export async function configExists(): Promise<boolean> {
+  try {
+    await readFile(CONFIG_PATH)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/lib/domain-identity.ts

@@ -0,0 +1,49 @@
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+import { AstraleError } from '../errors'
+
+export async function loadPrivateJwk(keyPath: string): Promise<Record<string, unknown>> {
+  const filePath = resolve(keyPath)
+  const raw = await readFile(filePath, 'utf-8')
+  return JSON.parse(raw) as Record<string, unknown>
+}
+
+/**
+ * True when the kernel rejected an `installDomain` call because the
+ * identity binding's signature failed to verify — i.e. the private/public
+ * JWK halves don't match. Callers re-throw with a regenerate-the-keypair
+ * hint instead of leaking the raw `AuthenticationError`.
+ */
+export function isSignatureVerificationError(e: unknown): boolean {
+  if (!e || typeof e !== 'object') return false
+  const name = (e as { name?: unknown }).name
+  const msg = (e as { message?: unknown }).message
+  return (
+    name === 'AuthenticationError' &&
+    typeof msg === 'string' &&
+    /signature verification failed/i.test(msg)
+  )
+}
+
+/**
+ * Resolve the JOSE algorithm to use with this key. Prefers `privateJwk.alg`
+ * when present, falls back to inferring from `crv`/`kty` so keys generated
+ * by older CLIs (which didn't stamp `alg`) keep working without manual
+ * editing — see META_TRACE #34. Throws a clean error if neither path
+ * resolves an algorithm.
+ */
+export function inferAlg(privateJwk: Record<string, unknown>, keyPath?: string): string {
+  const explicit = privateJwk.alg
+  if (typeof explicit === 'string' && explicit.length > 0) return explicit
+  const crv = privateJwk.crv
+  const kty = privateJwk.kty
+  if (kty === 'EC' && crv === 'P-256') return 'ES256'
+  if (kty === 'OKP' && crv === 'Ed25519') return 'EdDSA'
+  const where = keyPath ? ` at ${keyPath}` : ''
+  throw new AstraleError(
+    'INVALID_KEY_FILE',
+    `JWK${where} is missing both \`alg\` and a recognizable \`(kty, crv)\` pair — cannot pick a signing algorithm.`,
+    'Re-stamp the file with `"alg": "ES256"` (P-256 EC keys) or `"alg": "EdDSA"` (Ed25519 OKP keys), or regenerate via `astrale domain init` / `astrale identity create`.',
+  )
+}

package/src/lib/env.ts

@@ -0,0 +1,49 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export type Paths = {
+  home: string
+  keys: string
+  data: string
+  config: string
+  install: string
+  identities: string
+  instances: string
+  idps: string
+  idpSessionsDir: string
+  /** Per-IdP config dir: `~/.astrale/idps/<name>/`. */
+  idpDir: (name: string) => string
+  /** Per-identity IdP session cache: `~/.astrale/idp-sessions/<name>.json`. */
+  idpSession: (identityName: string) => string
+}
+
+/**
+ * Resolve the Astrale home dir.
+ *
+ * Priority: explicit arg → `ASTRALE_HOME` env var → `$HOME/.astrale`.
+ */
+function resolveHome(home?: string): string {
+  return home ?? process.env.ASTRALE_HOME ?? join(homedir(), '.astrale')
+}
+
+export function createPaths(home?: string): Paths {
+  const base = resolveHome(home)
+  const idpsDir = join(base, 'idps')
+  const idpSessionsDir = join(base, 'idp-sessions')
+  return {
+    home: base,
+    keys: process.env.ASTRALE_KEYS_DIR ?? join(base, 'keys'),
+    data: process.env.ASTRALE_DATA_DIR ?? join(base, 'data'),
+    config: join(base, 'config.json'),
+    install: join(base, 'install.json'),
+    identities: join(base, 'identities.json'),
+    instances: join(base, 'instances.json'),
+    idps: join(idpsDir, 'index.json'),
+    idpSessionsDir,
+    idpDir: (name: string) => join(idpsDir, name),
+    idpSession: (identityName: string) => join(idpSessionsDir, `${identityName}.json`),
+  }
+}
+
+/** Default singleton used by all lib modules. */
+export const paths: Paths = createPaths()

package/src/lib/format.ts

@@ -0,0 +1,4 @@
+export function formatElapsed(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  return `${(ms / 1000).toFixed(2)}s`
+}