@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/integrations/bb-plugin-build/src/task-navigation.ts

@@ -0,0 +1,446 @@
+/**
+ * Pure presentation and navigation helpers for the read-only task surfaces of
+ * the existing Planning Workspace.
+ *
+ * Every value here comes from data the caller already read from Build. Nothing
+ * in this module reads Build internals, managed planning files, Git, the
+ * filesystem, or the network, and nothing mutates planning state: Build remains
+ * the planning authority.
+ *
+ * Dependency classification, blocker reasons, and next-candidate order are
+ * rendered exactly as Build published them. This module never recomputes
+ * dependency satisfaction, re-ranks candidates, or invents a status. Empty,
+ * missing, unavailable, archived, and diverged states stay separate and are
+ * never collapsed into one another.
+ *
+ * The navigation targets below address only Build's existing single-task detail
+ * read and the existing backlog-detail read. No second workspace, poller, task
+ * mirror, or competition/judge action is introduced here.
+ */
+
+import type { CanonicalTaskStatus } from './planning-service.js';
+import { PRESENTED_TASK_STATUS } from './planning-service.js';
+import type {
+  PlanningBlockerRecord,
+  PlanningDependencyRecord,
+  PlanningNextCandidateView,
+  PlanningQueueView,
+  PlanningTaskStatus,
+  PlanningTaskView,
+} from './planning-workspace.js';
+import { PLANNING_QUEUE_LABELS } from './planning-workspace.js';
+import type { TaskDetailFacts, TaskDetailResult } from './task-detail-schema.js';
+
+/**
+ * Where a read-only navigation action goes. Only surfaces that already exist are
+ * addressable: one canonical task detail read, or the existing backlog detail.
+ */
+export type PlanningNavigationTarget =
+  | { kind: 'task'; taskId: string }
+  | { kind: 'backlog'; backlogItemId: string };
+
+export type PlanningTaskNavigationTarget = Extract<PlanningNavigationTarget, { kind: 'task' }>;
+
+export type PlanningBacklogNavigationTarget = Extract<
+  PlanningNavigationTarget,
+  { kind: 'backlog' }
+>;
+
+function taskTarget(taskId: string): PlanningTaskNavigationTarget {
+  return { kind: 'task', taskId };
+}
+
+function backlogTarget(backlogItemId: string): PlanningBacklogNavigationTarget {
+  return { kind: 'backlog', backlogItemId };
+}
+
+/** One selectable task row inside a queue. */
+export interface PlanningTaskRowView {
+  /** The queue task exactly as the workspace view reported it. */
+  task: PlanningTaskView;
+  /** Queue this row belongs to; every queue yields selectable rows. */
+  queue: PlanningTaskStatus;
+  selected: boolean;
+  /** Selecting a row reads fresh canonical detail for this task id. */
+  target: PlanningTaskNavigationTarget;
+  /** Existing backlog-detail target; null when Build published no link. */
+  linkedBacklog: PlanningBacklogNavigationTarget | null;
+}
+
+export interface PlanningTaskQueueRowsView {
+  status: PlanningTaskStatus;
+  label: string;
+  rows: readonly PlanningTaskRowView[];
+}
+
+/**
+ * Make every queue's tasks selectable, preserving the queue order and the task
+ * order the workspace view already produced.
+ */
+export function buildTaskQueueRows(
+  queues: readonly PlanningQueueView[],
+  selectedTaskId: string | null
+): readonly PlanningTaskQueueRowsView[] {
+  return queues.map((queue) => ({
+    status: queue.status,
+    label: queue.label,
+    rows: queue.tasks.map((task) => ({
+      task,
+      queue: queue.status,
+      selected: selectedTaskId !== null && task.id === selectedTaskId,
+      target: taskTarget(task.id),
+      linkedBacklog:
+        task.linkedBacklogItemId === null ? null : backlogTarget(task.linkedBacklogItemId),
+    })),
+  }));
+}
+
+/**
+ * Find one selectable row by task id. Returns null when the id is not in this
+ * projection, which stays distinct from a task that is present but unselected.
+ */
+export function findTaskRow(
+  queues: readonly PlanningTaskQueueRowsView[],
+  taskId: string
+): PlanningTaskRowView | null {
+  for (const queue of queues) {
+    const row = queue.rows.find((entry) => entry.task.id === taskId);
+    if (row) return row;
+  }
+  return null;
+}
+
+export interface PlanningNextCandidateNavigationView {
+  /** Build's candidate, including its reasoning, passed through verbatim. */
+  candidate: PlanningNextCandidateView;
+  /** Build's published position (1-based), kept so the order stays auditable. */
+  order: number;
+  /** Null when Build's kind has no read-only detail surface in this panel. */
+  target: PlanningNavigationTarget | null;
+  /** Why no navigation is offered; null when a target exists. */
+  unnavigableReason: string | null;
+}
+
+/**
+ * Attach a navigation target to each next candidate in Build's order. Tasks go
+ * to canonical task detail and backlog items to the existing backlog detail;
+ * any other kind Build reports is disclosed rather than guessed at. This helper
+ * never sorts or re-ranks the list.
+ */
+export function buildNextCandidateNavigation(
+  candidates: readonly PlanningNextCandidateView[]
+): readonly PlanningNextCandidateNavigationView[] {
+  return candidates.map((candidate, index) => {
+    const order = index + 1;
+    if (candidate.kind === 'task') {
+      return { candidate, order, target: taskTarget(candidate.id), unnavigableReason: null };
+    }
+    if (candidate.kind === 'backlog') {
+      return { candidate, order, target: backlogTarget(candidate.id), unnavigableReason: null };
+    }
+    return {
+      candidate,
+      order,
+      target: null,
+      unnavigableReason: `Build reports this candidate as kind "${candidate.kind}", which has no read-only detail surface in this panel.`,
+    };
+  });
+}
+
+const TASK_STATUS_LABELS: Readonly<Record<CanonicalTaskStatus, string>> = {
+  todo: 'To do',
+  in_progress: 'In progress',
+  review: 'Review',
+  done: 'Done',
+  blocked: 'Blocked',
+  cancelled: 'Cancelled',
+};
+
+const TASK_LOCATION_LABELS: Readonly<Record<'active' | 'archive', string>> = {
+  active: 'Active',
+  archive: 'Archived',
+};
+
+/**
+ * Build's dependency classification in words. `recorded-complete` keeps its own
+ * label so it is never read as a loaded task file or as a missing dependency.
+ */
+const DEPENDENCY_STATE_LABELS: Readonly<Record<PlanningDependencyRecord['state'], string>> = {
+  available: 'Dependency task is present in managed planning',
+  'recorded-complete': 'Recorded complete on the sprint; the task file is not present',
+  missing: 'Dependency task is not present in managed planning',
+};
+
+const BLOCKER_KIND_LABELS: Readonly<Record<PlanningBlockerRecord['kind'], string>> = {
+  'task-status': "This task's own recorded status",
+  dependency: 'Dependency',
+};
+
+export const UNREPORTED_TASK_STATUS_LABEL = 'Status not reported';
+export const UNREPORTED_TASK_LOCATION_LABEL = 'Location not reported';
+export const UNREPORTED_DEPENDENCY_STATUS_LABEL = 'Dependency status not reported';
+export const UNREPORTED_BLOCKER_REASON_LABEL = 'Build recorded no reason for this blocker';
+export const UNREPORTED_TASK_TITLE_LABEL = 'Title not reported';
+export const NO_DEPENDENCIES_LABEL = 'Build reports no dependencies for this task.';
+export const NO_BLOCKERS_LABEL = 'Build reports no blockers for this task.';
+export const NO_LINKED_BACKLOG_LABEL = 'Build reports no linked backlog item.';
+export const ARCHIVED_TASK_NOTICE =
+  'Build reports this task in the archive bucket, not in active planning.';
+
+function taskStatusLabel(status: CanonicalTaskStatus | null): string {
+  return status === null ? UNREPORTED_TASK_STATUS_LABEL : TASK_STATUS_LABELS[status];
+}
+
+export interface TaskDetailTimestampView {
+  label: string;
+  /** Build's timestamp verbatim; null when Build reported none. */
+  value: string | null;
+}
+
+export interface TaskDetailDependencyRowView {
+  id: string;
+  state: PlanningDependencyRecord['state'];
+  status: CanonicalTaskStatus | null;
+  satisfied: boolean;
+  stateLabel: string;
+  statusLabel: string;
+  satisfactionLabel: string;
+  /**
+   * A missing dependency stays navigable: the canonical read reports missing
+   * explicitly, which is more honest than hiding the id.
+   */
+  target: PlanningTaskNavigationTarget;
+}
+
+export interface TaskDetailBlockerRowView {
+  kind: PlanningBlockerRecord['kind'];
+  id: string;
+  kindLabel: string;
+  /** Build's reason, or an explicit label when Build recorded none. */
+  reason: string;
+  /**
+   * Null for a `task-status` blocker: it is this task's own status, so there is
+   * nowhere else to navigate.
+   */
+  target: PlanningTaskNavigationTarget | null;
+}
+
+export interface TaskDetailAvailableView {
+  state: 'available';
+  id: string;
+  title: string;
+  status: CanonicalTaskStatus | null;
+  statusLabel: string;
+  locationLabel: string;
+  /** True only when Build reported the archive bucket. */
+  archived: boolean;
+  archivedNotice: string | null;
+  assigneeLabel: string;
+  priorityLabel: string;
+  estimateLine: string;
+  /** All lifecycle timestamps, so an absent one is visible rather than omitted. */
+  timestamps: readonly TaskDetailTimestampView[];
+  dependencies: readonly TaskDetailDependencyRowView[];
+  dependenciesEmptyLabel: string;
+  blockers: readonly TaskDetailBlockerRowView[];
+  blockersEmptyLabel: string;
+  linkedBacklog: PlanningBacklogNavigationTarget | null;
+  linkedBacklogEmptyLabel: string;
+  /** Build's projection version, or null when it reported none. */
+  schemaVersion: string | null;
+}
+
+export interface TaskDetailAbsentView {
+  state: 'missing' | 'unavailable';
+  taskId: string;
+  headline: string;
+  detail: string;
+  schemaVersion: string | null;
+}
+
+export type TaskDetailView = TaskDetailAvailableView | TaskDetailAbsentView;
+
+/** One canonical task-detail reply as the panel received it. */
+export interface TaskDetailInput {
+  /** The task id BB asked for, used for missing and unavailable headlines. */
+  taskId: string;
+  schemaVersion: string | null;
+  task: TaskDetailResult;
+}
+
+function estimateLine(estimates: TaskDetailFacts['estimates']): string {
+  const hours = estimates.hours === null ? 'unavailable' : String(estimates.hours);
+  const runtime =
+    estimates.runtimeMinutes === null ? 'unavailable' : String(estimates.runtimeMinutes);
+  return `estimate ${hours}h / ${runtime}m runtime`;
+}
+
+function timestampViews(facts: TaskDetailFacts): TaskDetailTimestampView[] {
+  return [
+    { label: 'Created', value: facts.created },
+    { label: 'Updated', value: facts.updated },
+    { label: 'Started', value: facts.started },
+    { label: 'Completed', value: facts.completed },
+    { label: 'Archived', value: facts.archived },
+    { label: 'Cancelled', value: facts.cancelled },
+  ];
+}
+
+function dependencyRows(facts: TaskDetailFacts): TaskDetailDependencyRowView[] {
+  // Build's order and classification pass through; satisfaction is never re-decided.
+  return facts.dependencies.map((dependency) => ({
+    id: dependency.id,
+    state: dependency.state,
+    status: dependency.status,
+    satisfied: dependency.satisfied,
+    stateLabel: DEPENDENCY_STATE_LABELS[dependency.state],
+    statusLabel:
+      dependency.status === null
+        ? UNREPORTED_DEPENDENCY_STATUS_LABEL
+        : TASK_STATUS_LABELS[dependency.status],
+    satisfactionLabel: dependency.satisfied ? 'Satisfied' : 'Unsatisfied',
+    target: taskTarget(dependency.id),
+  }));
+}
+
+function blockerRows(facts: TaskDetailFacts): TaskDetailBlockerRowView[] {
+  return facts.blockers.map((blocker) => ({
+    kind: blocker.kind,
+    id: blocker.id,
+    kindLabel: BLOCKER_KIND_LABELS[blocker.kind],
+    reason: blocker.reason ?? UNREPORTED_BLOCKER_REASON_LABEL,
+    target: blocker.kind === 'dependency' ? taskTarget(blocker.id) : null,
+  }));
+}
+
+/**
+ * Project one canonical task-detail reply into the panel's rendered shape.
+ *
+ * Missing and unavailable keep separate states and are never rendered as a
+ * healthy task. Archived is disclosed on an otherwise available task rather than
+ * being treated as absence.
+ */
+export function buildTaskDetailView(input: TaskDetailInput): TaskDetailView {
+  if (input.task.state === 'missing') {
+    return {
+      state: 'missing',
+      taskId: input.taskId,
+      headline: 'Task not found',
+      detail: `Build reports no managed task with id ${input.taskId}.`,
+      schemaVersion: input.schemaVersion,
+    };
+  }
+  if (input.task.state === 'unavailable') {
+    return {
+      state: 'unavailable',
+      taskId: input.taskId,
+      headline: 'Task detail unavailable',
+      detail: input.task.reason,
+      schemaVersion: input.schemaVersion,
+    };
+  }
+
+  const facts = input.task.value;
+  const archived = facts.location === 'archive';
+  return {
+    state: 'available',
+    id: facts.id,
+    title: facts.title ?? UNREPORTED_TASK_TITLE_LABEL,
+    status: facts.status,
+    statusLabel: taskStatusLabel(facts.status),
+    locationLabel:
+      facts.location === null
+        ? UNREPORTED_TASK_LOCATION_LABEL
+        : TASK_LOCATION_LABELS[facts.location],
+    archived,
+    archivedNotice: archived ? ARCHIVED_TASK_NOTICE : null,
+    assigneeLabel: facts.assignee ?? 'Unassigned',
+    priorityLabel: facts.priority ?? 'No priority reported',
+    estimateLine: estimateLine(facts.estimates),
+    timestamps: timestampViews(facts),
+    dependencies: dependencyRows(facts),
+    dependenciesEmptyLabel: NO_DEPENDENCIES_LABEL,
+    blockers: blockerRows(facts),
+    blockersEmptyLabel: NO_BLOCKERS_LABEL,
+    linkedBacklog:
+      facts.linkedBacklogItemId === null ? null : backlogTarget(facts.linkedBacklogItemId),
+    linkedBacklogEmptyLabel: NO_LINKED_BACKLOG_LABEL,
+    schemaVersion: input.schemaVersion,
+  };
+}
+
+/**
+ * Whether the selected queue row still agrees with the freshly read canonical
+ * detail. `unknown` means the two cannot be compared at all, which stays
+ * distinct from an observed divergence.
+ */
+export interface TaskDetailFreshnessView {
+  state: 'consistent' | 'diverged' | 'unknown';
+  label: string;
+}
+
+/**
+ * Compare the selected queue row with canonical detail on the one field both
+ * publish: task status. This is an equality check over two values Build already
+ * reported, not a recomputed planning decision, and the canonical detail always
+ * remains authoritative.
+ */
+export function buildTaskDetailFreshnessView(
+  row: PlanningTaskRowView | null,
+  detail: TaskDetailView
+): TaskDetailFreshnessView {
+  if (detail.state !== 'available') {
+    return {
+      state: 'unknown',
+      label: 'Canonical task detail is not available, so the queue row cannot be compared with it.',
+    };
+  }
+  if (!row) {
+    return {
+      state: 'unknown',
+      label:
+        'This task is not in the current workspace projection; the canonical detail above is authoritative.',
+    };
+  }
+  if (detail.status === null) {
+    return {
+      state: 'unknown',
+      label:
+        'Build reported no status on the canonical detail, so the queue row cannot be compared with it.',
+    };
+  }
+  const canonicalQueue = PRESENTED_TASK_STATUS[detail.status];
+  if (canonicalQueue === row.task.status) {
+    return { state: 'consistent', label: 'The queue row matches the canonical task detail.' };
+  }
+  return {
+    state: 'diverged',
+    label: `The queue row shows ${PLANNING_QUEUE_LABELS[row.task.status]} and the canonical detail reports ${PLANNING_QUEUE_LABELS[canonicalQueue]}; the workspace projection is stale.`,
+  };
+}
+
+/**
+ * Identity of one task-detail read. `requestId` is monotonic per panel so two
+ * selections of the same task id stay distinguishable when their replies arrive
+ * out of order. Repository generation remains a separate guard.
+ */
+export interface TaskDetailRequestIdentity {
+  taskId: string;
+  requestId: number;
+}
+
+/** Allocate the next monotonic task-detail request id. */
+export function nextTaskDetailRequestId(previousRequestId: number): number {
+  return previousRequestId + 1;
+}
+
+/**
+ * Whether a task-detail reply still belongs to the newest request. Compared by
+ * request id so a same-id reselection discards an older in-flight reply.
+ */
+export function isCurrentTaskDetailRequest(
+  latest: TaskDetailRequestIdentity | null,
+  reply: TaskDetailRequestIdentity
+): boolean {
+  return latest !== null && latest.requestId === reply.requestId;
+}

