@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/integrations/bb-plugin-build/src/setup-config-view.ts

@@ -0,0 +1,388 @@
+/**
+ * Pure presentation of Build's read-only setup and configuration status.
+ *
+ * Guidance commands are rendered as copyable text only. This module never
+ * executes setup, reinstall, authentication, or configuration mutation.
+ */
+
+import {
+  SETUP_CONFIG_GUIDANCE,
+  SETUP_CONFIG_VIEW_VERSION,
+  type SetupConfigAttributedValue,
+  type SetupConfigResult,
+  type SetupConfigSnapshot,
+  type SetupConfigView,
+} from './setup-config-schema.js';
+
+export { SETUP_CONFIG_VIEW_VERSION };
+
+type Section = SetupConfigView['sections'][number];
+type Row = Section['rows'][number];
+
+function row(id: string, label: string, value: string, source?: Row['source']): Row {
+  return source === undefined ? { id, label, value } : { id, label, value, source };
+}
+
+function attributedRow(
+  id: string,
+  label: string,
+  value: SetupConfigAttributedValue | null
+): Row | null {
+  if (!value) return null;
+  return row(id, label, value.value, value.source);
+}
+
+function validityLabel(state: SetupConfigSnapshot['validity']['state']): string {
+  switch (state) {
+    case 'valid':
+      return 'Valid';
+    case 'invalid':
+      return 'Invalid';
+    case 'missing':
+      return 'Missing';
+    case 'unavailable':
+      return 'Unavailable';
+  }
+}
+
+function compatibilitySection(snapshot: SetupConfigSnapshot): Section {
+  const { compatibility } = snapshot;
+  return {
+    id: 'compatibility',
+    title: 'Build / BB compatibility',
+    rows: [
+      row('build-version', 'Build version', compatibility.buildVersion ?? 'unknown', 'repository'),
+      row('compatibility', 'Compatibility', compatibility.compatibility, 'repository'),
+      row('repository-state', 'Repository state', compatibility.repositoryState, 'repository'),
+    ],
+    notices:
+      compatibility.compatibility === 'incompatible'
+        ? ['Build is incompatible with this BB plugin. Upgrade or realign versions outside BB.']
+        : compatibility.compatibility === 'unavailable'
+          ? ['Compatibility could not be determined from the selected repository.']
+          : [],
+  };
+}
+
+function validitySection(snapshot: SetupConfigSnapshot): Section {
+  const { validity } = snapshot;
+  return {
+    id: 'validity',
+    title: 'Configuration validity',
+    rows: [
+      row('validity-state', 'Validity', validityLabel(validity.state)),
+      row('validity-message', 'Detail', validity.message),
+      row('error-count', 'Error count', String(validity.errorCount)),
+      row('warning-count', 'Warning count', String(validity.warningCount)),
+    ],
+    notices:
+      validity.state === 'missing'
+        ? [
+            'Configuration is missing. Run `build init` outside BB if this repository should be managed.',
+          ]
+        : validity.state === 'invalid'
+          ? ['Configuration is invalid. Inspect with `build config validate --json` outside BB.']
+          : [],
+  };
+}
+
+function defaultsSection(snapshot: SetupConfigSnapshot): Section {
+  if (snapshot.defaults.state === 'unavailable') {
+    return {
+      id: 'defaults',
+      title: 'Resolved defaults',
+      rows: [],
+      notices: ['Resolved defaults are unavailable from Build.'],
+    };
+  }
+  const rows = [
+    attributedRow('default-provider', 'Default provider', snapshot.defaults.provider),
+    attributedRow('default-model', 'Default model', snapshot.defaults.model),
+    attributedRow('judge-type', 'Judge type', snapshot.defaults.judgeType),
+    attributedRow('judge-provider', 'Judge provider', snapshot.defaults.judgeProvider),
+    attributedRow('judge-model', 'Judge model', snapshot.defaults.judgeModel),
+    attributedRow('synthesis-model', 'Fusion synthesis model', snapshot.defaults.synthesisModel),
+  ].filter((entry): entry is Row => entry !== null);
+
+  return {
+    id: 'defaults',
+    title: 'Resolved defaults (with source attribution)',
+    rows,
+    notices: [
+      'Build owns these resolved values and their source attribution.',
+      'Source labels never include raw configuration paths.',
+    ],
+  };
+}
+
+function competitionSection(snapshot: SetupConfigSnapshot): Section {
+  if (snapshot.competition.state === 'unavailable') {
+    return {
+      id: 'competition',
+      title: 'Competition / Fusion defaults',
+      rows: [],
+      notices: ['Competition defaults are unavailable from Build.'],
+    };
+  }
+  const sources = snapshot.competition.sources;
+  const rows: Row[] = [
+    row(
+      'variants',
+      'Variants',
+      snapshot.competition.variants.join(', ') || 'auto-discovered',
+      sources.variants
+    ),
+  ];
+  if (snapshot.competition.judge) {
+    rows.push(row('compete-judge', 'Compete judge', snapshot.competition.judge, sources.judge));
+  }
+  if (snapshot.competition.judgeRun) {
+    rows.push(
+      row('compete-judge-run', 'Judge run', snapshot.competition.judgeRun, sources.judgeRun)
+    );
+  }
+  if (snapshot.competition.judgePrimary) {
+    rows.push(
+      row(
+        'compete-judge-primary',
+        'Judge primary',
+        snapshot.competition.judgePrimary,
+        sources.judgePrimary
+      )
+    );
+  }
+  if (snapshot.competition.completionMode) {
+    rows.push(
+      row(
+        'completion-mode',
+        'Completion mode',
+        snapshot.competition.completionMode,
+        sources.completionMode
+      )
+    );
+  }
+  if (snapshot.competition.synthesisStrategy) {
+    rows.push(
+      row(
+        'synthesis-strategy',
+        'Fusion synthesis strategy',
+        snapshot.competition.synthesisStrategy,
+        sources.synthesisStrategy
+      )
+    );
+  }
+  if (snapshot.competition.timeoutMinutes !== null) {
+    rows.push(
+      row(
+        'timeout',
+        'Timeout (minutes)',
+        String(snapshot.competition.timeoutMinutes),
+        sources.timeout
+      )
+    );
+  }
+  if (snapshot.competition.requireMinVariants !== null) {
+    rows.push(
+      row(
+        'require-min-variants',
+        'Required minimum variants',
+        String(snapshot.competition.requireMinVariants),
+        sources.requireMinVariants
+      )
+    );
+  }
+
+  return {
+    id: 'competition',
+    title: 'Competition / Fusion defaults',
+    rows,
+    notices: ['Competition and Fusion synthesis defaults come from Build compete resolution.'],
+  };
+}
+
+function rolesSection(snapshot: SetupConfigSnapshot): Section {
+  if (snapshot.roles.state === 'unavailable') {
+    return {
+      id: 'roles',
+      title: 'Execution roles',
+      rows: [],
+      notices: ['Role defaults are unavailable from Build.'],
+    };
+  }
+  const rows = [
+    attributedRow(
+      'orchestrator-provider',
+      'Orchestrator provider',
+      snapshot.roles.orchestrator.provider
+    ),
+    attributedRow('orchestrator-model', 'Orchestrator model', snapshot.roles.orchestrator.model),
+    attributedRow('executor-provider', 'Executor provider', snapshot.roles.executor.provider),
+    attributedRow('executor-model', 'Executor model', snapshot.roles.executor.model),
+    attributedRow('reviewer-provider', 'Reviewer provider', snapshot.roles.reviewer.provider),
+    attributedRow('reviewer-model', 'Reviewer model', snapshot.roles.reviewer.model),
+  ].filter((entry): entry is Row => entry !== null);
+
+  return {
+    id: 'roles',
+    title: 'Execution roles',
+    rows,
+    notices: ['Role bindings are read-only disclosures; BB does not rebind providers or models.'],
+  };
+}
+
+function providersSection(snapshot: SetupConfigSnapshot): Section {
+  if (snapshot.providers.state === 'unavailable') {
+    return {
+      id: 'providers',
+      title: 'Provider installation and readiness',
+      rows: [],
+      notices: ['Provider readiness is unavailable from Build.'],
+    };
+  }
+
+  const rows: Row[] = [
+    row('ready-count', 'Ready providers', String(snapshot.providers.readyCount)),
+  ];
+  const notices: string[] = [
+    'Installed but unverified, unobserved, or deferred authentication is normal — never a failure or launch gate.',
+    'Missing provider CLI, authentication needed, installed-but-unverified, broken CLI, and unknown readiness stay distinct.',
+  ];
+
+  for (const provider of snapshot.providers.items) {
+    rows.push(
+      row(
+        `provider-${provider.id}`,
+        provider.displayName,
+        `${provider.readinessLabel}; install=${provider.installation}; auth=${provider.auth}`
+      )
+    );
+    if (provider.readiness === 'missing-cli' && provider.installGuidance) {
+      notices.push(
+        `${provider.displayName}: install guidance (run outside BB): ${provider.installGuidance}`
+      );
+    }
+  }
+
+  return {
+    id: 'providers',
+    title: 'Provider installation and readiness',
+    rows,
+    notices,
+  };
+}
+
+function guidanceSection(snapshot: SetupConfigSnapshot): Section {
+  return {
+    id: 'guidance',
+    title: 'Canonical setup and configuration guidance',
+    rows: snapshot.guidance.map((entry) =>
+      row(`guidance-${entry.id}`, entry.purpose, entry.command, 'guidance')
+    ),
+    notices: [
+      'These commands are copyable guidance only. This panel never executes setup, reinstall, authentication, or configuration mutation.',
+    ],
+  };
+}
+
+function availableSections(snapshot: SetupConfigSnapshot): Section[] {
+  return [
+    compatibilitySection(snapshot),
+    validitySection(snapshot),
+    defaultsSection(snapshot),
+    competitionSection(snapshot),
+    rolesSection(snapshot),
+    providersSection(snapshot),
+    guidanceSection(snapshot),
+  ];
+}
+
+/** Build the read-only setup/configuration workspace view. */
+export function buildSetupConfigView(result: SetupConfigResult): SetupConfigView {
+  if (result.state === 'unavailable') {
+    const sections: Section[] = [];
+    if (result.compatibility) {
+      sections.push(
+        compatibilitySection({
+          compatibility: result.compatibility,
+          validity: {
+            state: 'unavailable',
+            message: result.message,
+            errorCount: 0,
+            warningCount: 0,
+          },
+          defaults: {
+            state: 'unavailable',
+            provider: null,
+            model: null,
+            judgeType: null,
+            judgeProvider: null,
+            judgeModel: null,
+            synthesisModel: null,
+          },
+          competition: {
+            state: 'unavailable',
+            variants: [],
+            judge: null,
+            judgeRun: null,
+            judgePrimary: null,
+            completionMode: null,
+            synthesisStrategy: null,
+            timeoutMinutes: null,
+            requireMinVariants: null,
+            sources: {},
+          },
+          roles: {
+            state: 'unavailable',
+            orchestrator: { provider: null, model: null },
+            executor: { provider: null, model: null },
+            reviewer: { provider: null, model: null },
+          },
+          providers: { state: 'unavailable', readyCount: 0, items: [] },
+          guidance: result.guidance,
+        })
+      );
+    }
+    sections.push({
+      id: 'status',
+      title: 'Setup status',
+      rows: [row('reason', 'Reason', result.reason), row('detail', 'Detail', result.message)],
+      notices: [],
+    });
+    sections.push({
+      id: 'guidance',
+      title: 'Canonical setup and configuration guidance',
+      rows: (result.guidance.length > 0 ? result.guidance : [...SETUP_CONFIG_GUIDANCE]).map(
+        (entry) => row(`guidance-${entry.id}`, entry.purpose, entry.command, 'guidance')
+      ),
+      notices: [
+        'These commands are copyable guidance only. This panel never executes setup, reinstall, authentication, or configuration mutation.',
+      ],
+    });
+
+    return {
+      viewVersion: SETUP_CONFIG_VIEW_VERSION,
+      state: 'unavailable',
+      headline: 'Build setup and configuration unavailable',
+      sections,
+      guidance: result.guidance.length > 0 ? result.guidance : [...SETUP_CONFIG_GUIDANCE],
+      notices: [
+        result.message,
+        'No setup, reinstall, authentication, or configuration mutation is performed from BB.',
+      ],
+      controls: [],
+    };
+  }
+
+  return {
+    viewVersion: SETUP_CONFIG_VIEW_VERSION,
+    state: 'available',
+    headline: 'Build setup and configuration',
+    sections: availableSections(result.snapshot),
+    guidance: result.snapshot.guidance,
+    notices: [
+      'Build owns installation, authentication, and configuration. BB only discloses read-only status.',
+      'Unobserved or deferred provider authentication is unknown/normal and is never treated as a launch gate.',
+    ],
+    controls: [],
+  };
+}

