@patronage/factory-ci 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patronage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# @patronage/factory-ci
+
+The CI and deploy building blocks that already repeat across Patronage **factory projects** — projects that carry a `software-factory.profile.json`, deploy through Alchemy, and are subject to factory CI and proof gating.
+
+```bash
+pnpm add -E @patronage/factory-ci
+```
+
+It is a **pure library**. There is no `bin`: anything invocable belongs to `psf`. There is no `alchemy` or `effect` dependency of any kind — not a dependency, not a peer dependency — so the package can never pull a second copy of either into a consumer's graph. `esbuild` is its own dependency, which is what lets consumers delete their local arrangements for finding one.
+
+## What it is for
+
+Three repositories independently built the same scaffolding and then drifted: three wordings of the same setup block, the same `@v4` action tags pinned to different commits because they were generated months apart, two esbuild pre-bundles, two Alchemy CLI wrappers, and one disposable-stage grammar invented twice.
+
+The admission rule is **upstream on repetition**: nothing enters this package until it already repeats across at least two projects. Experiments live in one repository first. The public surface is made of three deep modules, not a workflow framework.
+
+## Exports
+
+### Workflow generation (gagen)
+
+```ts
+import {
+  factoryWorkflow,
+  NODE_PNPM_ACTION_FAMILY_V4,
+} from "@patronage/factory-ci";
+```
+
+`factoryWorkflow(options)` owns one generated source's complete workflow-support artifact:
+
+- `actions`: the explicit Node/pnpm action family plus every workflow-specific action pin
+- `setupSteps`: checkout → pnpm → Node → install, customizable by named role
+- `writeOptions`: the provenance banner and `pinDeps: false`, ready to spread into gagen's `writeOrLint`
+
+Every action is validated as `owner/repo@<full sha>`, with its release tag kept separately. A complete `actionFamily` is required; there is no default that could silently move a consumer between action majors. `NODE_PNPM_ACTION_FAMILY_V4` is the family already proven across HQ's workflows. Firedup supplies its own complete v6 family until that family repeats in another project and qualifies for upstream admission.
+
+```ts
+const generated = factoryWorkflow({
+  actionFamily: NODE_PNPM_ACTION_FAMILY_V4,
+  additionalActions: {
+    pathsFilter: {
+      tag: "v3",
+      uses: "dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590",
+    },
+  },
+  generated: {
+    source: ".github/workflows/verify.ts",
+    regenerate: "pnpm workflows:generate",
+  },
+  setup: {
+    setupNode: { cacheDependencyPath: "pnpm-lock.yaml" },
+  },
+});
+
+workflow({/* caller-owned jobs and topology */}).writeOrLint({
+  filePath,
+  ...generated.writeOptions,
+});
+```
+
+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.
+
+### Alchemy entries
+
+```ts
+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.
+
+`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.
+
+The caller still owns deploy/destroy/plan arguments, stage admission, credentials, environment shaping, destructive-plan guards, and convergence. Failure messages never repeat arguments or environment values.
+
+### Disposable stages
+
+```ts
+import {
+  isLocalPreviewStage,
+  localPreviewStage,
+  parseLocalPreviewStage,
+} from "@patronage/factory-ci";
+```
+
+`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.
+
+### 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.
+
+## No configuration surface
+
+Functions take plain typed options objects. Proof and preview configuration lives in the canonical `software-factory.profile.json` schema, never in this package (ADR 0021); mapping a profile into these options is the profile's job.
+
+## Secrets
+
+**This package introduces no GitHub-Actions-held secrets, and none may be added to it.**
+
+The credential env-block helper that the audit found repeated was deliberately cut on design grounds: shipping it would have entrenched Actions-held secrets across every project that adopts this package. The standing direction is that credentials resolve from Cloudflare, minimized toward the HQ Worker's documented posture — the floor being a single `CLOUDFLARE_API_TOKEN` where a deploy genuinely must run from Actions, because Cloudflare has no Actions OIDC today. This constraint binds later phases of the package, not just its first release.
+
+## Releases
+
+Attended and hand-cut, on the same terms as `@patronage/alchemy-d1-state`: bump the version, run the workspace checks, read the `npm pack --dry-run` file list, publish, tag `factory-ci@<version>`. There is no changesets setup and no automatic release trigger, by design. Consumers pin exact versions.
+
+## License
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,228 @@
+//#region src/actions.d.ts
+/**
+ * The GitHub Actions this family's workflow generators use, pinned to full
+ * commit SHAs in one place (#268).
+ *
+ * Every repository pinned the same *tags* and got different *commits*: this
+ * repository's `verify.yml` carried `actions/checkout@11d5960a` while
+ * `hq-deploy.yml` and all of paitronage carried `34e11487`, because gagen
+ * resolves a floating `@v4` at generation time and the files were generated
+ * months apart. Naming the SHA here is what makes that class of drift
+ * impossible: regenerating a workflow can no longer move a pin.
+ *
+ * `uses` is a bare `owner/repo@<sha>` string, safe to hand straight to a
+ * gagen step. The tag lives in its own field rather than as a `# v4.4.0`
+ * suffix on `uses`, because a `#` inside a YAML scalar forces quoting and
+ * gagen's pin pass reads the value with `\S+` — the two together corrupt the
+ * emitted `uses:` line. gagen writes the `# <tag>` comment itself.
+ */
+interface PinnedAction {
+  /** `owner/repo@<40-char commit sha>`, ready to use as a step's `uses`. */
+  readonly uses: string;
+  /** The release tag that commit carries, for humans and for bump tooling. */
+  readonly tag: string;
+}
+interface NodePnpmActionFamily {
+  /** Review-visible identity for the complete, compatible action family. */
+  readonly id: string;
+  readonly checkout: PinnedAction;
+  readonly setupNode: PinnedAction;
+  readonly setupPnpm: PinnedAction;
+}
+/**
+ * The v4 family already shared by HQ's generated workflows.
+ *
+ * Consumers must pass this (or their own complete family) to
+ * `factoryWorkflow`; there is deliberately no implicit default. In
+ * particular, Firedup's v6 action family must stay v6 during adoption.
+ */
+declare const NODE_PNPM_ACTION_FAMILY_V4: {
+  readonly checkout: {
+    readonly tag: "v4.4.0";
+    readonly uses: "actions/checkout@11d5960a326750d5838078e36cf38b85af677262";
+  };
+  readonly id: "node-pnpm-v4";
+  readonly setupNode: {
+    readonly tag: "v4.4.0";
+    readonly uses: "actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020";
+  };
+  readonly setupPnpm: {
+    readonly tag: "v4.3.0";
+    readonly uses: "pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1";
+  };
+};
+//#endregion
+//#region src/bundle-alchemy-entry.d.ts
+interface BundleAlchemyEntryOptions {
+  /** The Alchemy entry to bundle, e.g. `alchemy.run.ts`. */
+  readonly entry: string;
+  /** Where to write the bundled ESM file, e.g. `.alchemy/deploy-entry.mjs`. */
+  readonly outfile: string;
+  /** esbuild's working directory; also the base for relative paths. */
+  readonly absWorkingDir?: 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
+   * still inlined, which is the whole point. `"bundle"` inlines dependencies
+   * too, minus the Alchemy/Effect externals, for a runner without the
+   * consumer's node_modules.
+   */
+  readonly packages?: "bundle" | "external";
+  /** Emit a sourcemap next to the outfile. Default `false`. */
+  readonly sourcemap?: boolean;
+  /** esbuild target. Default `node24`. */
+  readonly target?: string;
+  /** tsconfig to apply to the entry's sources. */
+  readonly tsconfig?: string;
+}
+/**
+ * Pre-bundle an Alchemy entry to a single ESM file, keeping `alchemy` and
+ * `effect` external (#268).
+ *
+ * Both repos that deploy through Alchemy wrote this: the Alchemy CLI runs a
+ * JavaScript entry, so a TypeScript `alchemy.run.ts` has to be flattened
+ * first, and the flattening must not swallow the two packages whose identity
+ * matters. Firedup additionally resolved esbuild *through vite* because it had
+ * no direct dependency on it; here esbuild is a plain dependency of this
+ * package and that hack can be deleted.
+ *
+ * Returns the absolute path of the file written.
+ */
+declare const bundleAlchemyEntry: (options: BundleAlchemyEntryOptions) => Promise<string>;
+//#endregion
+//#region src/disposable-stage.d.ts
+declare const localPreviewStageBrand: unique symbol;
+type LocalPreviewStage = string & {
+  readonly [localPreviewStageBrand]: true;
+};
+interface ParsedLocalPreviewStage {
+  readonly headShaPrefix: string;
+  readonly pr: number;
+  readonly stage: LocalPreviewStage;
+}
+interface ParseLocalPreviewStageExpected {
+  /** Require the stage to belong to this pull request. */
+  readonly pr?: number;
+  /** Require the stage prefix to match this full 40-character head SHA. */
+  readonly headSha?: string;
+}
+/**
+ * Interpret an untrusted stage name through the one disposable-stage grammar.
+ * Returns `null` rather than throwing when the value or expected ownership
+ * does not match.
+ */
+declare const parseLocalPreviewStage: (stage: string, expected?: ParseLocalPreviewStageExpected) => ParsedLocalPreviewStage | null;
+/**
+ * Whether `stage` is disposable. Pass `pr` to also require PR ownership.
+ */
+declare const isLocalPreviewStage: (stage: string, pr?: number) => stage is LocalPreviewStage;
+interface LocalPreviewStageOptions {
+  /** The pull request number. */
+  readonly pr: number;
+  /** The full head SHA the preview is tied to. */
+  readonly headSha: string;
+  /** How much of the SHA to keep. Default 12; the grammar allows 7 to 40. */
+  readonly shaLength?: number;
+}
+/**
+ * Build the disposable stage name for a pull request head.
+ *
+ * Throws when the inputs cannot produce a valid stage, so a caller can never
+ * deploy into a name the cleanup sweep will not recognise.
+ */
+declare const localPreviewStage: (options: LocalPreviewStageOptions) => LocalPreviewStage;
+//#endregion
+//#region src/factory-workflow.d.ts
+interface WorkflowStep {
+  readonly name: string;
+  readonly uses?: string;
+  readonly with?: Readonly<Record<string, string>>;
+  readonly run?: string;
+}
+interface CheckoutStepOptions {
+  readonly name?: string;
+  readonly ref?: string;
+}
+interface SetupNodeStepOptions {
+  readonly cacheDependencyPath?: string;
+  readonly nodeVersionFile?: string;
+}
+interface InstallStepOptions {
+  readonly name?: string;
+  readonly run?: string;
+}
+interface FactoryWorkflowSetupOptions {
+  readonly checkout?: CheckoutStepOptions;
+  readonly install?: InstallStepOptions;
+  readonly setupNode?: SetupNodeStepOptions;
+}
+interface FactoryWorkflowOptions<Additional extends Readonly<Record<string, PinnedAction>>> {
+  /**
+   * Required complete family. There is no default, so adopting this package
+   * cannot silently move a consumer from one action major to another.
+   */
+  readonly actionFamily: NodePnpmActionFamily;
+  /** Every workflow-specific action source this artifact owns. */
+  readonly additionalActions?: Additional;
+  readonly generated: {
+    /** Generator path relative to the repository root. */readonly source: string; /** Exact command that regenerates the emitted workflow. */
+    readonly regenerate: string;
+  };
+  readonly setup?: FactoryWorkflowSetupOptions;
+}
+type FamilyActions = Omit<NodePnpmActionFamily, "id">;
+interface FactoryWorkflowArtifact<Additional extends Readonly<Record<string, PinnedAction>>> {
+  readonly actionFamilyId: string;
+  readonly actions: Readonly<FamilyActions & Additional>;
+  /** Checkout → pnpm → Node → install, customized by named role. */
+  readonly setupSteps: readonly WorkflowStep[];
+  /**
+   * Structurally accepted by gagen's `writeOrLint`; this package deliberately
+   * has no gagen dependency.
+   */
+  readonly writeOptions: {
+    readonly header: string;
+    readonly pinDeps: false;
+  };
+}
+/**
+ * Own one generated workflow source's action pins, setup block, provenance
+ * banner, and gagen pinning policy as a single artifact.
+ *
+ * The caller still owns workflow topology, jobs, runners, permissions, and
+ * every deployment policy decision.
+ */
+declare const factoryWorkflow: <const Additional extends Readonly<Record<string, PinnedAction>> = Record<never, never>>(options: FactoryWorkflowOptions<Additional>) => FactoryWorkflowArtifact<Additional>;
+//#endregion
+//#region src/execute-alchemy-entry.d.ts
+interface ExecuteAlchemyEntryOptions {
+  /**
+   * CLI arguments before the bundled entry. The absolute entry path is always
+   * appended as the final argument.
+   */
+  readonly args: readonly string[];
+  readonly bundle: BundleAlchemyEntryOptions;
+  /** Child working directory. Defaults to the bundle root, then process.cwd. */
+  readonly cwd?: string;
+  /** Child environment. Defaults to process.env. */
+  readonly env?: NodeJS.ProcessEnv;
+  /** Consumer module context; normally the caller's import.meta.url. */
+  readonly from: string | URL;
+  /** Child stdio. Default "inherit". */
+  readonly stdio?: "inherit" | "pipe";
+}
+interface ExecuteAlchemyEntryResult {
+  readonly bundledEntry: string;
+  readonly stderr: string | null;
+  readonly stdout: string | null;
+}
+/**
+ * Bundle a consumer-owned Alchemy entry, resolve that consumer's Alchemy CLI,
+ * run it under the current Node binary, and return only on a successful exit.
+ *
+ * Deploy/destroy/plan selection, stage admission, credentials, and every
+ * convergence or destructive-change policy remain the caller's responsibility.
+ */
+declare const executeAlchemyEntry: (options: ExecuteAlchemyEntryOptions) => Promise<ExecuteAlchemyEntryResult>;
+//#endregion
+export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_V4, type NodePnpmActionFamily, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type SetupNodeStepOptions, type WorkflowStep, bundleAlchemyEntry, executeAlchemyEntry, factoryWorkflow, isLocalPreviewStage, localPreviewStage, parseLocalPreviewStage };