package/integrations/bb-plugin-build/src/workbench-route.ts

@@ -0,0 +1,74 @@
+export type BuildWorkbenchRoute =
+  | { kind: 'overview' }
+  | { kind: 'plan' }
+  | { kind: 'task'; taskId: string }
+  | { kind: 'backlog' }
+  | { kind: 'backlog-detail'; backlogItemId: string }
+  | { kind: 'runs' }
+  | { kind: 'run'; runKey: string }
+  | { kind: 'settings' };
+
+function decodeIdentity(value: string): string | null {
+  try {
+    const decoded = decodeURIComponent(value).trim();
+    return decoded.length > 0 ? decoded : null;
+  } catch {
+    return null;
+  }
+}
+
+function backlogDetail(identity: string | undefined): BuildWorkbenchRoute | null {
+  if (!identity) return null;
+  const backlogItemId = decodeIdentity(identity);
+  return backlogItemId ? { kind: 'backlog-detail', backlogItemId } : null;
+}
+
+function runDetail(identity: string | undefined): BuildWorkbenchRoute | null {
+  if (!identity) return null;
+  const runKey = decodeIdentity(identity);
+  return runKey ? { kind: 'run', runKey } : null;
+}
+
+/** Parse BB's plugin-owned route remainder without adding another router. */
+export function parseBuildWorkbenchRoute(subPath: string): BuildWorkbenchRoute {
+  const parts = subPath.split('/').filter(Boolean);
+  if (parts.length === 0 || parts[0] === 'overview') return { kind: 'overview' };
+  if (parts[0] === 'plan' && parts.length === 1) return { kind: 'plan' };
+  if (parts[0] === 'plan' && parts[1] === 'tasks' && parts.length === 3) {
+    const taskId = decodeIdentity(parts[2]);
+    if (taskId) return { kind: 'task', taskId };
+  }
+  if (parts[0] === 'plan' && parts[1] === 'backlog' && parts.length === 2) {
+    return { kind: 'backlog' };
+  }
+  if (parts[0] === 'plan' && parts[1] === 'backlog' && parts.length === 3) {
+    const detail = backlogDetail(parts[2]);
+    if (detail) return detail;
+  }
+  if (parts[0] === 'backlog' && parts.length === 1) return { kind: 'backlog' };
+  if (parts[0] === 'backlog' && parts.length === 2) {
+    const detail = backlogDetail(parts[1]);
+    if (detail) return detail;
+  }
+  if (parts[0] === 'run' && parts.length === 1) return { kind: 'runs' };
+  if (parts[0] === 'run' && parts.length === 2) {
+    const detail = runDetail(parts[1]);
+    if (detail) return detail;
+  }
+  if (parts[0] === 'runs' && parts.length === 1) return { kind: 'runs' };
+  if (parts[0] === 'runs' && parts.length === 2) {
+    const detail = runDetail(parts[1]);
+    if (detail) return detail;
+  }
+  if ((parts[0] === 'settings' || parts[0] === 'setup') && parts.length === 1) {
+    return { kind: 'settings' };
+  }
+  return { kind: 'overview' };
+}
+
+export function buildEntitySubPath(kind: 'task' | 'backlog' | 'run', identity: string): string {
+  const encoded = encodeURIComponent(identity);
+  if (kind === 'task') return `plan/tasks/${encoded}`;
+  if (kind === 'backlog') return `plan/backlog/${encoded}`;
+  return `run/${encoded}`;
+}