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

package/src/lib/output.ts

@@ -1,238 +0,0 @@
-import chalk from 'chalk'
-import { stringify as yamlStringify } from 'yaml'
-
-import { invocationWantsMachine } from './invocation'
-import { renderTable, type Column } from './table'
-
-export type { Column } from './table'
-
-export type OutputOpts = {
-  raw?: boolean
-  json?: boolean
-  format?: 'yaml' | 'json'
-}
-
-export type RawOutputOpts = Pick<OutputOpts, 'raw' | 'json'>
-
-export type MachineOpts = RawOutputOpts & { readonly ci?: boolean }
-
-export const RAW_OUTPUT_OPTIONS = [
-  { flags: '--json', description: 'JSON; streaming commands emit one JSON value per line' },
-  { flags: '--raw', description: 'Unwrapped: bare scalar / raw bytes / JSON for objects' },
-] as const
-
-/**
- * Is the consumer a machine (emit structured data, not a pretty view)?
- * True for `--json`, `--raw`, `--ci`, a process-wide `--ci/--json/--raw` on argv,
- * or any non-TTY stdout (pipe, redirect, agent).
- */
-export function isMachine(opts?: MachineOpts): boolean {
-  return (
-    !!(opts?.raw || opts?.json || opts?.ci) ||
-    invocationWantsMachine() ||
-    !(process.stdout.isTTY ?? false)
-  )
-}
-
-/**
- * `--raw` = the *unwrapped* value (bare scalar, raw bytes). The raw-vs-json
- * distinction only manifests for scalars and binary; objects/arrays fall back
- * to JSON under either flag.
- */
-export function isUnwrapped(opts?: RawOutputOpts): boolean {
-  return !!opts?.raw
-}
-
-/**
- * Write structured data to stdout in the appropriate format.
- *
- * Precedence:
- * - `--raw` / `--json` → plain JSON, no colors (machine-readable)
- * - explicit `--format yaml|json` → honor regardless of TTY, colors only on TTY
- * - default on TTY → highlighted YAML
- * - default on non-TTY → plain JSON
- *
- * Void-returning syscalls surface as `undefined` here; `JSON.stringify(undefined)`
- * itself returns `undefined`, which would print the bare string `undefined` and
- * break any caller doing `JSON.parse(stdout)`. Normalize to `null` (parseable
- * JSON, valid YAML) at the entry so every formatter branch is consistent.
- */
-export function output(data: unknown, opts: OutputOpts): void {
-  if (data === undefined) data = null
-
-  if (opts.raw || opts.json) {
-    process.stdout.write(JSON.stringify(data, null, 2) + '\n')
-    return
-  }
-
-  const isTTY = process.stdout.isTTY ?? false
-
-  if (opts.format === 'json') {
-    const rendered = isTTY ? highlightJson(data) : JSON.stringify(data, null, 2)
-    process.stdout.write(rendered + '\n')
-    return
-  }
-
-  if (opts.format === 'yaml') {
-    const rendered = isTTY
-      ? highlightYaml(data)
-      : yamlStringify(data, { indent: 2, lineWidth: 120 }).trimEnd()
-    process.stdout.write(rendered + '\n')
-    return
-  }
-
-  // Default: TTY → highlighted YAML, non-TTY → plain JSON
-  if (isTTY) {
-    process.stdout.write(highlightYaml(data) + '\n')
-  } else {
-    process.stdout.write(JSON.stringify(data, null, 2) + '\n')
-  }
-}
-
-// ── YAML ───────────────────────────────────────────────────
-
-function highlightYaml(data: unknown): string {
-  const raw = yamlStringify(data, { indent: 2, lineWidth: 120 })
-  return raw
-    .replace(
-      /^(\s*-?\s*)([\w.-]+)(:)\s*(.*)/gm,
-      (_, indent: string, key: string, colon: string, value: string) =>
-        `${indent}${chalk.cyan(key)}${colon} ${colorYamlValue(value)}`,
-    )
-    .trimEnd()
-}
-
-function colorYamlValue(value: string): string {
-  if (value === 'null' || value === '~') return chalk.dim('null')
-  if (value === 'true' || value === 'false') return chalk.magenta(value)
-  if (/^-?\d+(\.\d+)?$/.test(value)) return chalk.yellow(value)
-  return chalk.green(value)
-}
-
-// ── JSON ───────────────────────────────────────────────────
-
-function highlightJson(data: unknown): string {
-  const json = JSON.stringify(data, null, 2)
-  return json
-    .replace(/"([^"]+)"(?=\s*:)/g, (_, key: string) => chalk.cyan(`"${key}"`))
-    .replace(/: "([^"]*)"(?=[,\n\r\]}])/g, (_, val: string) => `: ${chalk.green(`"${val}"`)}`)
-    .replace(/: (-?\d+\.?\d*(?:e[+-]?\d+)?)\b/gi, (_, num: string) => `: ${chalk.yellow(num)}`)
-    .replace(/: (true|false)\b/g, (_, bool: string) => `: ${chalk.magenta(bool)}`)
-    .replace(/: (null)\b/g, () => `: ${chalk.dim('null')}`)
-}
-
-// ── present: shape-aware rendering ──────────────────────────
-
-export type PresentOpts = OutputOpts & { denoise?: boolean }
-
-/** One display row per item plus the columns and (optional) `-q` paths. */
-export type ListProjection = {
-  columns: Column[]
-  rows: Array<Record<string, string>>
-  paths?: string[]
-}
-
-export type ListOpts = OutputOpts & {
-  quiet?: boolean
-  count?: boolean
-  long?: boolean
-}
-
-const NOISE_KEYS = new Set(['schema', 'icon', 'code', 'inputSchema', 'outputSchema'])
-
-function isNoiseKey(key: string): boolean {
-  if (NOISE_KEYS.has(key)) return true
-  const dot = key.lastIndexOf('.')
-  const colon = key.lastIndexOf(':')
-  const split = Math.max(dot, colon)
-  return split >= 0 && NOISE_KEYS.has(key.slice(split + 1))
-}
-
-/**
- * Strip heavy, low-signal keys (serialized schema blobs, SVG icons, code) at any
- * depth — so machine output is the kernel's data minus the noise, never a wall.
- */
-export function denoise(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(denoise)
-  if (value && typeof value === 'object') {
-    const out: Record<string, unknown> = {}
-    for (const [k, v] of Object.entries(value)) {
-      if (isNoiseKey(k)) continue
-      out[k] = v && typeof v === 'object' ? denoise(v) : v
-    }
-    return out
-  }
-  return value
-}
-
-function isBareScalar(v: unknown): v is string | number | boolean {
-  return typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean'
-}
-
-/**
- * Present a single kernel value, shape- and audience-aware.
- *
- * - scalar → `--raw` bare (no quotes, for `X=$(…)`) · `--json`/pipe JSON · TTY bare
- * - object → YAML on a TTY, JSON for machines (delegates to {@link output})
- * - array  → YAML/JSON fallback (use {@link presentList} for a table)
- *
- * `null`/`undefined` normalize to `null` (via `output`) so `JSON.parse(stdout)`
- * never breaks.
- */
-export function present(value: unknown, opts: PresentOpts = {}): void {
-  const data = opts.denoise ? denoise(value) : value
-
-  if (isBareScalar(data)) {
-    if (opts.raw) {
-      process.stdout.write(String(data) + '\n')
-      return
-    }
-    if (!opts.json && (process.stdout.isTTY ?? false)) {
-      process.stdout.write(String(data) + '\n')
-      return
-    }
-    // `--json` or non-TTY machine → JSON (quoted string / bare number).
-  }
-
-  output(data, opts)
-}
-
-/**
- * Present an array of objects.
- *
- * - `--count`     → just the number
- * - `-q/--quiet`  → one path per line (unix-pipeable)
- * - machine       → denoised JSON of the raw items (`-l` keeps full items)
- * - TTY           → an aligned table + a dim count footer
- *
- * Projection (columns/rows/paths) is for the human table and `-q` only; the
- * machine surface stays the kernel's own item fields.
- */
-export function presentList<T>(
-  items: T[],
-  opts: ListOpts,
-  project: (items: T[]) => ListProjection,
-): void {
-  if (opts.count) {
-    process.stdout.write(String(items.length) + '\n')
-    return
-  }
-
-  if (opts.quiet) {
-    const proj = project(items)
-    const paths = proj.paths ?? proj.rows.map((r) => r[proj.columns[0]?.key ?? ''] ?? '')
-    for (const p of paths) process.stdout.write(p + '\n')
-    return
-  }
-
-  if (isMachine(opts) || opts.format) {
-    output(opts.long ? items : denoise(items), opts)
-    return
-  }
-
-  const proj = project(items)
-  const table = renderTable(proj.rows, { columns: proj.columns })
-  const footer =
-    items.length > 0 ? chalk.dim(`\n  ${items.length} item${items.length === 1 ? '' : 's'}`) : ''
-  process.stdout.write(table + footer + '\n')
-}

