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.

17.2 KB
Raw Blame
// Pure halves of the `open-project` control verb and the `--project`-targeted opens
// (issue #338, spec §2.1/§2.2). Canvas.tsx's dispatch only wires these — the dialog, the store
// calls and the reply — so every decision that does not need React is unit-testable here, the
// same reasoning as controlRouting.ts / pendingLaunch.ts.
import { oneLine } from '@shared/one-line'
import { rootPositionWith } from '@shared/root-position'
import { sourceIsControlCapable } from './controlRouting'

/** The little these helpers need to know about a project. */
export interface ProjectForOpen {
  id: string
  name: string
  cwd?: string
}

/**
 * The dedupe rule (spec B1): the exact-string match `openFolderProject` uses, with the trailing
 * slash normalized away so `/a/b/` and `/a/b` cannot mint two tabs for one directory. `--cwd`
 * arrives here ALREADY resolved by main (`path.resolve`, spec P7) — this is cosmetic-slash
 * defense, never a second resolution.
 */
export function normalizeProjectCwd(resolvedCwd: string): string {
  // Both separators: a Windows cwd arrives with backslashes, and stripping only `/` left a
  // trailing `\` in place — which then became an empty final segment for anything splitting the
  // path afterwards.
  if (resolvedCwd.length <= 1) return resolvedCwd
  const stripped = resolvedCwd.replace(/[\\/]+$/, '')
  // …but a separator is not always cosmetic. `C:\` is the drive ROOT; `C:` is the current
  // directory ON drive C — a different place, and one that would dedupe against the wrong
  // project. Likewise a path that is nothing but separators. Keep the original wherever
  // removing the separator would change what the path MEANS.
  return stripped === '' || /^[A-Za-z]:$/.test(stripped) ? resolvedCwd : stripped
}

// `folderName` lives in shared/ so the core-side project loader can use the same rule; it stays
// exported from here too, because that is where every renderer caller already imports it from.
import { folderName } from '@shared/project-name'
export { folderName }

export function findProjectByCwd<T extends { cwd?: string }>(
  projects: readonly T[],
  resolvedCwd: string
): T | undefined {
  const cwd = normalizeProjectCwd(resolvedCwd)
  return projects.find((p) => p.cwd === cwd)
}

/**
 * The renderer-session attach-consent mirror (spec §4.2 Q1, adopted): which (caller, project)
 * pairs have already passed a human decision — creating, adopting, or the lighter first-attach
 * "Allow?" — so an idempotent re-open by the SAME caller does not re-raise the dialog, while a
 * DIFFERENT caller naming the same cwd still asks. DIALOG DEDUPE ONLY: authorization is main's
 * grant ledger (src/core/project-grants.ts), keyed to the core's own verified identity verdict; this
 * map decides nothing but whether a dialog is shown. In-memory, per app run — the same lifetime
 * as the grants it mirrors.
 */
const attachAsked = new Map<string, Set<string>>()

export function attachConsentRecorded(callerNodeId: string, projectId: string): boolean {
  return attachAsked.get(callerNodeId)?.has(projectId) ?? false
}

export function recordAttachConsent(callerNodeId: string, projectId: string): void {
  const set = attachAsked.get(callerNodeId) ?? new Set<string>()
  set.add(projectId)
  attachAsked.set(callerNodeId, set)
}

/** Caller-node teardown: the mirror dies with the node it asked for — the same lifetime as
 *  main's grant ledger (`clearCaller` on pty destroy/recycle), so a node id revived after a
 *  deletion faces a fresh dialog, exactly as it faces a fresh grant (review #363 M-1). */
export function clearAttachConsent(callerNodeId: string): void {
  attachAsked.delete(callerNodeId)
}

export function clearAttachConsentForTests(): void {
  attachAsked.clear()
}

/**
 * The v1 flag exclusion for `--project` (spec §2.2): `--group` and `--after` both name ids that
 * live INSIDE a project, and validating them across a project boundary is exactly the surface v1
 * excludes. Returns the named refusal, or null when neither flag is present. Pure so the guard
 * is red-capable (review #363 I-2) — the dispatch only relays the answer; an empty-string value
 * counts as "not passed" (the shim always sends a value for a bare flag).
 */
