dorfl 0.14.2 → 0.15.0

package/src/install-ci-github.ts

@@ -5,19 +5,27 @@
  * wizard / config / `models.json` / `--export-config` / `--fake` / secret
  * orchestration; THIS adapter only supplies the GitHub-specific I/O (repo
  * detection, `gh secret set`, the optional `delete_branch_on_merge` repo
- * setting). Because the seam is the boundary, a second CI provider could be added
+ * setting, branch protection, and the Actions workflow permissions that let
+ * GitHub Actions open pull requests). Because the seam is the boundary, a second CI provider could be added
  * WITHOUT touching the core (US #7/#10).
  *
  * `install-ci` uses the SEAMS, never `gh` directly in the core: this adapter is
  * the ONLY place that shells out to `gh`, and it does so behind the seam so tests
  * stub it entirely (no network, no real `gh`, no real GitHub repo detection). The
  * adapter NEVER `--force`s and degrades gracefully when `gh` is missing.
+ *
+ * WRITE-SEAM EXEMPT (task `ci-split-route-direct-writes-through-seams`): the
+ * `gh secret set` / `gh api` writes here (secrets, rulesets, branch protection,
+ * repo settings, Actions workflow permissions) are only reached from the human-run `install-ci` wizard, never
+ * from a CI job, so they stay on this adapter's own `runGh` wrapper instead of a
+ * dorfl write seam.
  */
 
 import {run, type RunResult} from './git.js';
 import {DEFAULT_GH_BIN} from './github.js';
 import {
 	parseRepoVisibility,
+	type ActionsWorkflowPermissions,
 	type CIProviderContext,
 	type RepoVisibility,
 } from './install-ci-core.js';
@@ -366,6 +374,72 @@ export class GitHubCIContext implements CIProviderContext {
 		}
 	}
 
+	/**
+	 * Read the repo's Actions workflow permissions via
+	 * `gh api repos/<repo>/actions/permissions/workflow`. Returns `undefined`
+	 * when `gh` is unavailable / the repo is unknown / the call fails (it needs
+	 * repo-admin read on some token kinds) / the answer is not the expected shape.
+	 */
+	async getActionsWorkflowPermissions(): Promise<
+		ActionsWorkflowPermissions | undefined
+	> {
+		if (!this.repo) {
+			return undefined;
+		}
+		const result = this.runGh([
+			'api',
+			`repos/${this.repo}/actions/permissions/workflow`,
+		]);
+		if (result === undefined || result.status !== 0) {
+			return undefined;
+		}
+		return parseActionsWorkflowPermissions(result.stdout);
+	}
+
+	/**
+	 * Set the repo's Actions workflow permissions via
+	 * `gh api -X PUT repos/<repo>/actions/permissions/workflow`, sending ONLY the
+	 * fields given (an omitted field keeps its GitHub value). `-F` sends the
+	 * boolean typed, `-f` the string. Throws on failure.
+	 */
+	async setActionsWorkflowPermissions(
+		permissions: Partial<ActionsWorkflowPermissions>,
+	): Promise<void> {
+		if (!this.repo) {
+			throw new Error('cannot set actions workflow permissions: repo unknown');
+		}
+		const args = [
+			'api',
+			'-X',
+			'PUT',
+			`repos/${this.repo}/actions/permissions/workflow`,
+		];
+		if (permissions.canApprovePullRequestReviews !== undefined) {
+			args.push(
+				'-F',
+				`can_approve_pull_request_reviews=${permissions.canApprovePullRequestReviews}`,
+			);
+		}
+		if (permissions.defaultWorkflowPermissions !== undefined) {
+			args.push(
+				'-f',
+				`default_workflow_permissions=${permissions.defaultWorkflowPermissions}`,
+			);
+		}
+		const result = this.runGh(args);
+		if (result === undefined) {
+			throw new Error(
+				'gh not available; cannot set actions workflow permissions',
+			);
+		}
+		if (result.status !== 0) {
+			throw new Error(
+				`gh api PUT repos/${this.repo}/actions/permissions/workflow failed: ` +
+					(result.stderr.trim() || 'unknown error'),
+			);
+		}
+	}
+
 	/**
 	 * Render the GitHub project-setup payload to the steps fragment the
 	 * composite setup action splices in FIRST. Free-function delegate so the
@@ -394,6 +468,37 @@ export class GitHubCIContext implements CIProviderContext {
 	}
 }
 
+/**
+ * Parse the JSON body of `GET repos/<r>/actions/permissions/workflow` into
+ * {@link ActionsWorkflowPermissions}, or `undefined` when it is not that shape
+ * (unparseable, or either field missing / mistyped). Pure, no I/O.
+ */
+export function parseActionsWorkflowPermissions(
+	body: string,
+): ActionsWorkflowPermissions | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(body);
+	} catch {
+		return undefined;
+	}
+	if (typeof parsed !== 'object' || parsed === null) {
+		return undefined;
+	}
+	const {default_workflow_permissions, can_approve_pull_request_reviews} =
+		parsed as Record<string, unknown>;
+	if (
+		typeof default_workflow_permissions !== 'string' ||
+		typeof can_approve_pull_request_reviews !== 'boolean'
+	) {
+		return undefined;
+	}
+	return {
+		defaultWorkflowPermissions: default_workflow_permissions,
+		canApprovePullRequestReviews: can_approve_pull_request_reviews,
+	};
+}
+
 /**
  * An in-memory STUB provider context for tests + `--fake` mode: `setSecret`
  * records to memory (NO real secrets store touched), `ghAvailable` is fixed
@@ -414,6 +519,16 @@ export class MemoryCIProviderContext implements CIProviderContext {
 	readonly branchProtections = new Map<string, unknown>();
 	/** Deadlock-guard rulesets recorded in memory (append-only). */
 	readonly rulesets: unknown[] = [];
