@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/integrations/bb-plugin-build/src/contract.ts

@@ -0,0 +1,718 @@
+import { defineRpcContract } from '@bb/plugin-sdk';
+import { z } from 'zod';
+import {
+  backlogAuthoringOutcomeSchema,
+  backlogAuthoringRequestSchema,
+} from './backlog-authoring-schema.js';
+import { competitionDefaultsViewSchema } from './competition-defaults-schema.js';
+import { applyBacklogFinalizeMethod } from './finalize-schema.js';
+import { judgeOperationsViewSchema } from './judge-operations-schema.js';
+import { applyTaskActionMethod } from './model.js';
+import { patchPreviewInputSchema, patchPreviewViewSchema } from './patch-preview-schema.js';
+import { planningWorkspaceProjectionSchema } from './planning-workspace-schema.js';
+import { compatibilitySchema, repositorySchema } from './repository-schema.js';
+import { resultReadbackInputSchema } from './result-readback-schema.js';
+import { setupConfigViewSchema } from './setup-config-schema.js';
+import { applySprintCloseMethod } from './sprint-close-schema.js';
+import {
+  applySprintCompositionMethod,
+  getSprintMethod,
+  listSprintsMethod,
+} from './sprint-composition-schema.js';
+import {
+  launchSprintRunInputSchema,
+  preflightSprintRunInputSchema,
+  sprintRunPreflightSchema,
+  sprintRunReviewPolicySchema,
+  sprintRunSubjectSchema,
+} from './sprint-execution-schema.js';
+import { applyTaskAuthoringMethod } from './task-authoring-schema.js';
+import { listTasksMethod } from './task-catalog-schema.js';
+import { getTaskInputSchema, getTaskOutputSchema } from './task-detail-schema.js';
+
+export { repositorySchema };
+
+/**
+ * Re-export the frozen planning-authoring contract surfaces for BB host/RPC
+ * consumers. Each lane owns its own schemas, consent object, and disclosure;
+ * BPAU-07A registers them below without consolidating or rewriting any of them.
+ */
+export {
+  backlogAuthoringOutcomeSchema,
+  backlogAuthoringRefusalSchema,
+  backlogAuthoringRequestSchema,
+  backlogAuthoringResultSchema,
+} from './backlog-authoring-schema.js';
+export {
+  applyBacklogFinalizeInputSchema,
+  applyBacklogFinalizeMethod,
+  applyBacklogFinalizeOutputSchema,
+  backlogFinalizeConsentSchema,
+  backlogFinalizeDisclosureSchema,
+} from './finalize-schema.js';
+/**
+ * Re-export the frozen task-action contract surface for BB host/RPC consumers.
+ * Schemas live in model.ts so unit tests can load them without @bb/plugin-sdk;
+ * `applyTaskActionMethod` is registered on the live contract below.
+ */
+export {
+  applyTaskActionInputSchema,
+  applyTaskActionMethod,
+  applyTaskActionOutputSchema,
+  taskActionConsentSchema,
+  taskActionTerminalConsentSchema,
+  taskPlanningDisclosureSchema,
+} from './model.js';
+export {
+  applySprintCloseInputSchema,
+  applySprintCloseMethod,
+  applySprintCloseOutputSchema,
+  sprintCloseConsentSchema,
+  sprintCloseDisclosureSchema,
+} from './sprint-close-schema.js';
+export {
+  applySprintCompositionInputSchema,
+  applySprintCompositionMethod,
+  applySprintCompositionOutputSchema,
+  getSprintInputSchema,
+  getSprintMethod,
+  getSprintOutputSchema,
+  listSprintsInputSchema,
+  listSprintsMethod,
+  listSprintsOutputSchema,
+  sprintCompositionConsentSchema,
+  sprintCompositionDisclosureSchema,
+} from './sprint-composition-schema.js';
+export {
+  applyTaskAuthoringInputSchema,
+  applyTaskAuthoringMethod,
+  applyTaskAuthoringOutputSchema,
+  taskAuthoringConsentSchema,
+  taskAuthoringDisclosureSchema,
+} from './task-authoring-schema.js';
+export {
+  getTaskInputSchema,
+  getTaskMethod,
+  getTaskOutputSchema,
+} from './task-detail-schema.js';
+
+const targetInputSchema = z
+  .object({
+    projectId: z.string().min(1),
+    sourceId: z.string().min(1),
+  })
+  .strict();
+
+export const backlogItemSchema = z
+  .object({
+    id: z.string(),
+    title: z.string(),
+    status: z.string(),
+    priority: z.string().nullable(),
+    complexity: z.number().nullable(),
+    domain: z.string().nullable(),
+  })
+  .strict();
+
+/**
+ * Build's tracked-execution evidence for one backlog item. Read fresh on every
+ * request and used only to refuse an unsafe duplicate launch; BB stores none of
+ * it.
+ */
+const trackedExecutionSchema = z
+  .object({
+    status: z.enum(['queued', 'running', 'blocked', 'succeeded', 'failed', 'cancelled', 'unknown']),
+    provenanceStatus: z.string(),
+    processState: z.enum(['alive', 'gone', 'unobserved']),
+    executingPid: z.number().int().positive().nullable(),
+    terminal: z.boolean(),
+    stale: z.boolean(),
+    label: z.string(),
+    compatibility: compatibilitySchema,
+    evidence: z.array(
+      z
+        .object({
+          kind: z.enum([
+            'artifact',
+            'branch',
+            'changed_file',
+            'commit',
+            'delivery',
+            'judge',
+            'patch',
+            'pull_request',
+            'synthesis',
+            'verification',
+            'workflow',
+            'blocker',
+            'finalization',
+            'worktree',
+          ]),
+          value: z.string(),
+        })
+        .strict()
+    ),
+    workflowId: z.string().nullable(),
+    taskIds: z.array(z.string()),
+    branch: z.string().nullable(),
+    pullRequestNumber: z.number().int().positive().nullable(),
+    lastCompletedStep: z.string().nullable(),
+    failedAtStep: z.string().nullable(),
+    errorMessage: z.string().nullable(),
+    blockers: z.array(z.string()),
+    finalizationState: z.string(),
+  })
+  .strict();
+
+export const backlogDetailSchema = backlogItemSchema
+  .extend({
+    body: z.string(),
+    createdAt: z.string().nullable(),
+    filePath: z.string(),
+    execution: trackedExecutionSchema.nullable(),
+  })
+  .strict();
+
+const disclosureSchema = z
+  .object({
+    fullTrust: z.literal(true),
+    hostEquivalentExecution: z.literal(true),
+    providerAuth: z.literal('native'),
+    planningSync: z.literal(false),
+    gitPush: z.literal(false),
+    summary: z.string(),
+  })
+  .strict();
+
+const trackedExecutionDisclosureSchema = 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),
+    pullRequestCreation: z.literal(true),
+    explicitFinalization: z.literal(true),
+    summary: z.string(),
+  })
+  .strict();
+
+const evidenceSchema = z
+  .object({
+    kind: z.enum([
+      'artifact',
+      'branch',
+      'changed_file',
+      'commit',
+      'delivery',
+      'judge',
+      'patch',
+      'pull_request',
+      'synthesis',
+      'verification',
+      'workflow',
+      'blocker',
+      'finalization',
+      'worktree',
+    ]),
+    value: z.string(),
+    variant: z.string().optional(),
+    repository: z.string(),
+    runId: z.string(),
+  })
+  .strict();
+
+/** The canonical readback kind a run card's result view is read from. */
+export const runResultKindSchema = z.enum(['competition', 'fusion', 'backlog-execute']);
+const runCardResultKindSchema = z.enum([
+  'competition',
+  'fusion',
+  'backlog-execute',
+  'sprint',
+  'build',
+]);
+
+const executionActivityStatusSchema = z.enum([
+  'pending',
+  'running',
+  'succeeded',
+  'failed',
+  'cancelled',
+  'skipped',
+  'unknown',
+]);
+
+const executionActivityItemSchema = z
+  .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    status: executionActivityStatusSchema,
+    detail: z.string(),
+  })
+  .strict();
+
+const executionActivityMilestoneSchema = z
+  .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    status: executionActivityStatusSchema,
+    detail: z.string(),
+    items: z.array(executionActivityItemSchema),
+  })
+  .strict();
+
+const executionActivitySchema = z
+  .object({
+    schemaVersion: z.literal('1.0.0'),
+    position: z.string().nullable(),
+    milestones: z.array(executionActivityMilestoneSchema),
+  })
+  .strict();
+
+export const runCardSchema = z
+  .object({
+    operationId: z.string(),
+    runId: z.string().nullable(),
+    resultKind: runCardResultKindSchema,
+    backlogItemId: z.string(),
+    title: z.string(),
+    repository: z.string(),
+    branch: z.string(),
+    status: z.enum([
+      'starting',
+      'running',
+      'blocked',
+      'succeeded',
+      'failed',
+      'cancelled',
+      'unknown',
+    ]),
+    phase: z.string(),
+    progressLine: z.string(),
+    progressSource: z.enum(['deterministic', 'narrated']),
+    progressNarratedAt: z.string().nullable(),
+    progressStale: z.boolean(),
+    progressLatencyMs: z.number().nonnegative().nullable(),
+    progressAdvisory: z.string().nullable(),
+    progressSignature: z.string().nullable(),
+    terminal: z.boolean(),
+    cancelEligible: z.boolean(),
+    processHandle: z.enum(['owned', 'lost', 'never-owned']),
+    controlEvidence: z.enum(['local-process', 'build-live-process', 'none']),
+    cancelRequested: z.boolean(),
+    compatibility: compatibilitySchema,
+    evidence: z.array(evidenceSchema),
+    standaloneCommand: z.string().nullable(),
+    error: z.string().nullable(),
+    /**
+     * Nullable because Build's judge-operations projection is optional: a record
+     * without it stays valid instead of forcing a fabricated judge state.
+     */
+    judgeOperations: judgeOperationsViewSchema.nullable(),
+    subject: z
+      .union([
+        z.object({ kind: z.literal('backlog'), backlogItemId: z.string().min(1) }).strict(),
+        sprintRunSubjectSchema,
+      ])
+      .optional(),
+    stages: z
+      .array(
+        z
+          .object({
+            id: z.string(),
+            status: z.enum(['pending', 'running', 'succeeded', 'failed', 'unknown']),
+          })
+          .strict()
+      )
+      .optional(),
+    activity: executionActivitySchema.optional(),
+  })
+  .strict();
+
+/**
+ * Wire shape of BRCS-03's read-only results explorer view.
+ *
+ * The presentation module is the only place that decides these values; this is
+ * the strict transport shape for them. It is declared here rather than imported
+ * so the app-side contract type stays free of the Node-dependent readback
+ * service, and the server registration is what type-checks the built view
+ * against this schema.
+ */
+const resultExplorerRowSchema = z
+  .object({ id: z.string(), label: z.string(), value: z.string() })
+  .strict();
+
+const resultExplorerReferenceSchema = z
+  .object({
+    id: z.string(),
+    type: z.enum([
+      'artifact',
+      'patch',
+      'commit',
+      'branch',
+      'changed-file',
+      'pull-request',
+      'workflow',
+      'verification',
+      'worktree',
+      'judge',
+      'synthesis',
+      'delivery',
+    ]),
+    label: z.string(),
+    value: z.string(),
+    variant: z.string().nullable(),
+    previewEligible: z.boolean(),
+  })
+  .strict();
+
+const resultExplorerSectionSchema = z
+  .object({
+    id: z.string(),
+    role: z.enum([
+      'outcome',
+      'comparison',
+      'winner',
+      'synthesis',
+      'delivery',
+      'workflow',
+      'git',
+      'verification',
+      'blockers',
+      'finalization',
+      'evidence',
+      'provenance',
+      'health',
+      'notice',
+    ]),
+    title: z.string(),
+    rows: z.array(resultExplorerRowSchema).readonly(),
+    references: z.array(resultExplorerReferenceSchema).readonly(),
+    emptyState: z.string().nullable(),
+  })
+  .strict();
+
+export const resultExplorerViewSchema = z
+  .object({
+    viewVersion: z.literal('1.0.0'),
+    state: z.enum(['available', 'unavailable']),
+    kind: runResultKindSchema,
+    runId: z.string(),
+    headline: z.string(),
+    conditions: z
+      .array(
+        z.enum([
+          'healthy',
+          'degraded',
+          'partial',
+          'stale',
+          'historical',
+          'unknown-freshness',
+          'malformed',
+          'incompatible',
+          'unavailable',
+          'empty',
+          'not-applicable',
+        ])
+      )
+      .readonly(),
+    standaloneCommand: z.string(),
+    sections: z.array(resultExplorerSectionSchema).readonly(),
+    /** This surface intentionally carries no result mutation controls. */
+    controls: z.tuple([]).readonly(),
+  })
+  .strict();
+
+export const buildRpcContract = defineRpcContract({
+  listProjects: {
+    input: z.null(),
+    output: z
+      .object({
+        projects: z.array(
+          z
+            .object({
+              id: z.string(),
+              name: z.string(),
+              sources: z.array(z.object({ id: z.string(), path: z.string() }).strict()),
+            })
+            .strict()
+        ),
+      })
+      .strict(),
+  },
+  capabilities: {
+    input: targetInputSchema,
+    output: z
+      .object({
+        repository: repositorySchema,
+        disclosure: disclosureSchema,
+        trackedExecutionDisclosure: trackedExecutionDisclosureSchema,
+      })
+      .strict(),
+  },
+  listBacklog: {
+    input: targetInputSchema,
+    output: z.object({ repository: repositorySchema, items: z.array(backlogItemSchema) }).strict(),
+  },
+  planningWorkspace: {
+    input: targetInputSchema,
+    output: z
+      .object({ repository: repositorySchema, workspace: planningWorkspaceProjectionSchema })
+      .strict(),
+  },
+  getBacklog: {
+    input: targetInputSchema.extend({ backlogItemId: z.string().min(1) }).strict(),
+    output: z.object({ repository: repositorySchema, item: backlogDetailSchema }).strict(),
+  },
+  /**
+   * Fresh single-task detail from Build. No BB cache or mirror. Task identity
+   * and repository are schema-validated; no arbitrary file/argv/cwd/env input.
+   */
+  getTask: {
+    input: getTaskInputSchema,
+    output: getTaskOutputSchema,
+  },
+  listTasks: listTasksMethod,
+  launchFusion: {
+    input: targetInputSchema
+      .extend({
+        backlogItemId: z.string().min(1),
+        consent: z
+          .object({
+            hostExecution: z.literal(true),
+            providerAuth: z.literal(true),
+            repositoryEffects: z.literal(true),
+            noPlanningSyncOrPush: z.literal(true),
+          })
+          .strict(),
+      })
+      .strict(),
+    output: z.object({ repository: repositorySchema, run: runCardSchema }).strict(),
+  },
+  launchCompetition: {
+    input: targetInputSchema
+      .extend({
+        backlogItemId: z.string().min(1),
+        consent: z
+          .object({
+            hostExecution: z.literal(true),
+            providerAuth: z.literal(true),
+            repositoryEffects: z.literal(true),
+            buildPolicyIsAuthoritative: z.literal(true),
+          })
+          .strict(),
+      })
+      .strict(),
+    output: z.object({ repository: repositorySchema, run: runCardSchema }).strict(),
+  },
+  launchBuild: {
+    input: targetInputSchema
+      .extend({
+        intent: z.string().trim().min(1).max(20_000),
+        reviewPolicy: sprintRunReviewPolicySchema.optional(),
+        consent: z
+          .object({
+            hostExecution: z.literal(true),
+            providerAuth: z.literal(true),
+            repositoryEffects: z.literal(true),
+          })
+          .strict(),
+      })
+      .strict(),
+    output: z.object({ repository: repositorySchema, run: runCardSchema }).strict(),
+  },
+  launchTrackedBacklog: {
+    input: targetInputSchema
+      .extend({
+        backlogItemId: z.string().min(1),
+        consent: z
+          .object({
+            hostExecution: z.literal(true),
+            buildReadinessIsAuthoritative: z.literal(true),
+            branchChanges: z.literal(true),
+            managedPlanningSync: z.literal(true),
+            providerAuth: z.literal(true),
+            gitCommitsAndPush: z.literal(true),
+            pullRequestCreation: z.literal(true),
+            finalizationIsSeparate: z.literal(true),
+          })
+          .strict(),
+      })
+      .strict(),
+    output: z
+      .object({
+        repository: repositorySchema,
+        disclosure: trackedExecutionDisclosureSchema,
+        run: runCardSchema,
+      })
+      .strict(),
+  },
+  /** Adopt one known competition result for read-only, process-local observation. */
+  observeCompetition: {
+    input: targetInputSchema.extend({ runId: z.string().min(1).max(200) }).strict(),
+    output: z.object({ repository: repositorySchema, run: runCardSchema }).strict(),
+  },
+  pollRuns: {
+    input: targetInputSchema
+      .extend({
+        operationIds: z.array(z.string()).max(50).optional(),
+        /**
+         * Set only by an active UI subscriber that wants optional narration.
+         * Absent or false means no narration model call is scheduled, which is
+         * how the BB background service polls.
+         */
+        narrate: z.boolean().optional(),
+        /**
+         * Default true. When false, the watch TTL is not refreshed, so a
+         * background or hidden refetch cannot keep a closed panel's repository
+         * watched.
+         */
+        observe: z.boolean().optional(),
+        /**
+         * Default false. When true, skip the one-generation monitor handoff and
+         * always re-read Build. Reconnect and Refresh send this.
+         */
+        fresh: z.boolean().optional(),
+      })
+      .strict(),
+    output: z.object({ repository: repositorySchema, runs: z.array(runCardSchema) }).strict(),
+  },
+  /**
+   * Cancel exactly one eligible active run. This is a plugin RPC action over
+   * Build's existing cancellation behavior, not a new public command, and
+   * naming one operation keeps a cancel from reaching a sibling run.
+   */
+  cancelRun: {
+    input: targetInputSchema.extend({ operationId: z.string().min(1) }).strict(),
+    output: z.object({ repository: repositorySchema, run: runCardSchema }).strict(),
+  },
+  /**
+   * Apply exactly one action from the closed task-action vocabulary through the
+   * installed `build plan task` commands. The frozen schemas accept no argv,
+   * flags, cwd, env, executable, or generic task update, and the output carries
+   * Build's authoritative Planning Workspace and task reread.
+   */
+  applyTaskAction: applyTaskActionMethod,
+  /**
+   * Read one run's canonical Build result readback and return the read-only
+   * explorer view for it. Identity is schema-validated, no content is read, and
+   * no result, winner, or verification value is recomputed here.
+   */
+  readResult: {
+    input: resultReadbackInputSchema,
+    output: z.object({ repository: repositorySchema, view: resultExplorerViewSchema }).strict(),
+  },
+  /**
+   * Preview exactly one canonical patch reference from the selected run. This is
+   * the only method that reads file content, and only after the reference is
+   * rebound to a freshly reread canonical evidence set.
+   */
+  previewPatch: {
+    input: patchPreviewInputSchema,
+    output: z.object({ repository: repositorySchema, view: patchPreviewViewSchema }).strict(),
+  },
+  /**
+   * Read-only disclosure of Build's resolved competition defaults. It changes no
+   * configuration and does not alter the existing PBB-20 launch command.
+   */
+  competitionDefaults: {
+    input: targetInputSchema,
+    output: z
+      .object({ repository: repositorySchema, view: competitionDefaultsViewSchema })
+      .strict(),
+  },
+  /**
+   * Read-only Build setup and configuration status. Guidance is copyable text
+   * only: this method never runs setup, provider auth, or config mutation.
+   */
+  setupStatus: {
+    input: targetInputSchema,
+    output: z.object({ repository: repositorySchema, view: setupConfigViewSchema }).strict(),
+  },
+  /**
+   * Apply exactly one action from the closed backlog-authoring vocabulary
+   * (BPAU-01). The frozen request schema accepts no `--force`, `--no-sync`,
+   * `--body-file`, status, relationship, argv, cwd, env, or executable field, and
+   * a request refused before launch becomes an RPC error rather than an outcome
+   * that could read as "nothing happened after the command ran".
+   */
+  applyBacklogAuthoring: {
+    input: backlogAuthoringRequestSchema,
+    output: backlogAuthoringOutcomeSchema,
+  },
+  /**
+   * Apply exactly one custom task authoring or relationship action (BPAU-02).
+   * The vocabulary is disjoint from `applyTaskAction`: no status transition,
+   * time log, split, or assignee field exists in the schema.
+   */
+  applyTaskAuthoring: applyTaskAuthoringMethod,
+  /**
+   * Apply exactly one sprint-composition action (BPAU-03). Creating a custom
+   * task and adding backlog work to a sprint stay separate products; neither
+   * reaches a splitter, a provider, or sprint completion.
+   */
+  applySprintComposition: applySprintCompositionMethod,
+  /**
+   * Read-only sprint enumeration. Build's own list payload is carried verbatim;
+   * no capacity number is recomputed in BB.
+   */
+  listSprints: listSprintsMethod,
+  /**
+   * Read-only single-sprint projection, always with an explicit sprint id. There
+   * is no capacity command here: `sprint capacity` publishes no JSON and parsing
+   * human output is forbidden.
+   */
+  getSprint: getSprintMethod,
+  preflightSprintRun: {
+    input: preflightSprintRunInputSchema,
+    output: z
+      .object({ repository: repositorySchema, preflight: sprintRunPreflightSchema })
+      .strict(),
+  },
+  launchSprintRun: {
+    input: launchSprintRunInputSchema,
+    output: z
+      .object({
+        repository: repositorySchema,
+        preflight: sprintRunPreflightSchema,
+        workflowId: z.string().min(1),
+        run: runCardSchema,
+      })
+      .strict(),
+  },
+  /**
+   * Finalize one backlog item with the exact Build argv
+   * `plan backlog finalize <id> --pr <n> --commit <sha>`. PR number and commit
+   * SHA are request fields passed through from Build-published evidence. There
+   * is no `--auto` finalize.
+   */
+  applyBacklogFinalize: applyBacklogFinalizeMethod,
+  /**
+   * Close one sprint with `plan sprint close <sprintId>` after a fresh
+   * closable read. There is no `--force`, `--archive-backlog`, or `--all-*`.
+   */
+  applySprintClose: applySprintCloseMethod,
+});
+
+export type ResultExplorerWireView = z.infer<typeof resultExplorerViewSchema>;
+
+export type {
+  BacklogDetail,
+  BacklogItem,
+  ControlEvidence,
+  ProcessHandleState,
+  RepositoryView,
+  RunCard,
+  RunResultKind,
+  TaskActionAdmissionScope,
+  TaskActionCommandEvidence,
+  TaskActionCommandRequest,
+  TaskActionConsent,
+  TaskActionKind,
+  TaskActionOutcome,
+  TaskActionReasonKind,
+  TaskActionTerminalConsent,
+  TaskActionTerminalKind,
+  TrackedExecutionEvidence,
+} from './model.js';