@astrale-os/cli 0.5.0-alpha.0 → 0.6.0-alpha.0

package/src/lib/view/session.ts

@@ -0,0 +1,123 @@
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { paths } from '../env'
+
+/**
+ * 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
+  view: {
+    url: string
+    functionId: string
+    handshake: 'shell' | 'none'
+    /** ViewPath or resolved view node path, when the view came from the graph. */
+    path?: string
+    name?: string
+  }
+  target?: { id?: string; path?: string }
+  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; caFile?: string; direct: boolean }
+  idleMs: number
+}
+
+export const recordPath = (id: string): string => join(VIEW_DIR, `${id}.json`)
+export const logPath = (id: string): string => join(VIEW_DIR, `${id}.log`)
+export const configPath = (id: string): string => join(VIEW_DIR, `${id}.config.json`)
+
+export async function saveRecord(record: ViewSessionRecord): Promise<void> {
+  await mkdir(VIEW_DIR, { recursive: true })
+  await writeFile(recordPath(record.id), `${JSON.stringify(record, null, 2)}\n`)
+}
+
+export async function removeSessionFiles(id: string): Promise<void> {
+  await Promise.all([
+    rm(recordPath(id), { force: true }),
+    rm(configPath(id), { force: true }),
+    rm(logPath(id), { 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

@@ -0,0 +1,101 @@
+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/program.ts

@@ -87,8 +87,10 @@ export async function buildProgram(): Promise<Command> {
   registerCommand(program, withKernelOptions((await import('./commands/describe')).default))
   registerCommand(program, withKernelOptions((await import('./commands/query')).default))
   registerCommand(program, withKernelOptions((await import('./commands/logs')).default))
+  registerCommand(program, withKernelOptions((await import('./commands/view')).default))
   registerCommand(program, (await import('./commands/status')).default)
   registerCommand(program, (await import('./commands/browser')).default)
+  registerCommand(program, (await import('./commands/view-serve')).default)
   registerCommand(program, (await import('./commands/studio')).default)
 
   registerGroup(program, {
@@ -153,6 +155,15 @@ export async function buildProgram(): Promise<Command> {
     ],
   })
 
+  registerGroup(program, {
+    name: 'session',
+    description: 'Locally recorded work sessions: list and DX-analyze them',
+    commands: [
+      (await import('./commands/session/list')).default,
+      (await import('./commands/session/analyze')).default,
+    ],
+  })
+
   registerGroup(program, {
     name: 'idp',
     description: 'Manage OpenID Connect identity providers',
@@ -192,7 +203,7 @@ Examples:
   $ astrale instance bookmark staging --url https://kernel.example.com
   $ astrale instance create my-app
   $ astrale instance status staging
-  $ astrale token --audience workspace.astrale.ai --ttl 3600
+  $ astrale token --audience shell.astrale.ai --ttl 3600
   $ astrale query / --depth 1
   $ astrale query --cypher 'MATCH (n) RETURN n LIMIT 5'
 `,

package/src/registry.ts

@@ -6,7 +6,7 @@ import type { CommandDefinition, CommandGroup } from './command'
  * Register a single command on a Commander program or subcommand.
  */
 export function registerCommand(parent: Command, def: CommandDefinition): void {
-  const cmd = parent.command(def.name).description(def.description)
+  const cmd = parent.command(def.name, { hidden: def.hidden ?? false }).description(def.description)
 
   if (def.summary) cmd.summary(def.summary)
 

package/src/setup/steps/instance.ts

@@ -3,7 +3,7 @@ import chalk from 'chalk'
 import type { SetupContext, SetupStep } from '../types'
 
 import { withAdminKernelClient } from '../../kernel/client'
-import { ADMIN_INSTANCE, type InstanceInfo } from '../../lib/admin-instance'
+import { adminInstanceMethod, type InstanceInfo } from '../../lib/admin-instance'
 import { normalizeInstanceKernelUrl, setActive, upsertManagedBookmark } from '../../lib/instance'
 import { readLocalStatus } from '../../lib/local-status'
 import { log, withSpinner } from '../../lib/log'
@@ -19,7 +19,7 @@ async function fetchManaged(ctx: SetupContext): Promise<InstanceInfo[]> {
       withAdminKernelClient(
         ctx.opts,
         async (client) =>
-          (await client.client.call(`${ADMIN_INSTANCE}/list`, {})) as InstanceInfo[],
+          (await client.client.call(adminInstanceMethod('list'), {})) as InstanceInfo[],
       ),
     )
   } catch {

package/src/telemetry/__tests__/gate.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test'
+
+import type { TelemetryEvent } from '../types'
+
+import { commandHead, extractSignals, hasSignals } from '../gate'
+
+function ev(argv: string[], exitCode: number, errorName?: string): TelemetryEvent {
+  return {
+    v: 1,
+    ts: '2026-07-10T10:00:00.000Z',
+    argv,
+    exitCode,
+    durationMs: 10,
+    errorName,
+    cwd: '/w',
+    root: '/w',
+    surface: 'cli',
+  }
+}
+
+describe('commandHead', () => {
+  test('keeps up to two leading command tokens, stops at flags/values', () => {
+    expect(commandHead(['get', '/path', '-i', 'x'])).toBe('get /path')
+    expect(commandHead(['domain', 'install', './foo'])).toBe('domain install')
+    expect(commandHead(['status'])).toBe('status')
+    expect(commandHead(['--help'])).toBe('(bare)')
+    expect(commandHead(['call', 'k=v'])).toBe('call')
+  })
+})
+
+describe('extractSignals / hasSignals', () => {
+  test('failures grouped by command with error names', () => {
+    const s = extractSignals([
+      ev(['domain', 'install'], 1, 'AUTH_ERROR'),
+      ev(['domain', 'install'], 1, 'AUTH_ERROR'),
+      ev(['status'], 0),
+    ])
+    expect(s.failures).toEqual([
+      { command: 'domain install', count: 2, errorNames: ['AUTH_ERROR'] },
+    ])
+    expect(s.retries).toEqual([])
+    expect(hasSignals(s)).toBe(true)
+  })
+
+  test('3+ runs of one command is a retry smell even when green', () => {
+    const s = extractSignals([ev(['get', '/a'], 0), ev(['get', '/a'], 0), ev(['get', '/a'], 0)])
+    expect(s.retries).toEqual([{ command: 'get /a', count: 3 }])
+    expect(hasSignals(s)).toBe(true)
+  })
+
+  test('quiet session has no signals until a transcript is attached', () => {
+    const s = extractSignals([ev(['status'], 0), ev(['ls', '/'], 0)])
+    expect(hasSignals(s)).toBe(false)
+    s.harnessSessions = [
+      {
+        harness: 'claude-code',
+        transcriptPath: '/t.jsonl',
+        sizeBytes: 1,
+      },
+    ]
+    expect(hasSignals(s)).toBe(true)
+  })
+})

package/src/telemetry/__tests__/recorder.test.ts

@@ -0,0 +1,110 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test'
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { Finalizer } from '../recorder'
+import type { SessionInfo } from '../store'
+import type { TelemetryEvent } from '../types'
+
+// ASTRALE_HOME must be set before the store/paths singleton is first imported.
+process.env.ASTRALE_HOME = mkdtempSync(join(tmpdir(), 'astrale-tele-recorder-'))
+
+let beginInvocation: (argv: string[]) => Finalizer
+let eventsPath: (id: string) => string
+let listSessions: () => SessionInfo[]
+let sessionsRoot: () => string
+let configPath: string
+
+const SESSION = 'rec-test'
+
+let work: string
+let cwd0: string
+
+beforeAll(async () => {
+  const recorder = await import('../recorder')
+  const store = await import('../store')
+  beginInvocation = recorder.beginInvocation
+  eventsPath = store.eventsPath
+  listSessions = store.listSessions
+  sessionsRoot = store.sessionsRoot
+  configPath = join(process.env.ASTRALE_HOME!, 'config.json')
+})
+
+beforeEach(() => {
+  // Destructive cleanup must be provably confined to this file's mkdtemp home.
+  if (!sessionsRoot().startsWith(tmpdir())) throw new Error('refusing to clean a non-tmp home')
+  rmSync(sessionsRoot(), { recursive: true, force: true })
+  rmSync(configPath, { force: true })
+  delete process.env.ASTRALE_TELEMETRY
+  process.env.ASTRALE_SESSION = SESSION
+  work = mkdtempSync(join(tmpdir(), 'astrale-tele-recwork-'))
+  cwd0 = process.cwd()
+  process.chdir(work)
+})
+
+afterEach(() => {
+  process.chdir(cwd0)
+  rmSync(work, { recursive: true, force: true })
+})
+
+function readEvents(id: string): TelemetryEvent[] {
+  return readFileSync(eventsPath(id), 'utf-8')
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => JSON.parse(l) as TelemetryEvent)
+}
+
+describe('beginInvocation', () => {
+  test('appends one valid, parseable event with redacted argv', () => {
+    const cwd = process.cwd()
+    const finalize = beginInvocation(['node', 'astrale', 'get', '--token', 'abc', 'x'])
+    finalize(0)
+
+    const events = readEvents(SESSION)
+    expect(events).toHaveLength(1)
+    const [e] = events
+    expect(e.v).toBe(1)
+    expect(e.surface).toBe('cli')
+    expect(e.exitCode).toBe(0)
+    expect(e.argv).toEqual(['get', '--token', '<redacted>', 'x'])
+    expect(e.cwd).toBe(cwd)
+    expect(e.root).toBe(cwd)
+    expect(typeof e.ts).toBe('string')
+    expect(typeof e.durationMs).toBe('number')
+    expect('errorName' in e).toBe(false)
+  })
+
+  test('records exitCode and errorName on failure', () => {
+    beginInvocation(['node', 'astrale', 'call', 'foo'])(1, 'AuthError')
+    const [e] = readEvents(SESSION)
+    expect(e.exitCode).toBe(1)
+    expect(e.errorName).toBe('AuthError')
+  })
+
+  test('appends a second line on a second invocation', () => {
+    beginInvocation(['node', 'astrale', 'query'])(0)
+    beginInvocation(['node', 'astrale', 'whoami'])(0)
+    expect(readEvents(SESSION)).toHaveLength(2)
+  })
+
+  test('writes nothing for help/version-only invocations', () => {
+    beginInvocation(['node', 'astrale', '--help'])(0)
+    beginInvocation(['node', 'astrale', '--version'])(0)
+    beginInvocation(['node', 'astrale'])(0)
+    expect(listSessions()).toHaveLength(0)
+  })
+
+  test('writes nothing when disabled via ASTRALE_TELEMETRY', () => {
+    process.env.ASTRALE_TELEMETRY = '0'
+    beginInvocation(['node', 'astrale', 'get', 'x'])(0)
+    expect(listSessions()).toHaveLength(0)
+    expect(existsSync(eventsPath(SESSION))).toBe(false)
+  })
+
+  test('writes nothing when disabled via config telemetry.enabled=false', () => {
+    writeFileSync(configPath, JSON.stringify({ telemetry: { enabled: false } }))
+    beginInvocation(['node', 'astrale', 'get', 'x'])(0)
+    expect(listSessions()).toHaveLength(0)
+  })
+})

package/src/telemetry/__tests__/redact.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from 'bun:test'
+
+import { redactArgv } from '../redact'
+
+describe('redactArgv', () => {
+  test('redacts the value following a secret flag', () => {
+    expect(redactArgv(['--token', 'abc123', '--json'])).toEqual(['--token', '<redacted>', '--json'])
+  })
+
+  test('matches secret substrings in flag names, case-insensitively', () => {
+    expect(redactArgv(['--api-Token', 's', '--Bearer', 'b', '--jwk', 'k'])).toEqual([
+      '--api-Token',
+      '<redacted>',
+      '--Bearer',
+      '<redacted>',
+      '--jwk',
+      '<redacted>',
+    ])
+  })
+
+  test('redacts the value part of inline k=v secret args', () => {
+    expect(redactArgv(['--secret=hunter2', 'password=p', '--verbose'])).toEqual([
+      '--secret=<redacted>',
+      'password=<redacted>',
+      '--verbose',
+    ])
+  })
+
+  test('leaves non-secret flags and their values intact', () => {
+    expect(redactArgv(['get', '--depth', '3', '--format=json'])).toEqual([
+      'get',
+      '--depth',
+      '3',
+      '--format=json',
+    ])
+  })
+
+  test('truncates any arg longer than 200 chars to 200 + ellipsis', () => {
+    const long = 'x'.repeat(300)
+    const [only] = redactArgv([long])
+    expect(only).toBe('x'.repeat(200) + '…')
+    expect([...only].length).toBe(201)
+  })
+
+  test('a secret value is redacted before length matters', () => {
+    expect(redactArgv(['--password', 'y'.repeat(500)])).toEqual(['--password', '<redacted>'])
+  })
+
+  test('caps the array at 40 items with a …+N marker', () => {
+    const args = Array.from({ length: 45 }, (_, i) => `a${i}`)
+    const out = redactArgv(args)
+    expect(out.length).toBe(41)
+    expect(out.slice(0, 40)).toEqual(args.slice(0, 40))
+    expect(out[40]).toBe('…+5')
+  })
+
+  test('does not cap at exactly 40 items', () => {
+    const args = Array.from({ length: 40 }, (_, i) => `a${i}`)
+    expect(redactArgv(args)).toEqual(args)
+  })
+
+  test('a trailing secret flag with no value does not throw', () => {
+    expect(redactArgv(['call', '--token'])).toEqual(['call', '--token'])
+  })
+})
+
+describe('secret-shaped values', () => {
+  test('positional JWT is redacted wherever it appears', () => {
+    const jwt =
+      'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U'
+    expect(redactArgv(['call', '/x::y', jwt])).toEqual(['call', '/x::y', '<redacted>'])
+    expect(redactArgv(['call', `body=Bearer ${jwt}`])[1]).toBe('body=Bearer <redacted>')
+  })
+  test('sk- style api key is redacted, plain paths are not', () => {
+    expect(redactArgv(['x', 'sk-abcdefghijklmnop1234'])).toEqual(['x', '<redacted>'])
+    const p = '/Users/someone/Documents/astrale/workspace/cli/src/telemetry/adapters/index.ts'
+    expect(redactArgv([p])).toEqual([p])
+  })
+})