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

package/src/github-app-token.ts

@@ -57,6 +57,20 @@ export class GitHubApiError extends Error {
   }
 }
 
+/**
+ * Installation-token permission subset. GitHub only grants permissions the
+ * App already has; a caller that wants least privilege names the subset here
+ * rather than taking the App's full installation grant (#949).
+ */
+export interface GithubAppInstallationPermissions {
+  checks?: "read" | "write";
+}
+
+/** The Factory App broker's token: repo-scoped Checks write, nothing else. */
+export const FACTORY_APP_BROKER_TOKEN_PERMISSIONS = {
+  checks: "write",
+} as const satisfies GithubAppInstallationPermissions;
+
 export interface GithubAppTokenOptions {
   /** Injectable `fetch` (tests, or a caller with its own instrumented one). */
   fetch?: typeof fetch;
@@ -115,11 +129,12 @@ const githubAppJson = (
   url: string,
   jwt: string,
   method: "GET" | "POST",
-  budget: { attempts?: number; timeoutMs: number }
+  budget: { attempts?: number; body?: string; timeoutMs: number }
 ): Promise<Record<string, unknown>> =>
   githubJson(
     {
       attempts: budget.attempts,
+      ...(budget.body === undefined ? {} : { body: budget.body }),
       closeConnection: true,
       fetch: request,
       method,
@@ -157,6 +172,18 @@ export const mintInstallationToken = async (
   input: {
     credentials: GithubAppCredentials;
     owner: string;
+    /**
+     * Installation permission subset. Omitted, GitHub grants the App's full
+     * installation permissions. The Factory App broker passes
+     * {@link FACTORY_APP_BROKER_TOKEN_PERMISSIONS}.
+     */
+    permissions?: GithubAppInstallationPermissions;
+    /**
+     * Repository names (not `owner/repo`) to bind the token to. Omitted, the
+     * token covers every repository the installation can reach. The broker
+     * always names the one repository the Cursor OIDC claim authenticated.
+     */
+    repositories?: readonly string[];
     repo: string;
   },
   options: GithubAppTokenOptions = {}
@@ -184,12 +211,23 @@ export const mintInstallationToken = async (
     installationId = installation.id;
   }
 
+  const restriction =
+    input.permissions === undefined && input.repositories === undefined
+      ? undefined
+      : JSON.stringify({
+          ...(input.permissions === undefined
+            ? {}
+            : { permissions: input.permissions }),
+          ...(input.repositories === undefined
+            ? {}
+            : { repositories: [...input.repositories] }),
+        });
   const minted = await githubAppJson(
     request,
     `https://api.github.com/app/installations/${installationId}/access_tokens`,
     jwt,
     "POST",
-    budget
+    restriction === undefined ? budget : { ...budget, body: restriction }
   );
   if (typeof minted.token !== "string") {
     throw new TypeError("GitHub App token response omitted token");

package/src/index.ts

@@ -71,9 +71,19 @@ export {
   type WorkflowStep,
 } from "./factory-workflow.ts";
 export {
+  FACTORY_CURSOR_OIDC_AUDIENCE,
+  FACTORY_CURSOR_OIDC_ISSUER,
+  FACTORY_CURSOR_OIDC_JWKS_URL,
+  FACTORY_CURSOR_OIDC_MANAGED_RUNTIME,
+  FACTORY_APP_BROKER_ORIGIN,
+  FACTORY_APP_BROKER_PATH,
+} from "./cursor-oidc.ts";
+export {
+  FACTORY_APP_BROKER_TOKEN_PERMISSIONS,
   GitHubApiError,
   GitHubAppTokenTransportError,
   type GithubAppCredentials,
+  type GithubAppInstallationPermissions,
   githubAppJwt,
   type GithubAppTokenOptions,
   mintInstallationToken,
@@ -92,7 +102,6 @@ export {
   FACTORY_PROOF_GATE_IF,
   FACTORY_PROOF_GATE_MODE_OUTPUT,
   FACTORY_PROOF_GATE_OUTPUT,
-  FACTORY_PROOF_GATE_PULL_REQUEST_IF,
   FACTORY_PROOF_GATE_REASON_OUTPUT,
   FACTORY_PROOF_GATE_REASONS,
   FACTORY_PROOF_GATE_SHELL,
@@ -101,7 +110,6 @@ export {
   FACTORY_PROOF_GATE_STEP_NAME,
   type FactoryProofGateOptions,
   type FactoryProofGateReason,
-  type FactoryProofGateReuse,
   factoryProofGateScript,
   type FactoryProofGateStep,
   factoryProofGateStep,

package/src/pr-status-hud-workflow.ts

@@ -3,6 +3,7 @@ import type { WorkflowStep } from "./factory-workflow.ts";
 import { assertPinnedAction } from "./pinned-action.ts";
 import { PREVIEW_PROOF_INVENTORY_LIST_PERMISSIONS } from "./preview-proof-inventory.ts";
 import { FACTORY_PROOF_GATE_APP_ID } from "./proof-reuse-gate.ts";
+import { assertRunnableCli } from "./runnable-cli.ts";
 
 export const FACTORY_PR_STATUS_HUD_JOB_ID = "status-hud";
 export const FACTORY_PR_STATUS_HUD_JOB_NAME = "Present PR status HUD";
@@ -56,6 +57,7 @@ export const factoryPrStatusHudWorkflow = (
     "actions/create-github-app-token"
   );
   const cli = options.cli || defaultCli;
+  assertRunnableCli("cli", cli);
   // Same unscoped mint as the freeze job. A subset (checks/issues/PRs)
   // 422s: those permissions are not granted to this installation.
   const mintStep: WorkflowStep = Object.freeze({

package/src/production-impact-workflow.ts

@@ -1,5 +1,6 @@
 import type { WorkflowStep } from "./factory-workflow.ts";
 import { impactDemandConditions } from "./impact-demand-condition.ts";
+import { assertRunnableCli } from "./runnable-cli.ts";
 
 export const FACTORY_PRODUCTION_IMPACT_STEP_ID = "production_impact";
 export const FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT = "decision";
@@ -71,6 +72,7 @@ export const factoryProductionImpactWorkflow = (
   const before = options.before ?? `\${{ github.event.before }}`;
   const after = options.after ?? `\${{ github.sha }}`;
   const cli = options.cli ?? "pnpm exec psf";
+  assertRunnableCli("cli", cli);
   const profile = options.profilePath
     ? ` --profile ${shellQuote(options.profilePath)}`
     : "";

package/src/proof-reuse-gate.ts

@@ -3,13 +3,9 @@
  *
  * It answers one question, before checkout and before install: may this job
  * reuse the local verification the factory already published for *this exact
- * head*? By default it asks that only on a pull request, so every
- * default-branch push executes the full hosted suite (#863). A consumer may
- * opt into `reuse: "pull-request-and-default-branch"`, where one fallback
- * extends "this exact head" to "this exact tree": a squash merge whose result
- * tree is byte-identical to the producing pull request's proven head tree
- * reuses that head's proof (#611). Refusing runs hosted CI; it never fails
- * the candidate. Three
+ * head*? It asks that only on a pull request, so every default-branch push
+ * executes the full hosted suite (#863). Refusing runs hosted CI; it never
+ * fails the candidate. Three
  * repositories had independently grown their own answer to that question and
  * had already drifted apart, so the answer lives here once, with the App
  * identity, check name, step identity, output names, guard, and every trust
@@ -123,77 +119,25 @@ export const FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT = "source-check-url";
 export const FACTORY_PROOF_GATE_GUARD = `steps.${FACTORY_PROOF_GATE_STEP_ID}.outputs.${FACTORY_PROOF_GATE_OUTPUT} != 'true'`;
 
 /**
- * Pull requests, plus pushes to the merge target (#611) — the **opt-out**
- * condition a consumer gets with `reuse: "pull-request-and-default-branch"`.
- *
- * It buys runner time on the merge target and pays for it in coverage. No
- * local proof is ever written for a merged SHA, so the direct read finds
- * nothing after a squash merge. The push path therefore exists only together
- * with the merge fallback below: when no generation exists at the merged SHA,
- * the gate may look up the producing pull request and reuse its head proof,
- * but only when the merge result's tree is exactly the proven head's tree.
- * Deploy gates keep waiting for a green required check at the merged SHA; a
- * reused proof turns that check green through the same guarded steps a pull
- * request uses.
- *
- * The trade this mode accepts: a candidate's proof may be impact-scoped, and
- * an impact-scoped proof is a sound gate for the candidate and an unsound
- * gate for the merge target. #931 is that defect observed — a `main` push
- * reused a candidate proof, executed no command, and left a red package
- * unnoticed for three days. Choose this mode only when the consumer accepts
- * that risk for speed.
- *
- * The push side is deliberately the merge target only — the repository's
- * default branch — not every pushed branch. Which branches trigger a
- * consumer's workflow at all stays repository-owned; this condition only
- * keeps the gate from consulting proof on pushes that are not merges into
- * the default branch.
- */
-export const FACTORY_PROOF_GATE_IF =
-  "github.event_name == 'pull_request' || (github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch))";
-
-/**
- * Pull requests only — the **default** condition, and the condition a
- * consumer gets with `reuse: "pull-request"` (#873, default since #863).
+ * Pull requests only — the gate's single condition (#873, default since #863,
+ * the only mode since the merge-target opt-out was deleted).
  *
  * A merge target's guarantee is about the whole tree, not the diff. A
  * candidate proof only ever binds the diff the candidate was scoped to, so
  * reusing it on the merged commit proves less than the merge target needs.
- * Every default-branch push therefore executes the full hosted suite,
- * whatever proof exists. The mode also skips the push-event merge fallback,
- * so no push path can reuse proof even if the workflow reaches the step
- * through some other trigger.
+ * #931 is that defect observed — a `main` push reused a candidate proof,
+ * executed no command, and left a red package unnoticed for three days. Every
+ * default-branch push therefore executes the full hosted suite, whatever
+ * proof exists.
  *
  * Which branches trigger the workflow at all stays repository-owned. This
  * condition only keeps the gate from consulting proof outside a pull request.
  */
-export const FACTORY_PROOF_GATE_PULL_REQUEST_IF =
-  "github.event_name == 'pull_request'";
-
-/**
- * Which events may reuse proof.
- *
- * A two-value enum, not a free-text condition: a string lets a consumer write
- * a condition this package cannot reason about — one that reuses proof on an
- * unproven ref — and the emitted condition is a trust predicate. The consumer
- * chooses the mode; `factory-ci` owns what each mode emits.
- *
- * - `pull-request` (default) pull requests only. Default-branch pushes
- *   execute the full hosted suite, and the merge fallback is not emitted.
- * - `pull-request-and-default-branch` the opt-out: pull requests plus pushes
- *   to the merge target, with the merge fallback. It is faster on the merge
- *   target and it lets an impact-scoped candidate proof gate a whole tree
- *   (#931), so a consumer must ask for it.
- */
-export type FactoryProofGateReuse =
-  | "pull-request"
-  | "pull-request-and-default-branch";
+export const FACTORY_PROOF_GATE_IF = "github.event_name == 'pull_request'";
 
 /**
  * The complete refusal vocabulary. Deliberately few, because these are the
  * only distinctions the gate can honestly make from its Checks API reads.
- * The merge fallback adds no words: a fallback that establishes nothing
- * leaves the direct read's refusal standing, with the specifics in `detail`.
  *
  * - `proven`     a covering, passing, unambiguous proof for this exact head
  * - `none`       no App-verified factory check run at this commit
@@ -537,109 +481,7 @@ const safeLabel = (surface: string): string => {
   return cleaned.length > 0 ? cleaned : "verification";
 };
 
-/**
- * The push-event merge fallback (#611), emitted only for
- * `reuse: "pull-request-and-default-branch"`. The default `"pull-request"`
- * mode omits it: that mode's whole point is that a default-branch push
- * executes everything, so a push path that could still reuse proof would
- * contradict the condition above it.
- */
-const MERGE_FALLBACK_BLOCK = String.raw`# Merge fallback (#611). A squash merge mints a new commit, so the direct
-# read at a pushed merge-target head finds nothing even when the factory
-# proved the producing pull request head. Only when the direct read found no
-# generation at all on a push event, look up the producing pull request and
-# reuse its head proof — and only when the merge commit's TREE id equals the
-# proven head's tree id, which makes the pushed content byte-identical to
-# what was verified (a clean squash of an unchanged tip). Patch identity was
-# considered and rejected as the comparator: git patch-id normalizes
-# whitespace and ignores base motion, so an identical patch can still
-# produce an integrated tree that was never tested. Everything else — no
-# unique merged producing PR, an unreadable commit, a proof that is anything
-# but proven, or tree drift from a dirty or stale merge — leaves the direct
-# "none" refusal standing, so the full suite runs (fail open).
-if [ "$reason" = 'none' ] && [ "${shellExpansion("GITHUB_EVENT_NAME:-")}" = 'push' ]; then
-  producing_head=''
-  merge_tree=''
-  head_tree=''
-  if ! producing_pulls=$(gh api --method GET --paginate \
-      "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA/pulls" \
-      -f per_page=100 2>&1); then
-    detail="producing pull request unreadable: $producing_pulls"
-  elif ! producing_head=$(printf '%s' "$producing_pulls" | jq -r -s \
-      --arg sha "$HEAD_SHA" \
-      '[ add[]?
-         | select((.merged_at // null) != null)
-         | select((.merge_commit_sha // "") == $sha)
-         | ((.head.sha // "") | tostring) ]
-       | if length == 1 then .[0] else "" end' 2>&1); then
-    detail="producing pull request unreadable: $producing_head"
-    producing_head=''
-  elif ! [[ "$producing_head" =~ ^[0-9a-f]{40}$ ]]; then
-    detail='no single merged producing pull request at this commit'
-    producing_head=''
-  elif ! merge_commit=$(gh api --method GET \
-      "repos/$GITHUB_REPOSITORY/commits/$HEAD_SHA" 2>&1); then
-    detail="merge commit unreadable: $merge_commit"
-  elif ! merge_tree=$(printf '%s' "$merge_commit" | jq -r \
-      '(.commit.tree.sha // "") | tostring' 2>&1); then
-    detail="merge commit unreadable: $merge_tree"
-    merge_tree=''
-  elif ! [[ "$merge_tree" =~ ^[0-9a-f]{40}$ ]]; then
-    detail='merge commit carries no readable tree id'
-    merge_tree=''
-  elif ! head_commit=$(gh api --method GET \
-      "repos/$GITHUB_REPOSITORY/commits/$producing_head" 2>&1); then
-    detail="producing head commit unreadable: $head_commit"
-  elif ! head_tree=$(printf '%s' "$head_commit" | jq -r \
-      '(.commit.tree.sha // "") | tostring' 2>&1); then
-    detail="producing head commit unreadable: $head_tree"
-    head_tree=''
-  elif ! [[ "$head_tree" =~ ^[0-9a-f]{40}$ ]]; then
-    detail='producing head commit carries no readable tree id'
-    head_tree=''
-  elif [ "$merge_tree" != "$head_tree" ]; then
-    detail='tree drift: the merge result is not the proven head tree'
-    merge_tree=''
-  fi
-  if [[ "$producing_head" =~ ^[0-9a-f]{40}$ ]] \
-      && [[ "$merge_tree" =~ ^[0-9a-f]{40}$ ]] \
-      && [ "$merge_tree" = "$head_tree" ]; then
-    gate_lookup "$producing_head"
-    if [ "$lookup_reason" = 'proven' ]; then
-      reason=proven
-      mode="$lookup_mode"
-      missing=''
-      source_url="$lookup_url"
-      proof_head="$producing_head"
-      merge_note="the merge result's tree is byte-identical to the tree proven at pull request head $producing_head"
-    else
-      detail="producing pull request proof not reusable ($lookup_reason)"
-    fi
-  fi
-fi`;
-
-/**
- * The fallback with the blank lines that surround it, or nothing at all. Kept
- * as one piece so `pull-request-and-default-branch` emits the exact script
- * that mode emitted before the option existed.
- *
- * Tests for the opt-out value, matching `factoryProofGateStep`'s condition
- * ternary. The polarity is the point: the condition and the script are two
- * halves of one decision, so an unrecognized value — an untyped JavaScript
- * consumer's typo — must resolve to the safe default at both sites. Testing
- * for `"pull-request"` here would pair the PR-only condition with a script
- * that still carries the fallback, a combination no mode means.
- */
-const mergeFallbackSection = (reuse: FactoryProofGateReuse): string =>
-  reuse === "pull-request-and-default-branch"
-    ? `\n${MERGE_FALLBACK_BLOCK}\n\n`
-    : "\n";
-
-const gateScript = (
-  required: readonly string[],
-  surface: string,
-  reuse: FactoryProofGateReuse
-): string =>
+const gateScript = (required: readonly string[], surface: string): string =>
   String.raw`
 set -uo pipefail
 
@@ -653,8 +495,6 @@ detail=''
 mode=''
 missing=''
 source_url=''
-proof_head="${shellExpansion("HEAD_SHA:-")}"
-merge_note=''
 
 # One proof lookup at one commit. Sets lookup_reason / lookup_mode /
 # lookup_missing / lookup_url, or lookup_detail when the read itself
@@ -727,7 +567,8 @@ else
   missing="$lookup_missing"
   source_url="$lookup_url"
 fi
-${mergeFallbackSection(reuse)}# The binding is App-verified, but it still reaches markdown. Only a plain
+
+# The binding is App-verified, but it still reaches markdown. Only a plain
 # lowercase token is quoted back; anything else is reported as unknown.
 case "$mode" in
   '') ;;
@@ -755,7 +596,7 @@ say ''
 
 case "$reason" in
   proven)
-    echo "Factory proof: reusing local verification of $proof_head; skipping the $SURFACE suite."
+    echo "Factory proof: reusing local verification of $HEAD_SHA; skipping the $SURFACE suite."
     say "Skipped. The factory already verified this exact content, so this job did not run the $SURFACE suite a second time."
     say ''
     if [ -n "$source_url" ]; then
@@ -763,20 +604,13 @@ case "$reason" in
     else
       say "- Reused proof: the \`$CHECK_NAME\` check run published by the pinned factory GitHub App."
     fi
-    say "- Covers head: \`$proof_head\`"
-    if [ -n "$merge_note" ]; then
-      say "- Merge-target reuse: $merge_note."
-    fi
+    say "- Covers head: \`$HEAD_SHA\`"
     say "- Recorded mode: \`$mode\` (diagnostic only), outcome \`passed\`."
     ;;
   none)
     say 'Ran the full suite. No trusted factory proof covers this commit.'
     say ''
     say "The factory GitHub App has published no \`$CHECK_NAME\` check run at head \`$HEAD_SHA\`. Proof is keyed to the commit, so proof written for any other commit is not visible here. A pull request opened by hand carries no factory proof at all, which is normal."
-    if [ -n "$detail" ]; then
-      say ''
-      say "- Merge fallback: $detail"
-    fi
     say ''
     say '${CORRECTIVE_LINE}'
     ;;
@@ -846,13 +680,6 @@ export interface FactoryProofGateOptions {
    * therefore requires a different coverage.
    */
   readonly commands: readonly ProofReuseCommand[];
-  /**
-   * Which events may reuse proof. Defaults to `"pull-request"`: every
-   * default-branch push executes the full hosted suite (#873, #863).
-   * `"pull-request-and-default-branch"` is the opt-out a consumer chooses for
-   * speed on the merge target, and it accepts #931's risk.
-   */
-  readonly reuse?: FactoryProofGateReuse;
   /** Names the suite in the job summary. Changes no trust decision. */
   readonly surface: string;
 }
@@ -871,12 +698,11 @@ export interface FactoryProofGateOptions {
  */
 export const factoryProofGateScript = ({
   commands,
-  reuse = "pull-request",
   surface,
 }: FactoryProofGateOptions): string => {
   const required = proofReuseRequiredCommands(commands);
   return required
-    ? gateScript(required, safeLabel(surface), reuse)
+    ? gateScript(required, safeLabel(surface))
     : UNUSABLE_SELECTION_SCRIPT;
 };
 
@@ -887,9 +713,7 @@ export interface FactoryProofGateStep {
     HEAD_SHA: string;
   }>;
   readonly id: typeof FACTORY_PROOF_GATE_STEP_ID;
-  readonly if:
-    | typeof FACTORY_PROOF_GATE_IF
-    | typeof FACTORY_PROOF_GATE_PULL_REQUEST_IF;
+  readonly if: typeof FACTORY_PROOF_GATE_IF;
   readonly name: string;
   readonly run: string;
   readonly shell: typeof FACTORY_PROOF_GATE_SHELL;
@@ -899,14 +723,8 @@ export interface FactoryProofGateStep {
  * The step itself, structurally accepted by gagen's `step()` without adding a
  * gagen runtime dependency. It belongs first in the job it guards: a few API
  * reads with the default `GITHUB_TOKEN`, no checkout, no install, so a proven
- * head costs a runner nothing beyond job startup. The default
- * `reuse: "pull-request"` emits neither the push clause nor the fallback, and
- * needs only `checks: read` (#873, #863). A consumer that opts into
- * `reuse: "pull-request-and-default-branch"` also runs the push-event merge
- * fallback, which reads the producing pull request (`pull-requests: read`)
- * and the two commit objects whose tree ids it compares (`contents: read`).
- * A job that grants less loses only the fallback — the failed read degrades
- * to the full suite.
+ * head costs a runner nothing beyond job startup. The step runs on pull
+ * requests only, so it needs only `checks: read` (#873, #863).
  *
  * A **step, not a job**, and that is not a style preference. A separate gate
  * job that errored would leave the guarded job `skipped`, and a summary job
@@ -922,23 +740,15 @@ export const factoryProofGateStep = (
     continueOnError: true as const,
     env: Object.freeze({
       GH_TOKEN: githubExpression("secrets.GITHUB_TOKEN"),
-      // On a pull request the verified head is the PR branch tip; on a push
-      // there is no pull_request payload and `github.sha` is the pushed head,
-      // which is what a 'pull-request-and-default-branch' consumer's merge
-      // fallback resolves from (#611). Under the PR-only default the step does
-      // not run on a push, so only the pull-request half is ever read.
+      // On a pull request the verified head is the PR branch tip. The step
+      // never runs on a push, so no reachable path reads the `github.sha`
+      // half.
       HEAD_SHA: githubExpression(
         "github.event.pull_request.head.sha || github.sha"
       ),
     }),
     id: FACTORY_PROOF_GATE_STEP_ID,
-    // The absent option is the PR-only default, so the opt-out is the value
-    // this ternary tests for. Testing for `"pull-request"` instead would
-    // leave `undefined` on the push clause and silently keep the old default.
-    if:
-      options.reuse === "pull-request-and-default-branch"
-        ? FACTORY_PROOF_GATE_IF
-        : FACTORY_PROOF_GATE_PULL_REQUEST_IF,
+    if: FACTORY_PROOF_GATE_IF,
     name: FACTORY_PROOF_GATE_STEP_NAME,
     run: factoryProofGateScript(options),
     // Never omit: the runner's default `run:` shell supplies `-e`, which

package/src/proof-reuse-presentation.ts

@@ -61,10 +61,8 @@ say ''
 
 if [ "${shellExpansion("GITHUB_EVENT_NAME:-")}" = 'push' ] && [ -z "${shellExpansion("PROOF_REASON:-")}" ]; then
   # A push run with no recorded reason is one where the gate step's condition
-  # kept it off entirely, so the full suite ran with no reuse decision. Under
-  # the PR-only reuse default (#863) that is every push. A consumer on
-  # 'pull-request-and-default-branch' reaches it only on a ref outside its
-  # merge target.
+  # kept it off entirely, so the full suite ran with no reuse decision. The
+  # gate runs on pull requests only (#863), so that is every push.
   say '- Path: full execution, no proof consulted'
   say '- Proof-reuse gate: did not run on this ref; the full suite ran.'
   say "- Verified head: \`${shellExpansion("GITHUB_SHA:-unknown")}\`"
@@ -109,10 +107,8 @@ export const factoryProofReuseSummaryStep = (
       CI_STARTED_MS: githubExpression(
         `steps.${FACTORY_PROOF_TIMING_STEP_ID}.outputs.started_ms`
       ),
-      // PR runs bind to the PR branch tip; push runs to the pushed head, which
-      // is the head a 'pull-request-and-default-branch' consumer's merge
-      // fallback resolves from (#611). Under the PR-only default no push run
-      // records a reason, and this value only labels the summary.
+      // PR runs bind to the PR branch tip; push runs to the pushed head. No
+      // push run records a reason, and this value only labels the summary.
       PROOF_HEAD_SHA: githubExpression(
         "github.event.pull_request.head.sha || github.sha"
       ),

package/src/runnable-cli.ts

@@ -0,0 +1,27 @@
+/**
+ * `@patronage/software-factory` publishes two dist entries. `dist/index.js` is
+ * the package export: consumers import it, so it runs no command. `dist/cli.js`
+ * is the bin, and it is the only entry that runs one (software-factory#386).
+ *
+ * A workflow step that invokes `dist/index.js` therefore loads a library and
+ * exits 0 — a green step that did nothing. This guard makes a generator refuse
+ * that `cli` at generation time, where the failure is loud, instead of letting
+ * it reach CI where the failure is silent. Invoke the bin by name (`psf`,
+ * `pnpm exec psf`, `pnpm dlx psf`) or by the `dist/cli.js` path.
+ */
+
+// A token match, not a shell parser. The terminator admits the quote
+// characters as well as whitespace, so `node "…/dist/index.js"` and the
+// single-quoted form are caught too. It stays deliberately short of parsing
+// the command: a `cli` string that hides the path from this scan is out of
+// scope for a text guard.
+const INERT_ENTRY_PATTERN = /(?:^|[/\\])dist[/\\]index\.js(?:["'\s]|$)/u;
+
+/** Shared validator for every `cli` string a factory-ci generator emits. */
+export const assertRunnableCli = (name: string, cli: string): void => {
+  if (INERT_ENTRY_PATTERN.test(cli)) {
+    throw new Error(
+      `${name} must invoke the software-factory bin, not the package entry dist/index.js, which imports as a library and exits 0 without running the command. Use the bin name (for example "pnpm exec psf") or dist/cli.js. Got "${cli}".`
+    );
+  }
+};