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.

14.9 KB
Raw Blame
import type {
  CanvasNodeState, KanbanColumn, KanbanColumnCategory, Project, ProjectKanban
} from '@shared/types'
import { columnCategory } from '@shared/kanban-category'
import { columnOrder, placeAssignment, type CardAnchor } from '@shared/kanban-order'
import { SYSTEM_NODE_COLORS } from '../state/workspace'
import { defaultKanbanFor } from '@shared/kanban-default-board'
import { autoLabelColor, boardLabels, cardMeta, createLabel, metaList, setCardLabels } from '@shared/kanban-labels'
import { prunePullLinks } from '@shared/kanban-pull-links'

// The card-meta + label transforms live in `@shared/kanban-labels` (the host core applies the
// same ones for the phone's label verb); re-exported so every renderer import stays as it was.
export * from '@shared/kanban-labels'

// Pure kanban board transforms — the ONLY place board structure changes. The UI computes
// the next board here and hands it whole to setProjectKanban (no second live source).
// Every function returns a new board; unknown ids are no-ops returning the input.
// Cards are the project's SESSION NODES — the board stores only column assignments; a
// session with no (or dangling) assignment sits in the virtual Ungrouped column.

const kid = (prefix: string): string => `${prefix}-${Math.random().toString(36).slice(2, 10)}`

/** Default board for a project whose file has no `kanban` yet. NOT written to disk
 *  until the first user edit (the spec's lazy-default rule) — EXCEPT when the phone asks for one
 *  outright (relay `projects.ensureBoard`), which seeds the same three columns from the same
 *  shared definition so a board born on either surface is the same board.
 *
 *  Its column ids are DETERMINISTIC per project (`defaultKanbanFor`): every client renders this
 *  board until someone edits it, and with boards syncing live two clients' first edits must land on
 *  the same three columns, not six. So it takes the project it is the default OF — never pass the
 *  active project's default for another project's board. */
export function defaultKanban(projectId: string): ProjectKanban {
  return defaultKanbanFor(projectId)
}

/** Color for the next added column — cycles the node palette. */
export function nextColumnColor(k: ProjectKanban): string {
  return SYSTEM_NODE_COLORS[k.columns.length % SYSTEM_NODE_COLORS.length]
}

export function addColumn(k: ProjectKanban, title: string, color: string): ProjectKanban {
  const column = { id: kid('kcol'), title, color }
  if (!k.github) return { ...k, columns: [...k.columns, column] }
  const base = `status:${title.trim().toLocaleLowerCase('en-US')
    .normalize('NFKC').replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-|-$/g, '') || 'column'}`
  const used = new Set(k.github.columnMappings.map((mapping) =>
    mapping.label.normalize('NFKC').toLocaleLowerCase('en-US')))
  let label = base.slice(0, 50)
  for (let suffix = 2; used.has(label.toLocaleLowerCase('en-US')); suffix++) {
    const ending = `-${suffix}`
    label = `${base.slice(0, 50 - ending.length)}${ending}`
  }
  return {
    ...k,
    columns: [...k.columns, column],
    github: {
      ...k.github,
      columnMappings: [...k.github.columnMappings, { columnId: column.id, label }]
    }
  }
}

export function renameColumn(k: ProjectKanban, columnId: string, title: string): ProjectKanban {
  return { ...k, columns: k.columns.map((c) => (c.id === columnId ? { ...c, title } : c)) }
}

export function recolorColumn(k: ProjectKanban, columnId: string, color: string): ProjectKanban {
  return { ...k, columns: k.columns.map((c) => (c.id === columnId ? { ...c, color } : c)) }
}

/** Sets (or, with `undefined`, clears) a column's lifecycle category. Returns the SAME board when
 *  nothing changes (unknown column, or the value it already reads as), so a caller can skip a
 *  no-op persist. The UI confirms first when the column holds cards (`categoryChangeImpact`). */
