@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/integrations/bb-plugin-build/src/result-readback-service.ts

@@ -0,0 +1,333 @@
+/**
+ * Isolated, single-shot result readback service.
+ *
+ * BRCS-07 owns executable resolution, live RPC wiring, and polling. This module
+ * accepts only an injected runner and always sends one fixed argv with a false
+ * shell flag; callers cannot supply argv, env, cwd, paths, URLs, or executables.
+ */
+
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import type { z } from 'zod';
+import { repositorySchema } from './repository-schema.js';
+import { mapOperationalReadback, type ResultReadbackView } from './result-readback-model.js';
+import {
+  operationalReadbackSchema,
+  type ResultReadbackInput,
+  resultCommandEnvelopeSchema,
+  resultReadbackInputSchema,
+} from './result-readback-schema.js';
+
+const SUPPORTED_MAJOR = '1';
+export const RESULT_READBACK_TIMEOUT_MS = 10_000;
+
+type Repository = z.infer<typeof repositorySchema>;
+
+export interface ResultReadbackCommand {
+  file: 'build';
+  args: readonly string[];
+  cwd: string;
+  timeoutMs: typeof RESULT_READBACK_TIMEOUT_MS;
+  shell: false;
+}
+
+export interface ResultReadbackCommandResult {
+  stdout: string;
+  stderr: string;
+}
+
+export type ResultReadbackRunner = (
+  command: ResultReadbackCommand
+) => Promise<ResultReadbackCommandResult>;
+
+export type ResultReadbackUnavailableReason =
+  | 'invalid-request'
+  | 'cross-repository'
+  | 'cross-run'
+  | 'mismatched-kind'
+  | 'malformed-output'
+  | 'unsupported-major'
+  | 'timeout'
+  | 'command-failed'
+  | 'unavailable';
+
+export type ResultReadbackResult =
+  | {
+      state: 'available';
+      conditions: Array<'stale' | 'partial'>;
+      repository: Repository;
+      runId: string;
+      schemaVersion: string;
+      view: ResultReadbackView;
+    }
+  | {
+      state: 'unavailable';
+      reason: ResultReadbackUnavailableReason;
+      repository: Repository;
+      runId: string;
+      message: string;
+    };
+
+const COMMANDS: Readonly<Record<ResultReadbackInput['kind'], readonly string[]>> = {
+  competition: ['run', 'competition', 'results'],
+  fusion: ['run', 'fusion', 'results'],
+  'backlog-execute': ['plan', 'backlog', 'show'],
+};
+
+function unavailable(
+  repository: Repository,
+  runId: string,
+  reason: ResultReadbackUnavailableReason,
+  message: string
+): ResultReadbackResult {
+  return { state: 'unavailable', reason, repository, runId, message };
+}
+
+function timeoutError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const value = error as { code?: unknown; name?: unknown };
+  return value.code === 'ETIMEDOUT' || value.name === 'TimeoutError';
+}
+
+function commandArgs(input: ResultReadbackInput): readonly string[] {
+  return [...COMMANDS[input.kind], input.runId, '--json'];
+}
+
+function conditions(
+  healthIssues: readonly string[],
+  freshness: string
+): Array<'stale' | 'partial'> {
+  return [
+    ...(freshness === 'stale' || healthIssues.includes('stale') ? (['stale'] as const) : []),
+    ...(healthIssues.includes('partial') ? (['partial'] as const) : []),
+  ];
+}
+
+export function repositoryPathState(
+  repositoryPath: string,
+  candidatePath: string
+): 'inside' | 'malformed' | 'outside' {
+  if (candidatePath.length === 0 || candidatePath.includes('\0')) return 'malformed';
+
+  const repositoryRoot = resolve(repositoryPath);
+  const resolvedCandidate = resolve(repositoryRoot, candidatePath);
+  const relativeCandidate = relative(repositoryRoot, resolvedCandidate);
+  if (
+    relativeCandidate === '..' ||
+    relativeCandidate.startsWith(`..${sep}`) ||
+    isAbsolute(relativeCandidate)
+  ) {
+    return 'outside';
+  }
+  return 'inside';
+}
+
+export class ResultReadbackService {
+  constructor(private readonly run: ResultReadbackRunner) {}
+
+  async read(repositoryValue: unknown, inputValue: unknown): Promise<ResultReadbackResult> {
+    const repository = repositorySchema.parse(repositoryValue);
+    const input = resultReadbackInputSchema.safeParse(inputValue);
+    const fallbackRunId =
+      inputValue &&
+      typeof inputValue === 'object' &&
+      'runId' in inputValue &&
+      typeof inputValue.runId === 'string'
+        ? inputValue.runId
+        : '';
+    if (!input.success) {
+      return unavailable(
+        repository,
+        fallbackRunId,
+        'invalid-request',
+        'Invalid result readback request.'
+      );
+    }
+    if (
+      input.data.projectId !== repository.projectId ||
+      input.data.sourceId !== repository.sourceId
+    ) {
+      return unavailable(
+        repository,
+        input.data.runId,
+        'cross-repository',
+        'The request does not identify the selected repository.'
+      );
+    }
+
+    let commandResult: ResultReadbackCommandResult;
+    try {
+      commandResult = await this.run({
+        file: 'build',
+        args: commandArgs(input.data),
+        cwd: repository.path,
+        timeoutMs: RESULT_READBACK_TIMEOUT_MS,
+        shell: false,
+      });
+    } catch (error) {
+      return unavailable(
+        repository,
+        input.data.runId,
+        timeoutError(error) ? 'timeout' : 'command-failed',
+        timeoutError(error) ? 'Build result readback timed out.' : 'Build result readback failed.'
+      );
+    }
+
+    let json: unknown;
+    try {
+      json = JSON.parse(commandResult.stdout);
+    } catch {
+      return unavailable(
+        repository,
+        input.data.runId,
+        'malformed-output',
+        'Build returned invalid JSON.'
+      );
+    }
+    const envelope = resultCommandEnvelopeSchema.safeParse(json);
+    if (!envelope.success) {
+      return unavailable(
+        repository,
+        input.data.runId,
+        'malformed-output',
+        'Build returned no result readback envelope.'
+      );
+    }
+    if (envelope.data.operationalReadbackV1 === null) {
+      return unavailable(
+        repository,
+        input.data.runId,
+        'unavailable',
+        'Build has no canonical readback for this run.'
+      );
+    }
+
+    const raw = envelope.data.operationalReadbackV1;
+    const version =
+      raw &&
+      typeof raw === 'object' &&
+      'schemaVersion' in raw &&
+      typeof raw.schemaVersion === 'string'
+        ? raw.schemaVersion
+        : null;
+    if (version !== null && version.split('.')[0] !== SUPPORTED_MAJOR) {
+      return unavailable(
+        repository,
+        input.data.runId,
+        'unsupported-major',
+        'Build returned an unsupported readback major version.'
+      );
+    }
+    const parsed = operationalReadbackSchema.safeParse(raw);
+    if (!parsed.success) {
+      return unavailable(
+        repository,
+        input.data.runId,
+        'malformed-output',
+        'Build returned malformed result evidence.'
+      );
+    }
+    if (parsed.data.kind !== input.data.kind) {
+      return unavailable(
+        repository,
+        input.data.runId,
+        'mismatched-kind',
+        'Build returned a different result kind.'
+      );
+    }
+    if (parsed.data.id !== input.data.runId) {
+      return unavailable(
+        repository,
+        input.data.runId,
+        'cross-run',
+        'Build returned evidence for a different run.'
+      );
+    }
+    if (parsed.data.kind === 'backlog-execute') {
+      if (parsed.data.backlogExecute.backlogItem.id !== input.data.runId) {
+        return unavailable(
+          repository,
+          input.data.runId,
+          'cross-run',
+          'Build returned tracked evidence for a different run.'
+        );
+      }
+      const pathState = repositoryPathState(
+        repository.path,
+        parsed.data.provenance.sources.executionProvenance.path
+      );
+      if (pathState === 'malformed') {
+        return unavailable(
+          repository,
+          input.data.runId,
+          'malformed-output',
+          'Build returned malformed execution provenance.'
+        );
+      }
+      if (pathState === 'outside') {
+        return unavailable(
+          repository,
+          input.data.runId,
+          'cross-repository',
+          'Build returned execution provenance outside the selected repository.'
+        );
+      }
+    } else {
+      const snapshot =
+        parsed.data.kind === 'competition' ? parsed.data.competition : parsed.data.fusion;
+      if (snapshot.schemaVersion.split('.')[0] !== SUPPORTED_MAJOR) {
+        return unavailable(
+          repository,
+          input.data.runId,
+          'unsupported-major',
+          'Build returned an unsupported nested snapshot major version.'
+        );
+      }
+      if (snapshot.id !== parsed.data.id) {
+        return unavailable(
+          repository,
+          input.data.runId,
+          'cross-run',
+          'Build returned nested evidence for a different run.'
+        );
+      }
+      const sourceRepository = snapshot.source.repository;
+      const sourceState =
+        sourceRepository === undefined
+          ? 'outside'
+          : repositoryPathState(repository.path, sourceRepository);
+      if (sourceState === 'malformed') {
+        return unavailable(
+          repository,
+          input.data.runId,
+          'malformed-output',
+          'Build returned a malformed repository path.'
+        );
+      }
+      if (sourceState !== 'inside') {
+        return unavailable(
+          repository,
+          input.data.runId,
+          'cross-repository',
+          'Build returned evidence for a different repository.'
+        );
+      }
+    }
+    if (parsed.data.health.state === 'unavailable') {
+      return unavailable(
+        repository,
+        input.data.runId,
+        'unavailable',
+        'Build reports this result readback as unavailable.'
+      );
+    }
+
+    return {
+      state: 'available',
+      conditions: conditions(parsed.data.health.issues, parsed.data.freshness.state),
+      repository,
+      runId: input.data.runId,
+      schemaVersion: parsed.data.schemaVersion,
+      view: mapOperationalReadback(parsed.data, repository),
+    };
+  }
+}

