@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/integrations/bb-plugin-build/src/execution-activity-view.ts

@@ -0,0 +1,98 @@
+export type ExecutionActivityStatus =
+  | 'pending'
+  | 'running'
+  | 'succeeded'
+  | 'failed'
+  | 'cancelled'
+  | 'skipped'
+  | 'unknown';
+
+export interface ExecutionActivityItem {
+  id: string;
+  label: string;
+  status: ExecutionActivityStatus;
+  detail: string;
+}
+
+export interface ExecutionActivityMilestone {
+  id: string;
+  label: string;
+  status: ExecutionActivityStatus;
+  detail: string;
+  items: ExecutionActivityItem[];
+}
+
+export interface ExecutionActivity {
+  schemaVersion: '1.0.0';
+  position: string | null;
+  milestones: ExecutionActivityMilestone[];
+}
+
+export interface ExecutionActivityMilestoneView extends ExecutionActivityMilestone {
+  current: boolean;
+  expanded: boolean;
+  summary: string;
+}
+
+export interface ExecutionActivityView {
+  position: string | null;
+  milestones: ExecutionActivityMilestoneView[];
+}
+
+function milestoneSummary(milestone: ExecutionActivityMilestone): string {
+  const total = milestone.items.length;
+  if (total === 0) return milestone.detail;
+  const complete = milestone.items.filter(
+    (item) =>
+      item.status === 'succeeded' ||
+      item.status === 'failed' ||
+      item.status === 'cancelled' ||
+      item.status === 'skipped'
+  ).length;
+  return milestone.detail
+    ? `${milestone.detail} · ${complete} of ${total}`
+    : `${complete} of ${total}`;
+}
+
+/**
+ * Pure BB presentation over Build-owned activity facts.
+ *
+ * The first running milestone is current. When nothing is running, the first
+ * failed milestone or the last terminal milestone is current. BB never changes
+ * a status or infers execution success; it only chooses which existing detail
+ * to disclose by default.
+ */
+export function buildExecutionActivityView(activity: ExecutionActivity): ExecutionActivityView {
+  const runningIndex = activity.milestones.findIndex((milestone) => milestone.status === 'running');
+  const failedIndex = activity.milestones.findIndex((milestone) => milestone.status === 'failed');
+  const cancelledIndex = activity.milestones.findIndex(
+    (milestone) => milestone.status === 'cancelled'
+  );
+  const lastTerminalIndex = activity.milestones.reduce(
+    (selected, milestone, index) =>
+      milestone.status === 'succeeded' ||
+      milestone.status === 'failed' ||
+      milestone.status === 'cancelled'
+        ? index
+        : selected,
+    -1
+  );
+  const currentIndex =
+    runningIndex >= 0
+      ? runningIndex
+      : failedIndex >= 0
+        ? failedIndex
+        : cancelledIndex >= 0
+          ? cancelledIndex
+          : lastTerminalIndex;
+
+  return {
+    position: activity.position,
+    milestones: activity.milestones.map((milestone, index) => ({
+      ...milestone,
+      current: index === currentIndex,
+      expanded: index === currentIndex && milestone.items.length > 0,
+      summary: milestoneSummary(milestone),
+    })),
+  };
+}

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