export function setColumnCategory(
  k: ProjectKanban,
  columnId: string,
  category: KanbanColumnCategory | undefined
): ProjectKanban {
  const target = k.columns.find((c) => c.id === columnId)
  if (!target || columnCategory(target) === columnCategory({ category })) return k
  return {
    ...k,
    columns: k.columns.map((c) => {
      if (c.id !== columnId) return c
      const { category: _old, ...rest } = c
      return category ? { ...rest, category } : rest
    })
  }
}

/** Moves a column before `beforeId` (null = to the end). */
export function moveColumn(k: ProjectKanban, columnId: string, beforeId: string | null): ProjectKanban {
  if (columnId === beforeId) return k
  const dragged = k.columns.find((c) => c.id === columnId)
  if (!dragged) return k
  const without = k.columns.filter((c) => c.id !== columnId)
  const idx = beforeId ? without.findIndex((c) => c.id === beforeId) : -1
  const at = idx === -1 ? without.length : idx
  return { ...k, columns: [...without.slice(0, at), dragged, ...without.slice(at)] }
}

/** Deletes a user column; its assigned sessions return to Ungrouped (assignments drop).
 *  Non-destructive by design — sessions are untouched, so no confirm dialog and no
 *  last-column rule (the virtual Ungrouped column always remains). */
export function deleteColumn(k: ProjectKanban, columnId: string): ProjectKanban {
  if (!k.columns.some((c) => c.id === columnId)) return k
  const github = (() => {
    if (!k.github) return undefined
    const { completionColumnId, ...rest } = k.github
    return {
      ...rest,
      columnMappings: k.github.columnMappings.filter((mapping) => mapping.columnId !== columnId),
      ...(completionColumnId && completionColumnId !== columnId ? { completionColumnId } : {})
    }
  })()
  return {
    ...k,
    columns: k.columns.filter((c) => c.id !== columnId),
    assignments: k.assignments.filter((a) => a.columnId !== columnId),
    ...(github ? { github } : {})
  }
}

/** Node ids assigned to `columnId`, in board order — rank first, array order for entries without
 *  one (@shared/kanban-order). Every board reader goes through this. */
export function assignedTo(k: ProjectKanban, columnId: string): string[] {
  return columnOrder(k.assignments, columnId).map((a) => a.nodeId)
}

/**
 * Resolve a user-supplied column reference (from the canvas-control `assign` verb) to a column
 * id. Empty or 'ungrouped' (case-insensitive) → `null` (the virtual Ungrouped column = unassign).
 * Otherwise match by exact id first, then by case-insensitive title. Unknown → `undefined`, so the
 * caller can distinguish "send to Ungrouped" (null) from "no such column" (undefined) and report
 * the available columns. Agents naturally pass a title ("In Progress"); ids come from `board`.
 */
export function resolveColumnRef(k: ProjectKanban, ref: string): string | null | undefined {
  const raw = ref.trim()
  if (!raw || raw.toLowerCase() === 'ungrouped') return null
  const byId = k.columns.find((c) => c.id === raw)
  if (byId) return byId.id
  const byTitle = k.columns.find((c) => c.title.toLowerCase() === raw.toLowerCase())
  return byTitle ? byTitle.id : undefined
}

/** Ids from `sessionIds` with no live assignment — never assigned, or assigned to a column
 *  that no longer exists (e.g. a git merge kept the assignment but lost the column). Order
 *  follows `sessionIds` (= canvas order). */
export function unassigned(k: ProjectKanban, sessionIds: string[]): string[] {
  const cols = new Set(k.columns.map((c) => c.id))
  const assigned = new Set(
    k.assignments.filter((a) => cols.has(a.columnId)).map((a) => a.nodeId)
  )
  return sessionIds.filter((id) => !assigned.has(id))
}

/** The explicit "bottom of the column" anchor for `assignNode` — a drop BELOW the last card, or on
 *  the column's empty space under its cards. Everything else that names no card lands at the top. */
