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

package/src/lib/view/session.ts

@@ -1,154 +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 }
-  /** Exact HTTPS origins the operator consented to open from this View session. */
-  externalOrigins: readonly string[]
-  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,43 +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
-  readonly variadic?: 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>

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,
-})