@brimveyn/aimux 1.16.3 → 1.18.2

package/src/cli/index.ts

@@ -0,0 +1,258 @@
+import type { DaemonClient } from './client/daemon-client'
+import type { CliContext } from './context'
+
+import { connectToDaemon, DaemonUnreachableError } from './client/bootstrap'
+import { resolveWorkspace } from './client/workspace-resolver'
+import { type ArgSpec, CliUsageError, type FlagSpec, parseArgs, SHARED_FLAGS } from './flags'
+import {
+  EXIT_DAEMON_UNREACHABLE,
+  EXIT_OK,
+  EXIT_RUNTIME,
+  EXIT_USAGE,
+  writeError,
+  writeJson,
+} from './output'
+import { type CliCommand, COMMANDS, resolveCommand } from './registry'
+
+const EXIT_CODES_BLOCK = [
+  'Exit codes:',
+  '  0    success',
+  '  2    usage error (bad flags, unknown command, missing argument)',
+  '  3    runtime error (server replied with error, command failed)',
+  '  4    daemon unreachable (socket missing and autostart failed)',
+  '  124  timeout (tab wait, tab tail --timeout, workspace switch --wait)',
+].join('\n')
+
+const OUTPUT_CONTRACT_BLOCK = [
+  'Output contract:',
+  '  stdout  one JSON object per command (NDJSON for `tab tail`, `tab wait`)',
+  '  stderr  human-readable error lines, prefixed with `aimux:`',
+].join('\n')
+
+function groupByCommand(commands: readonly CliCommand[]): Map<string, CliCommand[]> {
+  const byGroup = new Map<string, CliCommand[]>()
+  for (const command of commands) {
+    const existing = byGroup.get(command.group) ?? []
+    existing.push(command)
+    byGroup.set(command.group, existing)
+  }
+  return byGroup
+}
+
+function isSharedFlag(name: string): boolean {
+  return SHARED_FLAGS.some((f) => f.name === name)
+}
+
+function formatArgs(args: readonly ArgSpec[]): string {
+  if (args.length === 0) return ''
+  return args.map((a) => (a.required === true ? `<${a.name}>` : `[${a.name}]`)).join(' ')
+}
+
+function flagValueHint(flag: FlagSpec): string {
+  if (flag.kind === 'boolean') return ''
+  if (flag.kind === 'number') return ' <n>'
+  return ` <${flag.name}>`
+}
+
+function formatFlagLine(flag: FlagSpec): string {
+  const head = `  --${flag.name}${flagValueHint(flag)}`.padEnd(32)
+  return `${head}${flag.description ?? ''}`
+}
+
+function printHelp(): void {
+  process.stdout.write(
+    [
+      'aimux CLI control plane — drive workspaces, worktrees, and tabs from scripts.',
+      '',
+      'Usage:',
+      '  aimux <group> <verb> [flags] [args]',
+      '  aimux <group> --help                        List verbs in a group',
+      '  aimux <group> <verb> --help                 Show flags/args for a verb',
+      '',
+      'Groups:',
+      '',
+    ].join('\n')
+  )
+
+  const byGroup = groupByCommand(COMMANDS)
+  for (const [group, commands] of byGroup) {
+    process.stdout.write(`  ${group}\n`)
+    for (const command of commands) {
+      const args = formatArgs(command.args)
+      const signature = `aimux ${group} ${command.verb}${args === '' ? '' : ` ${args}`}`
+      process.stdout.write(`    ${signature.padEnd(46)} ${command.summary}\n`)
+    }
+    process.stdout.write('\n')
+  }
+
+  process.stdout.write(
+    [
+      'Shared flags (accepted by every command):',
+      ...SHARED_FLAGS.map(formatFlagLine),
+      '',
+      OUTPUT_CONTRACT_BLOCK,
+      '',
+      EXIT_CODES_BLOCK,
+      '',
+      'Env:',
+      '  AIMUX_PROFILE                  Runtime profile (state dir, socket paths); --profile overrides.',
+      '',
+      'Agent recipes:',
+      '  # spawn Claude in a new tab, wait until it idles, snapshot the screen',
+      '  TAB=$(aimux tab create --assistant claude --title fixup | jq -r .tabId)',
+      '  aimux tab send "$TAB" "explain this repo" --enter',
+      '  aimux tab wait "$TAB" --status idle --timeout 60000',
+      '  aimux tab snapshot "$TAB" --tail 40 --format text',
+      '',
+      '  # stream renders as NDJSON (one event per line)',
+      '  aimux tab tail "$TAB" --rate-limit-ms 100 --follow-status',
+      '',
+    ].join('\n')
+  )
+}
+
+function printGroupHelp(group: string): void {
+  const commands = COMMANDS.filter((c) => c.group === group)
+  if (commands.length === 0) {
+    printHelp()
+    return
+  }
+  process.stdout.write(
+    [
+      `aimux ${group} — ${commands.length} verb${commands.length === 1 ? '' : 's'}`,
+      '',
+      'Usage:',
+      `  aimux ${group} <verb> [flags] [args]`,
+      `  aimux ${group} <verb> --help    Show flags/args for a verb`,
+      '',
+      'Verbs:',
+      '',
+    ].join('\n')
+  )
+  for (const command of commands) {
+    const args = formatArgs(command.args)
+    const signature = `aimux ${group} ${command.verb}${args === '' ? '' : ` ${args}`}`
+    process.stdout.write(`  ${signature.padEnd(46)} ${command.summary}\n`)
+  }
+  process.stdout.write('\n')
+}
+
+function printCommandHelp(command: CliCommand): void {
+  const args = formatArgs(command.args)
+  const signature = `aimux ${command.group} ${command.verb}${args === '' ? '' : ` ${args}`}`
+  process.stdout.write([signature, '', `  ${command.summary}`, '', 'Flags:', ''].join('\n'))
+  const own = command.flags.filter((f) => !isSharedFlag(f.name))
+  if (own.length === 0) {
+    process.stdout.write('  (this command takes only the shared flags)\n')
+  } else {
+    for (const flag of own) process.stdout.write(`${formatFlagLine(flag)}\n`)
+  }
+  process.stdout.write('\nShared flags:\n')
+  for (const flag of SHARED_FLAGS) process.stdout.write(`${formatFlagLine(flag)}\n`)
+  process.stdout.write(`\n${OUTPUT_CONTRACT_BLOCK}\n\n${EXIT_CODES_BLOCK}\n`)
+}
+
+function argvRequestsHelp(argv: readonly string[]): boolean {
+  return argv.includes('--help') || argv.includes('-h')
+}
+
+export async function runCli(argv: readonly string[]): Promise<number> {
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    printHelp()
+    return EXIT_OK
+  }
+
+  const group = argv[0] ?? ''
+  const verb = argv[1] ?? ''
+
+  // `aimux <group> --help` (or bare `aimux <group>`) — group-scoped help. Print
+  // the verb list without erroring on the missing verb, so agents can drill
+  // down step by step.
+  if (verb === '' || verb === '--help' || verb === '-h') {
+    if (COMMANDS.some((c) => c.group === group)) {
+      printGroupHelp(group)
+      return EXIT_OK
+    }
+    writeError(`unknown group: ${group}`)
+    printHelp()
+    return EXIT_USAGE
+  }
+
+  const command = resolveCommand(group, verb)
+  if (!command) {
+    writeError(`unknown command: ${group} ${verb}`)
+    printHelp()
+    return EXIT_USAGE
+  }
+
+  // `aimux <group> <verb> --help` — verb-scoped help. Handle BEFORE parseArgs
+  // so verbs that don't declare a `--help` flag don't reject it as unknown.
+  if (argvRequestsHelp(argv.slice(2))) {
+    printCommandHelp(command)
+    return EXIT_OK
+  }
+
+  let parsed
+  try {
+    parsed = parseArgs(argv.slice(2), command.flags, command.args)
+  } catch (error) {
+    if (error instanceof CliUsageError) {
+      writeError(error.message)
+      writeError(`usage: aimux ${command.group} ${command.verb}`)
+      return EXIT_USAGE
+    }
+    throw error
+  }
+
+  // --profile overrides the env var BEFORE anyone touches a runtime path —
+  // the daemon socket path, catalog path, and TM socket path all derive from
+  // it. After this point all `getIpcDaemonSocketPath()` reads pick it up.
+  if (typeof parsed.flags.profile === 'string' && parsed.flags.profile !== '') {
+    process.env.AIMUX_PROFILE = parsed.flags.profile
+  }
+
+  const state: {
+    daemon: DaemonClient | null
+    workspace: ReturnType<typeof resolveWorkspace> | null
+  } = {
+    daemon: null,
+    workspace: null,
+  }
+  const ctx: CliContext = {
+    args: parsed,
+    getDaemon: async () => {
+      if (state.daemon) return state.daemon
+      state.daemon = await connectToDaemon()
+      return state.daemon
+    },
+    getWorkspace: () => {
+      if (state.workspace) return state.workspace
+      const workspaceFlag =
+        typeof parsed.flags.workspace === 'string' ? parsed.flags.workspace : undefined
+      state.workspace = resolveWorkspace(workspaceFlag)
+      return state.workspace
+    },
+  }
+
+  try {
+    const code = await command.run(ctx)
+    return code
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    // Classify by error type, not by string-sniffing the message: a runtime
+    // error whose message happens to include "socket" (e.g. daemon reply
+    // "socket write failed for tab X") must not masquerade as
+    // daemon-unreachable, or CI that treats exit 4 as a "restart the daemon"
+    // signal will retry spuriously.
+    if (error instanceof DaemonUnreachableError) {
+      writeError(message)
+      writeJson({ error: message, kind: 'daemon-unreachable' })
+      return EXIT_DAEMON_UNREACHABLE
+    }
+    writeError(message)
+    writeJson({ error: message, kind: 'runtime-error' })
+    return EXIT_RUNTIME
+  } finally {
+    state.daemon?.close()
+  }
+}

