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.

12.0 KB
Raw Blame
/**
 * The geometry half of canvas control (issue #1288): `resize`, `place` and `list --geometry` — the
 * verbs that let an agent rebuild an exact layout (two tight columns of four sessions filling a
 * vertical monitor, say) every time a session is replaced, instead of a human dragging windows.
 *
 * In `src/shared` for the same reason as `arrange-verb.ts`: the shape gate has three readers that
 * cannot import each other — desktop main refuses a malformed call before it is forwarded (that
 * handler never runs `parseControlRequest`), core's `parseControlRequest` (the Server Edition's
 * parser), and the renderer's dispatch belt — and the generated agent docs render their numbers
 * from the constants here. A limit typed once per reader is how the docs come to advertise a value
 * the parser refuses.
 *
 * What is decided HERE is only what no canvas could act on: a missing flag, a value that is not a
 * whole number, a flag the verb does not read. Whether an id exists, is a frame, is collapsed or
 * is maximized is the canvas's question (`resizeNodes` / `placeNodes` in renderer/state/workspace).
 *
 * EVERY FLAG TAKES A VALUE — the SSH shim-loop rule: an older shim on an SSH host takes the token
 * after any flag as its value, so a valueless `--geometry` would swallow whatever follows it.
 */

import { NODE_SIZE_MAX } from './default-node-size'

/**
 * The farthest from the canvas origin `place` puts anything, in px, on either axis. A canvas has no
 * edge, so this is not a bound on the canvas: it is a bound on a TYPO — 100 000 px is over forty
 * 2400 px-wide nodes side by side, and a node sent past it would take a zoom-out to find. Refused
 * above it, never clamped (a clamped coordinate is a placement the caller did not ask for).
 */
export const PLACE_COORD_MAX = 100_000

/** The values `list --geometry` reads. Absent = off, so the default text answer stays one short line per node. */
export const LIST_GEOMETRY_VALUES = ['on', 'off'] as const

/** The flags each geometry verb reads. Anything else is refused by name (#539: a silently dropped
 *  `--heigth 400` is indistinguishable from success to the agent that typed it). */
const RESIZE_FLAGS: ReadonlySet<string> = new Set(['nodes', 'width', 'height'])
const PLACE_FLAGS: ReadonlySet<string> = new Set(['nodes', 'x', 'y', 'dx', 'dy'])

/** The coordinate/size flags `move` must refuse — see `moveArgsRefusal`. */
const MOVE_GEOMETRY_FLAGS = ['x', 'y', 'dx', 'dy', 'width', 'height'] as const

/** The ids a `--nodes` list names, in order, blanks dropped. */
export function geometryIds(raw: string | undefined): string[] {
  return (raw ?? '').split(',').map((s) => s.trim()).filter(Boolean)
}

/** A whole, positive px count, or the refusal. The ceiling is NOT checked here: `resize` clamps to
 *  the kind's minimum and the canvas maximum and reports what it applied (`resizeNodes`). */
function parseSize(flag: 'width' | 'height', raw: string): number | string {
  const s = raw.trim()
  const n = /^\d+$/.test(s) ? Number(s) : NaN
  if (!Number.isSafeInteger(n) || n <= 0) {
    return `resize: --${flag} must be a whole number of pixels above 0 (got "${raw}")`
  }
  return n
}

/** A whole, signed px coordinate within ±PLACE_COORD_MAX, or the refusal. */
function parseCoord(flag: 'x' | 'y' | 'dx' | 'dy', raw: string): number | string {
  const s = raw.trim()
  if (!/^-?\d+$/.test(s)) return `place: --${flag} must be a whole number of pixels (got "${raw}")`
  const n = Number(s) + 0 // `+ 0` turns a typed "-0" into 0
  if (Math.abs(n) > PLACE_COORD_MAX) {
    return `place: --${flag} ${n} is beyond ±${PLACE_COORD_MAX} px — nothing was placed`
  }
  return n
}

function unknownFlag(verb: string, args: Record<string, string>, allowed: ReadonlySet<string>): string | null {
  const unknown = Object.keys(args).find((key) => !allowed.has(key))
  if (unknown === undefined) return null
  if (unknown === 'node') return `${verb}: takes --nodes <id,id> (plural, like arrange and move), not --node`
  return `${verb}: unknown flag --${unknown}`
}