package/integrations/bb-plugin-build/src/sprint-close-model.ts

@@ -0,0 +1,150 @@
+/**
+ * Pure single-sprint close semantics: one fixed argv, high consent, and
+ * process-local admission. Nothing here spawns a process. Closable is decided
+ * only by a fresh Build sprint status read, never recomputed here.
+ */
+
+import type { z } from 'zod';
+import type { PlanningWorkspaceProjection } from './planning-service.js';
+import type { repositorySchema } from './repository-schema.js';
+import type { SprintStatusEnvelope } from './sprint-composition-schema.js';
+
+export const SPRINT_CLOSE_VERSION = '1.0.0' as const;
+
+/**
+ * Close may wait on managed planning sync. This is a documented long mutation
+ * timeout for the child process only. BB never adds a CLI timeout flag.
+ */
+export const SPRINT_CLOSE_TIMEOUT_MS = 600_000;
+
+export const SPRINT_CLOSE_READ_TIMEOUT_MS = 15_000;
+export const SPRINT_CLOSE_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+export const SPRINT_CLOSE_MAX_DIAGNOSTIC_CHARS = 2_000;
+
+export const SPRINT_CLOSE_DISCLOSURE = {
+  fullTrust: true,
+  hostEquivalentExecution: true,
+  providerAuth: 'native',
+  planningSync: true,
+  gitCommits: true,
+  gitPush: true,
+  managedPlanningMutation: true,
+  pullRequestCreation: false,
+  fusionLaunch: false,
+  trackedBacklogExecution: false,
+  runCancellation: false,
+  sprintClose: true,
+  summary:
+    "Sprint close runs exactly `build plan sprint close <sprint-id>` as your host user for one sprint. It runs only after a fresh Build read reports closable. Build's managed sync may commit and push. BB never passes --force, --archive-backlog, --all-finished, --all-ready, or --no-sync, and it never auto-closes after finalize.",
+} as const;
+
+export type SprintCloseConsent = {
+  hostExecution: true;
+  managedPlanningSync: true;
+  closeCompletesTheNamedSprint: true;
+};
+
+export type SprintCloseRequest = {
+  projectId: string;
+  sourceId: string;
+  sprintId: string;
+  expected: { repository: string; branch: string };
+  consent: SprintCloseConsent;
+};
+
+/** Fixed argv for one-sprint close. Nothing else is appended. */
+export function sprintCloseArgv(sprintId: string): string[] {
+  return ['plan', 'sprint', 'close', sprintId];
+}
+
+/**
+ * True only when a fresh sprint status payload already reports the sprint
+ * closed. Exit code is not consulted.
+ */
+export function sprintStatusProvesClosed(sprint: SprintStatusEnvelope): boolean {
+  return sprint.archived === true || sprint.status === 'completed';
+}
+
+export interface SprintCloseCommandEvidence {
+  state: 'succeeded' | 'failed' | 'timed_out' | 'ambiguous';
+  attempts: 1;
+  argv: readonly string[];
+  exitCode: number | null;
+  diagnostics: string | null;
+  remoteSyncConfirmedByExitCode: false;
+}
+
+export type SprintCloseEvidence<T> =
+  | { state: 'available'; value: T }
+  | { state: 'unavailable'; reason: string };
+
+export type SprintCloseEffectPhase =
+  | 'refused-before-launch'
+  | 'applied'
+  | 'failed-after-partial-effect'
+  | 'unknown-after-timeout';
+
+export interface SprintCloseOutcome {
+  outcomeVersion: typeof SPRINT_CLOSE_VERSION;
+  repository: z.infer<typeof repositorySchema>;
+  disclosure: typeof SPRINT_CLOSE_DISCLOSURE;
+  action: 'closeSprint';
+  requestedIdentities: { sprintId: string };
+  command: SprintCloseCommandEvidence;
+  effect: {
+    phase: SprintCloseEffectPhase;
+    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: {
+    sprint: SprintCloseEvidence<SprintStatusEnvelope>;
+  };
+  workspace: SprintCloseEvidence<PlanningWorkspaceProjection>;
+}
+
+export interface SprintCloseRefusal {
+  outcomeVersion: typeof SPRINT_CLOSE_VERSION;
+  state: 'refused';
+  reason:
+    | 'invalid-request'
+    | 'repository-mismatch'
+    | 'repository-not-ready'
+    | 'stale-repository'
+    | 'missing-identity'
+    | 'not-closable'
+    | 'duplicate-submission';
+  message: string;
+}
+
+export type SprintCloseResult = SprintCloseOutcome | SprintCloseRefusal;
+
+export type SprintCloseAdmissionScope = {
+  repositoryPath: string;
+  sprintId: string;
+};
+
+/**
+ * Process-local admission for one repository+sprint close. Does not claim
+ * cross-process ownership or Build-side exclusivity.
+ */
+export class ProcessLocalSprintCloseAdmission {
+  private readonly claims = new Set<string>();
+
+  claim(scope: SprintCloseAdmissionScope): (() => void) | null {
+    const key = `${scope.repositoryPath}\0sprint:${scope.sprintId}\0close`;
+    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/sprint-close-schema.ts

@@ -0,0 +1,128 @@
+import { z } from 'zod';
+import { commandEvidenceShape } from './command-evidence-schema.js';
+import { planningWorkspaceProjectionSchema } from './planning-workspace-schema.js';
+import { repositorySchema } from './repository-schema.js';
+import { SPRINT_CLOSE_VERSION } from './sprint-close-model.js';
+import {
+  managedPlanningIdSchema,
+  sprintStatusEnvelopeSchema,
+} from './sprint-composition-schema.js';
+
+/**
+ * High consent for one-sprint close. Every field is a required true literal.
+ * There is no argv, cwd, env, executable, `--force`, `--archive-backlog`, or
+ * `--all-*` field.
+ */
+export const sprintCloseConsentSchema = z
+  .object({
+    hostExecution: z.literal(true),
+    managedPlanningSync: z.literal(true),
+    closeCompletesTheNamedSprint: z.literal(true),
+  })
+  .strict();
+
+export const applySprintCloseInputSchema = z
+  .object({
+    projectId: z.string().min(1),
+    sourceId: z.string().min(1),
+    sprintId: managedPlanningIdSchema,
+    expected: z.object({ repository: z.string().min(1), branch: z.string().min(1) }).strict(),
+    consent: sprintCloseConsentSchema,
+  })
+  .strict();
+
+export type ApplySprintCloseInput = z.infer<typeof applySprintCloseInputSchema>;
+
+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 sprintCloseDisclosureSchema = 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),
+    sprintClose: z.literal(true),
+    summary: z.string(),
+  })
+  .strict();
+
+export const applySprintCloseOutputSchema = z
+  .object({
+    outcomeVersion: z.literal(SPRINT_CLOSE_VERSION),
+    repository: repositorySchema,
+    disclosure: sprintCloseDisclosureSchema,
+    action: z.literal('closeSprint'),
+    requestedIdentities: z.object({ sprintId: managedPlanningIdSchema }).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(z.string().min(1)).readonly(),
+        affectedIdentities: z.array(z.string().min(1)).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({
+        sprint: evidenceSchema(sprintStatusEnvelopeSchema),
+      })
+      .strict(),
+    workspace: evidenceSchema(planningWorkspaceProjectionSchema),
+  })
+  .strict();
+
+export const sprintCloseRefusalSchema = z
+  .object({
+    outcomeVersion: z.literal(SPRINT_CLOSE_VERSION),
+    state: z.literal('refused'),
+    reason: z.enum([
+      'invalid-request',
+      'repository-mismatch',
+      'repository-not-ready',
+      'stale-repository',
+      'missing-identity',
+      'not-closable',
+      'duplicate-submission',
+    ]),
+    message: z.string(),
+  })
+  .strict();
+
+export const sprintCloseResultSchema = z.union([
+  applySprintCloseOutputSchema,
+  sprintCloseRefusalSchema,
+]);
+
+export const applySprintCloseMethod = {
+  input: applySprintCloseInputSchema,
+  output: applySprintCloseOutputSchema,
+} as const;