dorfl 0.2.1 → 0.3.1

package/src/gate-readiness.ts

@@ -2,6 +2,11 @@ import {existsSync} from 'node:fs';
 import {join} from 'node:path';
 import {run} from './git.js';
 import {resolvePrepareCommands, type PrepareConfig} from './prepare.js';
+import {
+	resolveVerifyCommands,
+	VerifyNotConfiguredError,
+	type VerifyConfig,
+} from './verify.js';
 
 /**
  * Pre-claim / pre-build startup GUARD for the fresh-worktree acceptance gate
@@ -21,12 +26,15 @@ import {resolvePrepareCommands, type PrepareConfig} from './prepare.js';
  * the guard KEYS off LOCKFILE-PRESENT evidence — never off `prepare`-unset
  * alone — and a genuinely dep-free repo (no lockfile) PROCEEDS unchanged.
  *
- * There is NO "verify unset" case: {@link resolveVerifyCommands} substitutes
- * `DEFAULT_VERIFY_COMMAND` when `verify` is unset OR all-blank, so `verify` is
- * NEVER statically unrunnable-because-unset. A "verify unset → STOP" guard
- * would be dead code (or fire wrongly on the default). The guard is deps-only.
+ * VERIFY-UNSET is ALSO a static stop, and — unlike the deps case — it is
+ * MODE-INDEPENDENT: Dorfl has no default gate, so a repo with no `verify`
+ * declared can never pass an acceptance gate in ANY mode (fresh-worktree or
+ * in-place). {@link resolveVerifyCommands} throws {@link VerifyNotConfiguredError}
+ * when `verify` is unset / empty / all-blank; the guard detects that at second
+ * zero and STOPS before a wasted claim + build. This check runs regardless of
+ * `freshWorktreeGate`.
  *
- * The guard is also gated on `freshWorktreeGate === true` for THIS invocation:
+ * The DEPS guard below is also gated on `freshWorktreeGate === true` for THIS invocation:
  * when the gate is OFF (`--no-fresh-worktree-gate`) the acceptance gate runs in
  * the agent's BUILD worktree (which HAS deps), so the throwaway-worktree
  * reasoning does not apply.
@@ -92,6 +100,12 @@ export interface GatePreconditionInput {
 	freshWorktreeGate: boolean | undefined;
 	/** The resolved `prepare` config (unset / string / list). */
 	prepare?: PrepareConfig;
+	/**
+	 * The resolved `verify` config (unset / string / list). When this is unset
+	 * (or all-blank) there is NO gate to run — a MODE-INDEPENDENT static stop,
+	 * checked before the deps guard.
+	 */
+	verify?: VerifyConfig;
 	/**
 	 * The lockfile basename probed for this repo (one of
 	 * {@link LOCKFILE_BASENAMES}), or `undefined` for the intentional dep-free
@@ -103,9 +117,13 @@ export interface GatePreconditionInput {
 }
 
 export interface GatePreconditionFailure {
-	/** The lockfile basename (from {@link LOCKFILE_BASENAMES}) that tripped the guard. */
-	lockfile: string;
-	/** A precise, actionable error message naming the lockfile and the two ways out. */
+	/**
+	 * The lockfile basename (from {@link LOCKFILE_BASENAMES}) that tripped the
+	 * DEPS guard, or `undefined` for the verify-unset failure (which is not tied
+	 * to any lockfile).
+	 */
+	lockfile?: string;
+	/** A precise, actionable error message naming the cause and the way(s) out. */
 	message: string;
 }
 