package/src/cli/output.ts

@@ -0,0 +1,30 @@
+/**
+ * JSON-pure stdio for CLI commands. Every command writes one JSON object to
+ * stdout (or an NDJSON stream for `wait`/`tail`) and one human-readable line
+ * to stderr on failure. No ANSI, no prose interleaved with JSON — agents
+ * consume stdout, humans read stderr.
+ */
+
+export function writeJson(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value)}\n`)
+}
+
+export function writeNdjson(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value)}\n`)
+}
+
+export function writeError(message: string): void {
+  process.stderr.write(`aimux: ${message}\n`)
+}
+
+// Exit code contract (docs/reference/cli.md):
+//   0   success
+//   2   usage error (bad flags, unknown command, missing argument)
+//   3   runtime error (server replied with `error`, command failed)
+//   4   daemon unreachable (socket missing and autostart failed)
+//   124 timeout (`tab wait`, `tab tail --timeout`, `workspace switch --wait`)
+export const EXIT_OK = 0
+export const EXIT_USAGE = 2
+export const EXIT_RUNTIME = 3
+export const EXIT_DAEMON_UNREACHABLE = 4
+export const EXIT_TIMEOUT = 124

package/src/cli/registry.ts

@@ -0,0 +1,54 @@
+import type { CliContext } from './context'
+import type { ArgSpec, FlagSpec } from './flags'
+
+import { tabClose } from './commands/tab/close'
+import { tabCreate } from './commands/tab/create'
+import { tabFocus } from './commands/tab/focus'
+import { tabList } from './commands/tab/list'
+import { tabSend } from './commands/tab/send'
+import { tabSnapshot } from './commands/tab/snapshot'
+import { tabTail } from './commands/tab/tail'
+import { tabWait } from './commands/tab/wait'
+import { workspaceClose } from './commands/workspace/close'
+import { workspaceCreate } from './commands/workspace/create'
+import { workspaceList } from './commands/workspace/list'
+import { workspaceShow } from './commands/workspace/show'
+import { workspaceSwitch } from './commands/workspace/switch'
+import { worktreeCreate } from './commands/worktree/create'
+import { worktreeList } from './commands/worktree/list'
+import { worktreeRemove } from './commands/worktree/remove'
+
+export interface CliCommand {
+  group: string
+  verb: string
+  summary: string
+  flags: readonly FlagSpec[]
+  args: readonly ArgSpec[]
+  run: (ctx: CliContext) => Promise<number>
+}
+
+export const COMMANDS: readonly CliCommand[] = [
+  tabList,
+  tabCreate,
+  tabSend,
+  tabFocus,
+  tabClose,
+  tabSnapshot,
+  tabTail,
+  tabWait,
+  workspaceList,
+  workspaceShow,
+  workspaceCreate,
+  workspaceSwitch,
+  workspaceClose,
+  worktreeList,
+  worktreeCreate,
+  worktreeRemove,
+]
+
+export function resolveCommand(group: string, verb: string): CliCommand | null {
+  for (const command of COMMANDS) {
+    if (command.group === group && command.verb === verb) return command
+  }
+  return null
+}

