typeclaw 0.1.0

package/src/cli/restart.ts

@@ -0,0 +1,66 @@
+import { defineCommand } from 'citty'
+
+import { config, validateConfig } from '@/config'
+import { start, stop } from '@/container'
+import { findAgentDir, isInitialized } from '@/init'
+
+import { c, errorLine, renderStartSuccess, spinner } from './ui'
+
+export const restartCommand = defineCommand({
+  meta: {
+    name: 'restart',
+    description: 'stop and relaunch the agent container (host stage)',
+  },
+  args: {
+    port: {
+      type: 'string',
+      description:
+        'preferred host port; if it is already bound, typeclaw allocates a free ephemeral port and reports it',
+      default: String(config.port),
+    },
+    build: {
+      type: 'boolean',
+      description: 'regenerate the Dockerfile from the latest template and rebuild the image',
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+
+    if (!isInitialized(cwd)) {
+      console.error(errorLine('TypeClaw config file not found. Run `typeclaw init` first.'))
+      process.exit(1)
+    }
+
+    const validated = validateConfig(cwd)
+    if (!validated.ok) {
+      console.error(errorLine(validated.reason))
+      process.exit(1)
+    }
+
+    const stopSpin = spinner()
+    stopSpin.start('Stopping container...')
+    const stopped = await stop({ cwd })
+    if (!stopped.ok) {
+      stopSpin.error(stopped.reason)
+      process.exit(1)
+    }
+    stopSpin.stop(stopped.running ? `Stopped ${c.cyan(stopped.containerName)}.` : 'Already stopped.')
+
+    const startSpin = spinner()
+    startSpin.start('Starting container...')
+    const started = await start({
+      cwd,
+      preferredHostPort: Number(args.port),
+      forceBuild: args.build,
+      cliEntry: process.argv[1],
+    })
+    if (!started.ok) {
+      startSpin.error(started.reason)
+      process.exit(1)
+    }
+    startSpin.stop('Started.')
+
+    console.log(renderStartSuccess(started))
+  },
+})

package/src/cli/run.ts

@@ -0,0 +1,77 @@
+import { defineCommand } from 'citty'
+
+import { CONTAINER_PORT } from '@/container'
+import { isInitialized } from '@/init'
+import { startAgent } from '@/run'
+
+export const run = defineCommand({
+  meta: {
+    name: 'run',
+    description: 'run the agent in the foreground (container stage)',
+  },
+  args: {
+    port: {
+      type: 'string',
+      description: 'port to listen on (defaults to the fixed container-internal port)',
+      default: String(CONTAINER_PORT),
+    },
+    prompt: {
+      type: 'positional',
+      description: 'initial prompt for the attached tui',
+      required: false,
+    },
+    tui: {
+      type: 'boolean',
+      description: 'attach a local tui (default: auto, on when stdin is a tty)',
+    },
+    'no-tui': {
+      type: 'boolean',
+      description: 'never attach a local tui, stay headless',
+    },
+  },
+  async run({ args }) {
+    if (!isInitialized(process.cwd())) {
+      console.error('TypeClaw config file not found. Run `typeclaw init` first.')
+      process.exit(1)
+    }
+
+    const attachTui = resolveAttachTui({
+      tui: args.tui,
+      noTui: args['no-tui'],
+      isTTY: Boolean(process.stdin.isTTY),
+    })
+
+    const { tuiPromise, stop } = await startAgent({
+      port: Number(args.port),
+      attachTui,
+      initialPrompt: args.prompt,
+    })
+
+    const onSignal = () => {
+      stop()
+      process.exit(0)
+    }
+    process.once('SIGINT', onSignal)
+    process.once('SIGTERM', onSignal)
+
+    if (tuiPromise) {
+      await tuiPromise
+      stop()
+      process.exit(0)
+    }
+  },
+})
+
+function resolveAttachTui({
+  tui,
+  noTui,
+  isTTY,
+}: {
+  tui: boolean | undefined
+  noTui: boolean | undefined
+  isTTY: boolean
+}): boolean {
+  if (noTui) return false
+  if (tui) return true
+  return isTTY
+}

package/src/cli/shell.ts

@@ -0,0 +1,33 @@
+import { defineCommand } from 'citty'
+
+import { shell } from '@/container'
+import { findAgentDir } from '@/init'
+
+import { c, errorLine } from './ui'
+
+export const shellCommand = defineCommand({
+  meta: {
+    name: 'shell',
+    description: 'open an interactive shell in the agent container (host stage)',
+  },
+  args: {
+    shell: {
+      type: 'string',
+      description: 'shell executable to run inside the container',
+      default: '/bin/bash',
+    },
+  },
+  async run({ args }) {
+    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+
+    console.log(c.cyan(`Attaching ${args.shell} inside the container...`))
+
+    const result = await shell({ cwd, shell: args.shell })
+    if (!result.ok) {
+      console.error(errorLine(result.reason))
+      process.exit(1)
+    }
+
+    process.exit(result.exitCode)
+  },
+})

package/src/cli/start.ts

@@ -0,0 +1,57 @@
+import { defineCommand } from 'citty'
+
+import { config, validateConfig } from '@/config'
+import { start } from '@/container'
+import { findAgentDir, isInitialized } from '@/init'
+
+import { errorLine, renderStartSuccess, spinner } from './ui'
+
+export const startCommand = defineCommand({
+  meta: {
+    name: 'start',
+    description: 'launch the agent container in the background (host stage)',
+  },
+  args: {
+    port: {
+      type: 'string',
+      description:
+        'preferred host port; if it is already bound, typeclaw allocates a free ephemeral port and reports it',
+      default: String(config.port),
+    },
+    build: {
+      type: 'boolean',
+      description: 'regenerate the Dockerfile from the latest template and rebuild the image',
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+
+    if (!isInitialized(cwd)) {
+      console.error(errorLine('TypeClaw config file not found. Run `typeclaw init` first.'))
+      process.exit(1)
+    }
+
+    const validated = validateConfig(cwd)
+    if (!validated.ok) {
+      console.error(errorLine(validated.reason))
+      process.exit(1)
+    }
+
+    const s = spinner()
+    s.start('Starting container...')
+    const result = await start({
+      cwd,
+      preferredHostPort: Number(args.port),
+      forceBuild: args.build,
+      cliEntry: process.argv[1],
+    })
+    if (!result.ok) {
+      s.error(result.reason)
+      process.exit(1)
+    }
+    s.stop(result.alreadyRunning ? 'Already running.' : 'Started.')
+
+    console.log(renderStartSuccess(result))
+  },
+})

package/src/cli/status.ts

@@ -0,0 +1,178 @@
+import { styleText } from 'node:util'
+
+import { defineCommand } from 'citty'
+
+import { status as containerStatus, type ContainerStatus } from '@/container'
+import { isDaemonReachable, send } from '@/hostd'
+import type { StatusResult } from '@/hostd'
+import { findAgentDir } from '@/init'
+
+export type HostdStatus =
+  | { kind: 'unreachable' }
+  | { kind: 'not-registered'; reason: string }
+  | { kind: 'registered'; cwd: string; forwardedPorts: number[] }
+
+export type StatusReport = {
+  cwd: string
+  container: ContainerStatus
+  hostd: HostdStatus
+}
+
+export const statusCommand = defineCommand({
+  meta: {
+    name: 'status',
+    description: 'show the agent container and host daemon status (host stage)',
+  },
+  async run() {
+    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const container = await containerStatus({ cwd })
+    const hostd = await fetchHostdStatus(container.containerName)
+
+    const useColor = Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined
+    process.stdout.write(`${formatStatus({ cwd, container, hostd }, { useColor })}\n`)
+  },
+})
+
+async function fetchHostdStatus(containerName: string): Promise<HostdStatus> {
+  if (!(await isDaemonReachable())) return { kind: 'unreachable' }
+  const reply = await send({ kind: 'status', containerName })
+  if (!reply.ok) return { kind: 'not-registered', reason: reply.reason }
+  const parsed = parseStatusResult(reply.result)
+  if (!parsed) return { kind: 'not-registered', reason: 'daemon returned malformed status' }
+  return { kind: 'registered', cwd: parsed.cwd, forwardedPorts: parsed.forwardedPorts }
+}
+
+// Validate the daemon payload at runtime: a drift-respawn race or an older
+// daemon binary can deliver a `StatusResult` without `forwardedPorts`, and the
+// blind `as` cast then crashed the renderer with `undefined.length`. Defaulting
+// the field to `[]` (and rejecting non-string `cwd`) keeps `typeclaw status`
+// usable as a diagnostic when the daemon and CLI have drifted.
+export function parseStatusResult(value: unknown): StatusResult | null {
+  if (typeof value !== 'object' || value === null) return null
+  const v = value as Record<string, unknown>
+  if (typeof v.cwd !== 'string') return null
+  const containerName = typeof v.containerName === 'string' ? v.containerName : ''
+  const forwardedPorts = Array.isArray(v.forwardedPorts)
+    ? v.forwardedPorts.filter((p): p is number => typeof p === 'number' && Number.isFinite(p))
+    : []
+  return { containerName, cwd: v.cwd, forwardedPorts }
+}
+
+export type FormatOptions = { useColor?: boolean }
+
+type ColorFn = (s: string) => string
+type Palette = {
+  bold: ColorFn
+  dim: ColorFn
+  green: ColorFn
+  yellow: ColorFn
+  red: ColorFn
+  cyan: ColorFn
+}
+
+const identity: ColorFn = (s) => s
+const NO_PALETTE: Palette = {
+  bold: identity,
+  dim: identity,
+  green: identity,
+  yellow: identity,
+  red: identity,
+  cyan: identity,
+}
+
+const COLOR_PALETTE: Palette = {
+  bold: (s) => styleText('bold', s),
+  dim: (s) => styleText('dim', s),
+  green: (s) => styleText('green', s),
+  yellow: (s) => styleText('yellow', s),
+  red: (s) => styleText('red', s),
+  cyan: (s) => styleText('cyan', s),
+}
+
+export function formatStatus(report: StatusReport, opts: FormatOptions = {}): string {
+  const useColor = opts.useColor ?? false
+  const p: Palette = useColor ? COLOR_PALETTE : NO_PALETTE
+
+  const lines: string[] = []
+  appendContainerSection(lines, report, p)
+  lines.push('')
+  appendHostdSection(lines, report, p)
+  lines.push('')
+  appendForwardingSection(lines, report, p)
+  while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+  return lines.join('\n')
+}
+
+function appendContainerSection(lines: string[], report: StatusReport, p: Palette): void {
+  const container = report.container
+  lines.push(`${p.bold('Container')}  ${container.containerName}`)
+  lines.push(row('cwd', report.cwd))
+  lines.push(row('image', container.imageTag))
+
+  if (container.kind === 'missing') {
+    lines.push(row('state', p.dim('missing')))
+    return
+  }
+
+  const stateLabel = container.kind === 'running' ? p.green('running') : p.yellow('stopped')
+  lines.push(row('state', stateLabel))
+  lines.push(row('id', shortId(container.containerId)))
+
+  if (container.kind === 'running') {
+    const port =
+      container.hostPort === null ? p.dim('unknown') : formatHostMapping(container.hostBindAddr, container.hostPort, p)
+    lines.push(row('port', port))
+  }
+}
+
+function appendHostdSection(lines: string[], report: StatusReport, p: Palette): void {
+  lines.push(p.bold('Host daemon'))
+
+  switch (report.hostd.kind) {
+    case 'unreachable':
+      lines.push(row('state', p.dim('unreachable')))
+      lines.push(`  ${p.dim('Daemon is not running. `typeclaw start` will spawn one.')}`)
+      return
+    case 'not-registered':
+      lines.push(row('state', p.yellow('not registered')))
+      lines.push(row('reason', report.hostd.reason))
+      return
+    case 'registered':
+      lines.push(row('state', p.green('registered')))
+      return
+  }
+}
+
+function appendForwardingSection(lines: string[], report: StatusReport, p: Palette): void {
+  lines.push(p.bold('Port forwarding'))
+
+  if (report.hostd.kind !== 'registered') {
+    lines.push(`  ${p.dim('requires the host daemon')}`)
+    return
+  }
+
+  const ports = report.hostd.forwardedPorts
+  if (ports.length === 0) {
+    lines.push(`  ${p.dim('no ports currently forwarded')}`)
+    return
+  }
+
+  for (const port of [...ports].sort((a, b) => a - b)) {
+    lines.push(`  ${p.cyan(`127.0.0.1:${port}`)} ${p.dim('->')} container:${port}`)
+  }
+}
+
+function row(label: string, value: string): string {
+  return `  ${label.padEnd(8)}${value}`
+}
+
+function shortId(id: string): string {
+  if (id.length === 0) return '-'
+  const trimmed = id.startsWith('sha256:') ? id.slice('sha256:'.length) : id
+  return trimmed.slice(0, 12)
+}
+
+function formatHostMapping(bindAddr: string | null, port: number, p: Palette): string {
+  const bind = bindAddr ?? '127.0.0.1'
+  return `${p.cyan(`${bind}:${port}`)} ${p.dim('->')} container:${port}`
+}

package/src/cli/stop.ts

@@ -0,0 +1,31 @@
+import { defineCommand } from 'citty'
+
+import { stop } from '@/container'
+import { findAgentDir } from '@/init'
+
+import { c, spinner } from './ui'
+
+export const stopCommand = defineCommand({
+  meta: {
+    name: 'stop',
+    description: 'stop the agent container (host stage)',
+  },
+  async run() {
+    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+
+    const s = spinner()
+    s.start('Stopping container...')
+    const result = await stop({ cwd })
+
+    if (!result.ok) {
+      s.error(result.reason)
+      process.exit(1)
+    }
+
+    if (result.running) {
+      s.stop(`Stopped ${c.cyan(result.containerName)}.`)
+    } else {
+      s.stop(c.dim(`Container ${result.containerName} is not running.`))
+    }
+  },
+})

package/src/cli/tui.ts

@@ -0,0 +1,35 @@
+import { defineCommand } from 'citty'
+
+import { resolveHostPort } from '@/container'
+import { findAgentDir } from '@/init'
+import { createTui } from '@/tui'
+
+export const tui = defineCommand({
+  meta: {
+    name: 'tui',
+    description: 'start the tui client',
+  },
+  args: {
+    prompt: {
+      type: 'positional',
+      description: 'initial prompt',
+      required: false,
+    },
+    url: {
+      type: 'string',
+      description:
+        "agent websocket url (defaults to ws://localhost:<host port> discovered from the running container's published port)",
+    },
+  },
+  async run({ args }) {
+    const url = args.url ?? (await defaultUrl())
+    const tui = createTui({ url, initialPrompt: args.prompt })
+    await tui.run()
+  },
+})
+
+async function defaultUrl(): Promise<string> {
+  const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+  const port = await resolveHostPort({ cwd })
+  return `ws://localhost:${port}`
+}

package/src/cli/ui.ts

@@ -0,0 +1,110 @@
+import { styleText } from 'node:util'
+
+import { cancel, intro, isCancel, log, note, outro, spinner as clackSpinner } from '@clack/prompts'
+
+export { cancel, intro, isCancel, log, note, outro }
+
+function colorize(modifier: Parameters<typeof styleText>[0], s: string): string {
+  if (!colorsEnabled()) return s
+  return styleText(modifier, s)
+}
+
+// Re-evaluated per call so tests can mutate NO_COLOR / FORCE_COLOR between
+// cases without stale module-load caching.
+function colorsEnabled(): boolean {
+  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '') return false
+  if (process.env.FORCE_COLOR === '0') return false
+  if (process.env.FORCE_COLOR) return true
+  return Boolean(process.stdout.isTTY)
+}
+
+export const c = {
+  cyan: (s: string) => colorize('cyan', s),
+  green: (s: string) => colorize('green', s),
+  red: (s: string) => colorize('red', s),
+  yellow: (s: string) => colorize('yellow', s),
+  dim: (s: string) => colorize('dim', s),
+  gray: (s: string) => colorize('gray', s),
+  magenta: (s: string) => colorize('magenta', s),
+  bold: (s: string) => colorize('bold', s),
+}
+
+// OSC 8 hyperlink with plain fallback when colors are off so piped output
+// and non-OSC-8 terminals stay readable.
+export function link(text: string, url: string): string {
+  if (!colorsEnabled()) return `${text} (${url})`
+  return `\u001b]8;;${url}\u0007${text}\u001b]8;;\u0007`
+}
+
+export type Spinner = {
+  start: (msg?: string) => void
+  stop: (msg?: string) => void
+  error: (msg?: string) => void
+  cancel: (msg?: string) => void
+  message: (msg?: string) => void
+}
+
+export function spinner(): Spinner {
+  const s = clackSpinner()
+  return {
+    start: (msg) => s.start(msg),
+    stop: (msg) => s.stop(msg),
+    error: (msg) => s.error(msg),
+    cancel: (msg) => s.cancel(msg),
+    message: (msg) => s.message(msg),
+  }
+}
+
+export type StartLikeResult = {
+  alreadyRunning?: boolean
+  built: boolean
+  plan: { containerName: string; imageTag: string }
+  hostPort: number
+  containerId: string
+  hostd: { state: 'registered' } | { state: 'unavailable'; reason: string } | { state: 'disabled' }
+}
+
+export function renderStartSuccess(result: StartLikeResult): string {
+  const lines: string[] = []
+  const name = c.cyan(result.plan.containerName)
+  const port = c.green(String(result.hostPort))
+
+  if (result.alreadyRunning) {
+    lines.push(`${c.green('●')} ${name} is already running on host port ${port}.`)
+  } else {
+    if (result.built) {
+      lines.push(`Built image ${c.cyan(result.plan.imageTag)}.`)
+    }
+    const shortId = result.containerId.slice(0, 12)
+    lines.push(`${c.green('●')} ${name} started on host port ${port} ${c.dim(`(${shortId})`)}.`)
+  }
+
+  if (result.hostd.state === 'registered') {
+    lines.push(c.dim('Host daemon active.'))
+  } else if (result.hostd.state === 'unavailable') {
+    lines.push(`${c.yellow('Host daemon unavailable:')} ${result.hostd.reason}`)
+  }
+
+  lines.push('')
+  lines.push(`${c.dim('Follow logs:')}  ${c.cyan('typeclaw logs -f')}`)
+  lines.push(`${c.dim('Attach TUI:')}   ${c.cyan('typeclaw tui')}`)
+  lines.push(`${c.dim('Stop:')}         ${c.cyan('typeclaw stop')}`)
+
+  return lines.join('\n')
+}
+
+export type NextStepHint = { label: string; command: string }
+
+export function done(opts: { title: string; hints: NextStepHint[] }): void {
+  const body = opts.hints.map((h) => `${c.dim(h.label)}  ${c.cyan(h.command)}`).join('\n')
+  note(body, opts.title)
+  outro(c.green('Done.'))
+}
+
+export function errorLine(reason: string): string {
+  return `${c.red('✖')} ${reason}`
+}
+
+export function successLine(message: string): string {
+  return `${c.green('●')} ${message}`
+}

package/src/commands/index.ts

@@ -0,0 +1,74 @@
+export type CommandHandler<Context> = (context: Context, command: ParsedCommand) => Promise<void> | void
+
+export type Command<Context> = {
+  name: string
+  aliases?: readonly string[]
+  handler: CommandHandler<Context>
+}
+
+export type ParsedCommand = {
+  name: string
+  args: string
+}
+
+export type CommandResult =
+  | { kind: 'not-command' }
+  | { kind: 'unknown-command'; name: string }
+  | { kind: 'handled'; name: string }
+
+export type CommandRegistry<Context> = {
+  parse: (text: string) => ParsedCommand | null
+  has: (name: string) => boolean
+  execute: (text: string, context: Context) => Promise<CommandResult>
+}
+
+// TODO: Add plugin-contributed commands once the public command context is stable.
+
+export function createCommandRegistry<Context>(commands: readonly Command<Context>[]): CommandRegistry<Context> {
+  const byName = new Map<string, Command<Context>>()
+  for (const command of commands) {
+    registerName(byName, command.name, command)
+    for (const alias of command.aliases ?? []) {
+      registerName(byName, alias, command)
+    }
+  }
+
+  return {
+    parse: parseCommand,
+    has: (name) => byName.has(name.toLowerCase()),
+    execute: async (text, context) => {
+      const parsed = parseCommand(text)
+      if (parsed === null) return { kind: 'not-command' }
+      const command = byName.get(parsed.name)
+      if (!command) return { kind: 'unknown-command', name: parsed.name }
+      await command.handler(context, parsed)
+      return { kind: 'handled', name: command.name }
+    },
+  }
+}
+
+export function parseCommand(text: string): ParsedCommand | null {
+  const trimmed = text.trim()
+  if (!trimmed.startsWith('/') || trimmed.startsWith('//')) return null
+
+  const body = trimmed.slice(1)
+  const match = /^(?<name>[a-z][a-z0-9_-]*)(?:\s+(?<args>[\s\S]*))?$/i.exec(body)
+  if (!match?.groups) return null
+
+  return {
+    name: match.groups.name!.toLowerCase(),
+    args: match.groups.args ?? '',
+  }
+}
+
+function registerName<Context>(
+  byName: Map<string, Command<Context>>,
+  rawName: string,
+  command: Command<Context>,
+): void {
+  const name = rawName.toLowerCase()
+  if (byName.has(name)) {
+    throw new Error(`duplicate command: ${name}`)
+  }
+  byName.set(name, command)
+}