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

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,
@@ -397,14 +536,18 @@ const isProofReuseCommand = (value) => {
 *
 * `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.
 */
 const proofReuseRequiredCommands = (commands) => {
 	if (!(Array.isArray(commands) && commands.length > 0)) return;
 	if (!commands.every(isProofReuseCommand)) return;
-	return [...new Set(commands.map(({ name }) => name))].toSorted();
+	const names = commands.map(({ name }) => name);
+	if (new Set(names).size !== names.length) return;
+	return names.toSorted();
 };
 /**
 * jq program: every page of the Checks API result in, three sanitized lines
@@ -736,10 +879,10 @@ const factoryProofGateStep = (options) => Object.freeze({
 * as CI quietly verifying nothing. The drift is real history: #227 wired a
 * workspace member into CI while the profile never learned about it.
 */
-const proofReuseCoverage = ({ commands, equivalents = {}, skipped }) => {
+const proofReuseCoverage = ({ commands, skipped }) => {
 	const requiredCommands = proofReuseRequiredCommands(commands) ?? [];
 	const proven = new Set(requiredCommands.length > 0 ? commands.map(({ command }) => command.trim()) : []);
-	const uncovered = [...new Set((Array.isArray(skipped) ? skipped : []).map((command) => String(command).trim()).filter((command) => command.length > 0 && !(proven.has(command) || Object.hasOwn(equivalents, command))))].toSorted();
+	const uncovered = [...new Set((Array.isArray(skipped) ? skipped : []).map((command) => String(command).trim()).filter((command) => command.length > 0 && !proven.has(command)))].toSorted();
 	return Object.freeze({
 		covered: requiredCommands.length > 0 && uncovered.length === 0,
 		requiredCommands,
@@ -755,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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/factory-ci",
-  "version": "0.2.0",
+  "version": "1.0.0-alpha.4",
   "description": "Deep CI and deploy building blocks for Patronage factory projects: workflow source artifacts, hosted diff classification, Alchemy entry execution, and disposable-stage semantics",
   "keywords": [
     "alchemy",
@@ -38,6 +38,7 @@
   },
   "devDependencies": {
     "@types/node": "24.13.3",
+    "@vitest/coverage-v8": "4.1.10",
     "oxfmt": "0.59.0",
     "oxlint": "1.74.0",
     "tsdown": "0.21.10",
@@ -56,6 +57,8 @@
     "prefix": "bash ../scripts/ensure-worktree-bootstrap.sh",
     "fix": "ultracite fix",
     "pretest": "bash ../scripts/ensure-worktree-bootstrap.sh",
+    "precoverage": "bash ../scripts/ensure-worktree-bootstrap.sh",
+    "coverage": "vitest run --coverage",
     "test": "vitest run",
     "pretypecheck": "bash ../scripts/ensure-worktree-bootstrap.sh",
     "typecheck": "tsc --noEmit"

package/src/bundle-alchemy-entry.ts

@@ -10,6 +10,79 @@ import { build } from "esbuild";
  */
 const ALCHEMY_EXTERNALS = ["alchemy", "alchemy/*", "effect", "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: string): string | undefined =>
+  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: Readonly<Record<string, string>>
+): void => {
+  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: string): boolean => {
+  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: readonly string[]): void => {
+  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.`
+    );
+  }
+};
+
 export interface BundleAlchemyEntryOptions {
   /** The Alchemy entry to bundle, e.g. `alchemy.run.ts`. */
   readonly entry: string;
@@ -17,6 +90,18 @@ export 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
@@ -49,6 +134,10 @@ export interface BundleAlchemyEntryOptions {
 export const bundleAlchemyEntry = async (
   options: BundleAlchemyEntryOptions
 ): Promise<string> => {
+  if (options.alias) {
+    assertAliasKeysAreAdmissible(options.alias);
+  }
+
   const root = options.absWorkingDir
     ? path.resolve(options.absWorkingDir)
     : process.cwd();
@@ -56,21 +145,25 @@ export const bundleAlchemyEntry = async (
 
   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;
 };