@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/integrations/bb-plugin-build/src/task-authoring-schema.ts

@@ -0,0 +1,629 @@
+/**
+ * Wire schemas for BB custom task authoring and task relationships.
+ *
+ * This is a closed authoring vocabulary. It is deliberately disjoint from the
+ * shipped task lifecycle vocabulary (`start|block|unblock|review|complete|
+ * cancel|reopen`): nothing here can move a task's status, archive it, reopen it,
+ * log time against it, split it, or reach `applyTaskAction`. Lifecycle stays
+ * with that shipped RPC.
+ *
+ * Every action maps to one fixed `build plan task …` argv. There is no
+ * caller-controlled argv, cwd, env, executable, path, `--body-file`,
+ * `--assignee`, `--allow-empty-results`, `--force`, `--no-sync`, splitter, or
+ * provider surface, and `--json` is never a caller field: the service appends it
+ * only on the one identity command that publishes `taskCreateV1`.
+ *
+ * Strict objects everywhere, so an unknown key — including a status or
+ * lifecycle field smuggled into `input` — fails validation before anything is
+ * spawned. `repositorySchema`, `planningWorkspaceProjectionSchema`, and the
+ * task-detail schemas are consumed read-only; nothing from the shared adapter,
+ * model, contract, server, app, or route modules is imported, re-exported, or
+ * shadowed here.
+ */
+
+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 { getTaskDetailOutputSchema } from './task-detail-schema.js';
+
+/** Version of the outcome envelope this lane publishes. */
+export const TASK_AUTHORING_OUTCOME_VERSION = '1.0.0' as const;
+
+/** One attempt, never retried; mutations get the long timeout, reads the short one. */
+export const TASK_AUTHORING_MUTATION_TIMEOUT_MS = 120_000;
+export const TASK_AUTHORING_READ_TIMEOUT_MS = 15_000;
+
+/** Captured stdout/stderr ceiling, and the diagnostics disclosure ceiling. */
+export const TASK_AUTHORING_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+export const TASK_AUTHORING_MAX_DIAGNOSTIC_CHARS = 2_000;
+
+/**
+ * Closed authoring vocabulary. `createCustomTask` is operator-authored task
+ * creation in an explicitly selected sprint; it is never an alias for adding
+ * existing backlog work to a sprint, which is a different product, command, and
+ * action name owned elsewhere.
+ */
+export const TASK_AUTHORING_VOCABULARY = [
+  'createCustomTask',
+  'updateCustomTask',
+  'addTaskDependency',
+  'removeTaskDependency',
+  'linkTaskToBacklog',
+] as const;
+
+export type TaskAuthoringAction = (typeof TASK_AUTHORING_VOCABULARY)[number];
+
+/**
+ * The shipped lifecycle vocabulary, restated locally so this lane can prove
+ * disjointness at runtime without importing the shared model module. The test
+ * suite pins this copy against the real `TASK_ACTION_VOCABULARY`.
+ */
+export const TASK_LIFECYCLE_VOCABULARY_MIRROR = [
+  'start',
+  'block',
+  'unblock',
+  'review',
+  'complete',
+  'cancel',
+  'reopen',
+] as const;
+
+/**
+ * Input keys refused before execution even though `.strict()` would also reject
+ * them. These are the shapes a caller could plausibly try in order to reach a
+ * status transition, an excluded flag, or a generic execution surface, and they
+ * are named explicitly so the refusal is legible rather than a generic schema
+ * error.
+ */
+export const TASK_AUTHORING_DENIED_INPUT_KEYS = [
+  'status',
+  'state',
+  'to',
+  'action',
+  'lifecycle',
+  'transition',
+  'reason',
+  'archive',
+  'archived',
+  'complete',
+  'completed',
+  'cancel',
+  'cancelled',
+  'reopen',
+  'start',
+  'started',
+  'block',
+  'blocked',
+  'unblock',
+  'review',
+  'assignee',
+  'hours',
+  'timeLogged',
+  'allowEmptyResults',
+  'bodyFile',
+  'body',
+  'force',
+  'noSync',
+  'sync',
+  'json',
+  'split',
+  'splitter',
+  'provider',
+  'model',
+  'hint',
+  'argv',
+  'cwd',
+  'env',
+  'executable',
+  'path',
+  'filePath',
+] as const;
+
+/**
+ * A managed planning id addresses one file under a Build-managed directory, so
+ * it must be a single safe path component: no separators, no traversal, and no
+ * leading dot or dash that could read as a hidden file or a CLI flag.
+ */
+export const taskAuthoringIdentitySchema = z
+  .string()
+  .min(1)
+  .max(200)
+  .regex(
+    /^[A-Za-z0-9][A-Za-z0-9._-]*$/,
+    'A managed planning id must be a single safe path component.'
+  );
+
+/**
+ * Free text carried as a single `--flag=value` token. The exact value `-` is
+ * refused because the CLI reads it as a stdin sentinel, and BB never streams a
+ * body from stdin or from a file.
+ */
+const taskAuthoringTextSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(4_000)
+  .refine((value) => value !== '-', 'A stdin sentinel is not an authoring value.');
+
+/**
+ * Numbers must render as plain decimal tokens, so no exponent or non-finite
+ * form can reach the argv. Bounds mirror Build's own planning validation.
+ */
+const plainDecimal = (value: number) => /^[0-9]+(\.[0-9]+)?$/.test(String(value));
+
+const taskAuthoringEstimateSchema = z
+  .number()
+  .positive()
+  .max(200)
+  .refine(plainDecimal, 'An estimate must be a plain decimal number.');
+
+const taskAuthoringRuntimeSchema = z
+  .number()
+  .positive()
+  .max(1_440)
+  .refine(plainDecimal, 'An expected runtime must be a plain decimal number.');
+
+const taskAuthoringPrioritySchema = z.enum(['P0', 'P1', 'P2', 'P3']);
+
+/**
+ * Consent every authoring mutation must carry. Each field is a required `true`
+ * literal inside a strict object, so partial or false consent fails validation
+ * rather than degrading into a silent default. This lane declares its own copy
+ * on purpose: it must not depend on another lane's consent module.
+ */
+export const taskAuthoringConsentSchema = z
+  .object({
+    hostExecution: z.literal(true),
+    managedPlanningMutation: z.literal(true),
+    automaticCommitAndPush: z.literal(true),
+    selectedRepositoryAndBranch: z.literal(true),
+  })
+  .strict();
+
+/** Creation additionally confirms that a new Build-minted id will exist. */
+export const taskAuthoringCreateConsentSchema = taskAuthoringConsentSchema
+  .extend({ newIdentityCreation: z.literal(true) })
+  .strict();
+
+/**
+ * Replacing the Description section additionally confirms the replacement. The
+ * scope is the `## Description` section only: Subtasks, Checklist, Acceptance
+ * Criteria, Notes, and Activity are untouched, and whole-task-body replacement
+ * is not offered at all because it would require the excluded `--body-file`.
+ */
+export const taskAuthoringSectionReplacementConsentSchema = taskAuthoringConsentSchema
+  .extend({ fullSectionReplacement: z.literal(true) })
+  .strict();
+
+export type TaskAuthoringConsent = z.infer<typeof taskAuthoringConsentSchema>;
+export type TaskAuthoringCreateConsent = z.infer<typeof taskAuthoringCreateConsentSchema>;
+export type TaskAuthoringSectionReplacementConsent = z.infer<
+  typeof taskAuthoringSectionReplacementConsentSchema
+>;
+
+/**
+ * What BB last read, submitted with the request so a checkout, an identity, or a
+ * sprint membership that moved since is refused rather than mutated blind. Every
+ * comparison against these values is made against a fresh Build read; BB never
+ * predicts the drift itself.
+ */
+export const taskAuthoringExpectedSchema = z
+  .object({
+    repositoryPath: z.string().min(1),
+    branch: z.string().min(1).nullable(),
+    entityIds: z.array(taskAuthoringIdentitySchema).max(64),
+    /**
+     * The sprint BB was showing this task in, or null when it holds none. It is
+     * evidence for the membership reread and the drift check, never an argv
+     * value: no authoring command takes a sprint except creation, which carries
+     * its own explicitly selected sprint in `input`.
+     */
+    observedSprintId: taskAuthoringIdentitySchema.nullable(),
+    /** Task `updated` timestamp BB last read, or null when it holds none. */
+    observedTaskUpdatedAt: z.string().min(1).nullable(),
+    /** Sprint membership BB last read, or null when it holds none. */
+    observedSprintTaskIds: z.array(taskAuthoringIdentitySchema).max(500).nullable(),
+  })
+  .strict();
+
+const requestTargetFields = {
+  projectId: z.string().min(1),
+  sourceId: z.string().min(1),
+  expected: taskAuthoringExpectedSchema,
+} as const;
+
+/**
+ * Creation input. The sprint is always explicit — there is no implicit "current
+ * sprint" — and the estimate is always required, so BB never silently inherits a
+ * CLI default. `dependsOn` and `backlogItemId` are permitted here so a new task
+ * lands with its relationships in one write; later relationship edits go through
+ * the dedicated dependency and link actions.
+ */
+export const createCustomTaskInputSchema = z
+  .object({
+    sprintId: taskAuthoringIdentitySchema,
+    title: taskAuthoringTextSchema,
+    estimate: taskAuthoringEstimateSchema,
+    expectedRuntimeMinutes: taskAuthoringRuntimeSchema.optional(),
+    description: taskAuthoringTextSchema.optional(),
+    priority: taskAuthoringPrioritySchema.optional(),
+    dependsOn: z.array(taskAuthoringIdentitySchema).max(64).optional(),
+    backlogItemId: taskAuthoringIdentitySchema.optional(),
+  })
+  .strict();
+
+/** Update whitelist. At least one field must be present; nothing else is accepted. */
+export const updateCustomTaskInputSchema = z
+  .object({
+    taskId: taskAuthoringIdentitySchema,
+    title: taskAuthoringTextSchema.optional(),
+    description: taskAuthoringTextSchema.optional(),
+    priority: taskAuthoringPrioritySchema.optional(),
+    estimate: taskAuthoringEstimateSchema.optional(),
+    expectedRuntimeMinutes: taskAuthoringRuntimeSchema.optional(),
+  })
+  .strict()
+  .refine(
+    (value) =>
+      value.title !== undefined ||
+      value.description !== undefined ||
+      value.priority !== undefined ||
+      value.estimate !== undefined ||
+      value.expectedRuntimeMinutes !== undefined,
+    'An update must change at least one whitelisted field.'
+  );
+
+/**
+ * Relationship endpoints are explicit and one-sided per action: an add carries
+ * only `onTaskId`, a remove only `removeTaskId`. The CLI requires exactly one of
+ * `--on` / `--remove`, and these separate actions make the other unreachable.
+ */
+export const addTaskDependencyInputSchema = z
+  .object({
+    taskId: taskAuthoringIdentitySchema,
+    onTaskId: taskAuthoringIdentitySchema,
+  })
+  .strict()
+  .refine((value) => value.taskId !== value.onTaskId, 'A task cannot depend on itself.');
+
+export const removeTaskDependencyInputSchema = z
+  .object({
+    taskId: taskAuthoringIdentitySchema,
+    removeTaskId: taskAuthoringIdentitySchema,
+  })
+  .strict()
+  .refine((value) => value.taskId !== value.removeTaskId, 'A task cannot depend on itself.');
+
+export const linkTaskToBacklogInputSchema = z
+  .object({
+    taskId: taskAuthoringIdentitySchema,
+    backlogItemId: taskAuthoringIdentitySchema,
+  })
+  .strict();
+
+/**
+ * Closed discriminated authoring request. Only the frozen action names are
+ * accepted, consent extras are required per action, and no member can carry a
+ * status, lifecycle, execution, or filesystem field.
+ */
+export const applyTaskAuthoringInputSchema = z.discriminatedUnion('action', [
+  z
+    .object({
+      ...requestTargetFields,
+      action: z.literal('createCustomTask'),
+      input: createCustomTaskInputSchema,
+      consent: taskAuthoringCreateConsentSchema,
+    })
+    .strict(),
+  z
+    .object({
+      ...requestTargetFields,
+      action: z.literal('updateCustomTask'),
+      input: updateCustomTaskInputSchema,
+      /**
+       * Either shape parses here; proportionality is enforced before launch by
+       * `taskAuthoringConsentRefusal`, which requires the section-replacement
+       * literal exactly when `description` is present and refuses it otherwise.
+       * The conditional is not expressed in the discriminated member itself
+       * because a discriminated-union member must stay a plain object schema.
+       */
+      consent: z.union([taskAuthoringSectionReplacementConsentSchema, taskAuthoringConsentSchema]),
+    })
+    .strict(),
+  z
+    .object({
+      ...requestTargetFields,
+      action: z.literal('addTaskDependency'),
+      input: addTaskDependencyInputSchema,
+      consent: taskAuthoringConsentSchema,
+    })
+    .strict(),
+  z
+    .object({
+      ...requestTargetFields,
+      action: z.literal('removeTaskDependency'),
+      input: removeTaskDependencyInputSchema,
+      consent: taskAuthoringConsentSchema,
+    })
+    .strict(),
+  z
+    .object({
+      ...requestTargetFields,
+      action: z.literal('linkTaskToBacklog'),
+      input: linkTaskToBacklogInputSchema,
+      consent: taskAuthoringConsentSchema,
+    })
+    .strict(),
+]);
+
+export type ApplyTaskAuthoringInput = z.infer<typeof applyTaskAuthoringInputSchema>;
+export type CreateCustomTaskInput = z.infer<typeof createCustomTaskInputSchema>;
+export type UpdateCustomTaskInput = z.infer<typeof updateCustomTaskInputSchema>;
+
+/**
+ * Lane disclosure. Every field is a literal, so the type system itself records
+ * that authoring never reaches the task lifecycle vocabulary.
+ */
+export const TASK_AUTHORING_DISCLOSURE = {
+  fullTrust: true,
+  hostEquivalentExecution: true,
+  providerAuth: 'native',
+  planningSync: true,
+  gitCommits: true,
+  gitPush: true,
+  managedPlanningMutation: true,
+  pullRequestCreation: false,
+  fusionLaunch: false,
+  trackedBacklogExecution: false,
+  runCancellation: false,
+  taskLifecycleTransition: false,
+  summary:
+    "Custom task authoring runs the installed Build plan-task commands as your host user in the selected repository and branch. It creates or edits managed task files and task relationships, and Build's built-in managed sync commits and pushes those planning changes. It never changes a task's status, never archives, completes, cancels, or reopens a task, never launches Fusion or tracked execution, never creates a pull request, and never cancels a run. BB never passes --no-sync, --force, --body-file, or --assignee.",
+} as const;
+
+export const taskAuthoringDisclosureSchema = 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),
+    taskLifecycleTransition: z.literal(false),
+    summary: z.string().min(1),
+  })
+  .strict();
+
+/**
+ * Build's `taskCreateV1` identity envelope, read from the create command's
+ * stdout. Unknown keys are stripped rather than refused: this is another
+ * process's output and the CLI may add fields, but the required identity content
+ * below is enforced, and a missing or inconsistent envelope makes the outcome
+ * ambiguous rather than assumed.
+ */
+export const taskCreateIdentityEnvelopeSchema = z.object({
+  schemaVersion: z.string().min(1),
+  state: z.enum(['created', 'refused', 'rolled-back', 'failed-after-partial-effect']),
+  taskId: z.string().nullable(),
+  sprintId: z.string(),
+  filePath: z.string().nullable(),
+  estimatedHours: z.number().nullable(),
+  expectedRuntimeMinutes: z.number().nullable(),
+  priority: z.string().nullable(),
+  dependencies: z.array(z.string()),
+  backlogItemId: z.string().nullable(),
+  fileCreated: z.boolean(),
+  sync: z.literal('refused-branch').optional(),
+  membershipApplied: z.boolean(),
+  capacity: z.object({
+    allocatedHours: z.number().nullable(),
+    totalHours: z.number().nullable(),
+  }),
+});
+
+export type TaskCreateIdentityEnvelope = z.infer<typeof taskCreateIdentityEnvelopeSchema>;
+
+/**
+ * Build's `taskDescriptionV1` sibling on `plan task status <id> --json
+ * --detail`. It is the only canonical source of a task's current Description
+ * section, and therefore the only permitted prepopulation source for a
+ * Description replacement.
+ */
+export const taskDescriptionEnvelopeSchema = z.object({
+  schemaVersion: z.string().min(1),
+  taskId: z.string().min(1),
+  description: z.string(),
+});
+
+export type TaskDescriptionEnvelope = z.infer<typeof taskDescriptionEnvelopeSchema>;
+
+/** Minimal sprint facts this lane rereads: identity, membership, capacity. */
+export const taskAuthoringSprintFactsSchema = z
+  .object({
+    id: z.string().min(1),
+    taskIds: z.array(z.string()),
+    capacity: z
+      .object({
+        allocatedHours: z.number().nullable(),
+        totalHours: z.number().nullable(),
+      })
+      .strict(),
+  })
+  .strict();
+
+export type TaskAuthoringSprintFacts = z.infer<typeof taskAuthoringSprintFactsSchema>;
+
+/**
+ * One canonical reread member. A reread that could not be performed is reported
+ * as unavailable with Build's own reason; it never converts an applied mutation
+ * into a failure and is never replaced by a predicted value.
+ */
+const rereadMemberSchema = <Value extends z.ZodTypeAny>(value: Value) =>
+  z.discriminatedUnion('state', [
+    z.object({ state: z.literal('available'), value }).strict(),
+    z.object({ state: z.literal('unavailable'), reason: z.string().min(1) }).strict(),
+  ]);
+
+/**
+ * The reread set for this lane. `sprint` and `description` are null when the
+ * action's reread set does not include them, which stays distinct from an
+ * attempted reread that was unavailable.
+ */
+export const taskAuthoringRereadsSchema = z
+  .object({
+    task: rereadMemberSchema(getTaskDetailOutputSchema),
+    sprint: rereadMemberSchema(taskAuthoringSprintFactsSchema).nullable(),
+    description: rereadMemberSchema(taskDescriptionEnvelopeSchema).nullable(),
+  })
+  .strict();
+
+/**
+ * What Build's single invocation reported. `argv` discloses the exact tokens
+ * that ran, `attempts` is a literal 1, and `remoteSyncConfirmedByExitCode` is a
+ * literal false so a zero exit can never be rendered as a confirmed push.
+ *
+ * `timed_out` and `ambiguous` exist because an exit code alone cannot settle
+ * whether a create applied: an unusable identity envelope or an interrupted
+ * command must render as neither success nor "nothing happened".
+ */
+export const taskAuthoringCommandEvidenceSchema = z
+  .object(commandEvidenceShape(z.array(z.string().min(1))))
+  .strict();
+
+/**
+ * The effect phase is explicit, never inferred by a consumer from an exit code.
+ * `unknown-after-timeout` is this envelope's only undetermined bucket: it covers
+ * an interrupted command and equally a command that ran but published no usable
+ * identity evidence.
+ */
+export const taskAuthoringEffectSchema = z
+  .object({
+    phase: z.enum([
+      'refused-before-launch',
+      'refused-before-effect',
+      'applied',
+      'applied-incomplete',
+      'failed-after-partial-effect',
+      'unknown-after-timeout',
+    ]),
+    createdIdentities: z.array(z.string()),
+    affectedIdentities: z.array(z.string()),
+  })
+  .strict();
+
+/**
+ * Sync state comes only from a fresh workspace reread. A zero exit proves the
+ * command's own logic completed; it never proves the managed push landed.
+ */
+export const taskAuthoringSyncSchema = z
+  .object({
+    state: z.enum([
+      'not_attempted',
+      'skipped_incomplete',
+      'remote_verified',
+      'local_commit_only',
+      'failed',
+      'unknown',
+    ]),
+    detail: z.string().nullable(),
+  })
+  .strict();
+
+export const taskAuthoringRequestedIdentitiesSchema = z
+  .object({
+    taskId: z.string().nullable(),
+    sprintId: z.string().nullable(),
+    dependencyTaskId: z.string().nullable(),
+    backlogItemId: z.string().nullable(),
+  })
+  .strict();
+
+/**
+ * Authoritative outcome of one authoring attempt. Once a process has run this
+ * envelope is returned even on a nonzero exit, so partial-effect evidence is
+ * never discarded.
+ */
+export const applyTaskAuthoringOutputSchema = z
+  .object({
+    outcomeVersion: z.literal(TASK_AUTHORING_OUTCOME_VERSION),
+    repository: repositorySchema,
+    disclosure: taskAuthoringDisclosureSchema,
+    action: z.enum(TASK_AUTHORING_VOCABULARY),
+    requestedIdentities: taskAuthoringRequestedIdentitiesSchema,
+    command: taskAuthoringCommandEvidenceSchema,
+    identityOutcome: taskCreateIdentityEnvelopeSchema.nullable(),
+    effect: taskAuthoringEffectSchema,
+    sync: taskAuthoringSyncSchema,
+    syncWarnings: z.array(z.string()),
+    integrityNotes: z.array(z.string()),
+    canonicalRereads: taskAuthoringRereadsSchema,
+    workspace: rereadMemberSchema(planningWorkspaceProjectionSchema),
+  })
+  .strict();
+
+export type ApplyTaskAuthoringOutput = z.infer<typeof applyTaskAuthoringOutputSchema>;
+export type TaskAuthoringCommandEvidence = z.infer<typeof taskAuthoringCommandEvidenceSchema>;
+export type TaskAuthoringEffect = z.infer<typeof taskAuthoringEffectSchema>;
+export type TaskAuthoringSync = z.infer<typeof taskAuthoringSyncSchema>;
+export type TaskAuthoringRereads = z.infer<typeof taskAuthoringRereadsSchema>;
+
+/**
+ * Why a request never reached a process. Each reason is a distinct BB refusal
+ * before launch; none of them describes a Build-side failure.
+ */
+export const TASK_AUTHORING_REFUSAL_REASONS = [
+  'invalid-request',
+  'lifecycle-field',
+  'repository-mismatch',
+  'repository-not-ready',
+  'repository-moved',
+  'expected-identity-mismatch',
+  'missing-identity',
+  'archived-identity',
+  'changed-identity',
+  'membership-drift',
+  'task-unavailable',
+  'sprint-unavailable',
+  'description-prepopulation-unavailable',
+  'already-in-flight',
+] as const;
+
+export type TaskAuthoringRefusalReason = (typeof TASK_AUTHORING_REFUSAL_REASONS)[number];
+
+export const taskAuthoringRefusalSchema = z
+  .object({
+    state: z.literal('refused'),
+    reason: z.enum(TASK_AUTHORING_REFUSAL_REASONS),
+    message: z.string().min(1),
+    action: z.enum(TASK_AUTHORING_VOCABULARY).nullable(),
+  })
+  .strict();
+
+/**
+ * A pre-launch refusal and a completed attempt are separate shapes: the former
+ * may be mapped to an RPC error by the registering surface, while the latter
+ * must always be delivered as the outcome envelope.
+ */
+export const taskAuthoringResultSchema = z.discriminatedUnion('state', [
+  taskAuthoringRefusalSchema,
+  z.object({ state: z.literal('completed'), outcome: applyTaskAuthoringOutputSchema }).strict(),
+]);
+
+export type TaskAuthoringRefusal = z.infer<typeof taskAuthoringRefusalSchema>;
+export type TaskAuthoringResult = z.infer<typeof taskAuthoringResultSchema>;
+
+/**
+ * Frozen public RPC method surface for custom task authoring. Registration on
+ * the live contract is owned by the later integration lane; nothing here
+ * registers, mounts, or renders anything.
+ */
+export const applyTaskAuthoringMethod = {
+  input: applyTaskAuthoringInputSchema,
+  output: applyTaskAuthoringOutputSchema,
+} as const;