@patronage/factory-ci 0.2.1 → 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
@@ -103,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.
 
@@ -121,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 {
   /**
@@ -445,4 +510,55 @@ declare const proofReuseCoverage: ({
 /** `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 };

package/dist/index.js

@@ -2,7 +2,9 @@ import { createRequire } from "node:module";
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import { build } from "esbuild";
-import { spawnSync } from "node:child_process";
+import { createSign } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { execFileSync, spawnSync } from "node:child_process";
 //#region src/actions.ts
 /**
 * The canonical Node 24 family shared by factory-project workflows.
@@ -40,6 +42,50 @@ const ALCHEMY_EXTERNALS = [
 	"effect/*"
 ];
 /**
+* The package names behind `ALCHEMY_EXTERNALS`, derived rather than restated so
+* a future external can never be guarded by only one of two lists.
+*/
+const RESERVED_ALIAS_PACKAGES = [...new Set(ALCHEMY_EXTERNALS.map((external) => external.replace(/\/\*$/u, "").toLowerCase()))];
+const reservedAliasKey = (key) => RESERVED_ALIAS_PACKAGES.find((name) => key === name || key.startsWith(`${name}/`));
+/**
+* Refuse an alias *key* that is itself a reserved package or one of its
+* subpaths. esbuild substitutes aliases before it decides what is external, so
+* such a key defeats `external` outright. Keys are compared, never resolved,
+* which is what makes string matching sound here.
+*/
+const assertAliasKeysAreAdmissible = (alias) => {
+	for (const key of Object.keys(alias)) {
+		const reserved = reservedAliasKey(key);
+		if (reserved) throw new Error(`bundleAlchemyEntry cannot alias "${key}": ${reserved} must stay external because its identity is shared with the consumer's runtime, and esbuild applies aliases before external matching. Point the consumer's own resolution at one copy instead.`);
+	}
+};
+/**
+* Whether a bundled input lives inside a reserved package.
+*
+* Metafile inputs are paths esbuild resolved and normalized itself, so
+* comparing whole segments here answers what was *bundled* rather than how the
+* config was spelled. Segments are compared case-insensitively: on a
+* case-insensitive filesystem `node_modules/Effect/…` resolves to the real
+* package and the metafile keeps the caller's spelling.
+*/
+const isReservedInput = (input) => {
+	const segments = input.toLowerCase().split(/[/\\]+/u);
+	return segments.some((segment, position) => position > 0 && segments[position - 1] === "node_modules" && RESERVED_ALIAS_PACKAGES.includes(segment));
+};
+/**
+* Assert the externals contract against the bundle esbuild actually produced.
+*
+* Checking alias *values* instead was unsound by construction: `..` segments,
+* symlinks, and every other spelling of the same file each need another string
+* rule, and the scanner loses. The metafile records the inputs after esbuild's
+* own resolution and normalization, so one check closes the whole class —
+* whatever route reached an identity-sensitive package, it shows up here.
+*/
+const assertNoReservedInputs = (inputs) => {
+	const offenders = inputs.filter(isReservedInput);
+	if (offenders.length > 0) throw new Error(`bundleAlchemyEntry refused a bundle carrying a second copy of an identity-sensitive package: ${offenders.join(", ")}. Those packages must resolve from the consumer's runtime, so nothing may pull their files into the bundle — an alias that re-exports them by bare specifier stays external and is fine.`);
+};
+/**
 * Pre-bundle an Alchemy entry to a single ESM file, keeping `alchemy` and
 * `effect` external (#268).
 *
@@ -53,22 +99,26 @@ const ALCHEMY_EXTERNALS = [
 * Returns the absolute path of the file written.
 */
 const bundleAlchemyEntry = async (options) => {
+	if (options.alias) assertAliasKeysAreAdmissible(options.alias);
 	const root = options.absWorkingDir ? path.resolve(options.absWorkingDir) : process.cwd();
 	const outfile = path.resolve(root, options.outfile);
 	await mkdir(path.dirname(outfile), { recursive: true });
-	await build({
+	const result = await build({
 		absWorkingDir: root,
 		bundle: true,
 		entryPoints: [path.resolve(root, options.entry)],
 		external: ALCHEMY_EXTERNALS,
 		format: "esm",
+		metafile: true,
 		outfile,
 		packages: options.packages ?? "external",
 		platform: "node",
 		sourcemap: options.sourcemap ?? false,
 		target: options.target ?? "node24",
+		...options.alias ? { alias: { ...options.alias } } : {},
 		...options.tsconfig ? { tsconfig: path.resolve(root, options.tsconfig) } : {}
 	});
+	assertNoReservedInputs(Object.keys(result.metafile.inputs));
 	return outfile;
 };
 //#endregion
@@ -210,6 +260,95 @@ const factoryWorkflow = (options) => {
 	});
 };
 //#endregion
+//#region src/github-app-token.ts
+/**
+* Minting a GitHub App installation token: the RS256 app JWT, the optional
+* installation lookup, and the token exchange (#617).
+*
+* Two projects had grown the same three steps independently — the factory's
+* check-run publisher and paitronage's proof-comment publisher — which is the
+* admitted-on-repetition bar. Only the *mechanism* lives here. Where the
+* private key comes from, how the app id is configured, and what the token is
+* then used for stay with each consumer: this module is handed credentials and
+* returns a token.
+*/
+/** The default request budget, matching the factory's other GitHub writes. */
+const DEFAULT_TIMEOUT_MS = 5e3;
+/** Nine-minute JWT lifetime, backdated a minute against runner clock skew. */
+const JWT_BACKDATE_SECONDS = 60;
+const JWT_LIFETIME_SECONDS = 600;
+/** Carries the HTTP status so a caller can tell a retryable failure apart. */
+var GitHubApiError = class extends Error {
+	status;
+	constructor(status, statusText) {
+		super(`GitHub API ${status} ${statusText}`);
+		this.name = "GitHubApiError";
+		this.status = status;
+	}
+};
+const base64url = (value) => Buffer.from(value).toString("base64url");
+/**
+* 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.
+*/
+const githubAppJwt = (credentials, options = {}) => {
+	const nowMs = (options.now ?? Date.now)();
+	const issuedAt = Math.floor(nowMs / 1e3) - JWT_BACKDATE_SECONDS;
+	const unsigned = `${base64url(JSON.stringify({
+		alg: "RS256",
+		typ: "JWT"
+	}))}.${base64url(JSON.stringify({
+		exp: issuedAt + JWT_LIFETIME_SECONDS,
+		iat: issuedAt,
+		iss: String(credentials.appId)
+	}))}`;
+	const readKey = options.readPrivateKey ?? readFileSync;
+	const signer = createSign("RSA-SHA256");
+	signer.update(unsigned);
+	signer.end();
+	return `${unsigned}.${signer.sign(readKey(credentials.privateKeyPath), "base64url")}`;
+};
+const githubAppJson = async (request, url, jwt, method, timeoutMs) => {
+	const response = await request(url, {
+		headers: {
+			Accept: "application/vnd.github+json",
+			Authorization: `Bearer ${jwt}`,
+			"X-GitHub-Api-Version": "2022-11-28"
+		},
+		method,
+		signal: AbortSignal.timeout(timeoutMs)
+	});
+	if (!response.ok) throw new GitHubApiError(response.status, response.statusText);
+	return await response.json();
+};
+/**
+* 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.
+*/
+const mintInstallationToken = async (input, options = {}) => {
+	const { credentials } = input;
+	const request = options.fetch ?? fetch;
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const jwt = githubAppJwt(credentials, options);
+	let { installationId } = credentials;
+	if (installationId === void 0) {
+		const installation = await githubAppJson(request, `https://api.github.com/repos/${input.owner}/${input.repo}/installation`, jwt, "GET", timeoutMs);
+		if (typeof installation.id !== "number") throw new TypeError("GitHub App installation response omitted id");
+		installationId = installation.id;
+	}
+	const minted = await githubAppJson(request, `https://api.github.com/app/installations/${installationId}/access_tokens`, jwt, "POST", timeoutMs);
+	if (typeof minted.token !== "string") throw new TypeError("GitHub App token response omitted token");
+	return minted.token;
+};
+//#endregion
 //#region src/execute-alchemy-entry.ts
 /**
 * Bundle a consumer-owned Alchemy entry, resolve that consumer's Alchemy CLI,
@@ -759,4 +898,268 @@ const assertProofReuseCoverage = (input) => {
 	throw new Error(`Proof-reuse coverage failed: the ${surface} surface ${problem}. Add the command to software-factory.profile.json (and to this surface's selection), or stop skipping it.`);
 };
 //#endregion
-export { 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, NODE_PNPM_ACTION_FAMILY_NODE24, assertProofReuseCoverage, bundleAlchemyEntry, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, isLocalPreviewStage, localPreviewStage, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands };
+//#region src/workflow-shell-lint.ts
+const RUN_KEY = /^(?<indent>\s*)(?:-\s+)?run:(?<inline>.*)$/u;
+/**
+* GitHub evaluates `${{ }}` before bash ever sees the script, and what it
+* substitutes is not knowable here. Neutralizing each expression to one plain
+* word is what the runner's *shape* looks like: a value in argument position.
+* Leaving them in would make every workflow fail to parse; expanding them to
+* nothing would silently change quoting.
+*
+* Scanned rather than matched with a lazy regex, because `}}` occurs inside
+* Actions string literals: `format('refs/{{0}}', github.ref_name)` escapes a
+* literal brace pair that way, and stopping there would leave half an
+* expression in the script and report a parse error the runner never sees.
+*/
+const neutralizeExpressions = (script) => {
+	let out = "";
+	let cursor = 0;
+	while (cursor < script.length) {
+		const start = script.indexOf("${{", cursor);
+		if (start === -1) {
+			out += script.slice(cursor);
+			break;
+		}
+		out += script.slice(cursor, start);
+		let scan = start + 3;
+		let quote;
+		let end = -1;
+		while (scan < script.length) {
+			const char = script[scan];
+			if (quote === void 0) {
+				if (char === "'" || char === "\"") quote = char;
+				else if (char === "}" && script[scan + 1] === "}") {
+					end = scan + 2;
+					break;
+				}
+			} else if (char === quote) if (script[scan + 1] === quote) scan += 1;
+			else quote = void 0;
+			scan += 1;
+		}
+		if (end === -1) {
+			out += script.slice(start);
+			break;
+		}
+		out += "FACTORY_ACTIONS_EXPRESSION";
+		cursor = end;
+	}
+	return out;
+};
+/** Strip one layer of YAML single quoting from a scalar value. */
+const unquote = (raw) => {
+	const value = raw.trim();
+	if (value.startsWith("'") && value.endsWith("'") && value.length > 1) return value.slice(1, -1).replaceAll("''", "'");
+	return value;
+};
+const indentOf = (line) => line.length - line.trimStart().length;
+/**
+* Where a mapping key sits, counting the `- ` sequence marker as indentation:
+* `- name:` and the `run:` below it are siblings in the same step even though
+* their raw columns differ by two.
+*/
+const keyIndentOf = (line) => indentOf(line) + (line.trimStart().startsWith("- ") ? 2 : 0);
+/** A sibling scalar of the `run:` key under inspection, when the line is one. */
+const keyValueAt = (line, indent, key) => {
+	if (keyIndentOf(line) !== indent) return;
+	const rest = line.trimStart().replace(/^-\s+/u, "");
+	return rest.startsWith(`${key}:`) ? rest.slice(key.length + 1) : void 0;
+};
+/**
+* Every `defaults: { run: { shell } }` in the document, with the span it
+* governs: the mapping that declares it, which is the whole workflow at the
+* top level and one job under `jobs:`.
+*
+* GitHub resolves a step's interpreter as step `shell:`, then the job's
+* default, then the workflow's, then bash. A scanner that only looked at the
+* step would call every step in a `defaults.run.shell: sh` workflow bash and
+* report a pass for scripts `sh` cannot parse — the very false negative this
+* control exists to close.
+*/
+const defaultShellScopes = (lines) => {
+	const scopes = [];
+	for (const [index, line] of lines.entries()) {
+		if (line.trim() !== "defaults:") continue;
+		const depth = keyIndentOf(line);
+		const shell = (() => {
+			let inRun = false;
+			for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+				const candidate = lines[cursor];
+				if (candidate.trim().length === 0) continue;
+				if (keyIndentOf(candidate) <= depth) return;
+				if (keyValueAt(candidate, depth + 2, "run") !== void 0) {
+					inRun = true;
+					continue;
+				}
+				if (keyIndentOf(candidate) <= depth + 2) {
+					inRun = false;
+					continue;
+				}
+				const value = inRun ? keyValueAt(candidate, depth + 4, "shell") : void 0;
+				if (value !== void 0) return unquote(value);
+			}
+		})();
+		if (shell === void 0) continue;
+		let start = 0;
+		for (let cursor = index - 1; cursor >= 0; cursor -= 1) if (lines[cursor].trim().length > 0 && keyIndentOf(lines[cursor]) < depth) {
+			start = cursor;
+			break;
+		}
+		let end = lines.length;
+		for (let cursor = index + 1; cursor < lines.length; cursor += 1) if (lines[cursor].trim().length > 0 && keyIndentOf(lines[cursor]) < depth) {
+			end = cursor;
+			break;
+		}
+		scopes.push({
+			depth,
+			end,
+			shell,
+			start
+		});
+	}
+	return scopes;
+};
+/** The innermost `defaults.run.shell` governing a line, if any. */
+const inheritedShell = (scopes, index) => scopes.filter((scope) => index >= scope.start && index < scope.end).toSorted((left, right) => right.depth - left.depth).at(0)?.shell;
+/**
+* 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.
+*/
+const workflowRunBlocks = (yaml) => {
+	const lines = yaml.split("\n");
+	const scopes = defaultShellScopes(lines);
+	const blocks = [];
+	for (const [index, line] of lines.entries()) {
+		const match = RUN_KEY.exec(line);
+		if (match?.groups === void 0) continue;
+		const keyIndent = keyIndentOf(line);
+		const inline = match.groups.inline.trim();
+		let script;
+		let end = index;
+		if (inline.startsWith(">")) throw new Error(`folded (\`run: >\`) scripts are not supported: YAML folds their line breaks into spaces, so what bash parses is not what is written. Use a literal block (\`run: |\`).`);
+		if (inline.trimStart().startsWith("\"")) throw new Error(`double-quoted \`run:\` scalars are not supported: their YAML escapes would have to be decoded before bash sees them. Use a literal block (\`run: |\`) or an unquoted scalar.`);
+		if (inline.startsWith("|")) {
+			const body = [];
+			for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+				const candidate = lines[cursor];
+				if (candidate.trim().length > 0 && indentOf(candidate) <= keyIndent) break;
+				body.push(candidate);
+				end = cursor;
+			}
+			const strip = Math.min(...body.filter((entry) => entry.trim().length > 0).map((entry) => indentOf(entry)));
+			script = body.map((entry) => entry.slice(strip)).join("\n");
+		} else if (inline.length > 0) script = unquote(inline);
+		else continue;
+		let shell;
+		let step;
+		const readSibling = (line_) => {
+			shell ??= keyValueAt(line_, keyIndent, "shell");
+			step ??= keyValueAt(line_, keyIndent, "name");
+		};
+		for (let cursor = index; cursor >= 0 && keyIndentOf(lines[cursor]) >= keyIndent; cursor -= 1) {
+			readSibling(lines[cursor]);
+			if (lines[cursor].trimStart().startsWith("- ")) break;
+		}
+		for (let cursor = end + 1; cursor < lines.length; cursor += 1) {
+			if (keyIndentOf(lines[cursor]) < keyIndent || lines[cursor].trimStart().startsWith("- ")) break;
+			readSibling(lines[cursor]);
+		}
+		const effectiveShell = shell === void 0 ? inheritedShell(scopes, index) : unquote(shell);
+		blocks.push({
+			script,
+			...effectiveShell === void 0 ? {} : { shell: effectiveShell },
+			...step === void 0 ? {} : { step: unquote(step) }
+		});
+	}
+	return blocks;
+};
+/** `NAME=value` in a shell command template, as `env` takes them. */
+const ASSIGNMENT = /^[A-Za-z_]\w*=/u;
+/**
+* Interpreters GitHub supports that this control deliberately leaves alone.
+* Named rather than inferred, so an unfamiliar command fails loudly instead of
+* being skipped as though it had been considered.
+*/
+const NON_SHELL_INTERPRETERS = new Set([
+	"cmd",
+	"powershell",
+	"pwsh",
+	"python",
+	"python3"
+]);
+/**
+* The interpreter that will parse a step's script, or `undefined` for one this
+* control leaves alone.
+*
+* A step declaring no shell gets bash: that is GitHub's default for `run:` on
+* Linux runners. A step declaring `sh` gets `sh`, because the runner runs it
+* with `sh` — whose grammar is narrower than bash's, so parsing it with bash
+* would report a pass for a script the runner cannot run. Anything else
+* (pwsh, python, cmd) is not this control's business.
+*/
+const parserFor = (shell) => {
+	if (shell === void 0) return ["bash"];
+	const argv = [];
+	let interpreter;
+	for (const token of shell.trim().split(/\s+/u)) {
+		if (token === "{0}") break;
+		if (interpreter !== void 0) {
+			argv.push(token);
+			continue;
+		}
+		const executable = token.slice(token.lastIndexOf("/") + 1);
+		if (executable === "bash" || executable === "sh") interpreter = token;
+		else if (!(executable === "env" || token.startsWith("-") || ASSIGNMENT.test(token))) {
+			if (NON_SHELL_INTERPRETERS.has(executable)) return;
+			throw new Error(`unrecognized \`shell:\` command: ${shell}. This control parses bash and sh scripts and knowingly skips pwsh, powershell, python, and cmd; it refuses rather than guess at anything else.`);
+		}
+		argv.push(token);
+	}
+	if (interpreter === void 0) throw new Error(`unrecognized \`shell:\` command: ${shell}. No interpreter to parse the script with.`);
+	return argv;
+};
+/** Every `run:` block its interpreter refuses to parse. Empty means sound. */
+const workflowShellParseFailures = (yaml) => {
+	const failures = [];
+	for (const block of workflowRunBlocks(yaml)) {
+		const parser = parserFor(block.shell);
+		if (parser === void 0) continue;
+		const [executable, ...parserArgs] = parser;
+		const script = neutralizeExpressions(block.script);
+		try {
+			execFileSync(executable, [...parserArgs, "-n"], {
+				input: script,
+				stdio: [
+					"pipe",
+					"ignore",
+					"pipe"
+				]
+			});
+		} catch (error) {
+			failures.push({
+				script,
+				...block.step === void 0 ? {} : { step: block.step },
+				stderr: String(error.stderr ?? error).trim()
+			});
+		}
+	}
+	return failures;
+};
+/**
+* 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.
+*/
+const assertWorkflowShellParses = (yaml, options) => {
+	const failures = workflowShellParseFailures(yaml);
+	if (failures.length === 0) return;
+	const detail = failures.map((failure) => `  - ${failure.step ?? "unnamed step"}: ${failure.stderr.replaceAll("\n", "\n    ")}`).join("\n");
+	throw new Error(`${options.source} emits shell bash cannot parse; the runner would treat it as a no-op:\n${detail}`);
+};
+//#endregion
+export { 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, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands, workflowRunBlocks, workflowShellParseFailures };