Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

20.3 KB
Raw Blame
// `node out/server/main.cjs team <command>` — the hosted team's admin CLI. It talks to the running
// server over the local admin socket (src/core/relay/team-admin.ts) and never touches team.json or
// the host key itself: the server is the only writer, which is what keeps two admin commands (or an
// admin command and a live approval) from racing each other on disk.
//
// Exit codes: 0 done, 1 the server refused or could not be reached, 2 the command line is wrong.
import path from 'node:path'
import {
  CONTROL_RE,
  adoptCwdProblem,
  callTeamAdmin,
  ownerKeyProblem,
  ownerLabelProblem,
  projectIdProblem,
  type AdminInfoResult,
  type AdminInitResult,
  type AdminRequest,
  type AdminRotateResult,
  type AdminStatusResult
} from '../core/relay/team-admin'
import { POP_REFUSED_MESSAGE } from '../core/relay/relay-pop'
import { parseResumeSessions } from '../shared/share-team'
import { SAS_COMPARE_HINT } from '../shared/remote/sas'

// One rule for what never reaches the admin's terminal: the same characters a label may not
// contain (C0/C1 controls, DEL, and the text-direction controls). Server-supplied strings can carry
// them — a hand-edited team.json, an error message quoting a path, a peer-influenced lastError.
const CONTROL_G = new RegExp(CONTROL_RE.source, 'gu')
const clean = (s: string): string => s.replace(CONTROL_G, '?')
/** JSON for the terminal. JSON.stringify already escapes C0 controls inside strings, but leaves
 *  DEL, the C1 controls and the bidi controls raw; those become \u escapes here. Still valid JSON:
 *  they only ever occur inside strings (the raw newlines are the pretty-printing, left alone). */