package/src/lib/panel.ts

@@ -1,61 +0,0 @@
-import chalk from 'chalk'
-
-// ESC[…m — built without a control char in the source so no lint disable is needed.
-const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g')
-
-/** Printable width of a string, ignoring ANSI color codes. */
-function visibleWidth(s: string): number {
-  return s.replace(ANSI, '').length
-}
-
-const BOX = { tl: '╭', tr: '╮', bl: '╰', br: '╯', h: '─', v: '│' } as const
-
-export type PanelOpts = {
-  /** Colorize the box border (default: cyan). */
-  borderColor?: (s: string) => string
-  /** Horizontal padding inside the box (default: 3). */
-  padX?: number
-  /** Left margin in spaces for the whole box (default: 2). */
-  margin?: number
-}
-
-/**
- * Draw a rounded box around pre-styled lines. Widths are computed on *visible*
- * length so embedded ANSI (bold/color/underline) never breaks alignment. The
- * lines are passed in already colored — `panel` only frames them.
- */
-export function panel(lines: string[], opts: PanelOpts = {}): string {
-  const padX = opts.padX ?? 3
-  const margin = ' '.repeat(opts.margin ?? 2)
-  const border = opts.borderColor ?? chalk.cyan
-  const inner = Math.max(0, ...lines.map(visibleWidth))
-  const span = inner + padX * 2
-
-  const top = margin + border(BOX.tl + BOX.h.repeat(span) + BOX.tr)
-  const bottom = margin + border(BOX.bl + BOX.h.repeat(span) + BOX.br)
-  const body = lines.map((line) => {
-    const fill = ' '.repeat(inner - visibleWidth(line))
-    return (
-      margin + border(BOX.v) + ' '.repeat(padX) + line + fill + ' '.repeat(padX) + border(BOX.v)
-    )
-  })
-  return [top, ...body, bottom].join('\n')
-}
-
-/**
- * The provisioned-instance hero: a bright, click-inviting panel that puts the
- * fresh instance URL front and center. Rendered only in interactive (human)
- * mode — machine output carries the URL in its JSON instead.
- */
-export function renderInstanceHero(slug: string, url: string): string {
-  return panel(
-    [
-      `${chalk.green('✦')}  ${chalk.bold('Your instance is live')}`,
-      '',
-      `   ${chalk.bold.cyan.underline(url)}`,
-      '',
-      chalk.dim(`   ${slug} · ⌘-click the link or paste it into your browser`),
-    ],
-    { borderColor: chalk.cyan },
-  )
-}

