@brimveyn/aimux 1.16.2 → 1.18.1

package/src/cli/index.ts

@@ -0,0 +1,113 @@
+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 { CliUsageError, parseArgs } from './flags'
+import {
+  EXIT_DAEMON_UNREACHABLE,
+  EXIT_OK,
+  EXIT_RUNTIME,
+  EXIT_USAGE,
+  writeError,
+  writeJson,
+} from './output'
+import { COMMANDS, resolveCommand } from './registry'
+
+function printHelp(): void {
+  process.stdout.write(
+    'aimux CLI control plane\n\nUsage:\n  aimux <group> <verb> [flags] [args]\n\n'
+  )
+  const byGroup = new Map<string, typeof COMMANDS>()
+  for (const command of COMMANDS) {
+    const existing = byGroup.get(command.group) ?? []
+    byGroup.set(command.group, [...existing, command] as typeof COMMANDS)
+  }
+  for (const [group, commands] of byGroup) {
+    process.stdout.write(`  ${group}\n`)
+    for (const command of commands) {
+      process.stdout.write(`    aimux ${group} ${command.verb.padEnd(10)} ${command.summary}\n`)
+    }
+    process.stdout.write('\n')
+  }
+}
+
+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] ?? ''
+  const command = resolveCommand(group, verb)
+  if (!command) {
+    writeError(`unknown command: ${group} ${verb}`)
+    printHelp()
+    return EXIT_USAGE
+  }
+
+  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 })
+}