+	/**
+	 * The Actions workflow permissions: seeded from the fixture, updated by
+	 * `setActionsWorkflowPermissions`. `undefined` ⇒ the read "fails".
+	 */
+	actionsWorkflowPermissions: ActionsWorkflowPermissions | undefined;
+	/** Every `setActionsWorkflowPermissions` body, in call order (append-only). */
+	readonly actionsWorkflowPermissionsSets: Partial<ActionsWorkflowPermissions>[] =
+		[];
+	/** Whether `setActionsWorkflowPermissions` should throw (tests configure). */
+	private readonly actionsWorkflowPermissionsError: string | undefined;
 	/** What `getRepoAdminScope()` should return (tests configure). */
 	private readonly adminScope: boolean | undefined;
 	/** What `getDefaultBranch()` should return (tests configure). */
@@ -442,6 +557,13 @@ export class MemoryCIProviderContext implements CIProviderContext {
 		branchProtectionError?: string;
 		/** When set, `setBranchRuleset` throws with this message (failure path). */
 		branchRulesetError?: string;
+		/**
+		 * Fixture Actions workflow permissions; `undefined` ⇒ the read fails
+		 * (models a `gh` that could not read the setting).
+		 */
+		actionsWorkflowPermissions?: ActionsWorkflowPermissions;
+		/** When set, `setActionsWorkflowPermissions` throws with this message. */
+		actionsWorkflowPermissionsError?: string;
 		/**
 		 * The provider id this stub claims (default `github`). Tests of the
 		 * project-setup seam may override to assert the orchestrator's
@@ -458,6 +580,9 @@ export class MemoryCIProviderContext implements CIProviderContext {
 		this.visibility = options.visibility;
 		this.branchProtectionError = options.branchProtectionError;
 		this.branchRulesetError = options.branchRulesetError;
+		this.actionsWorkflowPermissions = options.actionsWorkflowPermissions;
+		this.actionsWorkflowPermissionsError =
+			options.actionsWorkflowPermissionsError;
 		this.providerId = options.providerId ?? GITHUB_PROVIDER_ID;
 	}
 
@@ -498,4 +623,27 @@ export class MemoryCIProviderContext implements CIProviderContext {
 		}
 		this.rulesets.push(ruleset);
 	}
+
+	async getActionsWorkflowPermissions(): Promise<
+		ActionsWorkflowPermissions | undefined
+	> {
+		return this.actionsWorkflowPermissions === undefined
+			? undefined
+			: {...this.actionsWorkflowPermissions};
+	}
+
+	async setActionsWorkflowPermissions(
+		permissions: Partial<ActionsWorkflowPermissions>,
+	): Promise<void> {
+		if (this.actionsWorkflowPermissionsError !== undefined) {
+			throw new Error(this.actionsWorkflowPermissionsError);
+		}
+		this.actionsWorkflowPermissionsSets.push({...permissions});
+		if (this.actionsWorkflowPermissions !== undefined) {
+			this.actionsWorkflowPermissions = {
+				...this.actionsWorkflowPermissions,
+				...permissions,
+			};
+		}
+	}
 }

package/src/install-ci.ts

@@ -29,6 +29,7 @@ import {
 	type CapabilityEmitter,
 	type SecretSetResult,
 	DEFAULT_HARNESS,
+	PR_IDENTITY_SECRET_NAME,
 	loadCIConfigFile,
 	resolveCIConfig,
 	exportCIConfig,
@@ -41,6 +42,10 @@ import {
 	installCIBranchProtectionStep,
 	type BranchProtectionStepResult,
 } from './install-ci-branch-protection.js';
+import {
+	installCIActionsPrCreationStep,
+	type ActionsPrCreationStepResult,
+} from './install-ci-actions-pr-creation.js';
 
 /**
  * The interactive prompt SEAM the wizard drives. Production wires readline; tests
@@ -105,6 +110,11 @@ export interface InstallCIResult {
 	secrets: SecretSetResult[];
 	/** The Tier-1 branch-protection outcome (undefined on `exported`). */
 	branchProtection?: BranchProtectionStepResult;
+	/**
+	 * The "Allow GitHub Actions to create and approve pull requests" outcome
+	 * (undefined on `exported`).
+	 */
+	actionsPrCreation?: ActionsPrCreationStepResult;
 }
 
 /**
@@ -311,6 +321,21 @@ export async function installCI(
 		fake,
 		log,
 	});
+
+	// 5c. "Allow GitHub Actions to create and approve pull requests" (task
+	// install-ci-enables-actions-pr-creation). Off on a new repo, and with it off
+	// GitHub refuses every propose-mode PR the workflows open with GITHUB_TOKEN.
+	// Same posture as branch protection: set when off and admin-scoped (keeping
+	// default_workflow_permissions), print the exact command otherwise, report
+	// only under --fake.
+	const actionsPrCreation = await installCIActionsPrCreationStep({
+		ctx: options.ctx,
+		fake,
+		log,
+	});
+	for (const line of prApprovalReminderLines(secrets)) {
+		log(line);
+	}
 	// CI-autonomy posture (task `install-ci-emits-no-gate-env-let-config-decide`):
 	// the emitted advance workflow carries NO DORFL_AUTO_BUILD /
 	// DORFL_AUTO_TASK / DORFL_OBSERVATION_TRIAGE /
@@ -361,7 +386,49 @@ export async function installCI(
 	log(
 		'without that hook the conflicting case is unsupported. install-ci does NOT detect likely conflicts — this is a documented boundary.',
 	);
-	return {outcome: 'generated', config, written, secrets, branchProtection};
+	return {
+		outcome: 'generated',
+		config,
+		written,
+		secrets,
+		branchProtection,
+		actionsPrCreation,
+	};
+}
+
+/**
+ * The closing-summary note (task `document-that-bot-opened-prs-need-approval`)
+ * about GitHub holding the `verify` run of a PR opened with `GITHUB_TOKEN` in
+ * `action_required` until someone approves it. When this run did NOT set the
+ * PR-identity token (skipped, failed, or `--fake`, where no secret is touched)
+ * the advance PRs fall back to `GITHUB_TOKEN`, so the full note is printed. When
+ * it was set, only the intake line remains true: `intake.yml` never passes
+ * {@link PR_IDENTITY_SECRET_NAME} (`ci-split-generate-workflows` Decisions), so
+ * intake PRs always need the approval. See `docs/ci/README.md`.
+ */
+export function prApprovalReminderLines(secrets: SecretSetResult[]): string[] {
+	const name = PR_IDENTITY_SECRET_NAME;
+	const tokenSet = secrets.some((r) => r.name === name && r.status === 'set');
+	const intakeLine = `  - intake PRs always need it: intake.yml keeps the built-in GITHUB_TOKEN and never passes ${name}.`;
+	const approveLine =
+		'  To approve: open the PR, Files changed, "Awaiting approval", "Approve workflows to run" (see docs/ci/README.md).';
+	if (tokenSet) {
+		return [
+			'',
+			`PR approval: ${name} is set, so advance PRs trigger verify on their own.`,
+			intakeLine,
+			approveLine,
+		];
+	}
+	return [
+		'',
+		`PR approval: no ${name} was set in this run. Unless that secret already exists on the repository,`,
+		'  the workflows open PRs with GITHUB_TOKEN, and GitHub holds their verify run in "action_required"',
+		'  until someone with write access approves it:',
+		`  - advance PRs (build, tasking): set ${name} (a PAT or App token) and they trigger verify on their own;`,
+		intakeLine,
+		approveLine,
+	];
 }
 
 /**
@@ -400,54 +467,33 @@ async function gatherSecretsForExport(
 // ─── The interactive wizard ──────────────────────────────────────────────────
 
 /**
- * The interactive wizard: gather the auth mode, providers/models (models-json) or
- * the default provider/model (auth-json), and the harness, into a
- * {@link CIConfigFile}. Drives the {@link WizardPrompts} seam, so it runs
- * deterministically in tests and the gathered shape exactly equals a config-file
- * input — the equivalence the snapshot test pins. Mirrors whitesmith's prompt
- * flow (provider type → key env var → models → defaults).
+ * The interactive wizard: gather the providers/models and the harness into a
+ * {@link CIConfigFile}. There is no auth-mode prompt: `models-json` is the only
+ * mode (the former `auth-json` mode was removed, see {@link AuthMode}); OAuth or
+ * other rotating credentials go behind a proxy set as a provider's `baseUrl`.
+ * Drives the {@link WizardPrompts} seam, so it runs deterministically in tests
+ * and the gathered shape exactly equals a config-file input, the equivalence the
+ * snapshot test pins. Mirrors whitesmith's prompt flow (provider type → key env
+ * var → models → defaults).
  */
 export async function runWizard(prompts: WizardPrompts): Promise<CIConfigFile> {
-	const authMode = await prompts.select<AuthMode>('Auth mode:', [
-		{
-			name: 'models.json (default — one GitHub secret per provider key)',
-			value: 'models-json',
-		},
-		{
-			name: 'auth.json (single PI_AUTH_JSON + GH_PAT + OAuth refresh — the sharp edge)',
-			value: 'auth-json',
-		},
-	]);
-
 	const harness = await prompts.select<HarnessAdapter>('Agent harness:', [
 		{name: 'pi (the pi coding agent)', value: 'pi'},
 		{name: 'null (shell out to a configured agentCmd)', value: 'null'},
 	]);
 
-	if (authMode === 'auth-json') {
-		// auth.json mode: no per-provider keys, but the harness still needs a
-		// default provider/model for its invocations.
-		const defaultProvider = await prompts.input('Default AI provider:', {
-			default: 'anthropic',
-		});
-		const defaultModel = await prompts.input('Default AI model:', {
-			default: 'claude-sonnet-4-20250514',
-		});
-		return {
-			authMode,
-			providers: [],
-			defaultProvider,
-			defaultModel,
-			harness,
-		};
-	}
-
 	const providers = await promptProviders(prompts);
 	const {defaultProvider, defaultModel} = await promptDefaults(
 		prompts,
 		providers,
 	);
-	return {authMode, providers, defaultProvider, defaultModel, harness};
+	return {
+		authMode: 'models-json',
+		providers,
+		defaultProvider,
+		defaultModel,
+		harness,
+	};
 }
 
 /** Prompt for one or more providers (the models-json path). */