export interface ResizeRequest {
  ids: string[]
  width?: number
  height?: number
}

/** `resize --nodes <id,id> [--width <px>] [--height <px>]`, parsed, or the sentence that refuses it. */
export function parseResizeArgs(args: Record<string, string>): ResizeRequest | { error: string } {
  const flag = unknownFlag('resize', args, RESIZE_FLAGS)
  if (flag) return { error: flag }
  const ids = geometryIds(args.nodes)
  if (ids.length === 0) return { error: 'resize requires --nodes <id,id>' }
  if (args.width === undefined && args.height === undefined) {
    return { error: 'resize requires --width <px>, --height <px>, or both' }
  }
  const out: ResizeRequest = { ids }
  for (const axis of ['width', 'height'] as const) {
    if (args[axis] === undefined) continue
    const v = parseSize(axis, args[axis])
    if (typeof v === 'string') return { error: v }
    out[axis] = v
  }
  return out
}

export interface PlaceRequest {
  ids: string[]
  /** Absolute: where the top-left goes, in canvas (root) coordinates — the numbers `list` reports. */
  x?: number
  y?: number
  /** Relative: how far to shift, in px. Never mixed with `x`/`y` (`parsePlaceArgs` refuses it). */
  dx?: number
  dy?: number
}

/** `place --nodes <id,id> (--x <n> | --y <n> | --dx <n> | --dy <n>)…`, parsed, or the refusal. */
export function parsePlaceArgs(args: Record<string, string>): PlaceRequest | { error: string } {
  const flag = unknownFlag('place', args, PLACE_FLAGS)
  if (flag) return { error: flag }
  const ids = geometryIds(args.nodes)
  if (ids.length === 0) return { error: 'place requires --nodes <id,id>' }
  const absolute = args.x !== undefined || args.y !== undefined
  const relative = args.dx !== undefined || args.dy !== undefined
  if (!absolute && !relative) {
    return { error: 'place requires --x/--y (canvas coordinates, as `list` reports them) or --dx/--dy (an offset)' }
  }
  // Two answers to "where": a silent precedence would be a half-honoured call the agent cannot see.
  if (absolute && relative) {
    return { error: 'place takes --x/--y (where) or --dx/--dy (how far), not both' }
  }
  const out: PlaceRequest = { ids }
  for (const axis of ['x', 'y', 'dx', 'dy'] as const) {
    if (args[axis] === undefined) continue
    const v = parseCoord(axis, args[axis])
    if (typeof v === 'string') return { error: v }
    out[axis] = v
  }
  return out
}

/** Whether `list` was asked for its geometry, or the refusal for a value it does not read. */
export function parseListGeometry(args: Record<string, string>): { geometry: boolean } | { error: string } {
  const raw = args.geometry
  if (raw === undefined) return { geometry: false }
  const v = raw.trim().toLowerCase()
  if (!(LIST_GEOMETRY_VALUES as readonly string[]).includes(v)) {
    return { error: `list: --geometry takes ${LIST_GEOMETRY_VALUES.join(' or ')} (got "${raw}")` }
  }
  return { geometry: v === 'on' }
}

/** `list --geometry on`, for a request the gate already passed — a refused value never gets here. */
export function listGeometryRequested(args: Record<string, string>): boolean {
  const r = parseListGeometry(args)
  return 'geometry' in r && r.geometry
}

/**
 * `move` with a coordinate or a size flag, refused by name. The issue that asked for placement
 * spelled it `move --node <id> --x <n> --y <n>`, and that is the one spelling that must NOT work:
 * `move` without `--group` means "out of every frame, to the top level", so `move --nodes a --x 10`
 * would pull a framed node out of its frame and then ignore the `--x` — a structural change nobody
 * asked for, reported as a success. `place` keeps the parent.
 */
export function moveArgsRefusal(args: Record<string, string>): string | null {
  const flag = MOVE_GEOMETRY_FLAGS.find((f) => args[f] !== undefined)
  if (flag === undefined) return null
  return flag === 'width' || flag === 'height'
    ? `move: --${flag} is not a move flag — move only changes which frame a node is in; size it with \`resize --nodes <id> --${flag} <px>\``
    : `move: --${flag} is not a move flag — move only changes which frame a node is in (and without --group takes it OUT of its frame); put it at coordinates with \`place --nodes <id> --${flag} <n>\`, which keeps its frame`
}