export function projectTargetFlagRefusal(args: {
  group?: string
  after?: string
  'after-success'?: string
}): string | null {
  // `--after-success` names station ids exactly as `--after` does, so it is excluded for the same
  // reason (and it is folded into `after` before this runs, so either field refuses it).
  if (args.group || args.after || args['after-success']) {
    return 'project-target-flag-unsupported: --group/--after/--after-success cannot be combined with --project'
  }
  return null
}

/** What `resolveProjectTarget` needs to know about a project (a structural subset of `Project`). */
export interface ProjectTargetProject {
  id: string
  ssh?: unknown
  remote?: boolean
  nodes: readonly { id: string; agentId?: unknown }[]
}

export type ProjectTargetResolution<P> =
  /** The target IS the caller's own project: fall through to the legacy path (B3a). */
  | { kind: 'own' }
  | { kind: 'refused'; error: string }
  | { kind: 'target'; project: P }

/**
 * The renderer's `--project` belt, ONE definition for every verb that takes the flag
 * (`open-terminal`/`open-claude`/`open-agent` and `run`, #925). Main's `gateProjectTarget` already
 * enforced own-or-granted before forwarding, so none of this is the boundary — but it is the
 * cross-project reach's second line, and two hand-copies of it are how one of them drifts.
 *
 * Order matters and is the dispatch's historical one: the caller's own project first (it is not a
 * cross-project call at all, so nothing below applies to it), then the source checks, then the
 * target checks.
 * - The caller's project is the ACTIVE one when the source is on the live canvas, else the one
 *   whose serialized nodes hold it.
 * - The unknown-target refusal is worded TRANSIENT: main refused every stranger id with one
 *   byte-identical sentence (no existence oracle), so this only fires for a target main
 *   authorized that the renderer's store cannot see yet (mid-hydration).
 * - The SSH/relay refusal is belt for an invariant main already holds: grants are minted only by
 *   local open-project, so a granted SSH id cannot exist; if that ever breaks, the target is still
 *   refused, never acted on. A relay tab is another machine's project entirely. `sshVerbWord` is
 *   the one word the verbs differ in; with `opening` the sentence is byte-identical to core's
 *   `PROJECT_TARGET_SSH_UNSUPPORTED`.
 */
export function resolveProjectTarget<P extends ProjectTargetProject>(input: {
  targetId: string
  sourceNodeId: string
  /** React Flow's nodes — the ACTIVE project's. */
  liveNodes: readonly { id: string; data: { agentId?: unknown } }[]
  projects: readonly P[]
  activeProjectId: string
  sshVerbWord: 'opening' | 'starting'
}): ProjectTargetResolution<P> {
  const liveSrc = input.liveNodes.find((n) => n.id === input.sourceNodeId)
  const storedSrc = input.projects
    .flatMap((p) => p.nodes.map((n) => ({ node: n, projectId: p.id })))
    .find((x) => x.node.id === input.sourceNodeId)
  const callerProjectId = liveSrc ? input.activeProjectId : storedSrc?.projectId
  if (input.targetId === callerProjectId) return { kind: 'own' }
  if (!liveSrc && !storedSrc) {
    return { kind: 'refused', error: 'source node is not in any open project' }
  }
  if (!sourceIsControlCapable(liveSrc?.data.agentId ?? storedSrc?.node.agentId)) {
    return { kind: 'refused', error: 'source node is not a control-capable agent' }
  }
  const project = input.projects.find((p) => p.id === input.targetId)
  if (!project) {
    return {
      kind: 'refused',
      error: 'project-target-refused: the target project is not available here — try again'
    }
  }
  if (project.ssh || project.remote) {
    return {
      kind: 'refused',
      error: `project-target-ssh-unsupported: ${input.sshVerbWord} sessions into an SSH project is not supported — do not retry`
    }
  }
  return { kind: 'target', project }
}

export type OpenProjectPlan =
  | { kind: 'silent'; project: ProjectForOpen }
  | {
      kind: 'confirm'
      confirmKind: 'attach' | 'adopt' | 'create'
      message: string
      confirmLabel: string
      /** Set for `attach` — the existing project the caller is asking into. */
      project?: ProjectForOpen
    }