package/src/lib/port.ts

@@ -1,41 +0,0 @@
-import net from 'node:net'
-
-/**
- * Loopback port helpers for launching local servers (e.g. `astrale studio`).
- *
- * We probe by ACTUALLY trying to bind, not by connecting — a connect-probe to
- * 127.0.0.1 is racy and can falsely pass on a half-open socket. Whatever port
- * the OS lets us bind is, by definition, free for us right now. We bind on the
- * loopback interface specifically (matching the studio's 127.0.0.1 bind) with
- * `exclusive: true` so the probe never "succeeds" on a port another process
- * holds via SO_REUSEADDR/REUSEPORT.
- */
-const LOOPBACK = '127.0.0.1'
-
-/** Resolves true if [port] can be bound on loopback right now, false otherwise. */
-export function portFree(port: number, host = LOOPBACK): Promise<boolean> {
-  return new Promise((resolve) => {
-    const srv = net.createServer()
-    srv.once('error', () => resolve(false))
-    srv.once('listening', () => srv.close(() => resolve(true)))
-    srv.listen({ port, host, exclusive: true })
-  })
-}
-
-/**
- * First free port in [start, start + span) on loopback, or null if the whole
- * window is taken. We deliberately scan a small band in the IANA Registered
- * range (well below the OS ephemeral range, which starts at 49152 on
- * macOS/BSD and 32768 on Linux) so a probe can't collide with a short-lived
- * outbound socket the OS hands out a microsecond later.
- */
-export async function findFreePort(
-  start: number,
-  span = 20,
-  host = LOOPBACK,
-): Promise<number | null> {
-  for (let p = start; p < start + span; p++) {
-    if (await portFree(p, host)) return p
-  }
-  return null
-}

package/src/lib/proc.ts