const JSON_RAW_G = /[\u007F-\u009F\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/g
const safeJson = (v: unknown): string =>
  JSON.stringify(v, null, 2).replace(JSON_RAW_G, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`)

const USAGE_ROWS: Array<[string, string]> = [
  ['init', 'create the host key and the team, and start hosting'],
  // The desktop's Share with team detects this verb by grepping the built main.cjs for this row's
  // `bootstrap --owner-key` (BOOTSTRAP_MARKER); it never runs an unrecognised bundle. Keep that text.
  [
    'bootstrap --owner-key <key> --adopt <dir> [--owner-label <name>] [--json]',
    'set up the team, an owner and a shared project in one step'
  ],
  ['add-owner <device-key> [--label <name>]', 'make a device an owner (its 44-character public key)'],
  ['remove <device-key> [--force]', 'remove a member and cut its live sessions'],
  ['share <projectId>', 'show a project to non-editors'],
  ['unshare <projectId>', 'stop showing it'],
  ['info [--json]', "this host's team address and join code"],
  ['status [--json]', 'hosting state, members and join requests'],
  ['rotate-key', 'replace the host key (every teammate needs a new join code)'],
  ['resume --project <id> [--json] < sessions.json', 'restart handed-over agent sessions (a JSON list on stdin)']
]
const USAGE_WIDTH = Math.max(...USAGE_ROWS.map(([cmd]) => cmd.length))
export const TEAM_USAGE = [
  'usage: team <command> [--data-dir <dir>]',
  ...USAGE_ROWS.map(([cmd, what]) => `  ${cmd.padEnd(USAGE_WIDTH)}  ${what}`)
].join('\n')

type FlagKind = 'bool' | 'value'
interface CommandSpec {
  positionals: number
  flags: Record<string, FlagKind>
}
const COMMANDS: Record<string, CommandSpec> = {
  init: { positionals: 0, flags: {} },
  bootstrap: { positionals: 0, flags: { 'owner-key': 'value', 'owner-label': 'value', adopt: 'value', json: 'bool' } },
  'add-owner': { positionals: 1, flags: { label: 'value' } },
  remove: { positionals: 1, flags: { force: 'bool' } },
  share: { positionals: 1, flags: {} },
  unshare: { positionals: 1, flags: {} },
  info: { positionals: 0, flags: { json: 'bool' } },
  status: { positionals: 0, flags: { json: 'bool' } },
  'rotate-key': { positionals: 0, flags: {} },
  resume: { positionals: 0, flags: { project: 'value', json: 'bool' } }
}

const usageError = (why: string): { error: string } => ({ error: `${why}\n${TEAM_USAGE}` })

/**
 * Parse one command line into an admin request. Strict: an unknown option or a stray argument is a
 * usage error, not silently ignored — `remove K --forse` must not run as a remove without --force.
 * A bad add-owner key or label, or a bad project id, gets its OWN message (not the usage text),
 * before anything reaches the server. `--json` is presentation only and never part of the request.
 */
export function parseTeamArgv(argv: string[]): AdminRequest | { error: string } {
  const [cmd, ...rest] = argv
  if (cmd === undefined) return usageError('A command is required.')
  const spec = Object.hasOwn(COMMANDS, cmd) ? COMMANDS[cmd] : undefined
  if (!spec) return usageError(`unknown command "${clean(cmd)}"`)
  const positionals: string[] = []
  const flags: Record<string, string | true> = {}
  for (let i = 0; i < rest.length; i++) {
    const tok = rest[i]
    if (!tok.startsWith('--')) {
      positionals.push(tok)
      continue
    }
    const eq = tok.indexOf('=')
    const name = tok.slice(2, eq < 0 ? undefined : eq)
    const kind = Object.hasOwn(spec.flags, name) ? spec.flags[name] : undefined
    if (!kind) return usageError(`unknown option --${clean(name)} for "team ${cmd}"`)
    if (kind === 'bool') {
      if (eq >= 0) return usageError(`--${name} takes no value`)
      flags[name] = true
      continue
    }
    const value = eq >= 0 ? tok.slice(eq + 1) : rest[i + 1]
    if (value === undefined || (eq < 0 && value.startsWith('--'))) return usageError(`--${name} needs a value`)
    if (eq < 0) i++
    flags[name] = value
  }
  if (positionals.length !== spec.positionals) {
    return usageError(
      spec.positionals === 0 ? `"team ${cmd}" takes no arguments` : `"team ${cmd}" takes exactly ${spec.positionals} argument`
    )
  }
  switch (cmd) {
    case 'init':
    case 'info':
    case 'status':
    case 'rotate-key':
      return { cmd }
    case 'add-owner': {
      const pubkey = positionals[0]
      const label = typeof flags.label === 'string' ? flags.label : ''
      const problem = ownerKeyProblem(pubkey) ?? ownerLabelProblem(label)
      return problem ? { error: problem } : { cmd, pubkey, label }
    }
    case 'bootstrap': {
      const ownerKey = typeof flags['owner-key'] === 'string' ? flags['owner-key'] : ''
      const adoptCwd = typeof flags.adopt === 'string' ? flags.adopt : ''
      const ownerLabel = typeof flags['owner-label'] === 'string' ? flags['owner-label'] : ''
      if (!ownerKey || !adoptCwd) return usageError('bootstrap needs --owner-key <key> and --adopt <dir>')
      const problem = ownerKeyProblem(ownerKey) ?? ownerLabelProblem(ownerLabel) ?? adoptCwdProblem(adoptCwd)
      return problem ? { error: problem } : { cmd: 'bootstrap', ownerKey, ownerLabel, adoptCwd }
    }
    case 'remove':
      return flags.force ? { cmd, pubkey: positionals[0], force: true } : { cmd, pubkey: positionals[0] }
    case 'share':
    case 'unshare': {
      const problem = projectIdProblem(positionals[0])
      return problem ? { error: problem } : { cmd: 'share', projectId: positionals[0], on: cmd === 'share' }
    }
    case 'resume': {
      // The session list is not argv: it arrives on stdin (runTeamCli fills `sessions`), so a long
      // list never meets ARG_MAX and never shows up in `ps`.
      const projectId = typeof flags.project === 'string' ? flags.project : ''
      if (!projectId) return usageError('resume needs --project <id>')
      const problem = projectIdProblem(projectId)
      return problem ? { error: problem } : { cmd: 'resume', projectId, sessions: [] }
    }
  }
  return usageError(`unknown command "${clean(cmd)}"`)
}

/**
 * `main.cjs [server flags] team <command> …`: the team CLI's own argv, or null for a server boot.
 * `team` is recognised as the first NON-FLAG argument, skipping flag values the way the server's own
 * argv parser reads them (a `--flag` followed by a non-flag token takes it as its value, except
 * `--insecure-http`). So `main.cjs --data-dir X team status` runs the CLI rather than booting a whole
 * second server on X. Of the flags before `team`, only `--data-dir` means anything to the CLI; it is
 * carried over (runTeamCli reads it anywhere), and the rest configure a boot that is not happening.
 */
export function teamArgv(argv: string[]): string[] | null {
  const carried: string[] = []
  for (let i = 0; i < argv.length; i++) {
    const tok = argv[i]
    if (!tok.startsWith('--')) return tok === 'team' ? [...argv.slice(i + 1), ...carried] : null
    if (tok.startsWith('--data-dir=')) {
      carried.push(tok)
      continue
    }
    if (tok.includes('=') || tok === '--insecure-http') continue
    const next = argv[i + 1]
    if (next !== undefined && !next.startsWith('--')) {
      if (tok === '--data-dir') carried.push(tok, next)
      i++
    }
  }
  return null
}

/** Take a global `--data-dir <dir>` / `--data-dir=<dir>` off the command line, wherever it sits. */
function takeDataDir(argv: string[]): { dataDir?: string; argv: string[] } | { error: string } {
  const out: string[] = []
  let dataDir: string | undefined
  for (let i = 0; i < argv.length; i++) {
    const tok = argv[i]
    if (tok === '--data-dir' || tok.startsWith('--data-dir=')) {
      const value = tok === '--data-dir' ? argv[++i] : tok.slice('--data-dir='.length)
      if (!value || value.startsWith('--')) return usageError('--data-dir needs a value')
      dataDir = path.resolve(value)
      continue
    }
    out.push(tok)
  }
  return { dataDir, argv: out }
}

// ---- rendering. Every reader tolerates a shape it does not know: the CLI and the running server can
// be different builds (an update not yet followed by a restart).

const obj = (v: unknown): Record<string, unknown> =>
  v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {}
// Every server-supplied string is printed through `str` (see `clean`).
const str = (v: unknown, fallback = ''): string => (typeof v === 'string' ? clean(v) : fallback)
const num = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0)
const plural = (n: number, one: string, many = `${one}s`): string => `${n} ${n === 1 ? one : many}`

function addressLines(info: unknown, joinCode: unknown): string[] {
  const i = obj(info)
  const lines = [
    `  Team host:   ${str(i.label, '?')}`,
    `  Host id:     ${str(i.hostId, '?')}`,
    `  Host key:    ${str(i.hostPublicKeyB64, '?')}`,
    `  Relay:       ${str(i.relayEndpoint, '?')}`
  ]
  if (typeof joinCode === 'string') {
    lines.push('Join code (give it to teammates; an owner approves each new device):', `  ${str(joinCode)}`)
  }
  return lines
}

const OFF_TEXT: Record<string, string> = {
  'no-team': 'there is no hosted team on this server. Run `team init` to create one.',
  'no-host-key': 'the team has no host key. Run `team init` to create one.',
  stopped: 'hosting is not running. Run `team init` (or restart the service) to start it.'
}

/**
 * The human `team status`. The scheduler's `lastError` is the last failure SINCE THE RELAY LEG WAS
 * LAST PROVEN, not a current fault, so it is read together with `state` and the idle listener count:
 * beside an open idle listener it is history the next confirmed registration clears, and only with
 * NO idle listener does it mean teammates cannot connect yet.
 */
export function describeStatus(result: AdminStatusResult): string[] {
  const s = obj(result)
  const lines: string[] = []
  const sched = obj(s.scheduler)
  const lastError = typeof sched.lastError === 'string' ? str(sched.lastError) : null
  const idle = num(sched.idle)
  const bridged = num(sched.bridged)
  if (s.enabled !== true) {
    const off = obj(s.off)
    const reason = str(off.reason)
    const text =
      reason === 'host-key-unreadable'
        ? str(off.detail, 'the host key could not be read.')
        : Object.hasOwn(OFF_TEXT, reason)
          ? OFF_TEXT[reason]
          : 'hosting is not running.'
    lines.push(`Hosting: OFF — ${text}`)
  } else if (sched.state === 'backend-refused' && lastError === POP_REFUSED_MESSAGE) {
    // The advice is a sentence of its own, and it is how hosting comes back: `team rotate-key`
    // restarts it in place, so "until the service restarts" would be wrong here.
    lines.push(
      'Hosting: STOPPED — the nodeterm API refused to issue relay tokens.',
      `  ${POP_REFUSED_MESSAGE}`,
      '  Hosting stays off until nodeterm is updated or the key is rotated.'
    )
  } else if (sched.state === 'backend-refused') {
    lines.push(
      `Hosting: STOPPED — the nodeterm API refused to issue relay tokens${lastError ? ` (${lastError})` : ''}. ` +
        'Hosting stays off until the service restarts.'
    )
  } else if (idle > 0) {
    lines.push('Hosting: ON — listening for teammates.')
    if (lastError) {
      lines.push(`  Earlier failure, not yet cleared by a confirmed relay registration: ${lastError}`)
    }
  } else if (lastError) {
    lines.push(`Hosting: ON, but not reachable yet — retrying. Last error: ${lastError}`)
  } else {
    lines.push('Hosting: ON — opening a listener.')
  }
  if (s.enabled === true) {
    lines.push(
      `  ${plural(bridged, 'session')} (joined or awaiting approval) · ${plural(idle, 'idle listener')} · ` +
        `${plural(num(sched.mintsLastHour), 'relay token')} minted in the last hour`
    )
  }
  const peers = Array.isArray(s.peers) ? s.peers.map(obj) : []
  if (peers.length === 0) {
    lines.push('Members: none')
  } else {
    lines.push(`Members (${peers.length}):`)
    const roleWidth = Math.max(...peers.map((p) => str(p.role, '?').length))
    for (const p of peers) {
      const label = str(p.label) || '(no label)'
      lines.push(`  ${str(p.role, '?').padEnd(roleWidth)}  ${label}${p.connected === true ? '  — connected' : ''}`)
    }
  }
  const pending = Array.isArray(s.pending) ? s.pending.map(obj) : []
  if (pending.length > 0) {
    lines.push(`${plural(pending.length, 'join request')} waiting for an owner (approve from an owner's desktop):`)
    for (const p of pending) lines.push(`  code ${str(p.sas, '?')}`)
    lines.push(`  ${SAS_COMPARE_HINT}`)
  }
  return lines
}

/** Render a successful reply. The exit code is 1 when the command did its part but the outcome it
 *  exists for did not happen (hosting did not start, there is no address yet). Only `info`,
 *  `status`, `bootstrap` and `resume` take `--json`. */
function render(req: AdminRequest, result: unknown, json: boolean): { lines: string[]; code: number } {
  switch (req.cmd) {
    case 'init': {
      const r = obj(result) as Partial<AdminInitResult>
      const lines = [r.created ? 'Created the host key and the team.' : 'The host key already existed; the team is unchanged.']
      if (r.start === 'started') {
        lines.push('Hosting: ON.', ...addressLines(r.info, r.joinCode))
        return { lines, code: 0 }
      }
      const why =
        r.start === 'stopped'
          ? 'the service is shutting down'
          : r.start === 'host-key-unreadable'
            ? 'the host key could not be read (see `team status`)'
            : `start answered "${str(r.start, '?')}"`
      lines.push(`Hosting did not start: ${why}.`)
      return { lines, code: 1 }
    }
    case 'add-owner':
      return { lines: [`Added ${req.label || req.pubkey} as an owner.`], code: 0 }
    case 'remove':
      return { lines: ['Removed. Their live sessions were closed.'], code: 0 }
    case 'share':
      return {
        lines: [req.on ? `Project ${req.projectId} is now shared with the team.` : `Project ${req.projectId} is no longer shared.`],
        code: 0
      }
    case 'info': {
      const r = obj(result) as Partial<AdminInfoResult>
      const has = r.info !== null && r.info !== undefined
      if (json) return { lines: [safeJson(result)], code: has ? 0 : 1 }
      if (!has) {
        return {
          lines: ['Hosting has not started on this server, so there is no team address yet. Run `team init` (see `team status` for why).'],
          code: 1
        }
      }
      const lines = r.enabled === true ? ['Hosting: ON.'] : ['Hosting: OFF — this address answers nobody until hosting starts.']
      lines.push(...addressLines(r.info, r.enabled === true ? r.joinCode : null))
      return { lines, code: 0 }
    }
    case 'status':
      return { lines: json ? [safeJson(result)] : describeStatus(result as AdminStatusResult), code: 0 }
    case 'bootstrap': {
      if (json) return { lines: [safeJson(result)], code: 0 }
      const r = obj(result)
      const created = obj(r.created)
      const lines = [
        created.team === true ? 'Created the team.' : 'The team already existed.',
        `Project ${str(r.projectName, '?')} (${str(r.projectId, '?')}) is shared with the team.`,
        r.hosting === 'up' ? 'Hosting: ON.' : 'Hosting: starting — teammates can join in a moment.',
        'Join code (give it to teammates; an owner approves each new device):',
        `  ${str(r.joinCode, '?')}`
      ]
      return { lines, code: 0 }
    }
    case 'resume': {
      if (json) return { lines: [safeJson(result)], code: 0 }
      const rows = Array.isArray(obj(result).results) ? (obj(result).results as unknown[]).map(obj) : []
      const lines = rows.map(
        (r) =>
          `  ${str(r.nodeId, '?')}  ${r.status === 'already-running' ? 'already running' : str(r.status, '?')}` +
          (typeof r.reason === 'string' ? ` (${str(r.reason)})` : '')
      )
      return { lines: lines.length ? lines : ['No sessions to resume.'], code: 0 }
    }
    case 'rotate-key': {
      const r = obj(result) as Partial<AdminRotateResult>
      if (r.result === 'not-running') {
        return { lines: ['Host key rotated. Hosting is off; run `team init` (or restart the service) to start it.'], code: 0 }
      }
      if (r.result === 'started') {
        return {
          lines: [
            'Host key rotated. Every teammate needs a NEW join code; old bookmarks will not connect.',
            ...addressLines(r.info, r.joinCode)
          ],
          code: 0
        }
      }
      return {
        lines: [
          `Host key rotated, but hosting did not restart (${str(r.result, '?')}). Every teammate needs a NEW join code; ` +
            'see `team status`.'
        ],
        code: 1
      }
    }
  }
}

/** The longest stdin `team resume` reads: the admin socket's request cap, less its envelope. */
const RESUME_STDIN_MAX = 60 * 1024

function readProcessStdin(): Promise<string> {
  if (process.stdin.isTTY) return Promise.reject(new Error('pipe the session list on stdin'))
  return new Promise((resolve, reject) => {
    let buf = ''
    process.stdin.setEncoding('utf8')
    process.stdin.on('data', (d: string) => {
      buf += d
      if (buf.length > RESUME_STDIN_MAX) {
        process.stdin.destroy()
        reject(new Error(`the session list is larger than ${RESUME_STDIN_MAX} bytes`))
      }
    })
    process.stdin.on('end', () => resolve(buf))
    process.stdin.on('error', reject)
  })
}

export async function runTeamCli(
  argv: string[],
  dataDir: string,
  out: (s: string) => void,
  err: (s: string) => void = out,
  readStdin: () => Promise<string> = readProcessStdin
): Promise<number> {
  if (argv.length === 1 && (argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help')) {
    out(TEAM_USAGE)
    return 0
  }
  const dd = takeDataDir(argv)
  if ('error' in dd) {
    err(dd.error)
    return 2
  }
  const req = parseTeamArgv(dd.argv)
  if ('error' in req) {
    err(req.error)
    return 2
  }
  if (req.cmd === 'resume') {
    let raw: unknown
    try {
      raw = JSON.parse(await readStdin())
    } catch (e) {
      err(`team resume reads a JSON list of sessions on stdin: ${clean(e instanceof Error ? e.message : String(e))}`)
      return 2
    }
    const sessions = parseResumeSessions(raw)
    if (typeof sessions === 'string') {
      err(clean(sessions))
      return 2
    }
    req.sessions = sessions
  }
  const r = await callTeamAdmin(dd.dataDir ?? dataDir, req)
  const json = dd.argv.includes('--json')
  if (!r.ok) {
    // A remote caller (the desktop, over an ssh exec channel) reads stdout only: under --json the
    // refusal is also one machine-readable line there. The human line still goes to stderr.
    if (json) out(JSON.stringify({ ok: false, error: clean(r.error), ...(r.code ? { code: r.code } : {}) }))
    err(clean(r.error))
    return 1
  }
  // The reply is printed to `out` even when the exit code is 1: the command ran, and what it found
  // (hosting did not start, no address yet) is its answer, not a failure to run.
  const { lines, code } = render(req, r.result, json)
  for (const line of lines) out(line)
  return code
}