export const AT_COLUMN_END: unique symbol = Symbol('kanban.atColumnEnd')

/** Assigns/moves a session card. `columnId` null = back to Ungrouped (assignment removed;
 *  Ungrouped order is canvas order, so the anchor is ignored there).
 *
 *  Placement in the destination column:
 *  - `beforeNodeId` names a card IN that column → just above it;
 *  - `AT_COLUMN_END` → at the bottom (only a positional drop asks for this);
 *  - anything else — `null`, or a card that is not in that column — is UNANCHORED and lands at
 *    the TOP. An unanchored move is "file this here" (the card menu, the agent `assign` verb, a
 *    card created from a column): appended at the bottom of a long "Done" column, the card an
 *    agent just finished read as having disappeared.
 *
 *  The move writes one `rank` and keeps the array in rank order (`placeAssignment`, which the
 *  relay's move verb shares). Unknown target column, or a card already exactly there, returns the
 *  SAME board. */
export function assignNode(
  k: ProjectKanban,
  nodeId: string,
  columnId: string | null,
  beforeNodeId: string | null | typeof AT_COLUMN_END
): ProjectKanban {
  if (nodeId === beforeNodeId) return k
  if (columnId === null) {
    if (!k.assignments.some((a) => a.nodeId === nodeId)) return k
    return { ...k, assignments: k.assignments.filter((a) => a.nodeId !== nodeId) }
  }
  if (!k.columns.some((c) => c.id === columnId)) return k
  const anchor: CardAnchor =
    beforeNodeId === AT_COLUMN_END ? 'end' : typeof beforeNodeId === 'string' ? { before: beforeNodeId } : 'top'
  const assignments = placeAssignment(k.assignments, nodeId, columnId, anchor)
  return assignments === k.assignments ? k : { ...k, assignments }
}

/**
 * Moves SEVERAL session cards in one go (a multi-card drag, the selection bar's "Move to"),
 * landing them TOGETHER at the anchor and in the order given (callers pass board order).
 *
 * Same anchors as `assignNode`, with one addition: an anchor that is itself one of the moving
 * cards cannot hold a place, so it resolves to the next card below it that stays (else the bottom).
 * One card is exactly `assignNode`; nothing to move returns the SAME board.
 */
export function assignNodes(
  k: ProjectKanban,
  nodeIds: readonly string[],
  columnId: string | null,
  beforeNodeId: string | null | typeof AT_COLUMN_END
): ProjectKanban {
  const ids = [...new Set(nodeIds)]
  if (ids.length === 0) return k
  if (ids.length === 1) return assignNode(k, ids[0], columnId, beforeNodeId)
  const moving = new Set(ids)
  if (columnId === null) {
    if (!k.assignments.some((a) => moving.has(a.nodeId))) return k
    return { ...k, assignments: k.assignments.filter((a) => !moving.has(a.nodeId)) }
  }
  if (!k.columns.some((c) => c.id === columnId)) return k
  const column = assignedTo(k, columnId)
  let anchor = beforeNodeId
  if (typeof anchor === 'string' && moving.has(anchor)) {
    const at = column.indexOf(anchor)
    anchor = at === -1 ? null : column.slice(at + 1).find((id) => !moving.has(id)) ?? AT_COLUMN_END
  }
  // Unanchored = the TOP, where each card lands above the one before it: place them last-first so
  // the group reads top-down in the order given. Every other anchor stays put while cards arrive.
  const atTop = anchor === null || (typeof anchor === 'string' && !column.includes(anchor))
  return (atTop ? [...ids].reverse() : ids).reduce((acc, id) => assignNode(acc, id, columnId, anchor), k)
}

/** Drops assignments of nodes that no longer exist. Returns the SAME object when nothing
 *  changed, so callers can cheaply skip a no-op persist. */
