@patronage/software-factory 1.0.0-alpha.26 → 1.0.0-alpha.28

package/dist/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { PrPublishFollowUpError, run } from "./index.js";
+//#region src/cli.ts
+try {
+	await run(process.argv, import.meta.filename);
+} catch (error) {
+	if (error instanceof PrPublishFollowUpError) console.error(JSON.stringify(error.result, null, 2));
+	else console.error("\nError:", error instanceof Error ? error.message : String(error));
+	process.exit(1);
+}
+//#endregion
+export {};

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { existsSync, readFileSync, rmSync } from "node:fs";
 import { Command } from "commander";
 import { z } from "zod";
+import { existsSync, readFileSync, rmSync } from "node:fs";
 import { PreviewProofRegistration } from "@patronage/factory-ci";
 
 //#region src/review-rungs.d.ts
@@ -1186,6 +1186,58 @@ declare const followUpFromArgv: (argv: string[]) => FollowUpAction;
 /** Canonical zod schema for the optional follow-up field on JSON outputs. */
 declare const FollowUpActionSchema: z.ZodType<FollowUpAction>;
 //#endregion
+//#region src/user-config.d.ts
+declare const githubAppConfigSchema: z.ZodObject<{
+  appId: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+  installationId: z.ZodOptional<z.ZodNumber>;
+  privateKeyPath: z.ZodString;
+}, z.core.$strip>;
+type GithubAppConfig = z.infer<typeof githubAppConfigSchema>;
+declare const factoryUserConfigSchema: z.ZodObject<{
+  githubApp: z.ZodOptional<z.ZodObject<{
+    appId: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    installationId: z.ZodOptional<z.ZodNumber>;
+    privateKeyPath: z.ZodString;
+  }, z.core.$strip>>;
+  hqAllowedOrigins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  hqIngestCredentials: z.ZodOptional<z.ZodObject<{
+    clientIdRef: z.ZodString;
+    clientSecretRef: z.ZodString;
+  }, z.core.$strip>>;
+  schemaVersion: z.ZodLiteral<2>;
+}, z.core.$strip>;
+type FactoryUserConfig = z.infer<typeof factoryUserConfigSchema>;
+interface LoadUserConfigResult {
+  path: string;
+  config: FactoryUserConfig;
+  ignoredKeys?: string[];
+}
+//#endregion
+//#region src/github-app-access.d.ts
+interface FactoryAppAccessDependencies {
+  env?: NodeJS.ProcessEnv;
+  existsSync?: (path: string) => boolean;
+  exchangeBroker?: (input: {
+    fetch?: typeof fetch;
+    oidc: string;
+    owner: string;
+    repo: string;
+    timeoutMs?: number;
+    url?: string;
+  }) => Promise<string>;
+  fetch?: typeof fetch;
+  githubApp?: GithubAppConfig;
+  mintCursorOidc?: (input: {
+    audience?: string;
+    socketPath?: string;
+    timeoutMs?: number;
+  }) => Promise<string>;
+  now?: () => number;
+  timeoutMs?: number;
+  token?: string;
+  transportAttempts?: number;
+}
+//#endregion
 //#region src/pr-verify-mode.d.ts
 /**
  * The verification mode `pr:verify` resolved for a run.
@@ -1222,33 +1274,6 @@ interface PostCommitStatusInput {
 }
 type PostCommitStatus = (input: PostCommitStatusInput) => void;
 //#endregion
-//#region src/user-config.d.ts
-declare const githubAppConfigSchema: z.ZodObject<{
-  appId: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
-  installationId: z.ZodOptional<z.ZodNumber>;
-  privateKeyPath: z.ZodString;
-}, z.core.$strip>;
-type GithubAppConfig = z.infer<typeof githubAppConfigSchema>;
-declare const factoryUserConfigSchema: z.ZodObject<{
-  githubApp: z.ZodOptional<z.ZodObject<{
-    appId: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
-    installationId: z.ZodOptional<z.ZodNumber>;
-    privateKeyPath: z.ZodString;
-  }, z.core.$strip>>;
-  hqAllowedOrigins: z.ZodOptional<z.ZodArray<z.ZodString>>;
-  hqIngestCredentials: z.ZodOptional<z.ZodObject<{
-    clientIdRef: z.ZodString;
-    clientSecretRef: z.ZodString;
-  }, z.core.$strip>>;
-  schemaVersion: z.ZodLiteral<2>;
-}, z.core.$strip>;
-type FactoryUserConfig = z.infer<typeof factoryUserConfigSchema>;
-interface LoadUserConfigResult {
-  path: string;
-  config: FactoryUserConfig;
-  ignoredKeys?: string[];
-}
-//#endregion
 //#region src/github-check-runs.d.ts
 declare const FACTORY_CHECK_NAMES: {
   readonly "pr-ready": "patronage-factory/pr-ready";
@@ -1273,10 +1298,7 @@ interface PublishFactoryCheckInput {
   sha: string;
   status?: "completed" | "in_progress";
 }
-interface CheckRunDependencies {
-  fetch?: typeof fetch;
-  githubApp?: GithubAppConfig;
-  now?: () => number;
+interface CheckRunDependencies extends FactoryAppAccessDependencies {
   postCommitStatus?: PostCommitStatus;
   resolveDetailsUrl?: (input: PublishFactoryCheckInput) => Promise<string> | string;
   /**
@@ -1291,18 +1313,18 @@ interface CheckRunDependencies {
   };
   /** Injectable delay for the bounded retry (tests only). */
   sleep?: (ms: number) => Promise<void>;