/**
 * The whole consent decision for one `open-project` request (spec §2.1 steps 2–4 + Q1). Pure:
 * the caller has already resolved the cwd (main), looked for a probe result (only needed when no
 * cwd hit exists), and passes everything in. Every dialog message shows the RESOLVED path (P5) —
 * the raw argument never reaches the renderer at all (main rewrites args.cwd).
 *
 * Q1 (adopted): an idempotent hit is silent ONLY for a caller that already passed a human
 * decision for this project. The first attach confirms with lighter copy, so every grant main
 * records traces back to exactly one human decision — a silent hit would let a verified caller
 * reach BY CWD the very targeting rights B3 forbids reaching by id.
 */
export function planOpenProject(input: {
  projects: readonly ProjectForOpen[]
  callerNodeId: string
  srcTitle: string
  resolvedCwd: string
  /** The probed .nodeterm project's name, when `probeFolder` answered (adopt path). */
  probedName?: string
  requestedName?: string
}): OpenProjectPlan {
  const { projects, callerNodeId, srcTitle, resolvedCwd, probedName, requestedName } = input
  const existing = findProjectByCwd(projects, resolvedCwd)
  if (existing) {
    if (attachConsentRecorded(callerNodeId, existing.id)) return { kind: 'silent', project: existing }
    return {
      kind: 'confirm',
      confirmKind: 'attach',
      // `oneLine` on every interpolated name (review #363 M-2): a project/probe/--name string is
      // caller- or repo-supplied, and a newline in it would let it inject lines into the consent
      // dialog. The resolved path's own line breaks are the dialog's structure; nothing else adds
      // lines. (The stored name stays the raw create-only string, like the human addProject path
      // — this flattening is dialog copy only.)
      message: `Agent "${srcTitle}" wants to open sessions in project "${oneLine(existing.name)}". Allow?`,
      confirmLabel: 'Allow',
      project: existing
    }
  }
  if (probedName !== undefined) {
    return {
      kind: 'confirm',
      confirmKind: 'adopt',
      message:
        `Agent "${srcTitle}" wants to add the existing project at\n${resolvedCwd}\n` +
        `to your workspace ("${oneLine(probedName)}"). Add it?`,
      confirmLabel: 'Add project'
    }
  }
  const name = oneLine(
    (requestedName ?? '').trim() ||
      (folderName(normalizeProjectCwd(resolvedCwd)) || 'Project')
  )
  return {
    kind: 'confirm',
    confirmKind: 'create',
    message:
      `Agent "${srcTitle}" wants to create a project for\n${resolvedCwd}\n` +
      `(name "${name}"). Create it?`,
    confirmLabel: 'Create project'
  }
}

/**
 * The success reply (spec §2.1): `result` carries `{ projectId, name, cwd, created }` — the id is
 * what the caller feeds `--project`, and `created` is true for anything that added a new
 * workspace entry (create AND adopt; an idempotent hit answers false). The message carries the
 * project's REAL name, so an agent whose `--name` was ignored on a hit learns what it is.
 */
export function openProjectReply(
  project: ProjectForOpen,
  created: boolean,
  adopted: boolean
): {
  message: string
  result: { projectId: string; name: string; cwd: string; created: boolean }
} {
  const verb = created ? 'created' : adopted ? 'added' : 'opened'
  const cwd = project.cwd ?? ''
  return {
    message: `${verb} project "${project.name}" (${project.id}) for ${cwd}`,
    result: { projectId: project.id, name: project.name, cwd, created: created || adopted }
  }
}

/**
 * Re-arm a freshly-built node for a COLD open (spec §2.2): its composed launch command is MOVED —
 * never copied — from `initialCommand` into `pendingLaunch: { after: [], command, attempted: false }`.
 * `initialCommand` is deliberately never serialized (workspace.ts), while `pendingLaunch` is: a
 * command left in `initialCommand` on the store path would be silently dropped by serialization
 * and the node would never start; a copy left behind would double-deliver if that ever changed.
 * An empty `after` is vacuously ready (`launchesToFire`), so the armed-launch effect fires it on
 * the target project's first view — the cold-open contract.
 */
export function armForColdOpen<
  T extends { data: { initialCommand?: string; pendingLaunch?: unknown } }
>(node: T): T {
  const command = node.data.initialCommand
  if (!command) return node
  return {
    ...node,
    data: { ...node.data, initialCommand: undefined, pendingLaunch: { after: [], command, attempted: false } }
  }
}

/** A node as either the serialized store or the live canvas holds it — enough for placement. */
export interface PlacedNode {
  id?: string
  parentId?: string
  position: { x: number; y: number }
  size?: { width: number; height: number }
  width?: number | null
  height?: number | null
}