package/integrations/bb-plugin-build/src/run-page-view.ts

@@ -0,0 +1,332 @@
+/**
+ * Pure presentation helpers for the Run page. Every value is derived from
+ * typed data the caller already holds. Nothing here reads Build internals,
+ * managed planning files, Git, the filesystem, or the network, and nothing
+ * mutates planning or run state.
+ */
+
+import type { BacklogItem, RunCard } from './model.js';
+import type { TaskCatalogRow } from './task-catalog-schema.js';
+
+export type BrowserFilterValue = 'all' | string;
+
+export interface TaskBrowserOptions {
+  query: string;
+  status: BrowserFilterValue;
+  priority: BrowserFilterValue;
+  sprintId: BrowserFilterValue;
+  location: BrowserFilterValue;
+  sort: 'build' | 'title' | 'priority' | 'status' | 'sprint';
+}
+
+export interface TaskBrowserRow extends TaskCatalogRow {
+  sprintName: string | null;
+}
+
+export interface SprintBrowserInput {
+  id: string;
+  name: string;
+  goal: string | null;
+  status: string;
+  location: 'active' | 'archive';
+  startDate: string;
+  endDate: string;
+  taskCount: number;
+}
+
+export interface SprintBrowserOptions {
+  query: string;
+  status: BrowserFilterValue;
+  location: BrowserFilterValue;
+  sort: 'build' | 'name' | 'status' | 'startDate';
+}
+
+const TASK_STATUS_ORDER = new Map(
+  ['todo', 'in_progress', 'review', 'blocked', 'done', 'cancelled'].map((value, index) => [
+    value,
+    index,
+  ])
+);
+const PRIORITY_ORDER = new Map(['P0', 'P1', 'P2', 'P3'].map((value, index) => [value, index]));
+
+function text(value: string | null | undefined): string {
+  return value?.toLocaleLowerCase() ?? '';
+}
+
+function compareText(left: string | null | undefined, right: string | null | undefined): number {
+  return (left ?? '').localeCompare(right ?? '', undefined, { sensitivity: 'base' });
+}
+
+/** Pure client-side task search/filter/sort; source arrays remain untouched. */
+export function buildTaskBrowserRows(
+  tasks: readonly TaskCatalogRow[],
+  sprints: readonly { id: string; name: string }[],
+  options: TaskBrowserOptions
+): TaskBrowserRow[] {
+  const names = new Map(sprints.map((sprint) => [sprint.id, sprint.name]));
+  const query = text(options.query.trim());
+  const rows = tasks
+    .map((task) => ({ ...task, sprintName: names.get(task.sprintId) ?? null }))
+    .filter((task) => {
+      const searchable = [task.id, task.title, task.objective, task.sprintId, task.sprintName]
+        .map(text)
+        .join('\n');
+      return (
+        (!query || searchable.includes(query)) &&
+        (options.status === 'all' || task.status === options.status) &&
+        (options.priority === 'all' || task.priority === options.priority) &&
+        (options.sprintId === 'all' || task.sprintId === options.sprintId) &&
+        (options.location === 'all' || task.location === options.location)
+      );
+    });
+  if (options.sort === 'build') return rows;
+  return rows.sort((left, right) => {
+    if (options.sort === 'title') return compareText(left.title, right.title);
+    if (options.sort === 'priority') {
+      return (PRIORITY_ORDER.get(left.priority) ?? 99) - (PRIORITY_ORDER.get(right.priority) ?? 99);
+    }
+    if (options.sort === 'status') {
+      return (
+        (TASK_STATUS_ORDER.get(left.status) ?? 99) - (TASK_STATUS_ORDER.get(right.status) ?? 99)
+      );
+    }
+    return compareText(left.sprintName ?? left.sprintId, right.sprintName ?? right.sprintId);
+  });
+}
+
+/** Pure client-side sprint search/filter/sort; archive location is never inferred. */
+export function buildSprintBrowserRows(
+  sprints: readonly SprintBrowserInput[],
+  options: SprintBrowserOptions
+): SprintBrowserInput[] {
+  const query = text(options.query.trim());
+  const rows = sprints
+    .filter((sprint) => {
+      const searchable = [sprint.id, sprint.name, sprint.goal].map(text).join('\n');
+      return (
+        (!query || searchable.includes(query)) &&
+        (options.status === 'all' || sprint.status === options.status) &&
+        (options.location === 'all' || sprint.location === options.location)
+      );
+    })
+    .map((sprint) => ({ ...sprint }));
+  if (options.sort === 'build') return rows;
+  return rows.sort((left, right) => {
+    if (options.sort === 'name') return compareText(left.name, right.name);
+    if (options.sort === 'status') return compareText(left.status, right.status);
+    return right.startDate.localeCompare(left.startDate);
+  });
+}
+
+/** Pulse only while Build still reports a progressing launch, not every live card. */
+export function isRunProgressing(
+  run: Pick<RunCard, 'status' | 'terminal' | 'cancelRequested' | 'processHandle'>
+): boolean {
+  return (
+    !run.terminal &&
+    !run.cancelRequested &&
+    run.processHandle !== 'lost' &&
+    (run.status === 'starting' || run.status === 'running')
+  );
+}
+
+export function partitionRunCards(runs: readonly RunCard[]): {
+  live: RunCard[];
+  recent: RunCard[];
+} {
+  return {
+    live: runs.filter((run) => !run.terminal),
+    recent: runs.filter((run) => run.terminal),
+  };
+}
+
+export function progressingRunCount(runs: readonly RunCard[]): number {
+  return runs.filter(isRunProgressing).length;
+}
+
+export type DisplayedRunKind =
+  | 'fusion'
+  | 'competition'
+  | 'tracked'
+  | 'task-run'
+  | 'sprint-run'
+  | 'build'
+  | 'adopted';
+
+/**
+ * Registry-adopted runs are stored as Fusion with an unknown backlog id.
+ * Do not claim Fusion for that class; observed competitions stay competitions.
+ */
+export function displayedRunKind(
+  run: Pick<RunCard, 'resultKind' | 'processHandle' | 'backlogItemId' | 'subject'>
+): DisplayedRunKind {
+  if (run.resultKind === 'sprint') {
+    return run.subject?.kind === 'task' ? 'task-run' : 'sprint-run';
+  }
+  if (run.resultKind === 'build') return 'build';
+  if (
+    run.processHandle === 'never-owned' &&
+    run.resultKind === 'fusion' &&
+    run.backlogItemId === 'unknown'
+  ) {
+    return 'adopted';
+  }
+  if (run.resultKind === 'competition') return 'competition';
+  if (run.resultKind === 'backlog-execute') return 'tracked';
+  return 'fusion';
+}
+
+export const DISPLAYED_RUN_KIND_LABELS: Readonly<Record<DisplayedRunKind, string>> = {
+  fusion: 'Fusion',
+  competition: 'Competition',
+  tracked: 'Tracked execute',
+  'task-run': 'Task execution',
+  'sprint-run': 'Sprint execution',
+  build: 'Build',
+  adopted: 'Adopted run — kind unconfirmed',
+};
+
+export function canOpenRunResults(
+  run: Pick<RunCard, 'runId' | 'resultKind' | 'processHandle' | 'backlogItemId' | 'subject'>
+): boolean {
+  return (
+    Boolean(run.runId) &&
+    run.resultKind !== 'sprint' &&
+    run.resultKind !== 'build' &&
+    displayedRunKind(run) !== 'adopted'
+  );
+}
+
+export interface BacklogBrowserOptions {
+  query: string;
+  status: BrowserFilterValue;
+  priority: BrowserFilterValue;
+  sort: 'build' | 'title' | 'priority' | 'status';
+}
+
+export function buildBacklogBrowserRows(
+  items: readonly BacklogItem[],
+  options: BacklogBrowserOptions
+): BacklogItem[] {
+  const query = text(options.query.trim());
+  const rows = items
+    .filter(
+      (item) =>
+        (!query || text(`${item.id}\n${item.title}`).includes(query)) &&
+        (options.status === 'all' || item.status === options.status) &&
+        (options.priority === 'all' || item.priority === options.priority)
+    )
+    .map((item) => ({ ...item }));
+  if (options.sort === 'build') return rows;
+  return rows.sort((left, right) => {
+    if (options.sort === 'title') return compareText(left.title, right.title);
+    if (options.sort === 'priority') {
+      return (
+        (PRIORITY_ORDER.get(left.priority ?? '') ?? 99) -
+        (PRIORITY_ORDER.get(right.priority ?? '') ?? 99)
+      );
+    }
+    return compareText(left.status, right.status);
+  });
+}
+
+export type RunPickerDisabledReason = 'unlinked' | 'missing-link' | 'already-tracked';
+
+export const RUN_PICKER_DISABLED_REASON_LABELS: Readonly<Record<RunPickerDisabledReason, string>> =
+  {
+    unlinked: 'Link a backlog item on Plan before launch.',
+    'missing-link': 'Linked backlog item is not in the current list.',
+    'already-tracked': 'A tracked execute for this item is already live.',
+  };
+
+export interface RunPickerTaskInput {
+  id: string;
+  title: string;
+  linkedBacklogItemId: string | null;
+}
+
+export interface RunPickerRow {
+  key: string;
+  source: 'sprint-task' | 'backlog';
+  title: string;
+  backlogItem: BacklogItem | null;
+  taskId: string | null;
+  /** Why Fusion and Compete are disabled. */
+  launchDisabledReason: RunPickerDisabledReason | null;
+  /** Why the tracked Run button is disabled. */
+  trackedDisabledReason: RunPickerDisabledReason | null;
+}
+
+function itemById(items: readonly BacklogItem[]): Map<string, BacklogItem> {
+  return new Map(items.map((item) => [item.id, item]));
+}
+
+function liveTrackedItemIds(
+  runs: readonly Pick<RunCard, 'terminal' | 'resultKind' | 'backlogItemId'>[]
+): Set<string> {
+  return new Set(
+    runs
+      .filter((run) => !run.terminal && run.resultKind === 'backlog-execute')
+      .map((run) => run.backlogItemId)
+  );
+}
+
+function rowReasons(
+  item: BacklogItem | null,
+  linkedId: string | null,
+  liveTracked: Set<string>
+): Pick<RunPickerRow, 'launchDisabledReason' | 'trackedDisabledReason'> {
+  if (linkedId === null && item === null) {
+    return { launchDisabledReason: 'unlinked', trackedDisabledReason: 'unlinked' };
+  }
+  if (item === null) {
+    return { launchDisabledReason: 'missing-link', trackedDisabledReason: 'missing-link' };
+  }
+  if (liveTracked.has(item.id)) {
+    return { launchDisabledReason: null, trackedDisabledReason: 'already-tracked' };
+  }
+  return { launchDisabledReason: null, trackedDisabledReason: null };
+}
+
+/**
+ * Sprint tasks first, then backlog items that are not already represented by a
+ * linked task. List rows never call getBacklog; already-tracked is a local hint.
+ */
+export function buildRunPickerRows(input: {
+  tasks: readonly RunPickerTaskInput[];
+  items: readonly BacklogItem[];
+  runs: readonly Pick<RunCard, 'terminal' | 'resultKind' | 'backlogItemId'>[];
+}): RunPickerRow[] {
+  const items = itemById(input.items);
+  const liveTracked = liveTrackedItemIds(input.runs);
+  const represented = new Set<string>();
+  const rows: RunPickerRow[] = [];
+
+  for (const task of input.tasks) {
+    const linkedId = task.linkedBacklogItemId;
+    const item = linkedId ? (items.get(linkedId) ?? null) : null;
+    if (item) represented.add(item.id);
+    rows.push({
+      key: `task:${task.id}`,
+      source: 'sprint-task',
+      title: task.title,
+      backlogItem: item,
+      taskId: task.id,
+      ...rowReasons(item, linkedId, liveTracked),
+    });
+  }
+
+  for (const item of input.items) {
+    if (represented.has(item.id)) continue;
+    rows.push({
+      key: `backlog:${item.id}`,
+      source: 'backlog',
+      title: item.title,
+      backlogItem: item,
+      taskId: null,
+      ...rowReasons(item, item.id, liveTracked),
+    });
+  }
+
+  return rows;
+}