@@ -1,87 +0,0 @@
-import { spawn, type ChildProcess, type StdioOptions } from 'node:child_process'
-
-export type RunResult = {
-  /** Exit code, or -1 when the process was killed by a signal. */
-  code: number
-  stdout: string
-  stderr: string
-}
-
-/**
- * Spawn a child process and capture stdout/stderr as UTF-8 text.
- *
- * Uses `node:child_process` rather than `Bun.spawn` so the exact same code runs
- * under both the Bun-compiled standalone binary (Linux/macOS) and the Node/npm
- * build (Windows and any Node user). The promise rejects only when the process
- * fails to spawn (e.g. ENOENT); a non-zero exit resolves with that `code` so
- * callers can branch on it.
- */
-export function run(
-  file: string,
-  args: string[] = [],
-  opts: { cwd?: string } = {},
-): Promise<RunResult> {
-  return new Promise((resolve, reject) => {
-    const child = spawn(file, args, {
-      cwd: opts.cwd,
-      shell: false,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    })
-    let stdout = ''
-    let stderr = ''
-    child.stdout?.setEncoding('utf8')
-    child.stderr?.setEncoding('utf8')
-    child.stdout?.on('data', (chunk: string) => {
-      stdout += chunk
-    })
-    child.stderr?.on('data', (chunk: string) => {
-      stderr += chunk
-    })
-    child.on('error', reject)
-    child.on('close', (code) => resolve({ code: code ?? -1, stdout, stderr }))
-  })
-}
-
-/**
- * Spawn a child process with inherited stdio so its output streams live to the
- * user's terminal. Used for hand-held installs (npm / npx) where progress
- * matters and the output is for the human, not for parsing. Resolves with the
- * exit code; rejects only when the process fails to spawn (e.g. ENOENT).
- */
-export function runInherit(
-  file: string,
-  args: string[] = [],
-  opts: { cwd?: string } = {},
-): Promise<number> {
-  return new Promise((resolve, reject) => {
-    const child = spawn(file, args, { cwd: opts.cwd, shell: false, stdio: 'inherit' })
-    child.on('error', reject)
-    child.on('close', (code) => resolve(code ?? -1))
-  })
-}
-
-/**
- * Spawn a LONG-LIVED child and return the handle immediately so the caller can
- * supervise it (wait for exit, forward signals, tear down siblings). Unlike
- * run()/runInherit() — which resolve only once the child closes — this is for
- * servers the command keeps attached to (e.g. `astrale studio`'s Bun server and
- * Vite dev process). Same node:child_process basis (cross-runtime) and bare
- * PATH-name lookup convention. Default stdio streams stdout/stderr live but
- * ignores stdin, so two supervised children never contend for the TTY.
- */
-export function spawnHandle(
-  file: string,
-  args: string[] = [],
-  opts: { cwd?: string; env?: NodeJS.ProcessEnv; stdio?: StdioOptions; detached?: boolean } = {},
-): ChildProcess {
-  return spawn(file, args, {
-    cwd: opts.cwd,
-    env: opts.env,
-    shell: false,
-    // `detached` makes the child its own process-group leader so the caller can
-    // tear down the whole tree (the child AND its grandchildren) with a single
-    // group signal — `process.kill(-child.pid, …)`.
-    detached: opts.detached,
-    stdio: opts.stdio ?? ['ignore', 'inherit', 'inherit'],
-  })
-}

package/src/lib/prompt.ts