@@ -119,6 +137,17 @@ export interface GatePreconditionFailure {
 export function checkGatePreconditions(
 	input: GatePreconditionInput,
 ): GatePreconditionFailure | undefined {
+	// VERIFY-UNSET — MODE-INDEPENDENT (checked FIRST, before the fresh-worktree
+	// short-circuit): Dorfl has no default gate, so an unconfigured `verify` can
+	// never pass in ANY mode. `resolveVerifyCommands` throws when unset/all-blank.
+	try {
+		resolveVerifyCommands(input.verify);
+	} catch (err) {
+		if (err instanceof VerifyNotConfiguredError) {
+			return {message: err.message};
+		}
+		throw err;
+	}
 	// Gate OFF for THIS invocation ⇒ no throwaway worktree ⇒ the deps reasoning
 	// does not apply. (The default is ON; the guard fires when ON.)
 	if (input.freshWorktreeGate !== true) {

package/src/index.ts

@@ -572,7 +572,8 @@ export type {RunVerifyOptions, RunVerifyResult} from './verify.js';
 export {
 	runVerify,
 	resolveVerifyCommands,
-	DEFAULT_VERIFY_COMMAND,
+	VerifyNotConfiguredError,
+	VERIFY_NOT_CONFIGURED_MESSAGE,
 } from './verify.js';
 
 export type {

package/src/prepare.ts

@@ -16,10 +16,12 @@ import type {VerifyConfig} from './verify.js';
  * cheaply-re-runnable acceptance check and make every gate run pay the install
  * cost). `prepare` is where install belongs; `verify` stays the gate.
  *
- * Unlike `verify`, `prepare` has NO default command: an unset `prepare` is a
- * genuine NO-OP (a repo with no deps needs no install — we never invent a
- * default that would run `pnpm install` in a repo that has no lockfile). This is
- * the one shape difference from `verify` (whose unset ⇒ a sensible default gate).
+ * Like `verify`, `prepare` has NO default command — but the two differ in what
+ * "unset" MEANS. An unset `prepare` is a genuine NO-OP (a repo with no deps
+ * needs no install — we never invent a default that would run `pnpm install` in
+ * a repo that has no lockfile). An unset `verify`, by contrast, is a hard error
+ * (a repo MUST declare its acceptance gate; there is no gate to invent). So both
+ * are default-free, but unset-prepare passes vacuously while unset-verify FAILS.
  *
  * Like `verify` it is a DECLARED, deterministic shell step (a single command or
  * an ordered list, all must pass) — no model in the loop. It is read-only with
@@ -40,6 +42,9 @@ export type PrepareConfig = VerifyConfig;
  * difference from {@link resolveVerifyCommands}). A string ⇒ a single command. A
  * list ⇒ the list, with blank/whitespace-only entries dropped (which can leave
  * an empty list ⇒ still a no-op). Each command is run in sequence; all must pass.
+ *
+ * Contrast {@link resolveVerifyCommands}, which THROWS on the unset/all-blank
+ * case (there is no default gate) rather than resolving to a no-op.
  */
 export function resolvePrepareCommands(
 	prepare: PrepareConfig | undefined,

package/src/run.ts

@@ -630,8 +630,9 @@ async function runOneItem(
 	//     same `config-error` axis the PR-intent guard above uses (a wiring/config
 	//     fault, not a task fault). The repo discovery is either a working checkout
 	//     (in-place tests) OR a BARE hub mirror (production fleet); detect the
-	//     lockfile from whichever shape `repoPath` is. Deps-only — there is no
-	//     verify-unset case (the gate substitutes `DEFAULT_VERIFY_COMMAND`).
+	//     lockfile from whichever shape `repoPath` is. ALSO fails fast when
+	//     `verify` is unset/all-blank (a MODE-INDEPENDENT stop — Dorfl has no
+	//     default gate, so an unconfigured `verify` can never pass in any mode).
 	{
 		const lockfile =
 			detectLockfileOnDisk(repoPath) ??
@@ -639,6 +640,7 @@ async function runOneItem(
 		const guard = checkGatePreconditions({
 			freshWorktreeGate: config.freshWorktreeGate,
 			prepare: config.prepare,
+			verify: config.verify,
 			lockfile,
 		});
 		if (guard !== undefined) {

package/src/verify.ts

@@ -12,43 +12,77 @@ import {spawn} from 'node:child_process';
  *
  * It is read-only with respect to `work/`: it runs the declared check and never
  * moves or commits anything.
+ *
+ * There is NO default gate. A repo MUST declare its own `verify`; an unset gate
+ * is a loud failure (`notConfigured`), never a silent `pnpm -r …` fallback that
+ * could run the wrong check or pass vacuously.
  */
 
 /**
  * The per-repo gate, as declared in config. A single shell command, or an
  * ordered list of commands run in sequence (each must pass for the gate to
- * pass). `undefined` (unset) ⇒ {@link DEFAULT_VERIFY_COMMAND} is used.
+ * pass). `undefined` (unset) is NOT valid: there is NO default gate — a repo
+ * MUST declare its own `verify` (see {@link VerifyNotConfiguredError}).
  */
 export type VerifyConfig = string | string[];
 
 /**
- * The sensible default when no `verify` is configured: build, then test, then
- * check formatting across the workspace. Deterministic, auditable, no model.
+ * The precise, actionable message emitted whenever a `verify` gate is required
+ * but the repo declares none (unset, empty string, or an all-blank list). There
+ * is deliberately NO default gate: a silent `pnpm -r build && …` fallback runs
+ * the WRONG check in a repo whose real gate is something else (and passes
+ * vacuously in a repo pnpm knows nothing about — e.g. `pnpm -r` printing
+ * "No projects found" and exiting 0, a FALSE green). Failing loud here forces
+ * the repo to declare the gate it actually means.
+ */
+export const VERIFY_NOT_CONFIGURED_MESSAGE =
+	'no `verify` gate is configured for this repo. Dorfl has no default ' +
+	'acceptance gate: declare the exact command(s) in `dorfl.json` ' +
+	'(e.g. "verify": "pnpm -r build && pnpm -r test && pnpm format:check"), ' +
+	'as a single string or an ordered list of commands.';
+
+/**
+ * Thrown by {@link resolveVerifyCommands} when a gate is required but none is
+ * declared. A typed error (not a bare `Error`) so callers that must translate
+ * an unconfigured gate into a routed gate-FAILURE (rather than an uncaught
+ * crash) can detect it precisely — see {@link runVerify}, which catches it and
+ * returns a failing {@link RunVerifyResult} with `notConfigured: true`.
  */
-export const DEFAULT_VERIFY_COMMAND =
-	'pnpm -r build && pnpm -r test && pnpm -r format:check';
+export class VerifyNotConfiguredError extends Error {
+	constructor(message: string = VERIFY_NOT_CONFIGURED_MESSAGE) {
+		super(message);
+		this.name = 'VerifyNotConfiguredError';
+	}
+}
 
 /**
  * Resolve the declared gate into an ordered, non-empty list of shell commands.
- * Unset ⇒ the default. A string ⇒ a single command. A list ⇒ the list, with
- * blank/whitespace-only entries dropped (and the default substituted if that
- * leaves nothing). Each command is run in sequence; all must pass.
+ * A string ⇒ a single command. A list ⇒ the list, with blank/whitespace-only
+ * entries dropped. Each command is run in sequence; all must pass.
+ *
+ * There is NO default: unset, an empty string, or a list that is empty/all-blank
+ * THROWS {@link VerifyNotConfiguredError}. Dorfl never invents an acceptance
+ * gate — a repo must declare the exact check it means, so the gate can never
+ * silently run the wrong command (or pass vacuously).
  */
 export function resolveVerifyCommands(
 	verify: VerifyConfig | undefined,
 ): string[] {
 	if (verify === undefined) {
-		return [DEFAULT_VERIFY_COMMAND];
+		throw new VerifyNotConfiguredError();
 	}
 	const list = Array.isArray(verify) ? verify : [verify];
 	const commands = list.filter((command) => command.trim() !== '');
-	return commands.length > 0 ? commands : [DEFAULT_VERIFY_COMMAND];
+	if (commands.length === 0) {
+		throw new VerifyNotConfiguredError();
+	}
+	return commands;
 }
 
 export interface RunVerifyOptions {
 	/** The repo to run the gate in (its working directory). */
 	cwd: string;
-	/** The declared gate (string | list). Unset ⇒ the default command. */
+	/** The declared gate (string | list). Unset/blank ⇒ a failing, not-configured result. */
 	verify?: VerifyConfig;
 	/** Environment for the gate's child processes. */
 	env?: NodeJS.ProcessEnv;
@@ -61,10 +95,17 @@ export interface RunVerifyOptions {
 export interface RunVerifyResult {
 	/** The exit code of the gate: 0 iff every command passed. */
 	exitCode: number;
-	/** The ordered commands that were run (resolved from config). */
+	/** The ordered commands that were run (resolved from config). Empty when not configured. */
 	commands: string[];
 	/** Whether the gate passed (exitCode === 0). */
 	passed: boolean;
+	/**
+	 * True iff the gate could not run because NO `verify` is declared (unset /
+	 * empty / all-blank). A distinct, always-failing outcome (`passed: false`)
+	 * so runner callers route it as a normal gate FAILURE with a clear reason
+	 * rather than crashing on the thrown {@link VerifyNotConfiguredError}.
+	 */
+	notConfigured?: boolean;
 }
 
 /**
@@ -73,11 +114,28 @@ export interface RunVerifyResult {
  * the first non-zero exit short-circuits the rest and becomes the result
  * (mirroring `&&` semantics). Each command is run through `bash -c` so that
  * shell operators in the declared gate (`&&`, pipes, etc.) behave as written.
+ *
+ * A repo with NO `verify` declared yields a failing result with
+ * `notConfigured: true` (never throws): the shared runner call sites
+ * (`do`/`run`/`complete` → `performIntegration`) already route a non-passing
+ * gate to needs-attention, so an unconfigured gate surfaces the same way with a
+ * precise reason instead of an uncaught crash.
  */
 export async function runVerify(
 	options: RunVerifyOptions,
 ): Promise<RunVerifyResult> {
-	const commands = resolveVerifyCommands(options.verify);
+	let commands: string[];
+	try {
+		commands = resolveVerifyCommands(options.verify);
+	} catch (err) {
+		if (err instanceof VerifyNotConfiguredError) {
+			const onStderr =
+				options.onStderr ?? ((chunk: string) => process.stderr.write(chunk));
+			onStderr(`${err.message}\n`);
+			return {exitCode: 1, commands: [], passed: false, notConfigured: true};
+		}
+		throw err;
+	}
 	const onStdout =
 		options.onStdout ?? ((chunk: string) => process.stdout.write(chunk));
 	const onStderr =