package/dist/index.js

@@ -0,0 +1,244 @@
+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";
+//#region src/actions.ts
+/**
+* The v4 family already shared by HQ's generated workflows.
+*
+* Consumers must pass this (or their own complete family) to
+* `factoryWorkflow`; there is deliberately no implicit default. In
+* particular, Firedup's v6 action family must stay v6 during adoption.
+*/
+const NODE_PNPM_ACTION_FAMILY_V4 = {
+	checkout: {
+		tag: "v4.4.0",
+		uses: "actions/checkout@11d5960a326750d5838078e36cf38b85af677262"
+	},
+	id: "node-pnpm-v4",
+	setupNode: {
+		tag: "v4.4.0",
+		uses: "actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020"
+	},
+	setupPnpm: {
+		tag: "v4.3.0",
+		uses: "pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1"
+	}
+};
+//#endregion
+//#region src/bundle-alchemy-entry.ts
+/**
+* Alchemy and Effect must resolve from the *consumer's* node_modules at run
+* time, never from the bundle: Alchemy's resource registry and Effect's
+* service tags are identity-sensitive, and a second copy silently breaks both.
+*/
+const ALCHEMY_EXTERNALS = [
+	"alchemy",
+	"alchemy/*",
+	"effect",
+	"effect/*"
+];
+/**
+* Pre-bundle an Alchemy entry to a single ESM file, keeping `alchemy` and
+* `effect` external (#268).
+*
+* Both repos that deploy through Alchemy wrote this: the Alchemy CLI runs a
+* JavaScript entry, so a TypeScript `alchemy.run.ts` has to be flattened
+* first, and the flattening must not swallow the two packages whose identity
+* matters. Firedup additionally resolved esbuild *through vite* because it had
+* no direct dependency on it; here esbuild is a plain dependency of this
+* package and that hack can be deleted.
+*
+* Returns the absolute path of the file written.
+*/
+const bundleAlchemyEntry = async (options) => {
+	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({
+		absWorkingDir: root,
+		bundle: true,
+		entryPoints: [path.resolve(root, options.entry)],
+		external: ALCHEMY_EXTERNALS,
+		format: "esm",
+		outfile,
+		packages: options.packages ?? "external",
+		platform: "node",
+		sourcemap: options.sourcemap ?? false,
+		target: options.target ?? "node24",
+		...options.tsconfig ? { tsconfig: path.resolve(root, options.tsconfig) } : {}
+	});
+	return outfile;
+};
+//#endregion
+//#region src/disposable-stage.ts
+/**
+* The disposable Alchemy stage a local preview deploy runs in:
+* `local-pr-<pr>-<short sha>` (#268).
+*
+* Two repos invented this grammar independently and then had to agree on it
+* anyway, because the same cleanup sweeps delete these stages. A stage that
+* does not match is not disposable, and destructive operations must refuse it.
+*/
+const LOCAL_PREVIEW_STAGE_PATTERN = /^local-pr-(?<pr>[1-9]\d*)-(?<sha>[0-9a-f]{7,40})$/u;
+/**
+* Interpret an untrusted stage name through the one disposable-stage grammar.
+* Returns `null` rather than throwing when the value or expected ownership
+* does not match.
+*/
+const parseLocalPreviewStage = (stage, expected = {}) => {
+	const match = LOCAL_PREVIEW_STAGE_PATTERN.exec(stage);
+	if (!match?.groups) return null;
+	const pr = Number(match.groups.pr);
+	const headShaPrefix = match.groups.sha;
+	if (!Number.isSafeInteger(pr) || expected.pr !== void 0 && pr !== expected.pr) return null;
+	if (expected.headSha !== void 0) {
+		const headSha = expected.headSha.trim().toLowerCase();
+		if (!/^[0-9a-f]{40}$/u.test(headSha) || !headSha.startsWith(headShaPrefix)) return null;
+	}
+	return {
+		headShaPrefix,
+		pr,
+		stage
+	};
+};
+/**
+* Whether `stage` is disposable. Pass `pr` to also require PR ownership.
+*/
+const isLocalPreviewStage = (stage, pr) => parseLocalPreviewStage(stage, pr === void 0 ? {} : { pr }) !== null;
+/**
+* Build the disposable stage name for a pull request head.
+*
+* Throws when the inputs cannot produce a valid stage, so a caller can never
+* deploy into a name the cleanup sweep will not recognise.
+*/
+const localPreviewStage = (options) => {
+	const { headSha, pr, shaLength = 12 } = options;
+	if (!Number.isSafeInteger(pr) || pr < 1) throw new Error(`pr must be a positive safe integer, got ${pr}.`);
+	if (!Number.isInteger(shaLength) || shaLength < 7 || shaLength > 40) throw new Error(`shaLength must be an integer from 7 through 40, got ${shaLength}.`);
+	const normalizedHead = headSha.trim().toLowerCase();
+	if (!/^[0-9a-f]{40}$/u.test(normalizedHead)) throw new Error(`headSha must be exactly 40 hexadecimal characters, got "${headSha}".`);
+	return `local-pr-${pr}-${normalizedHead.slice(0, shaLength)}`;
+};
+//#endregion
+//#region src/factory-workflow.ts
+const PINNED_ACTION_PATTERN = /^[\w.-]+\/[\w.-]+@[0-9a-f]{40}$/u;
+const ACTION_TAG_PATTERN = /^v\d+(?:\.\d+){0,2}$/u;
+const RESERVED_ACTION_NAMES = new Set([
+	"checkout",
+	"setupNode",
+	"setupPnpm"
+]);
+const assertSingleLine = (name, value) => {
+	if (value.trim() !== value || value.length === 0 || /[\r\n]/u.test(value)) throw new Error(`${name} must be a single non-empty line.`);
+};
+const actionRepository = (action) => action.uses.slice(0, action.uses.indexOf("@"));
+const assertPinnedAction = (name, action, expectedRepository) => {
+	if (!PINNED_ACTION_PATTERN.test(action.uses)) throw new Error(`${name} must use owner/repository@<40-character commit SHA>, got "${action.uses}".`);
+	if (expectedRepository && actionRepository(action) !== expectedRepository) throw new Error(`${name} must pin ${expectedRepository}, got ${actionRepository(action)}.`);
+	if (!ACTION_TAG_PATTERN.test(action.tag)) throw new Error(`${name} tag must be vN, vN.N, or vN.N.N, got "${action.tag}".`);
+};
+const usesStep = (fallbackName, action) => ({
+	name: fallbackName,
+	uses: action.uses
+});
+const assertActionFamily = (family) => {
+	assertSingleLine("actionFamily.id", family.id);
+	assertPinnedAction("checkout", family.checkout, "actions/checkout");
+	assertPinnedAction("setupNode", family.setupNode, "actions/setup-node");
+	assertPinnedAction("setupPnpm", family.setupPnpm, "pnpm/action-setup");
+};
+const assertAdditionalActions = (actions) => {
+	for (const [name, action] of Object.entries(actions)) {
+		if (RESERVED_ACTION_NAMES.has(name)) throw new Error(`${name} is reserved by the Node/pnpm action family and cannot be replaced by additionalActions.`);
+		assertPinnedAction(name, action);
+	}
+};
+const setupSteps = (family, setup = {}) => {
+	const installRun = setup.install?.run ?? "pnpm install --frozen-lockfile";
+	if (/(?:^|\s)--ignore-scripts(?:\s|$)/u.test(installRun)) throw new Error("The install step must not use --ignore-scripts; workspace prepare scripts build required package artifacts.");
+	const { checkout, setupNode } = setup;
+	return Object.freeze([
+		{
+			name: checkout?.name ?? "Checkout",
+			uses: family.checkout.uses,
+			...checkout?.ref ? { with: { ref: checkout.ref } } : {}
+		},
+		usesStep("Setup pnpm", family.setupPnpm),
+		{
+			name: "Setup Node",
+			uses: family.setupNode.uses,
+			with: {
+				cache: "pnpm",
+				...setupNode?.cacheDependencyPath ? { "cache-dependency-path": setupNode.cacheDependencyPath } : {},
+				"node-version-file": setupNode?.nodeVersionFile ?? ".nvmrc"
+			}
+		},
+		{
+			name: setup.install?.name ?? "Install workspace",
+			run: installRun
+		}
+	]);
+};
+/**
+* Own one generated workflow source's action pins, setup block, provenance
+* banner, and gagen pinning policy as a single artifact.
+*
+* The caller still owns workflow topology, jobs, runners, permissions, and
+* every deployment policy decision.
+*/
+const factoryWorkflow = (options) => {
+	assertSingleLine("generated.source", options.generated.source);
+	assertSingleLine("generated.regenerate", options.generated.regenerate);
+	assertActionFamily(options.actionFamily);
+	assertAdditionalActions(options.additionalActions ?? {});
+	const actions = Object.freeze({
+		checkout: options.actionFamily.checkout,
+		setupNode: options.actionFamily.setupNode,
+		setupPnpm: options.actionFamily.setupPnpm,
+		...options.additionalActions ?? {}
+	});
+	return Object.freeze({
+		actionFamilyId: options.actionFamily.id,
+		actions,
+		setupSteps: setupSteps(options.actionFamily, options.setup),
+		writeOptions: Object.freeze({
+			header: [`# GENERATED BY ${options.generated.source} -- DO NOT EDIT.`, `# Regenerate: ${options.generated.regenerate}`].join("\n"),
+			pinDeps: false
+		})
+	});
+};
+//#endregion
+//#region src/execute-alchemy-entry.ts
+/**
+* Bundle a consumer-owned Alchemy entry, resolve that consumer's Alchemy CLI,
+* run it under the current Node binary, and return only on a successful exit.
+*
+* Deploy/destroy/plan selection, stage admission, credentials, and every
+* convergence or destructive-change policy remain the caller's responsibility.
+*/
+const executeAlchemyEntry = async (options) => {
+	const cliEntry = createRequire(options.from).resolve("alchemy/bin/alchemy.js");
+	const bundledEntry = await bundleAlchemyEntry(options.bundle);
+	const result = spawnSync(process.execPath, [
+		cliEntry,
+		...options.args,
+		bundledEntry
+	], {
+		cwd: options.cwd ?? options.bundle.absWorkingDir ?? process.cwd(),
+		encoding: "utf-8",
+		env: options.env ?? process.env,
+		stdio: options.stdio ?? "inherit"
+	});
+	if (result.error) throw new Error("Failed to start the Alchemy CLI.");
+	if (result.signal) throw new Error(`Alchemy CLI terminated by signal ${result.signal}.`);
+	if (result.status !== 0) throw new Error(result.status === null ? "Alchemy CLI exited without reporting a status." : `Alchemy CLI exited with status ${result.status}.`);
+	return {
+		bundledEntry,
+		stderr: result.stderr,
+		stdout: result.stdout
+	};
+};
+//#endregion
+export { NODE_PNPM_ACTION_FAMILY_V4, bundleAlchemyEntry, executeAlchemyEntry, factoryWorkflow, isLocalPreviewStage, localPreviewStage, parseLocalPreviewStage };

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@patronage/factory-ci",
+  "version": "0.1.1",
+  "description": "Deep CI and deploy building blocks for Patronage factory projects: workflow source artifacts, Alchemy entry execution, and disposable-stage semantics",
+  "keywords": [
+    "alchemy",
+    "cloudflare",
+    "continuous-integration",
+    "esbuild",
+    "github-actions"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/patronage/software-factory.git",
+    "directory": "factory-ci"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "esbuild": "0.28.1"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "oxfmt": "0.59.0",
+    "oxlint": "1.74.0",
+    "tsdown": "0.21.10",
+    "typescript": "5.9.3",
+    "ultracite": "7.9.4",
+    "vitest": "4.1.10"
+  },
+  "engines": {
+    "node": "^24.0.0"
+  },
+  "scripts": {
+    "prebuild": "bash ../scripts/ensure-worktree-bootstrap.sh",
+    "build": "tsdown",
+    "precheck": "bash ../scripts/ensure-worktree-bootstrap.sh",
+    "check": "ultracite check",
+    "prefix": "bash ../scripts/ensure-worktree-bootstrap.sh",
+    "fix": "ultracite fix",
+    "pretest": "bash ../scripts/ensure-worktree-bootstrap.sh",
+    "test": "vitest run",
+    "pretypecheck": "bash ../scripts/ensure-worktree-bootstrap.sh",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actions.ts

@@ -0,0 +1,54 @@
+/**
+ * The GitHub Actions this family's workflow generators use, pinned to full
+ * commit SHAs in one place (#268).
+ *
+ * Every repository pinned the same *tags* and got different *commits*: this
+ * repository's `verify.yml` carried `actions/checkout@11d5960a` while
+ * `hq-deploy.yml` and all of paitronage carried `34e11487`, because gagen
+ * resolves a floating `@v4` at generation time and the files were generated
+ * months apart. Naming the SHA here is what makes that class of drift
+ * impossible: regenerating a workflow can no longer move a pin.
+ *
+ * `uses` is a bare `owner/repo@<sha>` string, safe to hand straight to a
+ * gagen step. The tag lives in its own field rather than as a `# v4.4.0`
+ * suffix on `uses`, because a `#` inside a YAML scalar forces quoting and
+ * gagen's pin pass reads the value with `\S+` — the two together corrupt the
+ * emitted `uses:` line. gagen writes the `# <tag>` comment itself.
+ */
+export interface PinnedAction {
+  /** `owner/repo@<40-char commit sha>`, ready to use as a step's `uses`. */
+  readonly uses: string;
+  /** The release tag that commit carries, for humans and for bump tooling. */
+  readonly tag: string;
+}
+
+export interface NodePnpmActionFamily {
+  /** Review-visible identity for the complete, compatible action family. */
+  readonly id: string;
+  readonly checkout: PinnedAction;
+  readonly setupNode: PinnedAction;
+  readonly setupPnpm: PinnedAction;
+}
+
+/**
+ * The v4 family already shared by HQ's generated workflows.
+ *
+ * Consumers must pass this (or their own complete family) to
+ * `factoryWorkflow`; there is deliberately no implicit default. In
+ * particular, Firedup's v6 action family must stay v6 during adoption.
+ */
+export const NODE_PNPM_ACTION_FAMILY_V4 = {
+  checkout: {
+    tag: "v4.4.0",
+    uses: "actions/checkout@11d5960a326750d5838078e36cf38b85af677262",
+  },
+  id: "node-pnpm-v4",
+  setupNode: {
+    tag: "v4.4.0",
+    uses: "actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020",
+  },
+  setupPnpm: {
+    tag: "v4.3.0",
+    uses: "pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1",
+  },
+} as const satisfies NodePnpmActionFamily;

package/src/bundle-alchemy-entry.ts

@@ -0,0 +1,76 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+import { build } from "esbuild";
+
+/**
+ * Alchemy and Effect must resolve from the *consumer's* node_modules at run
+ * time, never from the bundle: Alchemy's resource registry and Effect's
+ * service tags are identity-sensitive, and a second copy silently breaks both.
+ */
+const ALCHEMY_EXTERNALS = ["alchemy", "alchemy/*", "effect", "effect/*"];
+
+export interface BundleAlchemyEntryOptions {
+  /** The Alchemy entry to bundle, e.g. `alchemy.run.ts`. */
+  readonly entry: string;
+  /** Where to write the bundled ESM file, e.g. `.alchemy/deploy-entry.mjs`. */
+  readonly outfile: string;
+  /** esbuild's working directory; also the base for relative paths. */
+  readonly absWorkingDir?: 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
+   * still inlined, which is the whole point. `"bundle"` inlines dependencies
+   * too, minus the Alchemy/Effect externals, for a runner without the
+   * consumer's node_modules.
+   */
+  readonly packages?: "bundle" | "external";
+  /** Emit a sourcemap next to the outfile. Default `false`. */
+  readonly sourcemap?: boolean;
+  /** esbuild target. Default `node24`. */
+  readonly target?: string;
+  /** tsconfig to apply to the entry's sources. */
+  readonly tsconfig?: string;
+}
+
+/**
+ * Pre-bundle an Alchemy entry to a single ESM file, keeping `alchemy` and
+ * `effect` external (#268).
+ *
+ * Both repos that deploy through Alchemy wrote this: the Alchemy CLI runs a
+ * JavaScript entry, so a TypeScript `alchemy.run.ts` has to be flattened
+ * first, and the flattening must not swallow the two packages whose identity
+ * matters. Firedup additionally resolved esbuild *through vite* because it had
+ * no direct dependency on it; here esbuild is a plain dependency of this
+ * package and that hack can be deleted.
+ *
+ * Returns the absolute path of the file written.
+ */
+export const bundleAlchemyEntry = async (
+  options: BundleAlchemyEntryOptions
+): Promise<string> => {
+  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({
+    absWorkingDir: root,
+    bundle: true,
+    entryPoints: [path.resolve(root, options.entry)],
+    external: ALCHEMY_EXTERNALS,
+    format: "esm",
+    outfile,
+    packages: options.packages ?? "external",
+    platform: "node",
+    sourcemap: options.sourcemap ?? false,
+    target: options.target ?? "node24",
+    ...(options.tsconfig
+      ? { tsconfig: path.resolve(root, options.tsconfig) }
+      : {}),
+  });
+
+  return outfile;
+};

package/src/disposable-stage.ts

@@ -0,0 +1,115 @@
+/**
+ * The disposable Alchemy stage a local preview deploy runs in:
+ * `local-pr-<pr>-<short sha>` (#268).
+ *
+ * Two repos invented this grammar independently and then had to agree on it
+ * anyway, because the same cleanup sweeps delete these stages. A stage that
+ * does not match is not disposable, and destructive operations must refuse it.
+ */
+const LOCAL_PREVIEW_STAGE_PATTERN =
+  /^local-pr-(?<pr>[1-9]\d*)-(?<sha>[0-9a-f]{7,40})$/u;
+
+declare const localPreviewStageBrand: unique symbol;
+
+export type LocalPreviewStage = string & {
+  readonly [localPreviewStageBrand]: true;
+};
+
+export interface ParsedLocalPreviewStage {
+  readonly headShaPrefix: string;
+  readonly pr: number;
+  readonly stage: LocalPreviewStage;
+}
+
+export interface ParseLocalPreviewStageExpected {
+  /** Require the stage to belong to this pull request. */
+  readonly pr?: number;
+  /** Require the stage prefix to match this full 40-character head SHA. */
+  readonly headSha?: string;
+}
+
+/**
+ * Interpret an untrusted stage name through the one disposable-stage grammar.
+ * Returns `null` rather than throwing when the value or expected ownership
+ * does not match.
+ */
+export const parseLocalPreviewStage = (
+  stage: string,
+  expected: ParseLocalPreviewStageExpected = {}
+): ParsedLocalPreviewStage | null => {
+  const match = LOCAL_PREVIEW_STAGE_PATTERN.exec(stage);
+  if (!match?.groups) {
+    return null;
+  }
+
+  const pr = Number(match.groups.pr);
+  const headShaPrefix = match.groups.sha;
+  if (
+    !Number.isSafeInteger(pr) ||
+    (expected.pr !== undefined && pr !== expected.pr)
+  ) {
+    return null;
+  }
+  if (expected.headSha !== undefined) {
+    const headSha = expected.headSha.trim().toLowerCase();
+    if (
+      !/^[0-9a-f]{40}$/u.test(headSha) ||
+      !headSha.startsWith(headShaPrefix)
+    ) {
+      return null;
+    }
+  }
+
+  return {
+    headShaPrefix,
+    pr,
+    stage: stage as LocalPreviewStage,
+  };
+};
+
+/**
+ * Whether `stage` is disposable. Pass `pr` to also require PR ownership.
+ */
+export const isLocalPreviewStage = (
+  stage: string,
+  pr?: number
+): stage is LocalPreviewStage =>
+  parseLocalPreviewStage(stage, pr === undefined ? {} : { pr }) !== null;
+
+export interface LocalPreviewStageOptions {
+  /** The pull request number. */
+  readonly pr: number;
+  /** The full head SHA the preview is tied to. */
+  readonly headSha: string;
+  /** How much of the SHA to keep. Default 12; the grammar allows 7 to 40. */
+  readonly shaLength?: number;
+}
+
+/**
+ * Build the disposable stage name for a pull request head.
+ *
+ * Throws when the inputs cannot produce a valid stage, so a caller can never
+ * deploy into a name the cleanup sweep will not recognise.
+ */
+export const localPreviewStage = (
+  options: LocalPreviewStageOptions
+): LocalPreviewStage => {
+  const { headSha, pr, shaLength = 12 } = options;
+  if (!Number.isSafeInteger(pr) || pr < 1) {
+    throw new Error(`pr must be a positive safe integer, got ${pr}.`);
+  }
+  if (!Number.isInteger(shaLength) || shaLength < 7 || shaLength > 40) {
+    throw new Error(
+      `shaLength must be an integer from 7 through 40, got ${shaLength}.`
+    );
+  }
+
+  const normalizedHead = headSha.trim().toLowerCase();
+  if (!/^[0-9a-f]{40}$/u.test(normalizedHead)) {
+    throw new Error(
+      `headSha must be exactly 40 hexadecimal characters, got "${headSha}".`
+    );
+  }
+
+  return `local-pr-${pr}-${normalizedHead.slice(0, shaLength)}` as LocalPreviewStage;
+};

package/src/execute-alchemy-entry.ts

@@ -0,0 +1,78 @@
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+
+import type { BundleAlchemyEntryOptions } from "./bundle-alchemy-entry.ts";
+import { bundleAlchemyEntry } from "./bundle-alchemy-entry.ts";
+
+export interface ExecuteAlchemyEntryOptions {
+  /**
+   * CLI arguments before the bundled entry. The absolute entry path is always
+   * appended as the final argument.
+   */
+  readonly args: readonly string[];
+  readonly bundle: BundleAlchemyEntryOptions;
+  /** Child working directory. Defaults to the bundle root, then process.cwd. */
+  readonly cwd?: string;
+  /** Child environment. Defaults to process.env. */
+  readonly env?: NodeJS.ProcessEnv;
+  /** Consumer module context; normally the caller's import.meta.url. */
+  readonly from: string | URL;
+  /** Child stdio. Default "inherit". */
+  readonly stdio?: "inherit" | "pipe";
+}
+
+export interface ExecuteAlchemyEntryResult {
+  readonly bundledEntry: string;
+  readonly stderr: string | null;
+  readonly stdout: string | null;
+}
+
+/**
+ * Bundle a consumer-owned Alchemy entry, resolve that consumer's Alchemy CLI,
+ * run it under the current Node binary, and return only on a successful exit.
+ *
+ * Deploy/destroy/plan selection, stage admission, credentials, and every
+ * convergence or destructive-change policy remain the caller's responsibility.
+ */
+export const executeAlchemyEntry = async (
+  options: ExecuteAlchemyEntryOptions
+): Promise<ExecuteAlchemyEntryResult> => {
+  // Resolve first so a caller that does not own Alchemy fails before the
+  // bundle writes anything.
+  const cliEntry = createRequire(options.from).resolve(
+    "alchemy/bin/alchemy.js"
+  );
+  const bundledEntry = await bundleAlchemyEntry(options.bundle);
+  const result = spawnSync(
+    process.execPath,
+    [cliEntry, ...options.args, bundledEntry],
+    {
+      cwd: options.cwd ?? options.bundle.absWorkingDir ?? process.cwd(),
+      encoding: "utf-8",
+      env: options.env ?? process.env,
+      stdio: options.stdio ?? "inherit",
+    }
+  );
+
+  if (result.error) {
+    // Node's spawn error carries `spawnargs`; retaining it as `cause` would
+    // let ordinary recursive error logging reveal caller arguments.
+    throw new Error("Failed to start the Alchemy CLI.");
+  }
+  if (result.signal) {
+    throw new Error(`Alchemy CLI terminated by signal ${result.signal}.`);
+  }
+  if (result.status !== 0) {
+    throw new Error(
+      result.status === null
+        ? "Alchemy CLI exited without reporting a status."
+        : `Alchemy CLI exited with status ${result.status}.`
+    );
+  }
+
+  return {
+    bundledEntry,
+    stderr: result.stderr,
+    stdout: result.stdout,
+  };
+};

package/src/factory-workflow.ts

@@ -0,0 +1,208 @@
+import type { NodePnpmActionFamily, PinnedAction } from "./actions.ts";
+
+const PINNED_ACTION_PATTERN = /^[\w.-]+\/[\w.-]+@[0-9a-f]{40}$/u;
+const ACTION_TAG_PATTERN = /^v\d+(?:\.\d+){0,2}$/u;
+const RESERVED_ACTION_NAMES = new Set(["checkout", "setupNode", "setupPnpm"]);
+
+export interface WorkflowStep {
+  readonly name: string;
+  readonly uses?: string;
+  readonly with?: Readonly<Record<string, string>>;
+  readonly run?: string;
+}
+
+export interface CheckoutStepOptions {
+  readonly name?: string;
+  readonly ref?: string;
+}
+
+export interface SetupNodeStepOptions {
+  readonly cacheDependencyPath?: string;
+  readonly nodeVersionFile?: string;
+}
+
+export interface InstallStepOptions {
+  readonly name?: string;
+  readonly run?: string;
+}
+
+export interface FactoryWorkflowSetupOptions {
+  readonly checkout?: CheckoutStepOptions;
+  readonly install?: InstallStepOptions;
+  readonly setupNode?: SetupNodeStepOptions;
+}
+
+export interface FactoryWorkflowOptions<
+  Additional extends Readonly<Record<string, PinnedAction>>,
+> {
+  /**
+   * Required complete family. There is no default, so adopting this package
+   * cannot silently move a consumer from one action major to another.
+   */
+  readonly actionFamily: NodePnpmActionFamily;
+  /** Every workflow-specific action source this artifact owns. */
+  readonly additionalActions?: Additional;
+  readonly generated: {
+    /** Generator path relative to the repository root. */
+    readonly source: string;
+    /** Exact command that regenerates the emitted workflow. */
+    readonly regenerate: string;
+  };
+  readonly setup?: FactoryWorkflowSetupOptions;
+}
+
+type FamilyActions = Omit<NodePnpmActionFamily, "id">;
+
+export interface FactoryWorkflowArtifact<
+  Additional extends Readonly<Record<string, PinnedAction>>,
+> {
+  readonly actionFamilyId: string;
+  readonly actions: Readonly<FamilyActions & Additional>;
+  /** Checkout → pnpm → Node → install, customized by named role. */
+  readonly setupSteps: readonly WorkflowStep[];
+  /**
+   * Structurally accepted by gagen's `writeOrLint`; this package deliberately
+   * has no gagen dependency.
+   */
+  readonly writeOptions: {
+    readonly header: string;
+    readonly pinDeps: false;
+  };
+}
+
+const assertSingleLine = (name: string, value: string): void => {
+  if (value.trim() !== value || value.length === 0 || /[\r\n]/u.test(value)) {
+    throw new Error(`${name} must be a single non-empty line.`);
+  }
+};
+
+const actionRepository = (action: PinnedAction): string =>
+  action.uses.slice(0, action.uses.indexOf("@"));
+
+const assertPinnedAction = (
+  name: string,
+  action: PinnedAction,
+  expectedRepository?: string
+): void => {
+  if (!PINNED_ACTION_PATTERN.test(action.uses)) {
+    throw new Error(
+      `${name} must use owner/repository@<40-character commit SHA>, got "${action.uses}".`
+    );
+  }
+  if (expectedRepository && actionRepository(action) !== expectedRepository) {
+    throw new Error(
+      `${name} must pin ${expectedRepository}, got ${actionRepository(action)}.`
+    );
+  }
+  if (!ACTION_TAG_PATTERN.test(action.tag)) {
+    throw new Error(
+      `${name} tag must be vN, vN.N, or vN.N.N, got "${action.tag}".`
+    );
+  }
+};
+
+const usesStep = (
+  fallbackName: string,
+  action: PinnedAction
+): WorkflowStep => ({
+  name: fallbackName,
+  uses: action.uses,
+});
+
+const assertActionFamily = (family: NodePnpmActionFamily): void => {
+  assertSingleLine("actionFamily.id", family.id);
+  assertPinnedAction("checkout", family.checkout, "actions/checkout");
+  assertPinnedAction("setupNode", family.setupNode, "actions/setup-node");
+  assertPinnedAction("setupPnpm", family.setupPnpm, "pnpm/action-setup");
+};
+
+const assertAdditionalActions = (
+  actions: Readonly<Record<string, PinnedAction>>
+): void => {
+  for (const [name, action] of Object.entries(actions)) {
+    if (RESERVED_ACTION_NAMES.has(name)) {
+      throw new Error(
+        `${name} is reserved by the Node/pnpm action family and cannot be replaced by additionalActions.`
+      );
+    }
+    assertPinnedAction(name, action);
+  }
+};
+
+const setupSteps = (
+  family: NodePnpmActionFamily,
+  setup: FactoryWorkflowSetupOptions = {}
+): readonly WorkflowStep[] => {
+  const installRun = setup.install?.run ?? "pnpm install --frozen-lockfile";
+  if (/(?:^|\s)--ignore-scripts(?:\s|$)/u.test(installRun)) {
+    throw new Error(
+      "The install step must not use --ignore-scripts; workspace prepare scripts build required package artifacts."
+    );
+  }
+
+  const { checkout, setupNode } = setup;
+  return Object.freeze([
+    {
+      name: checkout?.name ?? "Checkout",
+      uses: family.checkout.uses,
+      ...(checkout?.ref ? { with: { ref: checkout.ref } } : {}),
+    },
+    usesStep("Setup pnpm", family.setupPnpm),
+    {
+      name: "Setup Node",
+      uses: family.setupNode.uses,
+      with: {
+        cache: "pnpm",
+        ...(setupNode?.cacheDependencyPath
+          ? { "cache-dependency-path": setupNode.cacheDependencyPath }
+          : {}),
+        "node-version-file": setupNode?.nodeVersionFile ?? ".nvmrc",
+      },
+    },
+    {
+      name: setup.install?.name ?? "Install workspace",
+      run: installRun,
+    },
+  ]);
+};
+
+/**
+ * Own one generated workflow source's action pins, setup block, provenance
+ * banner, and gagen pinning policy as a single artifact.
+ *
+ * The caller still owns workflow topology, jobs, runners, permissions, and
+ * every deployment policy decision.
+ */
+export const factoryWorkflow = <
+  const Additional extends Readonly<Record<string, PinnedAction>> = Record<
+    never,
+    never
+  >,
+>(
+  options: FactoryWorkflowOptions<Additional>
+): FactoryWorkflowArtifact<Additional> => {
+  assertSingleLine("generated.source", options.generated.source);
+  assertSingleLine("generated.regenerate", options.generated.regenerate);
+  assertActionFamily(options.actionFamily);
+  assertAdditionalActions(options.additionalActions ?? {});
+
+  const actions = Object.freeze({
+    checkout: options.actionFamily.checkout,
+    setupNode: options.actionFamily.setupNode,
+    setupPnpm: options.actionFamily.setupPnpm,
+    ...(options.additionalActions ?? ({} as Additional)),
+  }) as Readonly<FamilyActions & Additional>;
+
+  return Object.freeze({
+    actionFamilyId: options.actionFamily.id,
+    actions,
+    setupSteps: setupSteps(options.actionFamily, options.setup),
+    writeOptions: Object.freeze({
+      header: [
+        `# GENERATED BY ${options.generated.source} -- DO NOT EDIT.`,
+        `# Regenerate: ${options.generated.regenerate}`,
+      ].join("\n"),
+      pinDeps: false as const,
+    }),
+  });
+};

package/src/index.ts

@@ -0,0 +1,43 @@
+/**
+ * `@patronage/factory-ci` — the CI and deploy building blocks that already
+ * repeat across Patronage factory projects (#266, #268).
+ *
+ * A pure library: no `bin`, no `alchemy` or `effect` dependency, no config
+ * surface of its own. Everything takes a plain typed options object; mapping
+ * `software-factory.profile.json` into those objects is the profile's job, not
+ * this package's (ADR 0021).
+ */
+
+export {
+  NODE_PNPM_ACTION_FAMILY_V4,
+  type NodePnpmActionFamily,
+  type PinnedAction,
+} from "./actions.ts";
+export {
+  bundleAlchemyEntry,
+  type BundleAlchemyEntryOptions,
+} from "./bundle-alchemy-entry.ts";
+export {
+  isLocalPreviewStage,
+  localPreviewStage,
+  type LocalPreviewStage,
+  type LocalPreviewStageOptions,
+  type ParsedLocalPreviewStage,
+  type ParseLocalPreviewStageExpected,
+  parseLocalPreviewStage,
+} from "./disposable-stage.ts";
+export {
+  type CheckoutStepOptions,
+  type FactoryWorkflowArtifact,
+  type FactoryWorkflowOptions,
+  type FactoryWorkflowSetupOptions,
+  factoryWorkflow,
+  type InstallStepOptions,
+  type SetupNodeStepOptions,
+  type WorkflowStep,
+} from "./factory-workflow.ts";
+export {
+  type ExecuteAlchemyEntryOptions,
+  type ExecuteAlchemyEntryResult,
+  executeAlchemyEntry,
+} from "./execute-alchemy-entry.ts";