@fuzdev/fuz_gitops 0.78.1 → 0.79.0

package/src/lib/output_helpers.ts

@@ -3,10 +3,24 @@ import { writeFile } from 'node:fs/promises';
 
 export type OutputFormat = 'stdout' | 'json' | 'markdown';
 
+/**
+ * Writes one machine-readable document, or one line of a stream, to stdout,
+ * ending it with a newline.
+ */
+export type WriteStdout = (content: string) => void;
+
 export interface OutputOptions {
 	format: OutputFormat;
 	outfile?: string;
 	log?: Logger;
+	/**
+	 * Where a `json` or `markdown` document goes without `outfile`; the one
+	 * `route_human_output` returns, so the document reaches stdout while the
+	 * logger's lines go to stderr.
+	 *
+	 * @default `console.log`
+	 */
+	write_stdout?: WriteStdout;
 }
 
 export interface OutputFormatters<T> {
@@ -18,6 +32,42 @@ export interface OutputFormatters<T> {
 	stdout: (data: T, log: Logger) => void;
 }
 
+/**
+ * Whether a task's stdout carries a machine-readable document: a `json` or
+ * `markdown` report not sent to `--outfile`.
+ *
+ * @param format - the task's `--format`
+ * @param outfile - the task's `--outfile`, if any
+ */
+export const output_is_machine = (format: string, outfile: string | undefined): boolean =>
+	(format === 'json' || format === 'markdown') && !outfile;
+
+/**
+ * Keeps a task's stdout for its machine-readable document or stream when
+ * `machine` is set: the logger's `info` and `debug` lines, which it writes with
+ * `console.log`, go where its errors go — stderr — and child loggers inherit
+ * that. Gro hands a task the logger its own lines go through, so gro's lines
+ * after the task runs (`✓`, the timings) follow to stderr; the two it prints
+ * before the task runs (`invoking`, `→ <task>`) stay on stdout, out of the
+ * task's reach.
+ *
+ * @param log - the task's logger
+ * @param machine - whether stdout carries a machine-readable document or stream
+ * @returns writes to the stdout the logger wrote to before, for the document
+ * @mutates log - overrides its `console` when `machine` is set
+ */
+export const route_human_output = (log: Logger, machine: boolean): WriteStdout => {
+	const stdout = log.console;
+	if (machine) {
+		log.console = {
+			log: (...args) => stdout.error(...args),
+			warn: (...args) => stdout.warn(...args),
+			error: (...args) => stdout.error(...args)
+		};
+	}
+	return (content) => stdout.log(content);
+};
+
 /**
  * Formats data and outputs to file or stdout based on options.
  *
@@ -33,7 +83,7 @@ export const format_and_output = async <T>(
 	formatters: OutputFormatters<T>,
 	options: OutputOptions
 ): Promise<void> => {
-	const { format, outfile, log } = options;
+	const { format, outfile, log, write_stdout = write_console_log } = options;
 
 	// Handle stdout format (special case - uses logger directly)
 	if (format === 'stdout') {
@@ -59,7 +109,9 @@ export const format_and_output = async <T>(
 		// line with `[taskname]`, corrupting JSON and cluttering markdown — keep the
 		// machine-readable formats unprefixed and pipeable (use `--outfile` for output
 		// fully free of Gro's own preamble).
-		// eslint-disable-next-line no-console
-		console.log(content);
+		write_stdout(content);
 	}
 };
+
+// eslint-disable-next-line no-console
+const write_console_log: WriteStdout = (content) => console.log(content);

package/src/lib/preflight_checks.ts

@@ -1,228 +1,113 @@
 import type { Logger } from '@fuzdev/fuz_util/log.ts';
-import type { Result } from '@fuzdev/fuz_util/result.ts';
-import { spawn_out } from '@fuzdev/fuz_util/process.ts';
 import { styleText as st } from 'node:util';
 
 import type { LocalRepo } from './local_repo.ts';
-import type {
-	GitOperations,
-	NpmOperations,
-	BuildOperations,
-	ChangesetOperations
-} from './operations.ts';
-import {
-	default_git_operations,
-	default_npm_operations,
-	default_build_operations,
-	default_changeset_operations
-} from './operations_defaults.ts';
-
-export interface PreflightOptions {
-	skip_changesets?: boolean;
-	skip_build_validation?: boolean; // Skip build validation (useful for tests)
-	required_branch?: string;
-	check_remote?: boolean; // Check if git remote is reachable
-	estimate_time?: boolean; // Estimate total publish time
-	log?: Logger;
-}
+import type { VersionChange } from './publishing_plan.ts';
+import type { NpmOperations, BuildOperations } from './operations.ts';
+import { default_npm_operations, default_build_operations } from './operations_defaults.ts';
 
 export interface PreflightResult {
 	ok: boolean;
 	warnings: Array<string>;
 	errors: Array<string>;
-	repos_with_changesets: Set<string>;
-	repos_without_changesets: Set<string>;
-	estimated_duration?: number; // In seconds
-	npm_username?: string;
 }
 
 export interface RunPreflightChecksOptions {
 	repos: Array<LocalRepo>;
-	preflight_options?: PreflightOptions;
-	git_ops?: GitOperations;
+	/**
+	 * The plan's version changes — every package the run publishes, explicit,
+	 * escalated, and auto-generated alike. Preflight builds exactly these.
+	 */
+	version_changes: Array<VersionChange>;
+	log?: Logger;
 	npm_ops?: NpmOperations;
 	build_ops?: BuildOperations;
-	changeset_ops?: ChangesetOperations;
 }
 
 /**
- * Validates all requirements before publishing can proceed.
+ * Validates the publish-time requirements beyond repo git state:
+ * - every package the plan publishes builds (fail-fast to prevent broken state)
+ * - npm authentication
+ * - npm registry connectivity
  *
- * Performs comprehensive pre-flight validation:
- * - Clean workspaces (100% clean required - no uncommitted changes)
- * - Correct branch (usually main)
- * - Changesets present (unless `skip_changesets`=true)
- * - Builds successful (fail-fast to prevent broken state)
- * - Git remote reachability
- * - NPM authentication with username
- * - NPM registry connectivity
+ * What publishes is the plan's to decide, so preflight reads no changesets: it
+ * builds each package in `version_changes`. Git state — each repo on its
+ * registry branch, clean, idle, in sync with origin or ahead of it, and no live
+ * session in its checkout — is the readiness gate's, which `gitops_publish
+ * --wetrun` runs before the plan's confirmation prompt (`repo_readiness.ts`), so
+ * preflight reads no git.
  *
  * Build validation runs BEFORE any publishing to prevent the scenario where
  * version is bumped but build fails, leaving repo in broken state.
  *
- * @returns result with `ok`=false if any errors, plus warnings and detailed status
+ * @returns result with `ok`=false if any errors, plus warnings
  */
 export const run_preflight_checks = async ({
 	repos,
-	preflight_options = {},
-	git_ops = default_git_operations,
+	version_changes,
+	log,
 	npm_ops = default_npm_operations,
-	build_ops = default_build_operations,
-	changeset_ops = default_changeset_operations
+	build_ops = default_build_operations
 }: RunPreflightChecksOptions): Promise<PreflightResult> => {
-	const {
-		skip_changesets = false,
-		skip_build_validation = false,
-		required_branch = 'main',
-		check_remote = true,
-		estimate_time = true,
-		log
-	} = preflight_options;
-
 	const warnings: Array<string> = [];
 	const errors: Array<string> = [];
-	const repos_with_changesets: Set<string> = new Set();
-	const repos_without_changesets: Set<string> = new Set();
-	let npm_username: string | undefined;
-	let estimated_duration: number | undefined;
 
 	log?.info(st('cyan', '✅ Running preflight checks...'));
 
-	// 1. Check clean workspaces - must be 100% clean before publishing
-	log?.info('  Checking workspace cleanliness...');
-	for (const repo of repos) {
-		const clean_result = await git_ops.check_clean_workspace({ cwd: repo.repo_dir });
-		if (!clean_result.ok) {
-			errors.push(`${repo.library.name} failed workspace check: ${clean_result.message}`);
-			continue;
-		}
-
-		if (!clean_result.value) {
-			// Get list of changed files for better error message
-			const files_result = await git_ops.list_uncommitted_files({ cwd: repo.repo_dir });
-			if (files_result.ok) {
-				// No filtering - workspace must be 100% clean
-				const unexpected_files = files_result.value;
-
-				if (unexpected_files.length > 0) {
-					errors.push(
-						`${repo.library.name} has uncommitted changes in: ${unexpected_files.slice(0, 3).join(', ')}${unexpected_files.length > 3 ? ` and ${unexpected_files.length - 3} more` : ''}`
-					);
-				}
-			} else {
-				errors.push(`${repo.library.name} has uncommitted changes`);
-			}
-		}
-	}
-
-	// 2. Check correct branch
-	log?.info(`  Checking branches (expecting ${required_branch})...`);
-	for (const repo of repos) {
-		const branch_result = await git_ops.current_branch_name({ cwd: repo.repo_dir });
-		if (!branch_result.ok) {
-			errors.push(`${repo.library.name} failed branch check: ${branch_result.message}`);
-			continue;
-		}
-
-		if (branch_result.value !== required_branch) {
-			errors.push(
-				`${repo.library.name} is on branch '${branch_result.value}', expected '${required_branch}'`
-			);
-		}
-	}
-
-	// 3. Check changesets (unless skipped)
-	if (!skip_changesets) {
-		log?.info('  Checking for changesets...');
-		for (const repo of repos) {
-			const has_result = await changeset_ops.has_changesets({ repo });
-			if (!has_result.ok) {
-				errors.push(`${repo.library.name} failed changeset check: ${has_result.message}`);
-				continue;
-			}
-
-			if (has_result.value) {
-				repos_with_changesets.add(repo.library.name);
-			} else {
-				repos_without_changesets.add(repo.library.name);
-				warnings.push(`${repo.library.name} has no changesets`);
-			}
-		}
-
-		if (repos_without_changesets.size > 0) {
-			log?.warn(st('yellow', `  ⚠️  ${repos_without_changesets.size} packages have no changesets`));
+	// 1. Build every package the plan publishes
+	const repo_by_name: Map<string, LocalRepo> = new Map(repos.map((r) => [r.library.name, r]));
+	const repos_to_build: Array<LocalRepo> = [];
+	for (const change of version_changes) {
+		const repo = repo_by_name.get(change.package_name);
+		if (repo) {
+			repos_to_build.push(repo);
+		} else {
+			errors.push(`${change.package_name} is in the plan but not among the repos`);
 		}
 	}
 
-	// 4. Validate builds for packages with changesets
-	if (!skip_build_validation && repos_with_changesets.size > 0) {
-		log?.info(st('cyan', `  Validating builds for ${repos_with_changesets.size} package(s)...`));
-		const repos_to_build = repos.filter((repo) => repos_with_changesets.has(repo.library.name));
-
+	if (repos_to_build.length > 0) {
+		log?.info(st('cyan', `  Validating builds for ${repos_to_build.length} package(s)...`));
+		let build_failures = 0;
 		for (let i = 0; i < repos_to_build.length; i++) {
 			const repo = repos_to_build[i]!;
 			log?.info(
 				st('dim', `    [${i + 1}/${repos_to_build.length}] Building ${repo.library.name}...`)
 			);
-			const build_result = await build_ops.build_package({ repo, log });
-			if (!build_result.ok) {
+			const build_result = await build_ops.build_package({ repo });
+			if (build_result.ok) {
+				log?.info(st('dim', `    ✓ ${repo.library.name} built successfully`));
+			} else {
+				build_failures++;
 				errors.push(
 					`${repo.library.name} failed to build: ${build_result.output || build_result.message || 'unknown error'}`
 				);
-			} else {
-				log?.info(st('dim', `    ✓ ${repo.library.name} built successfully`));
 			}
 		}
 
-		if (errors.some((err) => err.includes('failed to build'))) {
+		if (build_failures > 0) {
 			log?.error(st('red', '  ❌ Build validation failed - fix build errors before publishing'));
 		} else {
 			log?.info(st('green', '  ✓ All builds validated successfully'));
 		}
 	}
 
-	// 5. Check git remote reachability (skip in tests when check_remote is false)
-	if (check_remote && repos.length > 0) {
-		log?.info('  Checking git remote connectivity...');
-		// Only check first repo to avoid slowing down tests with multiple remote checks
-		const remote_result = await check_git_remote(repos[0]!.repo_dir);
-		if (!remote_result.ok) {
-			warnings.push(`git remote may not be reachable - ${remote_result.message}`);
-		}
-	}
-
-	// 6. Check npm authentication with username
+	// 2. Check npm authentication
 	log?.info('  Checking npm authentication...');
 	const npm_auth_result = await npm_ops.check_auth();
-	if (!npm_auth_result.ok) {
-		errors.push(`npm authentication failed: ${npm_auth_result.message || 'not logged in'}`);
+	if (npm_auth_result.ok) {
+		log?.info(st('dim', `    Logged in as: ${npm_auth_result.username}`));
 	} else {
-		npm_username = npm_auth_result.username;
-		log?.info(st('dim', `    Logged in as: ${npm_username}`));
+		errors.push(`npm authentication failed: ${npm_auth_result.message || 'not logged in'}`);
 	}
 
-	// 7. Check network connectivity (npm registry)
+	// 3. Check network connectivity (npm registry)
 	log?.info('  Checking npm registry connectivity...');
 	const registry_result = await npm_ops.check_registry();
 	if (!registry_result.ok) {
 		warnings.push(`npm registry check failed: ${registry_result.message}`);
 	}
 
-	// 8. Estimate total publish time
-	if (estimate_time) {
-		const packages_to_publish = repos_with_changesets.size;
-		if (packages_to_publish > 0) {
-			// Rough estimate: 30s per package + 10s per package for NPM propagation
-			estimated_duration = packages_to_publish * 40;
-			log?.info(
-				st(
-					'dim',
-					`  Estimated publish time: ~${Math.ceil(estimated_duration / 60)} minutes for ${packages_to_publish} package(s)`
-				)
-			);
-		}
-	}
-
 	// Report results
 	const ok = errors.length === 0;
 
@@ -244,26 +129,5 @@ export const run_preflight_checks = async ({
 		log?.info(st('green', '\n✨ All preflight checks passed!'));
 	}
 
-	return {
-		ok,
-		warnings,
-		errors,
-		repos_with_changesets,
-		repos_without_changesets,
-		estimated_duration,
-		npm_username
-	};
-};
-
-const check_git_remote = async (cwd: string): Promise<Result<object, { message: string }>> => {
-	try {
-		// Try to fetch refs from remote without downloading objects
-		const result = await spawn_out('git', ['ls-remote', '--heads', 'origin'], { cwd });
-		if (result.stdout || result.stderr) {
-			return { ok: true };
-		}
-		return { ok: false, message: 'No response from git remote' };
-	} catch (error) {
-		return { ok: false, message: String(error) };
-	}
+	return { ok, warnings, errors };
 };

package/src/lib/publish_steps.ts

@@ -9,15 +9,24 @@
  */
 
 import type { BumpType } from './version_utils.ts';
-import type { PublishingPlan, VersionChange } from './publishing_plan.ts';
+import {
+	version_change_kind,
+	type PublishingPlan,
+	type VersionChange,
+	type VersionChangeKind
+} from './publishing_plan.ts';
 import { UnreachableError } from '@fuzdev/fuz_util/error.ts';
 
-/** How a package's version bump arises in the plan. */
-export type PublishStepVia = 'changeset' | 'auto_changeset' | 'escalation';
-
 /** One ordered side-effect a wetrun would perform. */
 export type PublishStep =
-	| { kind: 'publish'; repo: string; from: string; to: string; bump: BumpType; via: PublishStepVia }
+	| {
+			kind: 'publish';
+			repo: string;
+			from: string;
+			to: string;
+			bump: BumpType;
+			via: VersionChangeKind;
+	  }
 	| { kind: 'npm_wait'; repo: string; version: string }
 	| {
 			kind: 'dependency_update';
@@ -35,13 +44,6 @@ export interface DerivePublishStepsOptions {
 	deploy?: boolean;
 }
 
-const step_via = (change: VersionChange): PublishStepVia =>
-	change.needs_bump_escalation
-		? 'escalation'
-		: change.has_changesets
-			? 'changeset'
-			: 'auto_changeset';
-
 /**
  * Derives the ordered side-effects a wetrun would perform from a frozen plan.
  *
@@ -72,7 +74,7 @@ export const derive_publish_steps = (
 			from: change.from,
 			to: change.to,
 			bump: change.bump_type,
-			via: step_via(change)
+			via: version_change_kind(change)
 		});
 		steps.push({ kind: 'npm_wait', repo, version: change.to });
 		changed.add(repo);

package/src/lib/publishing_event.ts

@@ -21,16 +21,17 @@ import { z } from 'zod';
  * failure kind without parsing the message.
  */
 export const PublishingErrorCode = z.enum([
+	// the publish step failed — its cause is in the message, not yet classified further
 	'publish',
+	// the published version never appeared on the npm registry within the wait
 	'network',
-	'auth',
-	'dependency',
-	'build',
 	// the real published version diverged from the frozen plan's prediction — an
 	// invariant violation, distinct from an ordinary publish failure (see fail-loud
 	// drift detection in `multi_repo_publisher.ts`)
 	'drift',
-	'other'
+	// the repo wasn't ready when re-checked right before its `gro publish` (origin moved,
+	// a tracked edit, a live session, …) — aborted before any npm side effect
+	'not_ready'
 ]);
 export type PublishingErrorCode = z.infer<typeof PublishingErrorCode>;
 

package/src/lib/publishing_event_handler.ts

@@ -4,12 +4,18 @@
  * A `PublishingEventHandler` is anything that can receive a `PublishingEvent`. Handlers
  * compose: `multi_handler` fans out, `masking_handler` redacts secrets then forwards.
  * Emission is best-effort and synchronous — an observability sink must never fail or
- * slow a run. The default sink is `null_handler` (drops everything).
+ * slow a run. The executor always captures events for its result (`capture_handler`)
+ * and forwards them to the caller's sink when one is supplied.
  *
  * @module
  */
 
 import type { PublishingEvent } from './publishing_event.ts';
+import type { WriteStdout } from './output_helpers.ts';
+
+const write_process_stdout_line: WriteStdout = (line) => {
+	process.stdout.write(line + '\n');
+};
 
 /** A sink for publishing events. */
 export interface PublishingEventHandler {
@@ -21,11 +27,6 @@ export interface CapturingEventHandler extends PublishingEventHandler {
 	readonly events: Array<PublishingEvent>;
 }
 
-/** Drops every event. The default when no handler is supplied. */
-export const null_handler = (): PublishingEventHandler => ({
-	emit: () => {}
-});
-
 /** Collects events in memory. Used to build the run report and in tests. */
 export const capture_handler = (): CapturingEventHandler => {
 	const events: Array<PublishingEvent> = [];
@@ -38,13 +39,17 @@ export const capture_handler = (): CapturingEventHandler => {
 };
 
 /**
- * Writes each event as one JSON object per line (JSON-lines) to `process.stdout`.
+ * Writes each event as one JSON object per line (JSON-lines) to stdout.
  * Write failures are swallowed — the stream is observability, not control flow.
+ *
+ * @param write_line - writes one line and its newline; defaults to `process.stdout`
  */
-export const stdout_handler = (): PublishingEventHandler => ({
+export const stdout_handler = (
+	write_line: WriteStdout = write_process_stdout_line
+): PublishingEventHandler => ({
 	emit: (event) => {
 		try {
-			process.stdout.write(JSON.stringify(event) + '\n');
+			write_line(JSON.stringify(event));
 		} catch {
 			// best-effort: a logging sink must never fail a run
 		}
@@ -61,17 +66,14 @@ export const multi_handler = (handlers: Array<PublishingEventHandler>): Publishi
 });
 
 /**
- * Wraps a handler, masking secrets in each event's string fields before forwarding.
+ * Wraps a handler, masking secrets in each event's string fields (`mask_secrets`)
+ * before forwarding.
  *
  * @param inner - the handler to forward masked events to
- * @param mask - the masking function, defaults to `mask_secrets`
  */
-export const masking_handler = (
-	inner: PublishingEventHandler,
-	mask: (event: PublishingEvent) => PublishingEvent = mask_secrets
-): PublishingEventHandler => ({
+export const masking_handler = (inner: PublishingEventHandler): PublishingEventHandler => ({
 	emit: (event) => {
-		inner.emit(mask(event));
+		inner.emit(mask_secrets(event));
 	}
 });