/**
 * The shape gate for every geometry-bearing verb, or `null`. `arrange --gap` is checked by
 * `arrangeArgsRefusal` with the rest of `arrange`'s flags; this covers the verbs this file owns.
 */
export function geometryArgsRefusal(verb: string, args: Record<string, string>): string | null {
  if (verb === 'resize') {
    const r = parseResizeArgs(args)
    return 'error' in r ? r.error : null
  }
  if (verb === 'place') {
    const r = parsePlaceArgs(args)
    return 'error' in r ? r.error : null
  }
  if (verb === 'list') {
    const r = parseListGeometry(args)
    return 'error' in r ? r.error : null
  }
  if (verb === 'move') return moveArgsRefusal(args)
  return null
}

/**
 * The agent-facing description of the geometry verbs, rendered into BOTH generated bodies (the
 * SKILL.md and the marker block) with every number taken from the constants the parser and the
 * transforms check — so the two bodies cannot describe different products, and neither can name a
 * limit the code does not hold.
 */
export function geometryGuidanceLines(): string[] {
  return [
    `- \`list --geometry ${LIST_GEOMETRY_VALUES.join('|')}\` — the text form adds each node's place and size:`,
    '  `@ x,y w×h` in canvas coordinates (whole px), plus `in <frameId>` for a framed node and',
    '  `collapsed` for a header-only one. The JSON result rows ALWAYS carry `x`, `y`, `width`, `height`',
    '  and `parent` (the frame id, or null), so a script reads them without the flag. `x`/`y` are the',
    '  numbers `place` takes; `width`/`height` the ones `resize` takes.',
    '- `resize --nodes <id,id> [--width <px>] [--height <px>]` — set the size of existing nodes (give',
    '  one axis or both; the other is kept). Each value is held between that node kind\'s minimum (the',
    `  smallest the user can drag it to) and ${NODE_SIZE_MAX.width}×${NODE_SIZE_MAX.height}, and applied exactly (no grid snapping); the reply`,
    '  reports the size actually applied and says when it was clamped. A terminal\'s rows and columns',
    '  follow by themselves. A group frame',
    '  is refused — a frame sizes itself to what it holds, so resize or `arrange` its contents. A',
    '  COLLAPSED node keeps its header-only look: the width applies now, the height when it is',
    '  expanded. A MAXIMIZED node is restored first, then sized. A framed node\'s frames re-fit around it.',
    '- `place --nodes <id> --x <n> --y <n>` — put a node\'s top-left at canvas coordinates (the numbers',
    '  `list` reports; give one axis to move along it only). `place --nodes <id,id> --dx <n> --dy <n>`',
    '  shifts nodes by an offset instead; the two forms do not mix. With several ids and `--x`/`--y`',
    '  the nodes move as ONE block: they keep their places relative to each other and the block\'s',
    `  top-left lands on (x, y). Whole px, within ±${PLACE_COORD_MAX}. A framed node STAYS in its frame, which`,
    '  grows or shrinks to hold it (to take it out, `move` it first); a frame moves with everything in',
    '  it. A MAXIMIZED node is restored first. Values are applied exactly — no grid snapping.',
    '  `move` takes none of these flags: it only changes which frame a node is in, and without',
    '  `--group` it takes a node OUT of its frame — so it refuses `--x`/`--y`/`--width` rather than',
    '  doing that silently.',
    '- Worked example — two tight columns of four sessions on a 1080×1920 vertical screen (at 100%',
    '  zoom a canvas px is a screen px): `resize --nodes a,b,c,d,e,f,g,h --width 540 --height 480`, then',
    '  `arrange --nodes a,e,b,f,c,g,d,h --layout grid --cols 2 --gap 0` (ids are laid out row by row,',
    '  so pair each row\'s left and right node), then `place --nodes a,b,c,d,e,f,g,h --x 0 --y 0` to pin',
    '  the block to the corner, and `list --geometry on` to check. Rerun the same calls after a session',
    '  is replaced, with the new id in its slot.'
  ]
}