package/src/cli/snapshot-render.ts

@@ -0,0 +1,54 @@
+import type { TerminalSnapshot } from '../state/types'
+
+export interface SnapshotLineOptions {
+  /** When true (default), strip trailing whitespace from each line so the
+   *  serialised output isn't a sea of padding cells the LLM has to chew
+   *  through. Pass false when you need the exact alignment of the terminal
+   *  (e.g. ASCII art / fixed-column TUIs). */
+  trim?: boolean
+}
+
+/**
+ * Flatten a TerminalSnapshot into plain text — concatenate every span's
+ * `text` per line. No ANSI, no palette resolution. Agents consume strings,
+ * not pixels.
+ */
+export function snapshotToLines(
+  snapshot: TerminalSnapshot,
+  options: SnapshotLineOptions = {}
+): string[] {
+  const trim = options.trim !== false
+  return snapshot.lines.map((line) => {
+    const joined = line.spans.map((span) => span.text).join('')
+    return trim ? joined.replace(/\s+$/u, '') : joined
+  })
+}
+
+/**
+ * Like `snapshotToLines` but trims trailing blank lines and slices to the
+ * last `n` non-blank lines. Mirrors the `--tail N` flag.
+ */
+export function snapshotTailLines(
+  snapshot: TerminalSnapshot,
+  n: number,
+  options: SnapshotLineOptions = {}
+): string[] {
+  const all = snapshotToLines(snapshot, options)
+  let end = all.length
+  while (end > 0 && (all[end - 1] ?? '').trim() === '') end--
+  const trimmed = all.slice(0, end)
+  if (n <= 0 || trimmed.length <= n) return trimmed
+  return trimmed.slice(trimmed.length - n)
+}
+
+/**
+ * Plain-text dump: lines joined by `\n`, single trailing newline. Best shape
+ * for piping into an LLM since it preserves the screen's visual layout
+ * without JSON-escape noise.
+ */
+export function snapshotToText(
+  snapshot: TerminalSnapshot,
+  options: SnapshotLineOptions = {}
+): string {
+  return `${snapshotToLines(snapshot, options).join('\n')}\n`
+}