package/src/intake-marker.ts

@@ -45,7 +45,12 @@ export type IntakeMarkerKind = 'ask' | 'bounced' | 'created';
 export interface IntakeMarker {
 	/** What intake did (a neutral fact; the TRIAGE owns terminal-ness, not this). */
 	kind: IntakeMarkerKind;
-	/** The HUMAN comment ids intake READ this run (the per-run delta; may be empty). */
+	/**
+	 * The HUMAN comment ids intake READ this run (the per-run delta; may be
+	 * empty). A CI run (task `ci-split-intake`) records EVERY comment id its lock
+	 * job read (intake's own and already-seen ones included): the apply job has
+	 * only the ids, and a superset of read ids is harmless to the triage.
+	 */
 	seen: string[];
 	/** The created task/spec slug \u2014 present only on `kind=created`. */
 	slug?: string;

package/src/intake-triage.ts

@@ -89,8 +89,12 @@ export function triageIntake(comments: IssueComment[]): IntakeTriageDecision {
 		const humanComments = comments.filter(
 			(c) => parseIntakeMarker(c.body) === undefined,
 		);
-		const currentHumanIds = new Set(
-			humanComments
+		// EVERY comment id still in the thread (not only the human ones): a CI run's
+		// `seen=` lists every comment id its lock job read, intake's own included
+		// (task `ci-split-intake`), and an intake comment that is still there was
+		// not deleted.
+		const currentIds = new Set(
+			comments
 				.map((c) => c.id)
 				.filter((id): id is string => id !== undefined && id !== ''),
 		);
@@ -105,7 +109,7 @@ export function triageIntake(comments: IssueComment[]): IntakeTriageDecision {
 			// previously-seen human id no longer present in the thread was deleted.
 			let deletedSeenCount = 0;
 			for (const id of seenSet) {
-				if (!currentHumanIds.has(id)) {
+				if (!currentIds.has(id)) {
 					deletedSeenCount += 1;
 				}
 			}