export function pruneAssignments(k: ProjectKanban, liveIds: string[]): ProjectKanban {
  const live = new Set(liveIds)
  const assignments = k.assignments.filter((a) => live.has(a.nodeId))
  const meta = metaList(k).filter((m) => m && live.has(m.nodeId))
  const sameAssignments = assignments.length === k.assignments.length
  const sameMeta = meta.length === metaList(k).length
  // Pull request tombstones/opt-outs name cards too, and prune with them.
  const pruned = prunePullLinks(k, live)
  if (sameAssignments && sameMeta) return pruned
  const next: ProjectKanban = { ...pruned, assignments }
  if (Array.isArray(k.meta)) {
    if (meta.length) next.meta = meta
    else delete next.meta
  }
  return next
}

/** The column a node is assigned to, resolved against a project's board — undefined when
 *  unassigned, dangling (column deleted elsewhere), or the project has no board yet. All
 *  three mean Ungrouped, and the canvas shows no column pill for Ungrouped. */
export function columnForNode(
  k: ProjectKanban | undefined,
  nodeId: string
): KanbanColumn | undefined {
  if (!k) return undefined
  const a = k.assignments.find((x) => x.nodeId === nodeId)
  return a ? k.columns.find((c) => c.id === a.columnId) : undefined
}

// ── Unification: legacy free-text node tags → board labels ────────────────────────────────────

/** Fold each node's free-text tags into board labels: reuse an existing label by name (case-
 *  insensitive) or create one (auto-colored), then apply its id to that card. Pure; the caller
 *  clears the nodes' `tags`. Idempotent by construction (an empty tag list contributes nothing). */
export function migrateTagsToLabels(
  k: ProjectKanban,
  nodeTags: Array<{ nodeId: string; tags: string[] }>
): ProjectKanban {
  let board = k
  for (const { nodeId, tags } of nodeTags) {
    const names = [...new Set(tags.map((t) => t.trim()).filter(Boolean))]
    if (!names.length) continue
    const ids: string[] = []
    for (const name of names) {
      const existing = boardLabels(board).find((l) => l.name.toLowerCase() === name.toLowerCase())
      if (existing) ids.push(existing.id)
      else {
        const res = createLabel(board, name, autoLabelColor(board))
        board = res.k
        ids.push(res.id)
      }
    }
    const cur = cardMeta(board, nodeId)?.labels ?? []
    board = setCardLabels(board, nodeId, [...cur, ...ids])
  }
  return board
}

/**
 * One-time per-project unification, run at workspace hydrate (idempotent — a project whose nodes
 * carry no `tags` is returned UNCHANGED, by identity). For every node with `tags`:
 *  - the legacy `['claude']` MARKER is honored (agentId ← 'claude' when unset) — it was never a
 *    user tag, so it is NOT turned into a label (mirrors nodeStatesToFlow's own claude migration);
 *  - every other tag becomes a board label (reused/created) applied to that card;
 *  - the node's `tags` field is dropped (so the next hydrate is a no-op).
 */
export function migrateProjectTags(project: Project): Project {
  const tagged = project.nodes.filter((n) => Array.isArray(n.tags) && n.tags.length > 0)
  if (!tagged.length) return project
  const nodeTags = tagged
    .map((n) => ({ nodeId: n.id, tags: (n.tags as string[]).filter((t) => t !== 'claude') }))
    .filter((x) => x.tags.length > 0)
  const kanban = migrateTagsToLabels(project.kanban ?? defaultKanban(project.id), nodeTags)
  const nodes: CanvasNodeState[] = project.nodes.map((n) => {
    if (!Array.isArray(n.tags) || !n.tags.length) return n
    const hadClaude = n.tags.includes('claude')
    const { tags: _t, ...rest } = n
    return !n.agentId && hadClaude ? { ...rest, agentId: 'claude' } : rest
  })
  return { ...project, nodes, kanban }
}