dorfl 0.14.2 → 0.15.0

package/src/install-ci-action-pins.ts

@@ -0,0 +1,209 @@
+/**
+ * The ONE table of third-party GitHub Actions that `dorfl install-ci` emits,
+ * each pinned to a full 40-character commit SHA, plus the regeneration rule that
+ * keeps a consumer repository's own pins.
+ *
+ * WHY SHAS. A tag such as `@v5` can be moved by whoever controls the action's
+ * repository, so a compromised or careless release reaches every job that uses
+ * it, including dorfl's jobs that hold `contents: write` and a provider API key.
+ * A commit SHA cannot move. This is GitHub's own hardening guidance ("Using
+ * third-party actions", Security hardening for GitHub Actions).
+ *
+ * THE FORMAT. Every reference is emitted as `owner/repo@<40-hex-sha> # vX.Y.Z`,
+ * the exact shape Dependabot writes and rewrites, so a consumer that enables
+ * Dependabot's `github-actions` ecosystem (with `/.github/actions/*` in
+ * `directories` for the composite action) gets reviewable bump PRs.
+ *
+ * HOW EACH SHA WAS RESOLVED (2026-09-26). For each tag:
+ *   1. `git ls-remote --tags https://github.com/<owner>/<repo>.git`, reading the
+ *      peeled `refs/tags/<tag>^{}` line when the tag is annotated (that line is
+ *      the COMMIT; the unpeeled line is the tag OBJECT and must never be used),
+ *      else the tag line itself for a lightweight tag;
+ *   2. cross-checked with `gh api repos/<owner>/<repo>/git/ref/tags/<tag>`
+ *      (object type) and `gh api repos/<owner>/<repo>/commits/<sha>` (the SHA is
+ *      a commit that exists in the repository).
+ *
+ *   actions/checkout v7.0.1: lightweight tag, `git/ref` type `commit`,
+ *     3d3c42e5aac5ba805825da76410c181273ba90b1 ("prep v7.0.1 release (#2531)").
+ *     The floating `v7` tag points at the same commit. v7 is the current major
+ *     and adds the fork-PR checkout block for `pull_request_target` /
+ *     `workflow_run` that v5 lacks; the inputs dorfl passes (`fetch-depth`,
+ *     `persist-credentials`) are unchanged.
+ *   actions/setup-node v7.0.0: lightweight tag, `git/ref` type `commit`,
+ *     820762786026740c76f36085b0efc47a31fe5020 ("Migrate to ESM and upgrade
+ *     dependencies (#1574)"). The floating `v7` tag points at the same commit.
+ *     `node-version` and `package-manager-cache` are still inputs (see the
+ *     comment on the setup-node step in `generateSetupAction`).
+ *   pnpm/action-setup v6.1.0: ANNOTATED tag. `git/ref` type `tag` with object
+ *     d9184bf108216479bc5a137cc391f4d7b14c870b (the tag object, NOT usable);
+ *     peeled `^{}` and `gh api .../git/tags/d9184bf...` both give the commit
+ *     ea17c68df8912ef543352723c149a84f56e3d413 ("feat: support pnpm v12
+ *     (#288)"). With no `version` input it still reads `packageManager` from
+ *     package.json, which is how dorfl's workspace mode uses it.
+ *
+ * Resolved 2026-09-28 (task `ci-split-generate-workflows`, the split CI item
+ * workflow's handoff artifact; the spec requires at least v4.1.3 of both):
+ *   actions/upload-artifact v7.0.1: lightweight tag (`ls-remote` lists no
+ *     peeled `^{}` line for it), `git/ref` type `commit`,
+ *     043fb46d1a93c77aae656e7c1c64a875d1fc6a0a ("Merge pull request #797 from
+ *     actions/yacaovsnc/update-dependency"). The floating `v7` tag points at
+ *     the same commit. The inputs dorfl passes (`name`, `path`,
+ *     `retention-days`, `if-no-files-found`) are unchanged since v4.
+ *   actions/download-artifact v8.0.1: lightweight tag, `git/ref` type
+ *     `commit`, 3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c ("Add regression tests
+ *     for CJK characters (#471)"). The floating `v8` tag points at the same
+ *     commit. v8 fails on a digest mismatch by default (`digest-mismatch:
+ *     error`), which is what the apply job wants; dorfl passes `name` and
+ *     `path` and never `run-id` (the apply job reads its OWN run's artifact).
+ *
+ * To bump a pin: resolve the new tag the same way, update the entry, and record
+ * the resolution above. `install-ci-actions-pinned.test.ts` fails on any
+ * emitted `uses:` that is not a full SHA.
+ */
+
+/** One pinned third-party action. */
+export interface ActionPin {
+	/** `owner/repo`, or `owner/repo/path` for an action in a subdirectory. */
+	readonly action: string;
+	/** The full 40-character lowercase commit SHA (never a tag object). */
+	readonly sha: string;
+	/** The release tag the SHA was resolved from, for the trailing comment. */
+	readonly version: string;
+}
+
+/** Every third-party action dorfl's generators emit. */
+export const ACTION_PINS = {
+	checkout: {
+		action: 'actions/checkout',
+		sha: '3d3c42e5aac5ba805825da76410c181273ba90b1',
+		version: 'v7.0.1',
+	},
+	setupNode: {
+		action: 'actions/setup-node',
+		sha: '820762786026740c76f36085b0efc47a31fe5020',
+		version: 'v7.0.0',
+	},
+	pnpmSetup: {
+		action: 'pnpm/action-setup',
+		sha: 'ea17c68df8912ef543352723c149a84f56e3d413',
+		version: 'v6.1.0',
+	},
+	uploadArtifact: {
+		action: 'actions/upload-artifact',
+		sha: '043fb46d1a93c77aae656e7c1c64a875d1fc6a0a',
+		version: 'v7.0.1',
+	},
+	downloadArtifact: {
+		action: 'actions/download-artifact',
+		sha: '3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c',
+		version: 'v8.0.1',
+	},
+} as const satisfies Record<string, ActionPin>;
+
+/**
+ * The value to put after `uses: ` for a pinned action:
+ * `owner/repo@<sha> # vX.Y.Z` (the Dependabot format).
+ */
+export function pinnedUses(pin: ActionPin): string {
+	return `${pin.action}@${pin.sha} # ${pin.version}`;
+}
+
+// ─── preserving the consumer's pins on regeneration ─────────────────────────
+
+/**
+ * A `uses:` step line: the prefix (indentation, an optional `- ` list marker,
+ * `uses:` and its spacing), then the VALUE (an optionally quoted
+ * `action@ref`), then an optional trailing comment. Matched per line, which is
+ * how both dorfl's templates and Dependabot write these lines. A flow-style or
+ * multi-line `uses:` value is not recognised (and so not preserved).
+ */
+const USES_LINE =
+	/^(\s*(?:-\s+)?uses:[ \t]+)((['"]?)([^\s'"@#]+)@([^\s'"#]+)\3(?:[ \t]+#.*)?)[ \t]*$/;
+
+/**
+ * A full commit SHA (what counts as "pinned"). Case-insensitive here, so a
+ * consumer's uppercase pin is still kept; dorfl itself emits lowercase.
+ */
+const FULL_SHA = /^[0-9a-f]{40}$/i;
+
+/** The lookup key for an action: GitHub treats `owner/repo` case-insensitively. */
+function actionKey(action: string): string {
+	return action.toLowerCase();
+}
+
+/** A remote action key (`owner/repo[/path]`), i.e. not `./local` nor `docker://`. */
+function isRemoteAction(action: string): boolean {
+	return !action.startsWith('.') && /^[^/\s]+\/[^/\s]+/.test(action);
+}
+
+/** Parse the version out of a trailing `# v1.2.3` comment, for ranking. */
+function versionOf(tail: string): number[] | undefined {
+	const m = /#\s*v?(\d+(?:\.\d+)*)/.exec(tail);
+	return m ? m[1].split('.').map(Number) : undefined;
+}
+
+/** Compare two parsed versions; a missing version ranks lowest. */
+function compareVersions(a?: number[], b?: number[]): number {
+	if (!a || !b) return (a ? 1 : 0) - (b ? 1 : 0);
+	for (let i = 0; i < Math.max(a.length, b.length); i++) {
+		const d = (a[i] ?? 0) - (b[i] ?? 0);
+		if (d !== 0) return d;
+	}
+	return 0;
+}
+
+/**
+ * Collect the SHA pins an existing file already carries, keyed by action
+ * (`owner/repo[/path]`). The value is the whole `uses:` value with its trailing
+ * comment, exactly as written. When the file pins the same action to several
+ * different SHAs, the one whose `# vX.Y.Z` comment is highest wins (ties: the
+ * first in the file), so a partial manual bump is never undone.
+ */
+export function existingPins(existing: string): Map<string, string> {
+	const pins = new Map<string, string>();
+	// `\r?\n`: a CRLF checkout (Windows, `core.autocrlf`) must not hide its pins,
+	// or dorfl's default would silently replace them.
+	for (const line of existing.split(/\r?\n/)) {
+		const m = USES_LINE.exec(line);
+		if (!m) continue;
+		const [, , value, , action, ref] = m;
+		if (!isRemoteAction(action) || !FULL_SHA.test(ref)) continue;
+		const key = actionKey(action);
+		const current = pins.get(key);
+		if (
+			current === undefined ||
+			compareVersions(versionOf(value), versionOf(current)) > 0
+		) {
+			pins.set(key, value);
+		}
+	}
+	return pins;
+}
+
+/**
+ * Rewrite a freshly generated workflow / composite action so every `uses:` of an
+ * action that `existing` already pins to a full SHA keeps the consumer's
+ * reference and trailing comment. Matching is by action (`owner/repo`, plus the
+ * path for an action in a subdirectory), never by position. An existing TAG is
+ * not a pin: the generated reference (dorfl's SHA) stays. So the result never
+ * swaps a SHA for a tag. Only the value after `uses: ` changes; indentation and
+ * every other line are the generated ones.
+ */
+export function preserveExistingPins(
+	generated: string,
+	existing: string | undefined,
+): string {
+	if (existing === undefined) return generated;
+	const pins = existingPins(existing);
+	if (pins.size === 0) return generated;
+	return generated
+		.split('\n')
+		.map((line) => {
+			const m = USES_LINE.exec(line);
+			if (!m) return line;
+			const [, prefix, , , action] = m;
+			const kept = pins.get(actionKey(action));
+			return kept === undefined ? line : `${prefix}${kept}`;
+		})
+		.join('\n');
+}

package/src/install-ci-actions-pr-creation.ts

@@ -0,0 +1,186 @@
+/**
+ * The "Allow GitHub Actions to create and approve pull requests" STEP for
+ * `install-ci` (task `install-ci-enables-actions-pr-creation`). A new GitHub
+ * repository has this setting OFF (`GET repos/<r>/actions/permissions/workflow`
+ * answers `can_approve_pull_request_reviews: false`), and with it off GitHub
+ * refuses every pull request the generated workflows try to open with the
+ * ambient `GITHUB_TOKEN`, so propose mode silently opens no PR. dorfl's own
+ * repository has it on, which is why this was only found in a fresh sandbox.
+ *
+ * BEHAVIOUR (mirrors the Tier-1 branch-protection step,
+ * `install-ci-branch-protection.ts`: auto-when-admin, instruct-otherwise):
+ *
+ *   - READ the setting ({@link CIProviderContext.getActionsWorkflowPermissions}).
+ *     Already on: leave it alone and say so.
+ *   - Off (or unreadable) and the credential is repo-admin-scoped: SET it
+ *     ({@link CIProviderContext.setActionsWorkflowPermissions}) with
+ *     `can_approve_pull_request_reviews: true`, carrying the
+ *     `default_workflow_permissions` value that was read so the GITHUB_TOKEN's
+ *     default scope is preserved, never widened or narrowed.
+ *   - Not admin (or unknown): never call the API; print the exact `gh api`
+ *     command and the settings page instead. A rejected PUT is `failed` and
+ *     prints the same command to retry by hand.
+ *   - `--fake`: report what would be checked, call nothing.
+ *
+ * Never throws: a failure is reported in the result and the log, so install-ci's
+ * later steps still run.
+ */
+
+import type {
+	ActionsWorkflowPermissions,
+	CIProviderContext,
+} from './install-ci-core.js';
+
+export type {ActionsWorkflowPermissions};
+
+/**
+ * The exact `gh api` command a user runs to turn the setting on by hand. When
+ * the current `default_workflow_permissions` is known it is passed back
+ * unchanged; when it is not, the field is omitted, which leaves it as it is on
+ * GitHub (both PUT fields are optional). Pure string, no I/O.
+ */
+export function formatManualActionsPrCreationCommand(
+	repo: string,
+	defaultWorkflowPermissions?: string,
+): string {
+	const keep =
+		defaultWorkflowPermissions !== undefined
+			? ` -f default_workflow_permissions=${defaultWorkflowPermissions}`
+			: '';
+	return (
+		`gh api -X PUT repos/${repo}/actions/permissions/workflow ` +
+		`-F can_approve_pull_request_reviews=true${keep}`
+	);
+}
+
+/** Options for {@link installCIActionsPrCreationStep}. */
+export interface ActionsPrCreationStepOptions {
+	/** The CI-provider seam (GitHub adapter in production; stub in tests). */
+	ctx: CIProviderContext;
+	/** Snapshot mode: never call the live API. */
+	fake?: boolean;
+	/** Sink for human-facing progress lines. */
+	log: (line: string) => void;
+}
+
+/** The outcome of one actions-PR-creation step run. */
+export interface ActionsPrCreationStepResult {
+	/**
+	 * - `already-enabled`: the setting was on; nothing was changed;
+	 * - `set`: it was off (or unreadable), admin scope, the PUT succeeded;
+	 * - `failed`: admin scope, the PUT was rejected (detail in `error`);
+	 * - `instructed`: not admin (or unknown), the manual command was printed;
+	 * - `skipped-no-repo`: the provider context has no `repo` known;
+	 * - `skipped-no-seam`: the provider does not implement the seam;
+	 * - `skipped-fake`: `--fake` snapshot mode (no real API touched).
+	 */
+	status:
+		| 'already-enabled'
+		| 'set'
+		| 'failed'
+		| 'instructed'
+		| 'skipped-no-repo'
+		| 'skipped-no-seam'
+		| 'skipped-fake';
+	/** The permissions read before any change (`undefined` when unreadable). */
+	before?: ActionsWorkflowPermissions;
+	/** The detected admin-scope verdict (`true`/`false`/`undefined`=unknown). */
+	adminScope?: boolean;
+	/** The failure detail when `status === 'failed'`. */
+	error?: string;
+}
+
+const LABEL = 'actions PR creation';
+
+/**
+ * Check, and when off and permitted, enable the repository setting that lets
+ * GitHub Actions create pull requests (see the module header).
+ */
+export async function installCIActionsPrCreationStep(
+	options: ActionsPrCreationStepOptions,
+): Promise<ActionsPrCreationStepResult> {
+	const {ctx, log, fake} = options;
+
+	if (fake) {
+		log(
+			`${LABEL}: skipped (--fake; would check that "Allow GitHub Actions to create and approve pull requests" is on, and enable it if not)`,
+		);
+		return {status: 'skipped-fake'};
+	}
+	if (
+		!ctx.getActionsWorkflowPermissions ||
+		!ctx.setActionsWorkflowPermissions
+	) {
+		log(
+			`${LABEL}: skipped (provider does not implement the seam, non-GitHub host).`,
+		);
+		return {status: 'skipped-no-seam'};
+	}
+	if (!ctx.repo) {
+		log(`${LABEL}: skipped (repo unknown, pass --repo to enable).`);
+		return {status: 'skipped-no-repo'};
+	}
+	const repo = ctx.repo;
+
+	const before = await ctx
+		.getActionsWorkflowPermissions()
+		.catch(() => undefined);
+	if (before?.canApprovePullRequestReviews === true) {
+		log(
+			`${LABEL}: "Allow GitHub Actions to create and approve pull requests" is already on for ${repo}.`,
+		);
+		return {status: 'already-enabled', before};
+	}
+
+	const keep = before?.defaultWorkflowPermissions;
+	const adminScope = ctx.getRepoAdminScope
+		? await ctx.getRepoAdminScope().catch(() => undefined)
+		: undefined;
+
+	if (adminScope !== true) {
+		log(
+			before === undefined
+				? `${LABEL}: could not read "Allow GitHub Actions to create and approve pull requests" for ${repo}, and no admin-scoped credential was detected.`
+				: `${LABEL}: "Allow GitHub Actions to create and approve pull requests" is OFF for ${repo}, and no admin-scoped credential was detected.`,
+		);
+		log(
+			'  With it off, propose mode opens no pull request (GitHub refuses PRs created with GITHUB_TOKEN).',
+		);
+		log(
+			'  install-ci will NOT call the GitHub API. Run this yourself (admin token required):',
+		);
+		log(`    ${formatManualActionsPrCreationCommand(repo, keep)}`);
+		log(
+			`  Manual UI fallback: https://github.com/${repo}/settings/actions ` +
+				'→ "Workflow permissions" → tick "Allow GitHub Actions to create and approve pull requests" → Save.',
+		);
+		return {status: 'instructed', before, adminScope};
+	}
+
+	try {
+		// Carry the default scope through unchanged; when it could not be read,
+		// omit it so GitHub keeps whatever it is.
+		await ctx.setActionsWorkflowPermissions({
+			canApprovePullRequestReviews: true,
+			...(keep !== undefined ? {defaultWorkflowPermissions: keep} : {}),
+		});
+	} catch (err) {
+		const error = err instanceof Error ? err.message : String(err);
+		log(`${LABEL}: FAILED (${error})`);
+		log(
+			'  With it off, propose mode opens no pull request (GitHub refuses PRs created with GITHUB_TOKEN).',
+		);
+		log(
+			`  Retry by hand (admin token required):\n` +
+				`    ${formatManualActionsPrCreationCommand(repo, keep)}`,
+		);
+		return {status: 'failed', before, adminScope, error};
+	}
+	log(
+		`${LABEL}: enabled "Allow GitHub Actions to create and approve pull requests" on ${repo}` +
+			(keep !== undefined
+				? ` (default_workflow_permissions kept as ${keep}).`
+				: '.'),
+	);
+	return {status: 'set', before, adminScope};
+}

package/src/install-ci-capabilities/dorfl-item.ts

@@ -0,0 +1,33 @@
+/**
+ * The SPLIT CI ITEM capability emitter (spec `ci-agent-job-without-write-token`,
+ * task `ci-split-generate-workflows`). A SELF-REGISTERING module (see
+ * `example-noop.ts`): it emits `dorfl-item.yml` (the lock, agent and apply jobs
+ * of ONE item) and `dorfl-item-dispatch.yml` (the per-item dispatch wrapper the
+ * advance tick starts), which the advance-lifecycle and intake workflows call.
+ *
+ * The workflow text lives in `dorfl-item-template.ts`; this file is the thin
+ * registry-wiring shim.
+ */
+
+import {registerCapability} from '../install-ci-core.js';
+import {
+	ITEM_DISPATCH_WORKFLOW_PATH,
+	ITEM_WORKFLOW_PATH,
+	generateItemDispatchWorkflow,
+	generateItemWorkflow,
+} from '../dorfl-item-template.js';
+
+registerCapability({
+	id: 'dorfl-item',
+	label:
+		'Run each CI item as lock, agent and apply jobs (the per-item workflow the advance tick and intake call)',
+	emit(config) {
+		return [
+			{path: ITEM_WORKFLOW_PATH, content: generateItemWorkflow(config)},
+			{
+				path: ITEM_DISPATCH_WORKFLOW_PATH,
+				content: generateItemDispatchWorkflow(config),
+			},
+		];
+	},
+});