-  /** Overrides GITHUB_PUBLISH_TIMEOUT_MS for the App fetch calls (tests only). */
-  timeoutMs?: number;
 }
 /**
  * Publish a factory check run and *wait* for it, so a caller that has just made
  * the head SHA visible on GitHub (pushed the branch, created the PR) can make
  * the proof reliably present for that SHA before it returns (#247).
  *
- * Never throws and never posts a commit-status fallback: the commit status is a
- * human-readable mirror, not a proof surface, so a caller that needs an
- * App-verified check run must be told plainly whether it got one. Returns
- * `true` only when the App-owned check run landed.
+ * Never posts a commit-status fallback: the commit status is a human-readable
+ * mirror, not a proof surface, so a caller that needs an App-verified check
+ * run must be told plainly whether it got one. Returns `true` only when the
+ * App-owned check run landed. Throws when Factory App access is fail-closed
+ * (missing mint or Cursor OIDC exchange, #949): `pr:ready` must not notice
+ * that miss and exit 0. An optional-App skip still returns `false`.
  *
  * "Landed" means GitHub serves it, not that the POST was accepted (#520). On
  * PR #519 the POST was accepted, `pr:ready` reported ready and armed, and the
@@ -1338,8 +1360,8 @@ declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   generationId: z.ZodNumber;
   headSha: z.ZodString;
   outcome: z.ZodEnum<{
-    active: "active";
     stale: "stale";
+    active: "active";
   }>;
   reason: z.ZodString;
   recordedAt: z.ZodISODateTime;
@@ -1586,10 +1608,10 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       reviewedHeadSha: z.ZodOptional<z.ZodString>;
       reviewedPatchId: z.ZodOptional<z.ZodString>;
       status: z.ZodEnum<{
-        stale: "stale";
         "not-required": "not-required";
         blocked: "blocked";
         current: "current";
+        stale: "stale";
         missing: "missing";
       }>;
     }, z.core.$strip>;
@@ -1598,10 +1620,10 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       reviewedHeadSha: z.ZodOptional<z.ZodString>;
       reviewedPatchId: z.ZodOptional<z.ZodString>;
       status: z.ZodEnum<{
-        stale: "stale";
         "not-required": "not-required";
         blocked: "blocked";
         current: "current";
+        stale: "stale";
         missing: "missing";
       }>;
     }, z.core.$strip>>;
@@ -1735,7 +1757,15 @@ interface UpsertFactoryPrStatusCommentResult {
 declare function upsertFactoryPrStatusComment(input: UpsertFactoryPrStatusCommentInput, dependencies?: UpsertFactoryPrStatusCommentDependencies): Promise<UpsertFactoryPrStatusCommentResult>;
 //#endregion
 //#region src/pr-verify-proof-contract.d.ts
-declare const SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS: readonly [1, 2, 3, 4];
+/**
+ * The pr:verify proof versions a reader accepts: the current one only (#920
+ * item 1). #917 narrowed the pr:ready reader the same way. A pr:verify proof
+ * is per-candidate and short-lived — it is rewritten on every head — so no
+ * stored v1–v3 proof can outlive the release that drops it. Pre-1.0 posture
+ * applies: one current contract, no compat reader. A consumer on an older
+ * factory must adopt this release before HQ ingests its pr:verify proofs.
+ */
+declare const SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS: readonly [4];
 type PrVerifySchemaVersion = (typeof SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS)[number];
 interface PrVerifyCommandResult {
   command: string;
@@ -1746,11 +1776,11 @@ interface PrVerifyCommandResult {
    * mapping: a `notRequiredCommands` entry must name the target recorded HERE
    * for the same command, so a withholding cannot point at whichever released
    * target happens to be convenient. Absent for a command the profile does
-   * not scope, and for v1–v3 proofs, which predate the field.
+   * not scope.
    */
   impactTarget?: string;
   name: string;
-  scope: "always" | "docs-only" | "trivial" | "full";
+  scope: "docs-only" | "trivial" | "full";
 }
 interface PrVerifyExecutedCommand {
   command: string;
@@ -1761,7 +1791,7 @@ interface PrVerifyExecutedCommand {
   durationMs: number;
   exitCode: number;
   name: string;
-  scope: "always" | "docs-only" | "trivial" | "full";
+  scope: "docs-only" | "trivial" | "full";
 }
 /**
  * Epic #550 wave 3 (#430): a verification command the impact stamp proved this
@@ -1780,8 +1810,7 @@ interface PrVerifyNotRequiredCommand {
 }
 /**
  * Epic #758 (#762): a consumer package a stamp-scoped selection skipped, and
- * why. Bound to the proof's stamp identity — the field is v4-only (the same
- * window that can carry `impactStamp`) and refused when the proof records no
+ * why. Bound to the proof's stamp identity — refused when the proof records no
  * stamp. The factory does not write this list; consumers do.
  */
 interface PrVerifyNotDemandedRecord {
@@ -1790,7 +1819,7 @@ interface PrVerifyNotDemandedRecord {
 }
 interface PrVerifyProof {
   schemaVersion: PrVerifySchemaVersion;
-  authoringSession?: string;
+  authoringSession: string;
   base: string;
   baselineFullProofs?: {
     base: string;
@@ -1883,7 +1912,7 @@ declare const trustedImpactStamp: ({
 /**
  * #833: the recorded catch-up recognition, consumed ONLY when it is
  * identity-bound to the current candidate under exactly the rules
- * `trustedImpactStamp` applies — the proof passed, is v4+, and its recorded
+ * `trustedImpactStamp` applies — the proof passed, and its recorded
  * headSha AND patchId both name this candidate. The recognition withdraws
  * review and preview demands, so it earns the same strict double binding and
  * the same fail-closed answer (`undefined`) on every other state.
@@ -2438,7 +2467,8 @@ interface PrReadyGitDependencies {
   fetchOriginRef?: (cwd: string, refName: string) => void;
   currentHeadSha: (cwd: string) => string;
   mergeBaseSha: (cwd: string, base: string) => string;
-  objectIdAtRef: (cwd: string, ref: string, absolutePath: string) => string | undefined;
+  /** `repositoryRelativePath` is repository-relative, never cwd-relative. */
+  objectIdAtRef: (cwd: string, ref: string, repositoryRelativePath: string) => string | undefined;
   resolveCommitSha: (cwd: string, ref: string) => string | undefined;
   showFileAtRef: (cwd: string, ref: string, absolutePath: string) => string | undefined;
   stablePatchId: (cwd: string, base: string) => string;
@@ -2608,10 +2638,10 @@ declare const loadEvidenceEnvelopes: (cwd: string) => LoadedEvidenceEnvelope[];
 //#region src/review-proof-applicability.d.ts
 declare const REVIEW_STATUS_VALUES: readonly ["not-required", "current", "stale", "missing", "blocked"];
 declare const reviewStatusSchema: z.ZodEnum<{
-  stale: "stale";
   "not-required": "not-required";
   blocked: "blocked";
   current: "current";
+  stale: "stale";
   missing: "missing";
 }>;
 type ReviewStatus = z.infer<typeof reviewStatusSchema>;
@@ -2901,6 +2931,13 @@ interface PrReviewArgs extends LoadProjectProfileInput {
   assemble?: boolean;
   base: string;
   cycle: number;
+  /**
+   * Issue carrying the factory-boundary manifest, which may be the work issue
+   * itself. `--assemble` uses it to name the review rung the candidate's wave
+   * demands, so the prompt asks for the findings schema the gate accepts
+   * (#1001). It is the same handle `pr:publish` and `pr:ready` take.
+   */
+  epic?: number;
   dispositions?: string;
   findings?: string;
   historical?: boolean;
@@ -2934,7 +2971,22 @@ interface PrReviewDependencies {
    * test can state, never a silent pass.
    */
   basePolicy?: BaseReviewPolicyAuthority;
+  /**
+   * How the wave resolver reads an issue's closing pull requests (#1001).
+   * Injected for the same reason `fetchIssueBody` is: the wave demand must be
+   * statable in a test without a live repository.
+   */
+  fetchClosingPullRequests?: (input: PrReviewIssueBodyInput) => {
+    number: number;
+    state?: "OPEN" | "CLOSED" | "MERGED";
+  }[];
   fetchIssueBody?: (input: PrReviewIssueBodyInput) => string;
+  /**
+   * How `--assemble` reads the pull request whose wave demand names the review
+   * rung (#1001). Defaults to the GitHub lookup, and its result is validated
+   * before use, so an injected stub is held to the same shape.
+   */
+  fetchWavePullRequest?: (cwd: string) => unknown;
   git?: PrReviewGitDependencies;
   hq?: HqIngestDependencies;
   /**
@@ -4409,13 +4461,13 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     reviews: {
       correctness: {
         required: boolean;
-        status: "stale" | "not-required" | "blocked" | "current" | "missing";
+        status: "not-required" | "blocked" | "current" | "stale" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       };
       security?: {
         required: boolean;
-        status: "stale" | "not-required" | "blocked" | "current" | "missing";
+        status: "not-required" | "blocked" | "current" | "stale" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       } | undefined;
@@ -4742,6 +4794,7 @@ interface AssembleReviewPromptInput {
   patchId: string;
   priorLedgerEntries?: FindingLedgerEntry[];
   profile: FactoryProjectProfile;
+  waveRung?: EvidenceReviewRung;
 }
 interface AssembleReviewPromptGitDependencies {
   repositoryRoot: (cwd: string) => string;
@@ -4763,7 +4816,8 @@ declare const assembleReviewPrompt: ({
   kind,
   patchId,
   priorLedgerEntries,
-  profile
+  profile,
+  waveRung
 }: AssembleReviewPromptInput, dependencies?: AssembleReviewPromptDependencies) => AssembledReviewPrompt;
 //#endregion
 //#region src/review-ladder-trace.d.ts
@@ -4949,6 +5003,12 @@ interface CreateProgramOptions {
   output?: CliOutput;
 }
 declare function createProgram(options?: CreateProgramOptions): Command;
-declare function run(argv?: string[]): Promise<void>;
+/**
+ * Parse `argv` and run the matching command. `cliEntry` is the path of the
+ * runnable bin module, which follow-up commands spawn; the bin entry passes its
+ * own path. This function never runs itself — `./cli.js` is the only caller
+ * that does (#386).
+ */
+declare function run(argv?: string[], cliEntry?: string): Promise<void>;
 //#endregion
 export { type AppendFactoryTraceEventResult, type AssembledReviewPrompt, type BatteryCommandDisposition, type BatteryDisposition, type BoundaryCheckArgs, type BoundaryCheckDependencies, type BoundaryCheckProofRecord, type BuildEpicStructureEventInput, type CloudflareAccessServiceToken, type CompletedFactoryCheckSnapshot, CreateProgramOptions, DEFAULT_DEMAND_WAIVER_PATH, DEFAULT_FACTORY_REPOSITORY, DEFAULT_ROOT_SHARED_GLOBS, type DagDocument, type DemandWaiveArgs, type DemandWaiveDependencies, DemandWaiveRefusalError, type DemandWaiver, type DemandWaiverStore, EMPTY_TREE_OBJECT_HASH, EPIC_STRUCTURE_NODE_STATUSES, EPIC_STRUCTURE_SCHEMA_VERSION, type EpicStructureEvent, type EpicStructureGraphPayload, type EpicStructureNodeStatus, EpicStructureValidationError, type EvidenceEmitArgs, type EvidenceEmitDependencies, type EvidenceEmitResult, FACTORY_BASE_REF_ENV, FACTORY_CHANGED_FILES_ENV, FACTORY_CHANGED_FILES_FILE_ENV, type FactoryCliInvocation, FactoryCliInvocationSchema, type FactoryPrStatusCheckName, type FactoryPrStatusSources, type FactoryProjectProfile, type FactoryTraceDiagnostic, type FactoryTraceEnvelope, type FactoryTraceEvent, type FindingDisposition, type FindingLedgerEntry, type FollowUpAction, FollowUpActionSchema, type GitHubCheckRunMergeFreezeApi, type ImpactScopeDecision, type ImpactScopeSurface, type IssueReviewFocus, type LadderDispositionDeclaration, MERGE_FREEZE_APP_SLUG, MERGE_FREEZE_CHECK_NAME, type MergeFreezeAuthority, type MergeFreezeGeneration, type MergeFreezeState, type MergeFreezeStoreInput, type PlanFactoryPrStatusHudInput, type PrPublishArgs, type PrPublishDependencies, PrPublishFollowUpError, type PrPublishFollowUpOutcome, type PrPublishHandoff, type PrPublishResult, type PrReadyArgs, type PrReadyProof, type PresentFactoryPrStatusHudDependencies, type PresentFactoryPrStatusHudInput, type PreviewDisposition, type PreviewLifecyclePlan, type PreviewTargetPlan, type PublishEpicStructureArgs, type PublishEpicStructureResult, type PublishFollowUpPlan, REVIEW_FOCUS_SECTION, type ReadFactoryPrStatusSourcesDependencies, type ReadFactoryPrStatusSourcesInput, type RefreshFactoryPrStatusHudInput, type RenderFactoryPrStatusHudInput, type ReviewGateNotRequiredProof, type ReviewGateTraceIdentity, type ReviewLadderCycle, type ReviewLadderEvaluation, type ReviewLadderPolicy, type ReviewLadderStageEvent, type ReviewLadderTraceIdentity, type ReviewPromptSection, type ReviewPromptSectionProvenance, type ScanFactoryTraceDiagnosticsOptions, type ScanFactoryTraceOptions, type ScanFactoryTraceResult, type ScopedOutCommand, type TraceMirrorDiagnostic, type TraceSink, type TraceWriteResult, type TraceWriteSinks, type VerificationBatteryPlan, type VerificationReuse, type VerificationRunContext, type VerificationRunContextInput, type WaivedDemand, WorkerCheckoutGuardError, type WorkerCloseoutLessonsTraceEvent, appendReviewLadderStageTraceEvent, appendWithTraceSinks, applyDemandWaiver, assembleReviewPrompt, assertFactoryPrStatusIdentity, assertWorkerCheckoutAllowed, authorizeDemandWaiver, batteryScopeSummaryLines, blockingLadderFindings, boundary_manifest_d_exports as boundaryManifest, boundary_review_proof_d_exports as boundaryReviewProof, buildEpicStructureEvent, buildEpicStructurePayload, buildEvidenceEnvelope, buildReviewGateNotRequiredTraceEvent, buildReviewLadderStageTraceEvent, comment_provenance_d_exports as commentProvenance, createGitHubCheckRunMergeFreezeStore, createLocalJsonlTraceSink, createProgram, createVerificationRunContext, doctorProjectProfile, epicStructureEventId, evaluateReviewLadder, evidenceEnvelopeFilename, findingKey, followUpFromArgv, impactStampScopeDecision, inferFixedInThreadDispositions, isProductionHqUrl, loadProjectProfile, normalizeIssueComments, openLadderFindings, planFactoryPrStatusHud, planPreviewLifecycle, planPublishFollowUp, planVerificationBattery, readiness_evaluation_d_exports as prReadinessEvaluation, external_evidence_d_exports as prReadinessExternalEvidence, pr_body_renderer_d_exports as prReadinessPrBodyRenderer, proof_identity_d_exports as prReadinessProofIdentity, review_proof_d_exports as prReadinessReviewProof, status_check_rollup_d_exports as prReadinessStatusChecks, verification_proof_d_exports as prReadinessVerificationProof, presentFactoryPrStatusHud, previewLifecycleTargets, publishEpicStructure, readDemandWaivers, readFactoryPrStatusSources, readPrReadyProof, readPrReviewProof, refreshFactoryPrStatusHud, refreshFactoryPrStatusHudSafely, renderFactoryPrStatusHud, resolveFactoryRepository, resolveFindingBlocking, resolveReviewFindingCategory, resolveReviewFindingSeverity, resolveReviewLadderPolicy, resolveTraceWriteSinks, reviewCycleStateFor, reviewFocusFromIssueBody, reviewPromptSectionSchema, reviewPromptSectionsSchema, run, runBoundaryCheck, runDemandWaive, runEvidenceEmit, runPrPublish, runPrReady, runPrReview, runPrVerify, scanFactoryTraceDiagnostics, scanFactoryTraceEvents, selectWaiversForCandidate, staleRepeatLadderFindings, toFactoryTraceEnvelope, tryAppendReviewGateNotRequiredTraceEvent, tryAppendReviewLadderStageTraceEvent, validateBoundaryCheckProof, validateDagDocument, validateDemandWaiverStore, validateFactoryTraceEvent, validateMergeFreezeState, validatePrReadyProof, validatePrReviewProof, validatePrVerifyProof, validatePreviewLifecyclePlan, waivedDemandNotice, waivedDemandSchema, worktree_scratch_files_d_exports as worktreeScratchFiles };