@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/integrations/bb-plugin-build/src/backlog-authoring-service.ts

@@ -0,0 +1,467 @@
+import type { z } from 'zod';
+import {
+  BACKLOG_AUTHORING_DISCLOSURE,
+  type BacklogAddOutcome,
+  type BacklogAuthoringCommandEvidence,
+  type BacklogAuthoringOutcome,
+  type BacklogAuthoringResult,
+  type BacklogEffectPhase,
+  type BacklogEvidence,
+  backlogAuthoringArgv,
+} from './backlog-authoring-model.js';
+import {
+  BACKLOG_AUTHORING_VERSION,
+  backlogAddEnvelopeSchema,
+  backlogAuthoringRequestSchema,
+  backlogDetailSchema,
+  backlogListSchema,
+} from './backlog-authoring-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';
+
+export const BACKLOG_AUTHORING_TIMEOUT_MS = 120_000;
+export const BACKLOG_AUTHORING_READ_TIMEOUT_MS = 15_000;
+export const BACKLOG_AUTHORING_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+export const BACKLOG_BODY_STDIN_MIN_VERSION = '1.42.0' as const;
+/** Build moved from 1.x to calendar versions (YYYY.M.D); the first year is 2026. */
+export const FIRST_CALENDAR_BUILD_MAJOR = 2026;
+const MAX_DIAGNOSTIC_CHARS = 2_000;
+
+type Repository = z.infer<typeof repositorySchema>;
+
+export interface BacklogAuthoringCommand {
+  file: 'build' | 'git';
+  args: readonly string[];
+  cwd: string;
+  timeoutMs: number;
+  maxOutputBytes: typeof BACKLOG_AUTHORING_MAX_OUTPUT_BYTES;
+  shell: false;
+  stdin?: string;
+}
+
+export interface BacklogAuthoringCommandResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export type BacklogAuthoringRunner = (
+  command: BacklogAuthoringCommand
+) => Promise<BacklogAuthoringCommandResult>;
+
+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 supportsBacklogBodyStdin(version: string | null): boolean {
+  const match = /^(\d+)\.(\d+)\./.exec(version ?? '');
+  if (!match) return false;
+  const major = Number(match[1]);
+  return (major === 1 && Number(match[2]) >= 42) || major >= FIRST_CALENDAR_BUILD_MAJOR;
+}
+
+function diagnostics(stdout: string, stderr: string): string | null {
+  const value = `${stdout}\n${stderr}`.trim();
+  return value.length === 0 ? null : value.slice(0, MAX_DIAGNOSTIC_CHARS);
+}
+
+function parseBoundedJson(stdout: string): unknown {
+  if (Buffer.byteLength(stdout, 'utf8') > BACKLOG_AUTHORING_MAX_OUTPUT_BYTES) {
+    throw new Error('Build output exceeded the backlog authoring capture limit.');
+  }
+  return JSON.parse(stdout) as unknown;
+}
+
+function unavailable<T>(reason: string): BacklogEvidence<T> {
+  return { state: 'unavailable', reason };
+}
+
+class ProcessLocalBacklogAdmission {
+  private readonly claims = new Set<string>();
+
+  claim(repositoryPath: string, identity: string): (() => void) | null {
+    const key = `${repositoryPath}\0backlog:${identity}\0authoring`;
+    if (this.claims.has(key)) return null;
+    this.claims.add(key);
+    return () => this.claims.delete(key);
+  }
+}
+
+function effectPhase(
+  action: BacklogAuthoringOutcome['action'],
+  command: BacklogAuthoringCommandEvidence,
+  identityOutcome: BacklogAddOutcome | null
+): BacklogEffectPhase {
+  if (command.state === 'timed_out') return 'unknown-after-timeout';
+  if (action === 'createBacklogItem') {
+    if (!identityOutcome) return 'failed-after-partial-effect';
+    if (identityOutcome.state.startsWith('refused-')) return 'refused-before-effect';
+    if (identityOutcome.state === 'created-incomplete') return 'applied-incomplete';
+    if (identityOutcome.state === 'failed-after-partial-effect') {
+      return 'failed-after-partial-effect';
+    }
+    return 'applied';
+  }
+  return command.state === 'succeeded' ? 'applied' : 'failed-after-partial-effect';
+}
+
+/**
+ * The sync state backlog add's own receipt proves for this action, or null when it
+ * carries none (no receipt, or a legacy receipt without a sync status).
+ *
+ * `synced` is Build's receipt that this change was pushed and verified on the
+ * remote; a written item whose sync capture then failed is `failed`. A `1.1.0`
+ * receipt names this mutation's publisher evidence: a retained
+ * candidate is a local commit only, an unverified publication stays unknown, and a
+ * creation with no recorded candidate was not synced. Workspace-wide health never
+ * replaces this; it only contributes separate warnings.
+ */
+function actionSync(identity: BacklogAddOutcome | null): BacklogAuthoringOutcome['sync'] | null {
+  if (!identity) return null;
+  if (identity.state.startsWith('refused-')) {
+    return { state: 'not_attempted', detail: 'Build created no backlog item.' };
+  }
+  if (!identity.sync) return null;
+  if (identity.state === 'failed-after-partial-effect') {
+    return { state: 'failed', detail: 'Build wrote this item but did not capture it for sync.' };
+  }
+  if (identity.schemaVersion === '1.1.0') {
+    const { publication } = identity;
+    if (publication.state === 'pending') {
+      return {
+        state: 'local_commit_only',
+        detail: `Build retained this change as a local candidate at ${publication.pendingRef}; publish it with: build plan storage sync`,
+      };
+    }
+    if (publication.state === 'unverified') {
+      return {
+        state: 'unknown',
+        detail: 'Build could not verify publication of this change.',
+      };
+    }
+  }
+  switch (identity.sync) {
+    case 'synced':
+      return { state: 'remote_verified', detail: null };
+    case 'local-only':
+      return identity.schemaVersion === '1.1.0'
+        ? { state: 'not_attempted', detail: 'Build recorded no candidate for this change.' }
+        : { state: 'local_commit_only', detail: 'Build committed this change locally only.' };
+    case 'skipped':
+      return identity.complete
+        ? { state: 'not_attempted', detail: 'Build did not sync this change.' }
+        : { state: 'skipped_incomplete', detail: 'Build skipped sync for an incomplete item.' };
+    case 'refused-branch':
+      return {
+        state: 'not_attempted',
+        detail: 'Build refused managed sync on this branch; nothing was committed or pushed.',
+      };
+    case 'staged':
+    case 'failed':
+      return { state: 'failed', detail: `Build reported sync ${identity.sync} for this change.` };
+    case 'unverified':
+      return { state: 'unknown', detail: 'Build could not verify publication of this change.' };
+  }
+}
+
+/**
+ * Workspace-wide sync health for an action whose own receipt proves nothing about
+ * its sync. Zero unpushed planning commits is reported as `unknown`, never
+ * `remote_verified`.
+ */
+function workspaceSync(workspace: BacklogEvidence<PlanningWorkspaceProjection>): {
+  sync: BacklogAuthoringOutcome['sync'];
+  warnings: string[];
+} {
+  const warnings =
+    workspace.state === 'unavailable' ? [workspace.reason] : planningSyncWarnings(workspace.value);
+  return { sync: planningWorkspaceSyncState(workspace), warnings };
+}
+
+export class BacklogAuthoringService {
+  private readonly admission = new ProcessLocalBacklogAdmission();
+
+  constructor(private readonly run: BacklogAuthoringRunner) {}
+
+  async apply(repositoryValue: unknown, requestValue: unknown): Promise<BacklogAuthoringResult> {
+    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 = backlogAuthoringRequestSchema.safeParse(requestValue);
+    if (!parsed.success) {
+      return this.refusal(
+        'invalid-request',
+        'The backlog authoring request contains unsupported or invalid fields.'
+      );
+    }
+    const request = parsed.data;
+    const sendsBody =
+      request.action === 'createBacklogItem' ||
+      (request.action === 'updateBacklogItem' && request.input.body !== undefined);
+    if (sendsBody && !supportsBacklogBodyStdin(repository.buildVersion)) {
+      return this.refusal(
+        'repository-not-ready',
+        `Backlog body authoring requires Build ${BACKLOG_BODY_STDIN_MIN_VERSION} or newer so the body can be sent safely over stdin.`
+      );
+    }
+    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 requestedId = request.action === 'createBacklogItem' ? null : request.input.backlogItemId;
+    const release = this.admission.claim(repository.path, requestedId ?? 'create:backlog');
+    if (!release) {
+      return this.refusal(
+        'duplicate-submission',
+        'A backlog authoring submission is already in progress for this target.'
+      );
+    }
+
+    try {
+      if (requestedId) {
+        const before = await this.readDetail(repository, requestedId);
+        if (before.state === 'unavailable') {
+          return this.refusal(
+            'missing-identity',
+            `Build could not confirm backlog item ${requestedId} before launch.`
+          );
+        }
+        if (
+          request.action === 'updateBacklogItem' &&
+          request.input.body !== undefined &&
+          request.expected.canonicalBody !== before.value.body
+        ) {
+          return this.refusal(
+            'canonical-prepopulation-mismatch',
+            'The canonical backlog body changed after the replacement form was populated.'
+          );
+        }
+      }
+      if (!(await this.repositoryIdentityMatches(repository))) {
+        return this.refusal(
+          'stale-repository',
+          'Git no longer reports the selected repository root and branch.'
+        );
+      }
+
+      const argv = backlogAuthoringArgv(request);
+      const stdin =
+        request.action === 'createBacklogItem' ||
+        (request.action === 'updateBacklogItem' && request.input.body !== undefined)
+          ? request.input.body
+          : undefined;
+      let commandResult: BacklogAuthoringCommandResult | null = null;
+      let commandError: unknown = null;
+      try {
+        commandResult = await this.runCommand(
+          'build',
+          argv,
+          repository,
+          BACKLOG_AUTHORING_TIMEOUT_MS,
+          stdin
+        );
+      } catch (error) {
+        commandError = error;
+      }
+
+      let identityOutcome: BacklogAddOutcome | null = null;
+      if (request.action === 'createBacklogItem' && commandResult) {
+        try {
+          const envelope = backlogAddEnvelopeSchema.safeParse(
+            parseBoundedJson(commandResult.stdout)
+          );
+          if (envelope.success && envelope.data.backlogAddV1.exitCode === commandResult.exitCode) {
+            identityOutcome = envelope.data.backlogAddV1;
+          }
+        } catch {
+          // Missing or malformed identity evidence is ambiguous, never inferred from the list.
+        }
+      }
+      const affectedId =
+        request.action === 'createBacklogItem' ? (identityOutcome?.id ?? null) : requestedId;
+      const commandState: BacklogAuthoringCommandEvidence['state'] = commandError
+        ? timedOut(commandError)
+          ? 'timed_out'
+          : 'failed'
+        : request.action === 'createBacklogItem' && identityOutcome === null
+          ? 'ambiguous'
+          : commandResult?.exitCode === 0
+            ? 'succeeded'
+            : 'failed';
+      const command: BacklogAuthoringCommandEvidence = {
+        state: commandState,
+        attempts: 1,
+        argv,
+        exitCode: commandResult?.exitCode ?? null,
+        diagnostics: commandResult
+          ? diagnostics(
+              request.action === 'createBacklogItem' && identityOutcome ? '' : commandResult.stdout,
+              commandResult.stderr
+            )
+          : diagnostics('', errorMessage(commandError)),
+        remoteSyncConfirmedByExitCode: false,
+      };
+
+      const detail = affectedId
+        ? await this.readDetail(repository, affectedId)
+        : unavailable<z.infer<typeof backlogDetailSchema>>(
+            'Build reported no created backlog identity.'
+          );
+      const list = await this.readList(repository);
+      const workspace = await this.readWorkspace(repository);
+      const workspaceEvidence = workspaceSync(workspace);
+      const syncEvidence = {
+        sync: actionSync(identityOutcome) ?? workspaceEvidence.sync,
+        warnings: workspaceEvidence.warnings,
+      };
+      const createdIdentities = identityOutcome?.id ? [identityOutcome.id] : [];
+      const affectedIdentities = affectedId ? [affectedId] : [];
+
+      return {
+        outcomeVersion: BACKLOG_AUTHORING_VERSION,
+        repository,
+        disclosure: BACKLOG_AUTHORING_DISCLOSURE,
+        action: request.action,
+        requestedIdentities: { backlogItemId: requestedId },
+        command,
+        identityOutcome,
+        effect: {
+          phase: effectPhase(request.action, command, identityOutcome),
+          createdIdentities,
+          affectedIdentities,
+        },
+        sync: syncEvidence.sync,
+        syncWarnings: syncEvidence.warnings,
+        integrityNotes:
+          detail.state === 'available' || affectedId === null
+            ? []
+            : [`Build could not reread backlog item ${affectedId}: ${detail.reason}`],
+        canonicalRereads: { detail, list },
+        workspace,
+        fullBodyReplacement:
+          request.action === 'updateBacklogItem' && request.input.body !== undefined,
+        prioritizeMayReviewAndBecomeLaunchEligible: request.action === 'prioritizeBacklogItem',
+      };
+    } finally {
+      release();
+    }
+  }
+
+  private refusal(
+    reason: Extract<BacklogAuthoringResult, { state: 'refused' }>['reason'],
+    message: string
+  ): Extract<BacklogAuthoringResult, { state: 'refused' }> {
+    return { outcomeVersion: BACKLOG_AUTHORING_VERSION, state: 'refused', reason, message };
+  }
+
+  private runCommand(
+    file: 'build' | 'git',
+    args: readonly string[],
+    repository: Repository,
+    timeoutMs: number,
+    stdin?: string
+  ): Promise<BacklogAuthoringCommandResult> {
+    return this.run({
+      file,
+      args,
+      cwd: repository.path,
+      timeoutMs,
+      maxOutputBytes: BACKLOG_AUTHORING_MAX_OUTPUT_BYTES,
+      shell: false,
+      ...(stdin === undefined ? {} : { stdin }),
+    });
+  }
+
+  private async repositoryIdentityMatches(repository: Repository): Promise<boolean> {
+    return selectedRepositoryIdentityMatches(repository, (args) =>
+      this.runCommand('git', args, repository, BACKLOG_AUTHORING_READ_TIMEOUT_MS)
+    );
+  }
+
+  private async readList(
+    repository: Repository
+  ): Promise<BacklogEvidence<z.infer<typeof backlogListSchema>>> {
+    try {
+      const result = await this.runCommand(
+        'build',
+        ['plan', 'backlog', 'list', '--json'],
+        repository,
+        BACKLOG_AUTHORING_READ_TIMEOUT_MS
+      );
+      if (result.exitCode !== 0) return unavailable('Build backlog list reread failed.');
+      const parsed = backlogListSchema.safeParse(parseBoundedJson(result.stdout));
+      return parsed.success
+        ? { state: 'available', value: parsed.data }
+        : unavailable('Build returned malformed backlog list evidence.');
+    } catch (error) {
+      return unavailable(`Build backlog list reread failed: ${errorMessage(error)}`);
+    }
+  }
+
+  private async readDetail(
+    repository: Repository,
+    backlogItemId: string
+  ): Promise<BacklogEvidence<z.infer<typeof backlogDetailSchema>>> {
+    try {
+      const result = await this.runCommand(
+        'build',
+        ['plan', 'backlog', 'show', backlogItemId, '--json'],
+        repository,
+        BACKLOG_AUTHORING_READ_TIMEOUT_MS
+      );
+      if (result.exitCode !== 0) return unavailable('Build did not find the backlog item.');
+      const parsed = backlogDetailSchema.safeParse(parseBoundedJson(result.stdout));
+      if (!parsed.success) return unavailable('Build returned malformed backlog detail evidence.');
+      if (parsed.data.id !== backlogItemId) {
+        return unavailable('Build returned a mismatched backlog identity.');
+      }
+      return { state: 'available', value: parsed.data };
+    } catch (error) {
+      return unavailable(`Build backlog detail reread failed: ${errorMessage(error)}`);
+    }
+  }
+
+  private async readWorkspace(
+    repository: Repository
+  ): Promise<BacklogEvidence<PlanningWorkspaceProjection>> {
+    return readPlanningWorkspaceEvidence(
+      () =>
+        this.runCommand(
+          'build',
+          ['plan', 'sprint', 'status', '--json'],
+          repository,
+          BACKLOG_AUTHORING_READ_TIMEOUT_MS
+        ),
+      parseBoundedJson
+    );
+  }
+}