@patronage/factory-ci 0.2.0 → 1.0.0-alpha.4

package/README.md

@@ -59,6 +59,30 @@ workflow({/* caller-owned jobs and topology */}).writeOrLint({
 
 The **runner is not this package's business**. Jobs, runners, permissions, workflow topology, and deploy policy remain with the caller. The returned values are plain structural objects; this package does not depend on gagen.
 
+### Generated shell
+
+```ts
+import { assertWorkflowShellParses } from "@patronage/factory-ci";
+
+const generated = workflow({/* jobs */});
+
+assertWorkflowShellParses(generated.toYamlString(), {
+  source: ".github/workflows/verify.ts",
+});
+
+generated.writeOrLint({ filePath, ...workflowArtifact.writeOptions });
+```
+
+A generated-workflow lint validates YAML shape. It does not parse the shell inside a `run:` block, so a script that cannot execute at all — a stray `fi`, an unclosed quote — passes every local check and only fails when the runner reaches it. paitronage#1090 shipped exactly that and made every automated preview destroy a parse-time no-op for five days.
+
+`assertWorkflowShellParses` extracts each `run:` block from the emitted YAML, neutralizes `${{ }}` expressions (they are substituted before bash sees the script), and parses it with the interpreter the runner would use — `bash -n`, or `sh -n` for a step declaring `sh`, whose grammar is narrower. The interpreter is resolved the way GitHub resolves it: the step's `shell:`, then the job's `defaults.run.shell`, then the workflow's, then bash. `shell:` is a command template, so `bash`, `/bin/sh {0}`, `env FOO=bar bash {0}` and `bash -O extglob {0}` all resolve — options included, since they change the grammar. It throws naming the source and the step.
+
+Steps resolving to pwsh, powershell, python, or cmd are left alone. Any other command is refused with an error rather than skipped, so an interpreter this control has not considered cannot pass for a checked one.
+
+`workflowShellParseFailures` returns the same findings without throwing, for a caller that wants to report rather than fail.
+
+Two scalar forms are refused outright rather than guessed at, because for both of them the text on the page is not the script the runner gets: a folded `run: >` block (YAML folds its line breaks into spaces) and a double-quoted `run: "..."` scalar (its YAML escapes would have to be decoded first). Neither is emitted by any generator in this fleet; a literal `run: |` block always is.
+
 ### Proof reuse
 
 ```ts
@@ -89,11 +113,13 @@ A proof is reusable only when the complete Checks API result (`filter=all`, ever
 
 The only thing a consumer chooses is **what its surface requires**, expressed as the plain profile command objects that surface selects — a repository with distinct core and docs jobs selects distinct sets and gets distinct required coverage. `proofReuseRequiredCommands()` is the single derivation both the gate and the assertion go through. Identities are baked into the emitted script, so they are held to a plain `[A-Za-z0-9_][\w.:@/-]*` allow-list and shell-quoted at the interpolation site; a selection carrying anything else is unusable and degrades to a gate that always refuses.
 
+Command names are executable authorization identities, not display labels. They must be unique in the profile; `factory-ci` also refuses a selected set with duplicates so two command strings can never collapse behind one proof identity.
+
 The gate is a **step, not a job**, marked `continue-on-error`, with no `set -e`. A gate job that errored would leave the guarded job `skipped`, which a summary job that only fails on `failure` / `cancelled` reports as green. As a step it fails open by construction: the step errors, the output is never written, the `!= 'true'` guard reads empty, and every command runs. It writes a machine-readable `reason` output — `proven | none | pending | failed | unreadable | incomplete | ambiguous | error` — so a reuse-collapses-to-never regression is visible instead of hidden behind fail-open.
 
 **Emit the step's `shell` verbatim.** `factoryProofGateStep()` sets `shell: bash --noprofile --norc {0}` (`FACTORY_PROOF_GATE_SHELL`) and a generator that drops it breaks the gate. GitHub's default for `run:` is `bash -e {0}` — errexit arrives from the invocation, not the script, so omitting `set -e` does not achieve it. Under the default the gate dies at the first non-zero command before its single `GITHUB_OUTPUT` write: no verdict, no `reason`, reuse silently collapsed to never while the job looks like healthy full CI. `shell: bash` is not a substitute; it expands to `bash --noprofile --norc -eo pipefail {0}`. The script is written to survive errexit as well, and its tests execute every case under both shells — a harness that runs this script under friendlier flags than the runner does is worse than no harness.
 
-`assertProofReuseCoverage({ commands, skipped, surface })` is the compile-time guard in front of the runtime `incomplete` refusal: hand it the same selection and the command strings the workflow would skip, and it fails the consumer's build when the two drift apart. Extracting the skipped strings stays with the consumer — this package never parses workflow source, because establishing trust that way is what killed an earlier attempt.
+`assertProofReuseCoverage({ commands, skipped, surface })` is the compile-time guard in front of the runtime `incomplete` refusal: hand it the same selection and the command strings the workflow would skip, and it fails the consumer's build when the two drift apart. Coverage is exact executable coverage. The deprecated `equivalents` input remains only for patch-release source compatibility and is ignored; prose cannot authorize a skip. Extracting the skipped strings stays with the consumer — this package never parses workflow source, because establishing trust that way is what killed an earlier attempt.
 
 ### Alchemy entries
 
@@ -101,7 +127,9 @@ The gate is a **step, not a job**, marked `continue-on-error`, with no `set -e`.
 import { bundleAlchemyEntry, executeAlchemyEntry } from "@patronage/factory-ci";
 ```
 
-`bundleAlchemyEntry({ entry, outfile, ... })` flattens a TypeScript Alchemy entry to a single ESM file the Alchemy CLI can run, keeping `alchemy`, `alchemy/*`, `effect`, and `effect/*` external — both packages are identity-sensitive and a second copy breaks them silently. Options: `absWorkingDir`, `packages` (`"external"` by default), `sourcemap`, `target`, `tsconfig`. Returns the absolute outfile path.
+`bundleAlchemyEntry({ entry, outfile, ... })` flattens a TypeScript Alchemy entry to a single ESM file the Alchemy CLI can run, keeping `alchemy`, `alchemy/*`, `effect`, and `effect/*` external — both packages are identity-sensitive and a second copy breaks them silently. Options: `absWorkingDir`, `alias`, `packages` (`"external"` by default), `sourcemap`, `target`, `tsconfig`. Returns the absolute outfile path.
+
+`alias` is a specifier-to-target map handed to esbuild. Substitution runs before the `packages` and `external` decisions, so an aliased bare specifier is inlined even under `packages: "external"` — that is how a repo points a workspace-only or duplicated package at one file. Give absolute paths or package names; which aliases a repo needs is consumer policy and this package ships no defaults. `executeAlchemyEntry` passes its whole `bundle` option through, so the map is available there too. Because substitution runs first, an alias on `alchemy`, `effect`, or any of their subpaths would silently defeat the externals and bundle a second copy, so those keys are rejected outright. Targets are not string-matched — no rule over how a path is spelled can survive `..` segments or symlinks — so instead the build's metafile is checked afterwards and the bundle is rejected if it carries any input from a reserved package, however that file was reached. A consumer shim that re-exports `effect` by bare specifier stays external naturally and is allowed.
 
 `executeAlchemyEntry({ from, bundle, args, ... })` owns the repeated choreography: resolve the consumer's Alchemy CLI from `from`, bundle the entry, run that CLI under the current Node binary with the absolute bundled entry appended, and throw on spawn errors, signals, missing statuses, or non-zero exits. It returns only after status 0.
 
@@ -119,6 +147,25 @@ import {
 
 `local-pr-<pr>-<short sha>` construction and interpretation live behind one private grammar. `localPreviewStage({ pr, headSha, shaLength? })` accepts a positive PR, a full 40-character SHA, and a 7–40-character slice length (default 12). `parseLocalPreviewStage(stage, expected?)` returns the PR and SHA prefix, optionally proving ownership against a PR and full head SHA. `isLocalPreviewStage(stage, pr?)` is the boolean type guard. The raw regex is not public.
 
+### GitHub App installation tokens
+
+```ts
+import { GitHubApiError, mintInstallationToken } from "@patronage/factory-ci";
+
+const token = await mintInstallationToken(
+  { credentials: operatorGithubApp, owner, repo },
+  { timeoutMs: 5000 }
+);
+```
+
+The factory publishes its check runs, and paitronage its proof comments, under the same GitHub App identity — two projects that had each written the same three steps: sign an RS256 app JWT, look the installation up when it is not already known, exchange the JWT for an installation access token.
+
+`mintInstallationToken({ credentials, owner, repo }, options?)` is that mechanism and nothing more. `credentials` is `{ appId, installationId?, privateKeyPath }`: the app id GitHub issued, the installation when a consumer has recorded one, and the path to the private key. The key is a _path_, not key material, so no caller has to hold a secret in memory to make this call — and **where that path comes from stays the consumer's**. Operator config, a secret manager, an environment variable: this package neither reads a config file nor knows a key-path convention. `githubAppJwt(credentials, options?)` is the signing step alone, for a caller that needs the app JWT rather than an installation token.
+
+Nothing is cached. The token is returned to the caller, which owns its lifetime — this module keeps no copy of the token or the key, and never writes either to any output. A failing GitHub response throws `GitHubApiError`, which carries `status` so a caller can tell a retryable failure (422, 429, 5xx) from a wrong-credentials one.
+
+`options` are all injectable seams: `fetch`, `now`, `readPrivateKey`, and a `timeoutMs` per request (five seconds by default). Tests substitute the first three; production passes at most a timeout.
+
 ### Published-package contract
 
 The tests pack the actual tarball, extract it into a throwaway external consumer, import the built package root without the workspace's `development` condition, assert the exact runtime exports, and exercise the workflow and stage interfaces. This catches source-only successes, stale or missing `dist/`, exports-map mistakes, and accidental tarball growth before the attended release check.

package/dist/index.d.ts

@@ -60,6 +60,18 @@ interface BundleAlchemyEntryOptions {
   readonly outfile: string;
   /** esbuild's working directory; also the base for relative paths. */
   readonly absWorkingDir?: string;
+  /**
+   * Import specifiers to rewrite before resolution, passed straight to
+   * esbuild's `alias`. Substitution happens before the `packages` and
+   * `external` decisions, so an aliased bare specifier is inlined even under
+   * `packages: "external"`. Values are resolved the way esbuild resolves any
+   * import, so give absolute paths or package names — which aliases a repo
+   * needs is the consumer's policy and this package bakes in none. A key on
+   * `alchemy`, `effect`, or a subpath of either is rejected outright, and the
+   * finished bundle is checked for files from those packages however they were
+   * reached.
+   */
+  readonly alias?: Readonly<Record<string, string>>;
   /**
    * `"external"` (default) leaves every bare import outside the entry's own
    * source graph to Node's resolver at run time — the entry's TypeScript is
@@ -194,6 +206,59 @@ interface FactoryWorkflowArtifact<Additional extends Readonly<Record<string, Pin
  */
 declare const factoryWorkflow: <const Additional extends Readonly<Record<string, PinnedAction>> = Record<never, never>>(options: FactoryWorkflowOptions<Additional>) => FactoryWorkflowArtifact<Additional>;
 //#endregion
+//#region src/github-app-token.d.ts
+/**
+ * What a consumer must know to mint: the app id, where the private key is, and
+ * — when it has been recorded — which installation to mint against.
+ *
+ * `installationId` is optional because the installation is discoverable from
+ * the repository. `privateKeyPath` is a path rather than key material so no
+ * consumer has to hold a secret in memory to call this, and so the key-path
+ * convention stays the consumer's.
+ */
+interface GithubAppCredentials {
+  appId: number | string;
+  installationId?: number;
+  privateKeyPath: string;
+}
+/** Carries the HTTP status so a caller can tell a retryable failure apart. */
+declare class GitHubApiError extends Error {
+  readonly status: number;
+  constructor(status: number, statusText: string);
+}
+interface GithubAppTokenOptions {
+  /** Injectable `fetch` (tests, or a caller with its own instrumented one). */
+  fetch?: typeof fetch;
+  /** Wall clock in milliseconds; only the JWT's validity window uses it. */
+  now?: () => number;
+  /** Injectable key read, so a caller can hold the PEM itself if it must. */
+  readPrivateKey?: (privateKeyPath: string) => Buffer | string;
+  /** Per-request timeout; defaults to five seconds. */
+  timeoutMs?: number;
+}
+/**
+ * The signed app JWT GitHub accepts as `Authorization: Bearer` for the App
+ * endpoints. `iss` is stringified because GitHub accepts either spelling and a
+ * numeric app id must not depend on JSON's number formatting.
+ *
+ * The signature is produced from the key on disk and returned; the key
+ * material itself never leaves this call.
+ */
+declare const githubAppJwt: (credentials: GithubAppCredentials, options?: Pick<GithubAppTokenOptions, "now" | "readPrivateKey">) => string;
+/**
+ * Mint an installation access token for one repository.
+ *
+ * When the credentials omit `installationId`, the installation is discovered
+ * from the repository first — the same call every consumer had written for
+ * itself. Nothing is cached: the token is returned to the caller and this
+ * module keeps no copy.
+ */
+declare const mintInstallationToken: (input: {
+  credentials: GithubAppCredentials;
+  owner: string;
+  repo: string;
+}, options?: GithubAppTokenOptions) => Promise<string>;
+//#endregion
 //#region src/execute-alchemy-entry.d.ts
 interface ExecuteAlchemyEntryOptions {
   /**
@@ -343,9 +408,11 @@ interface ProofReuseCommand {
  *
  * `undefined` means the selection is unusable — not an array, empty, or
  * carrying an entry whose `command` is blank or whose `name` is not a plain
- * command identity. An empty required set would make *every* passing proof
- * trivially covering, so it is never silently treated as "requires nothing";
- * callers must refuse instead.
+ * command identity, or carrying duplicate names. A name is the executable
+ * authorization identity recorded in proof, so two commands may never collapse
+ * behind one. An empty required set would make *every* passing proof trivially
+ * covering, so it is never silently treated as "requires nothing"; callers
+ * must refuse instead.
  */
 declare const proofReuseRequiredCommands: (commands: readonly ProofReuseCommand[]) => readonly string[] | undefined;
 interface FactoryProofGateOptions {
@@ -404,10 +471,8 @@ interface ProofReuseCoverageInput {
   /** The same selection handed to the gate for this surface. */
   readonly commands: readonly ProofReuseCommand[];
   /**
-   * Skipped work covered under a different command string, keyed by the
-   * skipped string with the reason as its value. Deliberately explicit: a
-   * prose rationale for why some narrower command is "equivalent enough" is
-   * exactly what this assertion exists to force into the open.
+   * @deprecated Ignored. Consumer prose cannot authorize executable coverage;
+   * retained only so the 0.2.1 security patch remains source-compatible.
    */
   readonly equivalents?: Readonly<Record<string, string>>;
   /**
@@ -440,10 +505,60 @@ interface ProofReuseCoverageReport {
  */
 declare const proofReuseCoverage: ({
   commands,
-  equivalents,
   skipped
 }: ProofReuseCoverageInput) => ProofReuseCoverageReport;
 /** `proofReuseCoverage`, as a build failure. */
 declare const assertProofReuseCoverage: (input: ProofReuseCoverageInput) => ProofReuseCoverageReport;
 //#endregion
-export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_STEP_ID, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, type WorkflowStep, assertProofReuseCoverage, bundleAlchemyEntry, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, isLocalPreviewStage, localPreviewStage, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands };
+//#region src/workflow-shell-lint.d.ts
+/**
+ * Parse-check the shell embedded in generated workflow YAML (#376).
+ *
+ * The generated-workflow lint validates YAML shape. It never parses the shell
+ * inside a `run:` block, so a script that cannot execute at all — a stray
+ * `fi`, an unclosed quote, a `then` with no `if` — passes every local check
+ * and only fails when the runner reaches it. That is not hypothetical:
+ * paitronage#1090 shipped a stray `fi` into a generated workflow and made
+ * every automated preview destroy a parse-time no-op for five days.
+ *
+ * `bash -n` is the whole control: it parses without executing. It lives here,
+ * once, rather than as a contract test in each consumer, because a guard
+ * copied per repository is a guard that exists in some of them.
+ */
+/** One `run:` block that bash refuses to parse. */
+interface WorkflowShellParseFailure {
+  /** The step's `name:` when the YAML carried one. */
+  readonly step?: string;
+  /** The script as bash saw it, expressions already neutralized. */
+  readonly script: string;
+  /** What bash said. */
+  readonly stderr: string;
+}
+/** A `run:` block lifted out of generated YAML, with its step's `shell:`. */
+interface RunBlock {
+  readonly script: string;
+  readonly shell?: string;
+  readonly step?: string;
+}
+/**
+ * Every `run:` block in a generated workflow, paired with the `shell:` its
+ * step declares.
+ *
+ * Deliberately a scanner over the emitted text and not a YAML parse: this
+ * package takes no dependency it does not need, and the emitted shape is one
+ * generator's output, not arbitrary YAML. It reads both block scalars
+ * (`run: |-`) and inline scripts.
+ */
+declare const workflowRunBlocks: (yaml: string) => RunBlock[];
+/** Every `run:` block its interpreter refuses to parse. Empty means sound. */
+declare const workflowShellParseFailures: (yaml: string) => WorkflowShellParseFailure[];
+/**
+ * Fail the generated-workflow lint when any embedded `run:` block is not
+ * parseable bash. Call it on the YAML a generator is about to write, so the
+ * defect is caught at generation rather than by the runner.
+ */
+declare const assertWorkflowShellParses: (yaml: string, options: {
+  readonly source: string;
+}) => void;
+//#endregion
+export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_STEP_ID, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, type WorkflowShellParseFailure, type WorkflowStep, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands, workflowRunBlocks, workflowShellParseFailures };