@@ -1,136 +0,0 @@
-import { checkbox, confirm as confirmPrompt, input, select } from '@inquirer/prompts'
-import chalk from 'chalk'
-import { createInterface } from 'node:readline/promises'
-
-// All interactive prompts go through `@inquirer/prompts` so a single library
-// owns stdin (raw mode, keypress handling, cleanup). Hand-rolling some prompts
-// with `node:readline` alongside inquirer used to fight over the TTY — the
-// raw↔line-mode handoff swallowed the first keystroke, so a step right after an
-// inquirer prompt needed a double Enter. One owner, no handoff, no lost keys.
-//
-// Every helper guards on `process.stdin.isTTY` BEFORE touching inquirer (which
-// requires a TTY): a piped / CI / no-TTY (LLM) run returns the default
-// immediately and renders nothing, so callers never hang on a read.
-
-/**
- * Prompt the user for Y/N confirmation (default No). Returns false in non-TTY
- * environments (use --yes / a flag to bypass).
- */
-export async function confirm(message: string): Promise<boolean> {
-  if (!process.stdin.isTTY) return false
-  return confirmPrompt({ message, default: false })
-}
-
-/**
- * Prompt with a Y default — "Y/n" semantics. Returns true unless the user
- * explicitly declines; returns true in non-TTY.
- */
-export async function confirmDefaultYes(message: string): Promise<boolean> {
-  if (!process.stdin.isTTY) return true
-  return confirmPrompt({ message, default: true })
-}
-
-/**
- * Prompt the user to type a specific string to confirm a dangerous action.
- * Returns false in non-TTY environments (use a flag to bypass).
- */
-export async function confirmWithInput(message: string, expected: string): Promise<boolean> {
-  if (!process.stdin.isTTY) return false
-  process.stdout.write(chalk.yellow(`${message}\n`))
-  const answer = await input({ message: `Type "${expected}" to confirm:` })
-  return answer.trim() === expected
-}
-
-/**
- * Free-text prompt (a styled `@inquirer/prompts` input — shows the default,
- * supports inline `validate` with live re-ask). Returns the typed value, or the
- * default on empty input (`undefined` when none) in a non-TTY run.
- */
-export async function promptText(
-  message: string,
-  opts: { default?: string; validate?: (value: string) => boolean | string } = {},
-): Promise<string | undefined> {
-  if (!process.stdin.isTTY) return opts.default
-  const answer = await input({
-    message,
-    ...(opts.default !== undefined ? { default: opts.default } : {}),
-    ...(opts.validate ? { validate: opts.validate } : {}),
-  })
-  return answer.trim() || opts.default
-}
-
-/**
- * Single-choice selector (arrow-key `@inquirer/prompts` select). Returns the
- * chosen value, or `undefined` in a non-TTY environment.
- */
-export async function promptSelect<T>(
-  message: string,
-  choices: Array<{ name: string; value: T; description?: string }>,
-): Promise<T | undefined> {
-  if (!process.stdin.isTTY) return undefined
-  return select({ message, choices })
-}
-
-/**
- * Multi-choice selector (a styled `@inquirer/prompts` checkbox — space toggles,
- * enter confirms). Pre-check options with `checked: true`. Returns the chosen
- * values, or `undefined` in a non-TTY environment.
- */
-export async function promptMultiSelect<T>(
-  message: string,
-  choices: Array<{ name: string; value: T; checked?: boolean; description?: string }>,
-): Promise<T[] | undefined> {
-  if (!process.stdin.isTTY) return undefined
-  return checkbox({ message, choices })
-}
-
-/**
- * Single-choice selector over labeled values. Returns the chosen value, or
- * `null` in a non-TTY environment (callers decide how to fail). In a terminal
- * the user always picks one (Enter selects the highlighted option; Ctrl-C
- * aborts the command), so `null` only ever signals "no TTY".
- */
-export async function selectFrom<T>(
-  message: string,
-  choices: Array<{ label: string; value: T }>,
-): Promise<T | null> {
-  if (!process.stdin.isTTY) return null
-  return select({ message, choices: choices.map((c) => ({ name: c.label, value: c.value })) })
-}
-
-/** Prompt a passphrase without echoing. Fails in non-TTY unless env override. */
-export async function readPassphrase(
-  message: string,
-  opts: { minLength?: number } = {},
-): Promise<string> {
-  const env = process.env.ASTRALE_PASSPHRASE
-  if (env) return env
-  if (!process.stdin.isTTY) {
-    throw new Error('Passphrase required but no TTY. Pipe via ASTRALE_PASSPHRASE env var.')
-  }
-  // v1 note: passphrase echoes on interactive terminals. Pipe
-  // ASTRALE_PASSPHRASE=... for scripted flows. Silent stdin with raw
-  // mode is roadmap (requires terminal capabilities handling).
-  process.stdout.write(chalk.yellow(message))
-  const answer = await readLine()
-  process.stdout.write('\n')
-  if (opts.minLength && answer.length < opts.minLength) {
-    throw new Error(`Passphrase too short (min ${opts.minLength} chars)`)
-  }
-  return answer
-}
-
-/**
- * Read one line from stdin via Node's own line reader (stdlib, zero-dep).
- * Used only by `readPassphrase` (a single-shot prompt that intentionally echoes
- * and honors ASTRALE_PASSPHRASE) — every navigational prompt uses inquirer.
- * Only ever reached behind an `isTTY` gate, so it never blocks a piped run.
- */
-async function readLine(): Promise<string> {
-  const rl = createInterface({ input: process.stdin, output: process.stdout })
-  try {
-    return (await rl.question('')).trim()
-  } finally {
-    rl.close()
-  }
-}