@opsee/cli 0.11.9

package/src/foreman/opsee-tracker-adapter.ts

@@ -0,0 +1,612 @@
+/**
+ * The Opsee Tracker Adapter: TrackerAdapter over the generated Connect-RPC client (ADR-0010).
+ *
+ * It calls the same backend RPCs the MCP tools do, directly, and mirrors their traps: EditTask is
+ * read-modify-write (its validators want the whole Task back), list RPCs need explicit pagination,
+ * DeleteTaskLabel takes the join-row id, AddComment needs the caller's user id.
+ */
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { Code, ConnectError } from "@connectrpc/connect";
+import type { Run, RunEvent, RunEventInput } from "@opsee/mcp-server/gen/api/v1/initiative_pb.js";
+import {
+  TaskDependencyType,
+  type BoardColumn,
+  type Comment,
+  type InitiativeMemoryEntry,
+  type Label,
+  type Task,
+  type TaskDependency,
+  type TaskPullRequest,
+} from "@opsee/mcp-server/gen/api/v1/models_pb.js";
+import { defaultPagination, overridePagination, type ApiClients } from "@opsee/mcp-server/src/client/api.js";
+import { blockNoteToMarkdown, isBlockNoteJSON } from "@opsee/mcp-server/src/utils/format/blocknote.js";
+// One implementation, shared with `opsee_file_defect`: the two filers must resolve the same label,
+// the same task type and the same priority, or the Tasks they file differ on the board (OPS-284).
+import { sameName } from "@opsee/mcp-server/src/utils/text.js";
+import {
+  pickColumn,
+  TrackerError,
+  type DependencyType,
+  type TrackerErrorCode,
+  type InitiativeContext,
+  type Lifecycle,
+  type TrackerEdge,
+  type TrackerPullRequest,
+  MemoryEntry,
+  MemoryKind,
+  MemoryQuery,
+  MemoryRecord,
+  NewTask,
+  ProjectRepository,
+  PullRequestLink,
+  ReadyTasks,
+  RunRecord,
+  RunRecordQuery,
+  TaskWithContext,
+  TrackerAdapter,
+  TrackerColumn,
+  TrackerComment,
+  TrackerDependency,
+  TrackerTask,
+} from "./tracker-adapter.js";
+
+/** The generated clients the adapter talks to; tests hand in a set pointed at the harness. */
+export type TrackerClients = Pick<
+  ApiClients,
+  | "tasks"
+  | "boards"
+  | "boardColumns"
+  | "taskTypes"
+  | "taskPriorities"
+  | "users"
+  | "labels"
+  | "taskLabels"
+  | "comments"
+  | "taskDependencies"
+  | "initiatives"
+  | "vcsIntegrations"
+>;
+
+/** A Tracker-side refusal the Foreman can act on: a missing label or column, an unknown Task. */
+export { TrackerError };
+
+/** Events fetched per GetRunEvents call while walking a Run Record. */
+const RUN_RECORD_PAGE = 500;
+/** Entries fetched per GetInitiativeMemory call while walking the memory log. */
+const MEMORY_PAGE = 500;
+
+/** The colour a Status Label gets when the Foreman has to create it. */
+const STATUS_LABEL_COLOR = "#6b7280";
+
+const DEPENDENCY_TYPES: Record<number, DependencyType | undefined> = {
+  [TaskDependencyType.BLOCKS]: "blocks",
+  [TaskDependencyType.BLOCKED_BY]: "blocked_by",
+  [TaskDependencyType.DUPLICATES]: "duplicates",
+  [TaskDependencyType.RELATES_TO]: "relates_to",
+};
+
+function byDisplayOrder(a: BoardColumn, b: BoardColumn): number {
+  return a.displayOrder - b.displayOrder;
+}
+
+export function toColumn(c: BoardColumn): TrackerColumn {
+  return { id: c.id, name: c.name, lifecycle: c.lifecycleState };
+}
+
+/** The label names on TaskLabel join rows (rows whose label was not loaded are dropped). */
+function labelNames(rows: { label?: { name: string } }[]): string[] {
+  return rows.map((row) => row.label?.name).filter((name): name is string => !!name);
+}
+
+/** The web app the Task pages live on; the MCP server's OAuth flow reads the same variable. */
+export function appUrl(): string {
+  return (process.env.OPSEE_APP_URL || "https://opsee.ai").replace(/\/+$/, "");
+}
+
+/** The Task's canonical page (`/<company>/<project>/<IDENTIFIER>`, the backend's TaskCanonicalURL
+ * without the decorative title slug), when the Task came with its project and company. */
+export function taskUrl(t: Task): string | undefined {
+  const company = t.project?.company?.slug;
+  const project = t.project?.slug;
+  if (!company || !project || !t.identifier) return undefined;
+  return `${appUrl()}/${company}/${project}/${t.identifier.toUpperCase()}`;
+}
+
+/** A Task description as the Foreman reads it: markdown. Opsee stores what the web UI saved after an
+ * edit as BlockNote JSON, so that is converted here, once, for every consumer of a TrackerTask. */
+function markdownOf(description: string | undefined): string {
+  if (!description) return "";
+  return isBlockNoteJSON(description) ? blockNoteToMarkdown(description) : description;
+}
+
+/** Maps a generated Task; `labels` overrides what the Task embeds when the caller fetched them. */
+export function toTask(t: Task, labels?: string[]): TrackerTask {
+  return {
+    url: taskUrl(t),
+    id: t.id,
+    identifier: t.identifier,
+    title: t.title,
+    description: markdownOf(t.description),
+    projectId: t.project?.id ?? t.projectId,
+    initiativeId: t.initiativeId,
+    parentTaskId: t.parentTaskId,
+    column: t.boardColumn ? toColumn(t.boardColumn) : undefined,
+    labels: labels ?? labelNames(t.taskLabels),
+    type: t.taskType?.name,
+    priority: t.taskPriority?.name,
+    // The scheduler's sort keys (core/scheduler.ts), both already on the Task the RPCs hand out:
+    // GetReadyTasks preloads TaskPriority, and created_at is a column of the Task itself.
+    priorityLevel: t.taskPriority?.level,
+    createdAt: t.createdAt ? timestampDate(t.createdAt) : undefined,
+  };
+}
+
+export function toComment(c: Comment): TrackerComment {
+  return {
+    id: c.id,
+    // A comment edited in the web UI comes back as BlockNote JSON, like a description.
+    body: markdownOf(c.content),
+    authorUserId: c.userId,
+    createdAt: c.createdAt ? timestampDate(c.createdAt) : undefined,
+  };
+}
+
+function toDependency(d: TaskDependency): TrackerDependency | undefined {
+  const type = DEPENDENCY_TYPES[d.type];
+  return type ? { id: d.id, fromTaskId: d.fromTaskId, toTaskId: d.toTaskId, type } : undefined;
+}
+
+/** A graph edge as GetInitiativeContext reports it: the type is the lowercase name (`blocks`). */
+function toEdge(e: { fromTaskId: number; toTaskId: number; type: string }): TrackerEdge | undefined {
+  const type = e.type.toLowerCase() as DependencyType;
+  return type === "blocks" || type === "blocked_by" || type === "duplicates" || type === "relates_to"
+    ? { fromTaskId: e.fromTaskId, toTaskId: e.toTaskId, type }
+    : undefined;
+}
+
+export function toPullRequest(pr: TaskPullRequest): TrackerPullRequest {
+  return {
+    taskId: pr.taskId,
+    number: pr.prNumber,
+    title: pr.title,
+    url: pr.url,
+    state: pr.state,
+    repository: pr.projectRepository?.repositoryFullName || undefined,
+  };
+}
+
+function toMemoryRecord(e: InitiativeMemoryEntry): MemoryRecord {
+  return {
+    id: e.id,
+    kind: e.kind as MemoryKind,
+    body: e.body,
+    sourceTaskId: e.sourceType === "task" ? e.sourceId : undefined,
+    sourceUrl: e.sourceUrl,
+    isAgent: e.isAgent,
+    isSystem: e.isSystem,
+    createdAt: e.createdAt ? timestampDate(e.createdAt) : undefined,
+  };
+}
+
+interface ProjectDefaults {
+  boardId: number;
+  /** Where a new Task lands: the `todo` column, else the board's first. */
+  newTaskColumnId: number;
+  types: { id: number; name: string }[];
+  priorities: { id: number; name: string }[];
+}
+
+export class OpseeTrackerAdapter implements TrackerAdapter {
+  private userId?: number;
+  private readonly columnsByBoard = new Map<number, BoardColumn[]>();
+  private readonly defaultsByProject = new Map<number, ProjectDefaults>();
+
+  constructor(private readonly clients: TrackerClients) {}
+
+  async listReadyTasks(initiativeId: number): Promise<ReadyTasks> {
+    let res;
+    try {
+      res = await this.clients.initiatives.getReadyTasks({ initiativeId });
+    } catch (error) {
+      // The likeliest way to get here is `foreman run <taskId>`: say so instead of echoing the RPC.
+      if (error instanceof ConnectError && error.code === Code.NotFound) {
+        throw new TrackerError(`Initiative ${initiativeId} not found. foreman run takes an Initiative id, not a Task id.`);
+      }
+      throw error;
+    }
+    // GetReadyTasks does not preload labels; a Ready Task's labels are what routes it (vendor and
+    // Account pins live there), so fetch them rather than report none.
+    const tasks = await Promise.all(res.tasks.map(async (t) => toTask(t, await this.labelsOf(t.id))));
+    return { tasks, dispatchLabel: res.dispatchLabel, dispatchLabelExists: res.dispatchLabelExists };
+  }
+
+  async getTask(taskId: number): Promise<TaskWithContext> {
+    const task = await this.rawTask(taskId);
+    const page = overridePagination();
+    const [labels, comments, dependencies, parent] = await Promise.all([
+      this.labelsOf(taskId),
+      this.clients.comments.getComments({ taskId, pagination: page }),
+      this.clients.taskDependencies.getTaskDependencies({ taskId, pagination: page }),
+      task.parentTaskId ? this.rawTask(task.parentTaskId) : undefined,
+    ]);
+    return {
+      task: toTask(task, labels),
+      comments: comments.comments.map(toComment),
+      dependencies: dependencies.taskDependencies
+        .map(toDependency)
+        .filter((d): d is TrackerDependency => !!d),
+      parent: parent ? toTask(parent) : undefined,
+    };
+  }
+
+  async addComment(taskId: number, body: string): Promise<TrackerComment> {
+    const res = await this.clients.comments.addComment({
+      content: body,
+      isInternal: false,
+      taskId,
+      userId: await this.me(),
+    });
+    if (!res.comment) throw new TrackerError(`Comment on task ${taskId} came back empty`);
+    return toComment(res.comment);
+  }
+
+  /** The Initiative's discussion thread. The same RPC a Task comment uses — it already takes an
+   * `initiative_id` instead of a `task_id` — so this needed nothing of the backend. */
+  async addInitiativeComment(initiativeId: number, body: string): Promise<TrackerComment> {
+    const res = await this.clients.comments.addComment({
+      content: body,
+      isInternal: false,
+      initiativeId,
+      userId: await this.me(),
+    });
+    if (!res.comment) throw new TrackerError(`Comment on Initiative ${initiativeId} came back empty`);
+    return toComment(res.comment);
+  }
+
+  async moveTask(taskId: number, lifecycle: Lifecycle): Promise<TrackerColumn> {
+    const task = await this.rawTask(taskId);
+    const column = await this.columnFor(task.board?.id ?? task.boardId, lifecycle);
+    if (column.id !== (task.boardColumn?.id ?? task.boardColumnId)) {
+      await this.editTask(task, { boardColumnId: column.id });
+    }
+    return toColumn(column);
+  }
+
+  async attachLabel(taskId: number, label: string): Promise<void> {
+    const task = await this.rawTask(taskId);
+    const existing = await this.taskLabelRow(taskId, label);
+    if (existing) return;
+    const found = await this.labelByName(task.project?.id ?? task.projectId, label);
+    await this.clients.taskLabels.addTaskLabel({ taskId, labelId: found.id });
+  }
+
+  async detachLabel(taskId: number, label: string): Promise<void> {
+    const existing = await this.taskLabelRow(taskId, label);
+    if (!existing) return;
+    await this.clients.taskLabels.deleteTaskLabel({ id: existing.id });
+  }
+
+  async ensureLabel(projectId: number, label: string): Promise<void> {
+    const res = await this.clients.labels.getLabels({ projectId, pagination: overridePagination() });
+    if (res.labels.some((l) => l.isActive && sameName(l.name, label))) return;
+    await this.clients.labels.addLabel({ name: label, projectId, color: STATUS_LABEL_COLOR, isActive: true });
+  }
+
+  async createTask(input: NewTask): Promise<TrackerTask> {
+    const res = await this.clients.initiatives.getInitiative({ id: input.initiativeId });
+    if (!res.initiative) throw new TrackerError(`Initiative ${input.initiativeId} not found`);
+    const projectId = res.initiative.projectId;
+    const defaults = await this.projectDefaults(projectId);
+    const labels = await Promise.all(
+      (input.labels ?? []).map((name) => this.labelByName(projectId, name)),
+    );
+
+    const created = await this.clients.tasks.addTask({
+      title: input.title,
+      description: input.description,
+      displayOrder: "",
+      aiModeEnabled: false,
+      boardId: defaults.boardId,
+      boardColumnId: defaults.newTaskColumnId,
+      projectId,
+      taskTypeId: pickNamed(defaults.types, input.type, "task type", "unknown_task_type").id,
+      taskPriorityId: pickNamed(defaults.priorities, input.priority, "priority", "unknown_priority").id,
+      reporterUserId: await this.me(),
+      parentTaskId: input.parentTaskId,
+      labelIds: labels.map((l) => l.id),
+    });
+    const task = created.task;
+    if (!task) throw new TrackerError(`Creating "${input.title}" returned no task`);
+
+    // AddTask cannot place a Task in an Initiative (only EditTask carries initiative_id), and edges
+    // need the new id, so this is three RPCs. If a later one fails the Task is deleted again, so the
+    // caller never sees a half-wired Task; if even that fails, the error names what was left.
+    try {
+      await this.editTask(task, { initiativeId: input.initiativeId });
+      for (const other of input.relatesTo ?? []) {
+        await this.clients.taskDependencies.addTaskDependency({
+          fromTaskId: task.id,
+          toTaskId: other,
+          type: TaskDependencyType.RELATES_TO,
+        });
+      }
+      for (const blocker of input.blockedBy ?? []) {
+        await this.clients.taskDependencies.addTaskDependency({
+          fromTaskId: blocker,
+          toTaskId: task.id,
+          type: TaskDependencyType.BLOCKS,
+        });
+      }
+    } catch (error) {
+      const why = `placing task "${input.title}" in initiative ${input.initiativeId} or wiring its edges failed: ${errorMessage(error)}`;
+      try {
+        await this.clients.tasks.deleteTask({ id: task.id });
+      } catch (undoError) {
+        throw new TrackerError(
+          `${why}; removing the half-wired task ${task.identifier} (${task.id}) failed too: ${errorMessage(undoError)}`,
+        );
+      }
+      throw new TrackerError(`${why} (the task was removed again)`);
+    }
+    return { ...toTask(task, labels.map((l) => l.name)), initiativeId: input.initiativeId };
+  }
+
+  async projectRepositories(projectId: number): Promise<ProjectRepository[]> {
+    const res = await this.clients.vcsIntegrations.getVCSIntegrations({
+      projectId,
+      pagination: overridePagination(),
+    });
+    return res.projectRepositories.map((r) => ({
+      id: r.id,
+      fullName: r.repositoryFullName,
+      url: r.url,
+    }));
+  }
+
+  async linkPullRequest(taskId: number, pr: PullRequestLink): Promise<void> {
+    await this.clients.tasks.linkTaskPullRequest({
+      taskId,
+      projectRepositoryId: pr.projectRepositoryId,
+      prNumber: pr.number,
+      url: pr.url,
+      title: pr.title,
+      headBranch: pr.headBranch,
+      headSha: pr.headSha,
+    });
+  }
+
+  async addMemory(initiativeId: number, entry: MemoryEntry): Promise<{ id: number }> {
+    const res = await this.clients.initiatives.addInitiativeMemoryEntry({
+      initiativeId,
+      kind: entry.kind,
+      body: entry.body,
+      contentType: "text",
+      sourceType: entry.sourceTaskId ? "task" : entry.sourceUrl ? "pull_request" : "none",
+      sourceId: entry.sourceTaskId,
+      sourceUrl: entry.sourceUrl,
+    });
+    if (!res.memoryEntry) throw new TrackerError(`Memory entry on initiative ${initiativeId} came back empty`);
+    return { id: res.memoryEntry.id };
+  }
+
+  /** Walks GetInitiativeMemory page by page: like GetRunEvents it windows to 50 entries and does
+   * not honour override_pagination, so one call would silently drop a long Run's memory. The
+   * filters are sent to the server and applied again on the way out, so what Context Assembly sees
+   * does not depend on which filters the server implements. Newest first. */
+  async listMemory(initiativeId: number, query: MemoryQuery = {}): Promise<MemoryRecord[]> {
+    const entries: InitiativeMemoryEntry[] = [];
+    for (let page = 1; ; page++) {
+      const res = await this.clients.initiatives.getInitiativeMemory({
+        initiativeId,
+        pagination: defaultPagination(page, MEMORY_PAGE),
+        kinds: query.kinds ?? [],
+        sourceType: query.sourceTaskId === undefined ? "" : "task",
+        sourceId: query.sourceTaskId,
+      });
+      entries.push(...res.memoryEntries);
+      if (res.memoryEntries.length < MEMORY_PAGE) break;
+    }
+    return entries
+      .filter(
+        (e) =>
+          (!query.kinds || (query.kinds as string[]).includes(e.kind)) &&
+          (query.sourceTaskId === undefined || (e.sourceType === "task" && e.sourceId === query.sourceTaskId)),
+      )
+      .map(toMemoryRecord)
+      .sort((a, b) => b.id - a.id);
+  }
+
+  /** GetInitiativeContext, the RPC behind the MCP's `opsee_get_initiative_context`, for the
+   * Initiative, its graph and its pull requests; the memory log is walked through `listMemory`
+   * instead of taken from the response, whose `memory_limit` windows it, so a planning session
+   * sees the whole log the way Context Assembly does. */
+  async getInitiativeContext(initiativeId: number): Promise<InitiativeContext> {
+    let res;
+    try {
+      res = await this.clients.initiatives.getInitiativeContext({ initiativeId, memoryLimit: 1 });
+    } catch (error) {
+      if (error instanceof ConnectError && error.code === Code.NotFound) throw new TrackerError(`Initiative ${initiativeId} not found`);
+      throw error;
+    }
+    const ini = res.initiative;
+    if (!ini) throw new TrackerError(`Initiative ${initiativeId} not found`);
+    const memory = await this.listMemory(initiativeId);
+    return {
+      initiative: {
+        id: ini.id,
+        title: ini.title,
+        summary: ini.summary || undefined,
+        status: ini.status,
+        coreIdea: markdownOf(ini.coreIdea),
+        projectId: ini.projectId,
+      },
+      tasks: (res.graph?.tasks ?? []).map((t) => toTask(t)),
+      edges: (res.graph?.edges ?? []).map(toEdge).filter((e): e is TrackerEdge => !!e),
+      slices: (res.graph?.slices ?? []).map((s) => ({ layer: s.layer, taskIds: [...s.taskIds] })),
+      memory,
+      pullRequests: res.pullRequests.map(toPullRequest),
+    };
+  }
+
+  async appendRunEvents(initiativeId: number, events: RunEventInput[]): Promise<RunEvent[]> {
+    const res = await this.clients.initiatives.appendRunEvents({ initiativeId, events });
+    return res.events;
+  }
+
+  /** Walks the Run Record with the server's `afterId` cursor: GetRunEvents windows to 50 events by
+   * default and does not honour override_pagination, so one call would silently truncate a Run. */
+  async readRunRecord(initiativeId: number, query: RunRecordQuery = {}): Promise<RunRecord> {
+    const events: RunEvent[] = [];
+    let run: Run | undefined;
+    let afterId = query.afterId;
+    for (;;) {
+      const res = await this.clients.initiatives.getRunEvents({
+        initiativeId,
+        pagination: defaultPagination(1, RUN_RECORD_PAGE),
+        kinds: query.kinds ?? [],
+        taskId: query.taskId,
+        afterId,
+      });
+      run ??= res.run;
+      events.push(...res.events);
+      if (res.events.length < RUN_RECORD_PAGE) return { run, events };
+      afterId = res.events[res.events.length - 1].id;
+    }
+  }
+
+  // ---- internals ----
+
+  private async me(): Promise<number> {
+    if (this.userId !== undefined) return this.userId;
+    const res = await this.clients.users.getMe({});
+    if (!res.user) throw new TrackerError("Backend returned no user for this token");
+    this.userId = res.user.id;
+    return res.user.id;
+  }
+
+  private async rawTask(id: number): Promise<Task> {
+    const res = await this.clients.tasks.getTask({ id });
+    if (!res.task) throw new TrackerError(`Task ${id} not found`);
+    return res.task;
+  }
+
+  /** EditTask validates the whole Task, so every edit resends what the backend already has. Only
+   * the fields in `patch` change; labels and repository links are left untouched by omission. */
+  private async editTask(task: Task, patch: { boardColumnId?: number; initiativeId?: number }): Promise<void> {
+    await this.clients.tasks.editTask({
+      initiativeId: patch.initiativeId,
+      id: task.id,
+      identifier: task.identifier,
+      title: task.title,
+      description: task.description,
+      displayOrder: task.displayOrder,
+      storyPoints: task.storyPoints,
+      estimatedHours: task.estimatedHours,
+      actualHours: task.actualHours,
+      dueDate: task.dueDate,
+      aiModeEnabled: task.aiModeEnabled,
+      metadataJson: task.metadataJson,
+      boardId: task.board?.id ?? task.boardId,
+      boardColumnId: patch.boardColumnId ?? task.boardColumn?.id ?? task.boardColumnId,
+      projectId: task.project?.id ?? task.projectId,
+      taskTypeId: task.taskType?.id ?? task.taskTypeId,
+      taskPriorityId: task.taskPriority?.id ?? task.taskPriorityId,
+      reporterUserId: task.reporterUser?.id ?? task.reporterUserId,
+      assignedUserId: task.assignedUser?.id ?? task.assignedUserId,
+      cycleId: task.cycle?.id ?? task.cycleId,
+      milestoneId: task.milestoneId,
+      parentTaskId: task.parentTaskId,
+    });
+  }
+
+  private async columns(boardId: number, refresh = false): Promise<BoardColumn[]> {
+    let columns = refresh ? undefined : this.columnsByBoard.get(boardId);
+    if (!columns) {
+      const res = await this.clients.boardColumns.getBoardColumns({
+        boardId,
+        pagination: overridePagination(),
+      });
+      columns = res.boardColumns.filter((c) => c.isActive).sort(byDisplayOrder);
+      this.columnsByBoard.set(boardId, columns);
+    }
+    return columns;
+  }
+
+  /** The first active column (by display order) for `lifecycle` (tracker-adapter.ts `pickColumn`:
+   * by state, or for `in_review` by name or the lone `active` column); refetches once on a miss so
+   * a column added since the cache was filled is still found. */
+  private async columnFor(boardId: number, lifecycle: Lifecycle): Promise<BoardColumn> {
+    const pick = (columns: BoardColumn[]) => {
+      const hit = pickColumn(columns.map(toColumn), lifecycle);
+      return hit ? columns.find((c) => c.id === hit.id) : undefined;
+    };
+    let column = pick(await this.columns(boardId));
+    if (!column) column = pick(await this.columns(boardId, true));
+    if (!column) {
+      const states = (await this.columns(boardId))
+        .map((c) => `${c.name}=${c.lifecycleState ?? "(none)"}`)
+        .join(", ");
+      throw new TrackerError(`Board ${boardId} has no column with lifecycle "${lifecycle}" (columns: ${states})`);
+    }
+    return column;
+  }
+
+  private async labelByName(projectId: number, name: string): Promise<Label> {
+    const res = await this.clients.labels.getLabels({ projectId, pagination: overridePagination() });
+    const label = res.labels.find((l) => l.isActive && sameName(l.name, name));
+    if (!label) throw new TrackerError(`Project ${projectId} has no active label "${name}"`);
+    return label;
+  }
+
+  private async taskLabelRows(taskId: number) {
+    const res = await this.clients.taskLabels.getTaskLabels({ taskId, pagination: overridePagination() });
+    return res.taskLabels;
+  }
+
+  private async labelsOf(taskId: number): Promise<string[]> {
+    return labelNames(await this.taskLabelRows(taskId));
+  }
+
+  private async taskLabelRow(taskId: number, name: string) {
+    return (await this.taskLabelRows(taskId)).find((row) => row.label && sameName(row.label.name, name));
+  }
+
+  private async projectDefaults(projectId: number): Promise<ProjectDefaults> {
+    let defaults = this.defaultsByProject.get(projectId);
+    if (defaults) return defaults;
+    const page = overridePagination();
+    const [boards, types, priorities] = await Promise.all([
+      this.clients.boards.getBoards({ projectId, pagination: page }),
+      this.clients.taskTypes.getTaskTypes({ projectId, pagination: page }),
+      this.clients.taskPriorities.getTaskPriorities({ projectId, pagination: page }),
+    ]);
+    const board = boards.boards.find((b) => b.isActive) ?? boards.boards[0];
+    if (!board) throw new TrackerError(`Project ${projectId} has no board`);
+    const columns = await this.columns(board.id);
+    const landing = columns.find((c) => c.lifecycleState === "todo") ?? columns[0];
+    if (!landing) throw new TrackerError(`Board ${board.id} has no columns`);
+    if (types.taskTypes.length === 0) throw new TrackerError(`Project ${projectId} has no task types`);
+    if (priorities.taskPriorities.length === 0) throw new TrackerError(`Project ${projectId} has no priorities`);
+    defaults = {
+      boardId: board.id,
+      newTaskColumnId: landing.id,
+      types: types.taskTypes.map((t) => ({ id: t.id, name: t.name })),
+      priorities: priorities.taskPriorities.map((p) => ({ id: p.id, name: p.name })),
+    };
+    this.defaultsByProject.set(projectId, defaults);
+    return defaults;
+  }
+}
+
+function pickNamed<T extends { name: string }>(options: T[], name: string | undefined, what: string, code?: TrackerErrorCode): T {
+  if (!name) return options[0];
+  const found = options.find((o) => sameName(o.name, name));
+  if (!found) {
+    throw new TrackerError(`No ${what} named "${name}" (have: ${options.map((o) => o.name).join(", ")})`, code);
+  }
+  return found;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}