@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/integrations/bb-plugin-build/src/finalize-service.ts

@@ -0,0 +1,330 @@
+/**
+ * Isolated backlog-finalize service.
+ *
+ * Accepts only an injected runner and always sends one fixed argv with
+ * `shell: false`. Callers cannot supply argv, env, cwd, an executable, or
+ * `--auto` / `--force` / `--no-sync` / `--dry-run`. PR number and commit SHA
+ * are request fields only; this service never invents or scrapes them.
+ *
+ * Refusal before launch is a refused result. After launch the outcome envelope
+ * is always returned. Exit code does not prove what changed: Build's reread
+ * of `plan backlog show <id> --json` and `plan sprint status --json` is the
+ * authority. Nothing is retried (`attempts: 1`).
+ */
+
+import type { z } from 'zod';
+import { backlogDetailSchema } from './backlog-authoring-schema.js';
+import {
+  BACKLOG_FINALIZE_DISCLOSURE,
+  BACKLOG_FINALIZE_MAX_DIAGNOSTIC_CHARS,
+  BACKLOG_FINALIZE_MAX_OUTPUT_BYTES,
+  BACKLOG_FINALIZE_READ_TIMEOUT_MS,
+  BACKLOG_FINALIZE_TIMEOUT_MS,
+  BACKLOG_FINALIZE_VERSION,
+  type BacklogFinalizeCommandEvidence,
+  type BacklogFinalizeEffectPhase,
+  type BacklogFinalizeEvidence,
+  type BacklogFinalizeOutcome,
+  type BacklogFinalizeResult,
+  backlogFinalizeArgv,
+  ProcessLocalBacklogFinalizeAdmission,
+  showJsonProvesFinalize,
+  showJsonPublishesFinalize,
+} from './finalize-model.js';
+import { applyBacklogFinalizeInputSchema } from './finalize-schema.js';
+import type { PlanningWorkspaceProjection } from './planning-service.js';
+import { planningSyncWarnings, planningWorkspaceSyncState } from './planning-sync-evidence.js';
+import { readPlanningWorkspaceEvidence } from './planning-workspace-readback.js';
+import { selectedRepositoryIdentityMatches } from './repository-identity.js';
+import { repositorySchema } from './repository-schema.js';
+
+type Repository = z.infer<typeof repositorySchema>;
+
+export interface BacklogFinalizeCommand {
+  file: 'build' | 'git';
+  args: readonly string[];
+  cwd: string;
+  timeoutMs: number;
+  maxOutputBytes: typeof BACKLOG_FINALIZE_MAX_OUTPUT_BYTES;
+  shell: false;
+}
+
+export interface BacklogFinalizeCommandResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export type BacklogFinalizeRunner = (
+  command: BacklogFinalizeCommand
+) => Promise<BacklogFinalizeCommandResult>;
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function timedOut(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 diagnostics(stdout: string, stderr: string): string | null {
+  const value = `${stdout}\n${stderr}`.trim();
+  return value.length === 0 ? null : value.slice(0, BACKLOG_FINALIZE_MAX_DIAGNOSTIC_CHARS);
+}
+
+function parseBoundedJson(stdout: string): unknown {
+  if (Buffer.byteLength(stdout, 'utf8') > BACKLOG_FINALIZE_MAX_OUTPUT_BYTES) {
+    throw new Error('Build output exceeded the finalize capture limit.');
+  }
+  return JSON.parse(stdout) as unknown;
+}
+
+function workspaceSync(workspace: BacklogFinalizeEvidence<PlanningWorkspaceProjection>): {
+  sync: BacklogFinalizeOutcome['sync'];
+  warnings: string[];
+} {
+  const warnings =
+    workspace.state === 'unavailable' ? [workspace.reason] : planningSyncWarnings(workspace.value);
+  return { sync: planningWorkspaceSyncState(workspace), warnings };
+}
+
+function effectPhase(
+  command: BacklogFinalizeCommandEvidence,
+  detail: BacklogFinalizeEvidence<z.infer<typeof backlogDetailSchema>>
+): BacklogFinalizeEffectPhase {
+  if (detail.state === 'available' && showJsonProvesFinalize(detail.value)) return 'applied';
+  if (command.state === 'timed_out') return 'unknown-after-timeout';
+  return 'failed-after-partial-effect';
+}
+
+export class BacklogFinalizeService {
+  private readonly admission = new ProcessLocalBacklogFinalizeAdmission();
+
+  constructor(private readonly run: BacklogFinalizeRunner) {}
+
+  async apply(repositoryValue: unknown, requestValue: unknown): Promise<BacklogFinalizeResult> {
+    const repositoryResult = repositorySchema.safeParse(repositoryValue);
+    if (!repositoryResult.success) {
+      return this.refusal('repository-not-ready', 'The selected repository is invalid.');
+    }
+    const repository = repositoryResult.data;
+    if (repository.state === 'blocked' || repository.branch === null) {
+      return this.refusal(
+        'repository-not-ready',
+        'The selected repository is not ready on a named branch.'
+      );
+    }
+    const parsed = applyBacklogFinalizeInputSchema.safeParse(requestValue);
+    if (!parsed.success) {
+      return this.refusal(
+        'invalid-request',
+        'The finalize request contains unsupported or invalid fields.'
+      );
+    }
+    const request = parsed.data;
+    if (request.projectId !== repository.projectId || request.sourceId !== repository.sourceId) {
+      return this.refusal(
+        'repository-mismatch',
+        'The request does not identify the selected repository.'
+      );
+    }
+    if (
+      request.expected.repository !== repository.path ||
+      request.expected.branch !== repository.branch
+    ) {
+      return this.refusal(
+        'stale-repository',
+        'The selected repository or branch changed before submission.'
+      );
+    }
+
+    const release = this.admission.claim({
+      repositoryPath: repository.path,
+      backlogItemId: request.backlogItemId,
+    });
+    if (!release) {
+      return this.refusal(
+        'duplicate-submission',
+        'A finalize submission is already in progress for this backlog item.'
+      );
+    }
+
+    try {
+      const before = await this.readShow(repository, request.backlogItemId);
+      if (before.state === 'unavailable') {
+        return this.refusal(
+          'missing-identity',
+          `Build could not confirm backlog item ${request.backlogItemId} before launch.`
+        );
+      }
+      if (!showJsonPublishesFinalize(before.raw, request.pr, request.commit)) {
+        return this.refusal(
+          'missing-identity',
+          'Build has not published this pull request number and commit SHA for the item.'
+        );
+      }
+      if (!(await this.repositoryIdentityMatches(repository))) {
+        return this.refusal(
+          'stale-repository',
+          'Git no longer reports the selected repository root and branch.'
+        );
+      }
+
+      const argv = backlogFinalizeArgv(request);
+      let commandResult: BacklogFinalizeCommandResult | null = null;
+      let commandError: unknown = null;
+      try {
+        commandResult = await this.runCommand(
+          'build',
+          argv,
+          repository,
+          BACKLOG_FINALIZE_TIMEOUT_MS
+        );
+      } catch (error) {
+        commandError = error;
+      }
+
+      const commandState: BacklogFinalizeCommandEvidence['state'] = commandError
+        ? timedOut(commandError)
+          ? 'timed_out'
+          : 'failed'
+        : commandResult?.exitCode === 0
+          ? 'succeeded'
+          : 'failed';
+      const command: BacklogFinalizeCommandEvidence = {
+        state: commandState,
+        attempts: 1,
+        argv,
+        exitCode: commandResult?.exitCode ?? null,
+        diagnostics: commandResult
+          ? diagnostics(commandResult.stdout, commandResult.stderr)
+          : diagnostics('', errorMessage(commandError)),
+        remoteSyncConfirmedByExitCode: false,
+      };
+
+      const detail = await this.readDetail(repository, request.backlogItemId);
+      const workspace = await this.readWorkspace(repository);
+      const syncEvidence = workspaceSync(workspace);
+
+      return {
+        outcomeVersion: BACKLOG_FINALIZE_VERSION,
+        repository,
+        disclosure: BACKLOG_FINALIZE_DISCLOSURE,
+        action: 'finalizeBacklogItem',
+        requestedIdentities: {
+          backlogItemId: request.backlogItemId,
+          pr: request.pr,
+          commit: request.commit,
+        },
+        command,
+        effect: {
+          phase: effectPhase(command, detail),
+          createdIdentities: [],
+          affectedIdentities: [request.backlogItemId],
+        },
+        sync: syncEvidence.sync,
+        syncWarnings: syncEvidence.warnings,
+        integrityNotes:
+          detail.state === 'available'
+            ? []
+            : [`Build could not reread backlog item ${request.backlogItemId}: ${detail.reason}`],
+        canonicalRereads: { detail },
+        workspace,
+      };
+    } finally {
+      release();
+    }
+  }
+
+  private refusal(
+    reason: Extract<BacklogFinalizeResult, { state: 'refused' }>['reason'],
+    message: string
+  ): Extract<BacklogFinalizeResult, { state: 'refused' }> {
+    return { outcomeVersion: BACKLOG_FINALIZE_VERSION, state: 'refused', reason, message };
+  }
+
+  private runCommand(
+    file: 'build' | 'git',
+    args: readonly string[],
+    repository: Repository,
+    timeoutMs: number
+  ): Promise<BacklogFinalizeCommandResult> {
+    return this.run({
+      file,
+      args,
+      cwd: repository.path,
+      timeoutMs,
+      maxOutputBytes: BACKLOG_FINALIZE_MAX_OUTPUT_BYTES,
+      shell: false,
+    });
+  }
+
+  private async repositoryIdentityMatches(repository: Repository): Promise<boolean> {
+    return selectedRepositoryIdentityMatches(repository, (args) =>
+      this.runCommand('git', args, repository, BACKLOG_FINALIZE_READ_TIMEOUT_MS)
+    );
+  }
+
+  private async readShow(
+    repository: Repository,
+    backlogItemId: string
+  ): Promise<
+    | { state: 'available'; value: z.infer<typeof backlogDetailSchema>; raw: unknown }
+    | { state: 'unavailable'; reason: string }
+  > {
+    try {
+      const result = await this.runCommand(
+        'build',
+        ['plan', 'backlog', 'show', backlogItemId, '--json'],
+        repository,
+        BACKLOG_FINALIZE_READ_TIMEOUT_MS
+      );
+      if (result.exitCode !== 0) {
+        return { state: 'unavailable', reason: 'Build did not find the backlog item.' };
+      }
+      const raw = parseBoundedJson(result.stdout);
+      const parsed = backlogDetailSchema.safeParse(raw);
+      if (!parsed.success) {
+        return {
+          state: 'unavailable',
+          reason: 'Build returned malformed backlog detail evidence.',
+        };
+      }
+      if (parsed.data.id !== backlogItemId) {
+        return { state: 'unavailable', reason: 'Build returned a mismatched backlog identity.' };
+      }
+      return { state: 'available', value: parsed.data, raw };
+    } catch (error) {
+      return {
+        state: 'unavailable',
+        reason: `Build backlog detail reread failed: ${errorMessage(error)}`,
+      };
+    }
+  }
+
+  private async readDetail(
+    repository: Repository,
+    backlogItemId: string
+  ): Promise<BacklogFinalizeEvidence<z.infer<typeof backlogDetailSchema>>> {
+    const show = await this.readShow(repository, backlogItemId);
+    if (show.state === 'unavailable') return show;
+    return { state: 'available', value: show.value };
+  }
+
+  private async readWorkspace(
+    repository: Repository
+  ): Promise<BacklogFinalizeEvidence<PlanningWorkspaceProjection>> {
+    return readPlanningWorkspaceEvidence(
+      () =>
+        this.runCommand(
+          'build',
+          ['plan', 'sprint', 'status', '--json'],
+          repository,
+          BACKLOG_FINALIZE_READ_TIMEOUT_MS
+        ),
+      parseBoundedJson
+    );
+  }
+}

package/integrations/bb-plugin-build/src/finalize-view.ts

@@ -0,0 +1,159 @@
+/**
+ * Pure presentation for one-item backlog finalize. Nothing here runs a command
+ * or scrapes Git. PR number and commit SHA are taken only from Build-published
+ * evidence the panel already holds.
+ */
+
+import { BACKLOG_FINALIZE_DISCLOSURE, backlogFinalizeArgv } from './finalize-model.js';
+import type { ApplyBacklogFinalizeInput } from './finalize-schema.js';
+import type { BacklogDetail, RunCard } from './model.js';
+
+export const BACKLOG_FINALIZE_VIEW_VERSION = '1.0.0' as const;
+
+const BUILD_COMMIT_SHA = /^[0-9a-f]{40}$/i;
+
+export interface BacklogFinalizeConsentState {
+  hostExecution: boolean;
+  managedPlanningSync: boolean;
+  finalizeArchivesOrLifecycleUpdatesItem: boolean;
+  prAndCommitAreBuildPublished: boolean;
+}
+
+export const EMPTY_BACKLOG_FINALIZE_CONSENT: Readonly<BacklogFinalizeConsentState> = {
+  hostExecution: false,
+  managedPlanningSync: false,
+  finalizeArchivesOrLifecycleUpdatesItem: false,
+  prAndCommitAreBuildPublished: false,
+};
+
+export const BACKLOG_FINALIZE_CONSENT_LABELS: Readonly<
+  Record<keyof BacklogFinalizeConsentState, string>
+> = {
+  hostExecution: 'Build runs as my host user in the selected repository.',
+  managedPlanningSync:
+    "Build's built-in managed planning sync may commit and push these lifecycle changes.",
+  finalizeArchivesOrLifecycleUpdatesItem:
+    'Finalize archives or lifecycle-updates this backlog item. Build owns that lifecycle.',
+  prAndCommitAreBuildPublished:
+    'The pull request number and commit SHA shown are Build-published evidence. BB did not invent or scrape them.',
+};
+
+export const BACKLOG_FINALIZE_CONSENT_KEYS: ReadonlyArray<keyof BacklogFinalizeConsentState> = [
+  'hostExecution',
+  'managedPlanningSync',
+  'finalizeArchivesOrLifecycleUpdatesItem',
+  'prAndCommitAreBuildPublished',
+];
+
+/** PR number and commit SHA already published by Build for this item, or null. */
+export interface PublishedFinalizeEvidence {
+  pr: number;
+  commit: string;
+}
+
+function publishedCommitSha(
+  entries: ReadonlyArray<{ kind: string; value: string }> | undefined
+): string | null {
+  const commit = entries?.find((entry) => entry.kind === 'commit')?.value ?? null;
+  return commit !== null && BUILD_COMMIT_SHA.test(commit) ? commit : null;
+}
+
+/**
+ * Extract finalize fields only from Build-published evidence. A missing PR,
+ * a missing commit, or a value that is not a 40-character SHA yields null so
+ * the control stays disabled. Nothing is guessed from Git.
+ */
+export function publishedFinalizeEvidence(
+  detail: BacklogDetail | null,
+  runs: readonly RunCard[] = []
+): PublishedFinalizeEvidence | null {
+  const execution = detail?.execution;
+  const matchingRun = detail
+    ? (runs.find(
+        (run) => run.backlogItemId === detail.id && run.resultKind === 'backlog-execute'
+      ) ?? null)
+    : null;
+  const pr = execution?.pullRequestNumber ?? null;
+  if (pr === null || !Number.isSafeInteger(pr) || pr <= 0) return null;
+  const commit =
+    publishedCommitSha(execution?.evidence) ?? publishedCommitSha(matchingRun?.evidence);
+  if (commit === null) return null;
+  return { pr, commit };
+}
+
+export function backlogFinalizeConsentPayload(
+  consent: BacklogFinalizeConsentState
+): ApplyBacklogFinalizeInput['consent'] | null {
+  if (BACKLOG_FINALIZE_CONSENT_KEYS.some((key) => !consent[key])) return null;
+  return {
+    hostExecution: true,
+    managedPlanningSync: true,
+    finalizeArchivesOrLifecycleUpdatesItem: true,
+    prAndCommitAreBuildPublished: true,
+  };
+}
+
+export interface BacklogFinalizeConfirmationView {
+  backlogItemId: string;
+  pr: number;
+  commit: string;
+  headline: string;
+  effect: string;
+  commandLine: string;
+  disclosureSummary: string;
+  submittable: boolean;
+  blockedReason: string | null;
+}
+
+export function buildBacklogFinalizeConfirmationView(input: {
+  backlogItemId: string;
+  evidence: PublishedFinalizeEvidence | null;
+  consent: BacklogFinalizeConsentState;
+  inFlight: boolean;
+}): BacklogFinalizeConfirmationView | null {
+  if (input.evidence === null) return null;
+  const consent = backlogFinalizeConsentPayload(input.consent);
+  const blockedReason = input.inFlight
+    ? 'A finalize submission is already waiting for Build.'
+    : consent === null
+      ? 'Accept every consent line before submitting.'
+      : null;
+  return {
+    backlogItemId: input.backlogItemId,
+    pr: input.evidence.pr,
+    commit: input.evidence.commit,
+    headline: 'Confirm finalize',
+    effect:
+      'Asks Build to finalize this backlog item with the published pull request and commit. Build archives or lifecycle-updates the item; BB does not.',
+    commandLine: `build ${backlogFinalizeArgv({
+      backlogItemId: input.backlogItemId,
+      pr: input.evidence.pr,
+      commit: input.evidence.commit,
+    }).join(' ')}`,
+    disclosureSummary: BACKLOG_FINALIZE_DISCLOSURE.summary,
+    submittable: blockedReason === null,
+    blockedReason,
+  };
+}
+
+export function buildBacklogFinalizeRequest(input: {
+  projectId: string;
+  sourceId: string;
+  repositoryPath: string;
+  branch: string;
+  backlogItemId: string;
+  evidence: PublishedFinalizeEvidence;
+  consent: BacklogFinalizeConsentState;
+}): ApplyBacklogFinalizeInput | null {
+  const consent = backlogFinalizeConsentPayload(input.consent);
+  if (consent === null) return null;
+  return {
+    projectId: input.projectId,
+    sourceId: input.sourceId,
+    backlogItemId: input.backlogItemId,
+    pr: input.evidence.pr,
+    commit: input.evidence.commit,
+    expected: { repository: input.repositoryPath, branch: input.branch },
+    consent,
+  };
+}