const placedW = (n: PlacedNode): number => n.size?.width ?? (n.width as number) ?? 0
const placedH = (n: PlacedNode): number => n.size?.height ?? (n.height as number) ?? 0

/**
 * A stored node's ROOT-space position (a group child's stored position is frame-relative), over
 * the shared parent walk in `@shared/root-position`.
 */
export function rootPositionIn(
  nodes: readonly PlacedNode[],
  node: PlacedNode
): { x: number; y: number } {
  const byId = new Map<string, PlacedNode>()
  for (const n of nodes) if (n.id) byId.set(n.id, n)
  return rootPositionWith(node, (id) => byId.get(id))
}

/**
 * Where a node opened INTO another project lands (spec §2.2): centered below the lowest existing
 * node, because `placeBelow(src)` is meaningless in a project that does not contain the source.
 * Returns a CENTER point (the factories' `center` parameter — `placeAt` converts to top-left).
 * Guaranteed non-overlapping: everything else ends above the returned rect's top edge. Positions
 * are resolved to root space first, so a group child poking below its frame still counts.
 */
export function nextFreePosition(
  nodes: readonly PlacedNode[],
  size: { width: number; height: number } = { width: 640, height: 440 }
): { x: number; y: number } {
  if (!nodes.length) return { x: 40 + size.width / 2, y: 40 + size.height / 2 }
  const byId = new Map<string, PlacedNode>()
  for (const n of nodes) if (n.id) byId.set(n.id, n)
  let left = Infinity
  let bottom = -Infinity
  for (const n of nodes) {
    const at = rootPositionWith(n, (id) => byId.get(id))
    if (Number.isFinite(at.x)) left = Math.min(left, at.x)
    const b = at.y + placedH(n)
    if (Number.isFinite(b)) bottom = Math.max(bottom, b)
  }
  if (!Number.isFinite(left) || !Number.isFinite(bottom)) {
    return { x: 40 + size.width / 2, y: 40 + size.height / 2 }
  }
  return { x: left + size.width / 2, y: bottom + 80 + size.height / 2 }
}

/**
 * What an explicit "Open folder…" should do when it lands on a project already showing the
 * `unavailable` placeholder (issue #385).
 *
 * The placeholder is minted at load time when the ref can't be read, and a save deliberately
 * emits a header-only ref for it — never a file — so a stale placeholder can't clobber a source
 * that might come back. Correct, but it also means a project whose file the user DELETED can
 * never write one again: nothing clears the flag for a local project, so it stays unreadable at
 * every later load. The tab goes inert (`tabClickAction` → 'ignore') while the sessions sidebar,
 * which knows nothing of `unavailable`, still switches to it — the asymmetry issue #385 reports.
 *
 * Opening the folder is a deliberate act, so it is the right moment to break the loop — but only
 * on evidence:
 *   - `absent`  → the file really is gone. Clear the flag so the next save recreates it; an empty
 *                 canvas is the truthful state, since that is what deleting the file left.
 *   - `present` → it reads again (restored, a git checkout). Rehydrate from disk rather than
 *                 clearing the flag, or an empty placeholder would be saved over real nodes.
 *   - `unreadable` → we cannot tell. Change nothing; the placeholder is exactly the right answer.
 */
export type UnavailableRecovery = 'clear' | 'rehydrate' | 'keep'

export function unavailableRecovery(
  project: { unavailable?: boolean; ssh?: unknown; storeInAppData?: boolean },
  fileState: 'present' | 'absent' | 'unreadable'
): UnavailableRecovery {
  // Remote projects are not ours to judge from a local stat — their file lives on the host, and
  // their placeholder is cleared by the reconnect path instead.
  if (!project.unavailable || project.ssh) return 'keep'
  // A project stored in app data (#1145) never had its canvas in the folder: a project.json there
  // is a stale copy or a teammate's, never this project's to rehydrate from. Its placeholder means
  // its app-data file and cache are both gone, so opening the folder starts it again, empty, in app
  // data — and the store still refuses to write that empty canvas over a data file that reappears.
  if (project.storeInAppData) return 'clear'
  if (fileState === 'absent') return 'clear'
  if (fileState === 'present') return 'rehydrate'
  return 'keep'
}