package/src/daemon/catalog-writer.ts

@@ -0,0 +1,123 @@
+import type { SessionRecord, WorktreeRecord } from '../state/types'
+
+import { logDebug } from '../debug/input-log'
+import { createPrefixedId } from '../platform/id'
+import { loadSessionCatalog, saveSessionCatalog } from '../state/session-catalog'
+import { createEmptyWorkspaceSnapshot } from '../state/session-persistence'
+import { createPrimaryWorktree, ensureSessionWorktrees } from '../state/session-worktrees'
+
+/**
+ * Catalog mutations invoked by the daemon when NO UI is attached. When a UI
+ * is attached the daemon relays the request as an event and the UI's reducer
+ * owns the write (so the live workspace snapshot is preserved).
+ *
+ * Each helper is a pure read-modify-write against `aimux-sessions.json` —
+ * safe to call from the daemon process, no React / dispatcher involved.
+ */
+
+export function createWorkspaceInCatalog(name: string, projectPath?: string): SessionRecord {
+  const sessions = loadSessionCatalog()
+  const now = new Date().toISOString()
+  const session: SessionRecord = {
+    activeWorktreeId: undefined,
+    createdAt: now,
+    id: createPrefixedId('session'),
+    lastOpenedAt: now,
+    name,
+    projectPath,
+    updatedAt: now,
+    workspaceSnapshot: createEmptyWorkspaceSnapshot(),
+    worktrees: undefined,
+  }
+  if (projectPath != null && projectPath !== '') {
+    const worktree = createPrimaryWorktree(projectPath, now)
+    session.activeWorktreeId = worktree.id
+    session.worktrees = [worktree]
+  }
+  saveSessionCatalog([...sessions, ensureSessionWorktrees(session)])
+  logDebug('daemon.catalog.createWorkspace', { name, projectPath, sessionId: session.id })
+  return session
+}
+
+/**
+ * Throws when the target session isn't in the catalog. Used by the daemon
+ * before broadcasting a workspace-lifecycle request so the CLI's `expectOk`
+ * fails fast (with a meaningful message) instead of the `--wait` path
+ * hanging out for its timeout while the UI silently ignores an unknown id.
+ */
+export function assertSessionInCatalog(sessionId: string): void {
+  const sessions = loadSessionCatalog()
+  if (!sessions.some((s) => s.id === sessionId)) {
+    throw new Error(`workspace not found: ${sessionId}`)
+  }
+}
+
+export function bumpLastOpenedInCatalog(sessionId: string): void {
+  const sessions = loadSessionCatalog()
+  const now = new Date().toISOString()
+  const target = sessions.find((s) => s.id === sessionId)
+  if (!target) {
+    throw new Error(`workspace not found: ${sessionId}`)
+  }
+  const updated = sessions.map((s) => (s.id === sessionId ? { ...s, lastOpenedAt: now } : s))
+  saveSessionCatalog(updated)
+  logDebug('daemon.catalog.switchWorkspace', { sessionId })
+}
+
+export function deleteFromCatalog(sessionId: string): void {
+  const sessions = loadSessionCatalog()
+  const remaining = sessions.filter((s) => s.id !== sessionId)
+  if (remaining.length === sessions.length) {
+    throw new Error(`workspace not found: ${sessionId}`)
+  }
+  saveSessionCatalog(remaining)
+  logDebug('daemon.catalog.closeWorkspace', { sessionId })
+}
+
+export function addWorktreeToCatalog(sessionId: string, worktree: WorktreeRecord): void {
+  const sessions = loadSessionCatalog()
+  const target = sessions.find((s) => s.id === sessionId)
+  if (!target) {
+    throw new Error(`workspace not found: ${sessionId}`)
+  }
+  const existing = target.worktrees ?? []
+  if (existing.some((w) => w.id === worktree.id)) {
+    throw new Error(`worktree already exists: ${worktree.id}`)
+  }
+  const updated = sessions.map((s) =>
+    s.id === sessionId
+      ? { ...s, updatedAt: new Date().toISOString(), worktrees: [...existing, worktree] }
+      : s
+  )
+  saveSessionCatalog(updated)
+  logDebug('daemon.catalog.addWorktree', {
+    sessionId,
+    worktreeId: worktree.id,
+    worktreeName: worktree.name,
+  })
+}
+
+export function removeWorktreeFromCatalog(sessionId: string, worktreeId: string): void {
+  const sessions = loadSessionCatalog()
+  const target = sessions.find((s) => s.id === sessionId)
+  if (!target) {
+    throw new Error(`workspace not found: ${sessionId}`)
+  }
+  const existing = target.worktrees ?? []
+  const nextWorktrees = existing.filter((w) => w.id !== worktreeId)
+  if (nextWorktrees.length === existing.length) {
+    throw new Error(`worktree not found: ${worktreeId}`)
+  }
+  const updated = sessions.map((s) =>
+    s.id === sessionId
+      ? {
+          ...s,
+          activeWorktreeId: s.activeWorktreeId === worktreeId ? undefined : s.activeWorktreeId,
+          updatedAt: new Date().toISOString(),
+          worktrees: nextWorktrees,
+        }
+      : s
+  )
+  saveSessionCatalog(updated)
+  logDebug('daemon.catalog.removeWorktree', { sessionId, worktreeId })
+}