@@ -0,0 +1,205 @@
+/**
+ * Pure finalize semantics: one fixed argv, high consent, and process-local
+ * admission. Nothing here spawns a process or reads Git. PR number and commit
+ * SHA are request fields the host passes through from Build-published evidence;
+ * this module never invents, guesses, or scrapes them.
+ */
+
+import type { z } from 'zod';
+import type { backlogDetailSchema } from './backlog-authoring-schema.js';
+import type { PlanningWorkspaceProjection } from './planning-service.js';
+import type { repositorySchema } from './repository-schema.js';
+
+export const BACKLOG_FINALIZE_VERSION = '1.0.0' as const;
+
+/**
+ * Finalize may wait on merge, archive, and managed planning sync. This is a
+ * documented long mutation timeout for the child process only. BB never adds a
+ * CLI timeout flag.
+ */
+export const BACKLOG_FINALIZE_TIMEOUT_MS = 600_000;
+
+export const BACKLOG_FINALIZE_READ_TIMEOUT_MS = 15_000;
+export const BACKLOG_FINALIZE_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+export const BACKLOG_FINALIZE_MAX_DIAGNOSTIC_CHARS = 2_000;
+
+export const BACKLOG_FINALIZE_DISCLOSURE = {
+  fullTrust: true,
+  hostEquivalentExecution: true,
+  providerAuth: 'native',
+  planningSync: true,
+  gitCommits: true,
+  gitPush: true,
+  managedPlanningMutation: true,
+  pullRequestCreation: false,
+  fusionLaunch: false,
+  trackedBacklogExecution: false,
+  runCancellation: false,
+  explicitFinalization: true,
+  summary:
+    'Finalize runs exactly `build plan backlog finalize <id> --pr <n> --commit <sha>` as your host user. Build owns the lifecycle: it may archive or update the item and its built-in managed sync may commit and push. The PR number and commit SHA must already be Build-published evidence; BB never invents them, never scrapes Git, and never passes --auto, --force, or --no-sync.',
+} as const;
+
+export type BacklogFinalizeConsent = {
+  hostExecution: true;
+  managedPlanningSync: true;
+  finalizeArchivesOrLifecycleUpdatesItem: true;
+  prAndCommitAreBuildPublished: true;
+};
+
+export type BacklogFinalizeRequest = {
+  projectId: string;
+  sourceId: string;
+  backlogItemId: string;
+  pr: number;
+  commit: string;
+  expected: { repository: string; branch: string };
+  consent: BacklogFinalizeConsent;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * True only when a fresh `plan backlog show --json` payload already publishes
+ * this exact PR number and commit SHA. Nested mergeCommit fields and evidence
+ * `kind: commit` both count; nothing is scraped from Git.
+ */
+export function showJsonPublishesFinalize(raw: unknown, pr: number, commit: string): boolean {
+  if (!isRecord(raw)) return false;
+  const readback = isRecord(raw.operationalReadbackV1) ? raw.operationalReadbackV1 : null;
+  if (!readback) return false;
+  const payload = isRecord(readback.backlogExecute) ? readback.backlogExecute : null;
+  const pullRequest = isRecord(payload?.pullRequest) ? payload.pullRequest : null;
+  const finalization = isRecord(payload?.finalization) ? payload.finalization : null;
+  const publishedPr = typeof pullRequest?.number === 'number' ? pullRequest.number : null;
+  if (publishedPr !== pr) return false;
+  const evidenceCommit = Array.isArray(readback.evidence)
+    ? readback.evidence.find(
+        (entry) => isRecord(entry) && entry.kind === 'commit' && typeof entry.value === 'string'
+      )
+    : undefined;
+  const fromEvidence =
+    isRecord(evidenceCommit) && typeof evidenceCommit.value === 'string'
+      ? evidenceCommit.value
+      : null;
+  const nested =
+    (typeof pullRequest?.mergeCommit === 'string' ? pullRequest.mergeCommit : null) ??
+    (typeof finalization?.mergeCommit === 'string' ? finalization.mergeCommit : null);
+  const publishedCommit = fromEvidence ?? nested;
+  return publishedCommit !== null && publishedCommit.toLowerCase() === commit.toLowerCase();
+}
+
+/**
+ * True only when a fresh show payload already reports the item archived.
+ * Exit code is not consulted.
+ */
+export function showJsonProvesFinalize(raw: unknown): boolean {
+  if (!isRecord(raw)) return false;
+  const status = typeof raw.status === 'string' ? raw.status : null;
+  const filePath = typeof raw.filePath === 'string' ? raw.filePath.replace(/\\/g, '/') : '';
+  return status === 'archived' || filePath.includes('/archive/');
+}
+
+/**
+ * Fixed argv for one-item finalize. PR and commit are the request fields only.
+ * Nothing else is appended: no `--auto`, `--force`, `--no-sync`, `--dry-run`.
+ */
+export function backlogFinalizeArgv(
+  request: Pick<BacklogFinalizeRequest, 'backlogItemId' | 'pr' | 'commit'>
+): string[] {
+  return [
+    'plan',
+    'backlog',
+    'finalize',
+    request.backlogItemId,
+    '--pr',
+    String(request.pr),
+    '--commit',
+    request.commit,
+  ];
+}
+
+export interface BacklogFinalizeCommandEvidence {
+  state: 'succeeded' | 'failed' | 'timed_out' | 'ambiguous';
+  attempts: 1;
+  argv: readonly string[];
+  exitCode: number | null;
+  diagnostics: string | null;
+  remoteSyncConfirmedByExitCode: false;
+}
+
+export type BacklogFinalizeEvidence<T> =
+  | { state: 'available'; value: T }
+  | { state: 'unavailable'; reason: string };
+
+export type BacklogFinalizeEffectPhase =
+  | 'refused-before-launch'
+  | 'applied'
+  | 'failed-after-partial-effect'
+  | 'unknown-after-timeout';
+
+export interface BacklogFinalizeOutcome {
+  outcomeVersion: typeof BACKLOG_FINALIZE_VERSION;
+  repository: z.infer<typeof repositorySchema>;
+  disclosure: typeof BACKLOG_FINALIZE_DISCLOSURE;
+  action: 'finalizeBacklogItem';
+  requestedIdentities: { backlogItemId: string; pr: number; commit: string };
+  command: BacklogFinalizeCommandEvidence;
+  effect: {
+    phase: BacklogFinalizeEffectPhase;
+    createdIdentities: readonly string[];
+    affectedIdentities: readonly string[];
+  };
+  sync: {
+    state: 'not_attempted' | 'remote_verified' | 'local_commit_only' | 'failed' | 'unknown';
+    detail: string | null;
+  };
+  syncWarnings: readonly string[];
+  integrityNotes: readonly string[];
+  canonicalRereads: {
+    detail: BacklogFinalizeEvidence<z.infer<typeof backlogDetailSchema>>;
+  };
+  workspace: BacklogFinalizeEvidence<PlanningWorkspaceProjection>;
+}
+
+export interface BacklogFinalizeRefusal {
+  outcomeVersion: typeof BACKLOG_FINALIZE_VERSION;
+  state: 'refused';
+  reason:
+    | 'invalid-request'
+    | 'repository-mismatch'
+    | 'repository-not-ready'
+    | 'stale-repository'
+    | 'missing-identity'
+    | 'duplicate-submission';
+  message: string;
+}
+
+export type BacklogFinalizeResult = BacklogFinalizeOutcome | BacklogFinalizeRefusal;
+
+export type BacklogFinalizeAdmissionScope = {
+  repositoryPath: string;
+  backlogItemId: string;
+};
+
+/**
+ * Process-local admission for one repository+item finalize. Does not claim
+ * cross-process ownership or Build-side exclusivity.
+ */
+export class ProcessLocalBacklogFinalizeAdmission {
+  private readonly claims = new Set<string>();
+
+  claim(scope: BacklogFinalizeAdmissionScope): (() => void) | null {
+    const key = `${scope.repositoryPath}\0backlog:${scope.backlogItemId}\0finalize`;
+    if (this.claims.has(key)) return null;
+    this.claims.add(key);
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.claims.delete(key);
+    };
+  }
+}

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

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+import { backlogDetailSchema } from './backlog-authoring-schema.js';
+import { commandEvidenceShape } from './command-evidence-schema.js';
+import { BACKLOG_FINALIZE_VERSION } from './finalize-model.js';
+import { planningWorkspaceProjectionSchema } from './planning-workspace-schema.js';
+import { repositorySchema } from './repository-schema.js';
+
+const safeIdentitySchema = z
+  .string()
+  .min(1)
+  .max(200)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, 'Expected a single safe identity component.');
+
+/**
+ * Full Git object name as Build publishes it. Abbreviated or invented values
+ * are refused; BB never scrapes Git to complete a SHA.
+ */
+const buildCommitShaSchema = z
+  .string()
+  .min(40)
+  .max(40)
+  .regex(/^[0-9a-f]{40}$/i, 'A finalize commit must be a 40-character Build-published SHA.');
+
+const buildPrNumberSchema = z.number().int().positive();
+
+/**
+ * High consent for one-item finalize. Every field is a required true literal.
+ * There is no argv, cwd, env, executable, `--auto`, or `--force` field.
+ */
+export const backlogFinalizeConsentSchema = z
+  .object({
+    hostExecution: z.literal(true),
+    managedPlanningSync: z.literal(true),
+    finalizeArchivesOrLifecycleUpdatesItem: z.literal(true),
+    prAndCommitAreBuildPublished: z.literal(true),
+  })
+  .strict();
+
+export const applyBacklogFinalizeInputSchema = z
+  .object({
+    projectId: z.string().min(1),
+    sourceId: z.string().min(1),
+    backlogItemId: safeIdentitySchema,
+    pr: buildPrNumberSchema,
+    commit: buildCommitShaSchema,
+    expected: z.object({ repository: z.string().min(1), branch: z.string().min(1) }).strict(),
+    consent: backlogFinalizeConsentSchema,
+  })
+  .strict();
+
+export type ApplyBacklogFinalizeInput = z.infer<typeof applyBacklogFinalizeInputSchema>;
+
+const evidenceSchema = <T extends z.ZodType>(value: T) =>
+  z.discriminatedUnion('state', [
+    z.object({ state: z.literal('available'), value }).strict(),
+    z.object({ state: z.literal('unavailable'), reason: z.string() }).strict(),
+  ]);
+
+export const backlogFinalizeDisclosureSchema = z
+  .object({
+    fullTrust: z.literal(true),
+    hostEquivalentExecution: z.literal(true),
+    providerAuth: z.literal('native'),
+    planningSync: z.literal(true),
+    gitCommits: z.literal(true),
+    gitPush: z.literal(true),
+    managedPlanningMutation: z.literal(true),
+    pullRequestCreation: z.literal(false),
+    fusionLaunch: z.literal(false),
+    trackedBacklogExecution: z.literal(false),
+    runCancellation: z.literal(false),
+    explicitFinalization: z.literal(true),
+    summary: z.string(),
+  })
+  .strict();
+
+export const applyBacklogFinalizeOutputSchema = z
+  .object({
+    outcomeVersion: z.literal(BACKLOG_FINALIZE_VERSION),
+    repository: repositorySchema,
+    disclosure: backlogFinalizeDisclosureSchema,
+    action: z.literal('finalizeBacklogItem'),
+    requestedIdentities: z
+      .object({
+        backlogItemId: safeIdentitySchema,
+        pr: buildPrNumberSchema,
+        commit: buildCommitShaSchema,
+      })
+      .strict(),
+    command: z.object(commandEvidenceShape(z.array(z.string()).readonly())).strict(),
+    effect: z
+      .object({
+        phase: z.enum([
+          'refused-before-launch',
+          'applied',
+          'failed-after-partial-effect',
+          'unknown-after-timeout',
+        ]),
+        createdIdentities: z.array(safeIdentitySchema).readonly(),
+        affectedIdentities: z.array(safeIdentitySchema).readonly(),
+      })
+      .strict(),
+    sync: z
+      .object({
+        state: z.enum([
+          'not_attempted',
+          'remote_verified',
+          'local_commit_only',
+          'failed',
+          'unknown',
+        ]),
+        detail: z.string().nullable(),
+      })
+      .strict(),
+    syncWarnings: z.array(z.string()).readonly(),
+    integrityNotes: z.array(z.string()).readonly(),
+    canonicalRereads: z
+      .object({
+        detail: evidenceSchema(backlogDetailSchema),
+      })
+      .strict(),
+    workspace: evidenceSchema(planningWorkspaceProjectionSchema),
+  })
+  .strict();
+
+export const backlogFinalizeRefusalSchema = z
+  .object({
+    outcomeVersion: z.literal(BACKLOG_FINALIZE_VERSION),
+    state: z.literal('refused'),
+    reason: z.enum([
+      'invalid-request',
+      'repository-mismatch',
+      'repository-not-ready',
+      'stale-repository',
+      'missing-identity',
+      'duplicate-submission',
+    ]),
+    message: z.string(),
+  })
+  .strict();
+
+export const backlogFinalizeResultSchema = z.union([
+  applyBacklogFinalizeOutputSchema,
+  backlogFinalizeRefusalSchema,
+]);
+
+export const applyBacklogFinalizeMethod = {
+  input: applyBacklogFinalizeInputSchema,
+  output: applyBacklogFinalizeOutputSchema,
+} as const;