@fuzdev/fuz_gitops 0.78.0 → 0.79.0

package/src/lib/npm_registry.ts

@@ -1,7 +1,7 @@
-import type {Logger} from '@fuzdev/fuz_util/log.ts';
-import {spawn_out} from '@fuzdev/fuz_util/process.ts';
-import {wait} from '@fuzdev/fuz_util/async.ts';
-import {styleText as st} from 'node:util';
+import type { Logger } from '@fuzdev/fuz_util/log.ts';
+import { spawn_out } from '@fuzdev/fuz_util/process.ts';
+import { wait } from '@fuzdev/fuz_util/async.ts';
+import { styleText as st } from 'node:util';
 
 export interface WaitOptions {
 	log?: Logger;
@@ -11,28 +11,44 @@ export interface WaitOptions {
 	timeout?: number;
 }
 
-export interface PackageInfo {
-	name: string;
-	version: string;
+/**
+ * The side effects of the registry checks — running npm, sleeping, and reading
+ * the clock — injected so tests drive them with plain objects.
+ */
+export interface NpmRegistryDeps {
+	/**
+	 * Runs `npm` with `args` and resolves to what it wrote to stdout — empty when
+	 * nothing, or when npm couldn't run. A throw counts as unavailable too.
+	 */
+	run_npm: (args: Array<string>) => Promise<string>;
+	/** Sleeps for `ms` milliseconds. */
+	wait: (ms: number) => Promise<void>;
+	/** The current time in milliseconds, as `Date.now`. */
+	now: () => number;
 }
 
+export const default_npm_registry_deps: NpmRegistryDeps = {
+	run_npm: async (args) => (await spawn_out('npm', args)).stdout ?? '',
+	wait,
+	now: () => Date.now()
+};
+
+/**
+ * Checks whether `pkg@version` is on the npm registry, by `npm view`.
+ *
+ * @returns `true` when the registry reports that exact version, `false` when it
+ * doesn't or npm couldn't run
+ */
 export const check_package_available = async (
 	pkg: string,
 	version: string,
-	options: {log?: Logger} = {},
+	options: { log?: Logger } = {},
+	deps: NpmRegistryDeps = default_npm_registry_deps
 ): Promise<boolean> => {
-	const {log} = options;
+	const { log } = options;
 	try {
-		// Use npm view to check if the specific version exists
-		const result = await spawn_out('npm', ['view', `${pkg}@${version}`, 'version']);
-
-		if (result.stdout) {
-			const output = result.stdout.trim();
-			// If we get a version back, it exists
-			return output === version;
-		}
-
-		return false;
+		const stdout = await deps.run_npm(['view', `${pkg}@${version}`, 'version']);
+		return stdout.trim() === version;
 	} catch (error) {
 		log?.debug(`Failed to check ${pkg}@${version}: ${error}`);
 		return false;
@@ -58,43 +74,41 @@ export const wait_for_package = async (
 	pkg: string,
 	version: string,
 	options: WaitOptions = {},
+	deps: NpmRegistryDeps = default_npm_registry_deps
 ): Promise<void> => {
 	const {
 		log,
 		max_attempts = 30,
 		initial_delay = 1000,
 		max_delay = 60000,
-		timeout = 300000, // 5 minutes default
+		timeout = 300000 // 5 minutes default
 	} = options;
 
-	const start_time = Date.now();
+	const start_time = deps.now();
 	let attempt = 0;
 	let delay = initial_delay;
 
 	while (attempt < max_attempts) {
 		attempt++;
 
-		// Check timeout
-		if (Date.now() - start_time > timeout) {
+		if (deps.now() - start_time > timeout) {
 			throw new Error(`Timeout waiting for ${pkg}@${version} after ${timeout}ms`);
 		}
 
-		// Check if package is available
-
-		if (await check_package_available(pkg, version, {log})) {
+		if (await check_package_available(pkg, version, { log }, deps)) {
 			log?.info(st('green', `    ✓ ${pkg}@${version} is now available on NPM`));
 			return;
 		}
 
 		// Log progress occasionally
-		if (attempt > 0 && attempt % 5 === 0) {
+		if (attempt % 5 === 0) {
 			log?.info(st('dim', `    Still waiting... (attempt ${attempt}/${max_attempts})`));
 		}
 
 		// Wait with exponential backoff + jitter
 		const jitter = Math.random() * delay * 0.1; // 10% jitter
 		const actual_delay = Math.min(delay + jitter, max_delay);
-		await wait(actual_delay);
+		await deps.wait(actual_delay);
 
 		// Exponential backoff
 		delay = Math.min(delay * 1.5, max_delay);
@@ -102,42 +116,3 @@ export const wait_for_package = async (
 
 	throw new Error(`${pkg}@${version} not available after ${max_attempts} attempts`);
 };
-
-/**
- * Fetches package metadata from NPM registry.
- *
- * Returns name and latest version. Returns null if package doesn't exist
- * or registry is unreachable.
- *
- * @returns package info or null on error/not found
- */
-export const get_package_info = async (
-	pkg: string,
-	options: {log?: Logger} = {},
-): Promise<PackageInfo | null> => {
-	const {log} = options;
-	try {
-		const result = await spawn_out('npm', ['view', pkg, '--json']);
-
-		if (result.stdout) {
-			const data = JSON.parse(result.stdout);
-			return {
-				name: data.name,
-				version: data.version,
-			};
-		}
-
-		return null;
-	} catch (error) {
-		log?.debug(`Failed to get package info for ${pkg}: ${error}`);
-		return null;
-	}
-};
-
-export const package_exists = async (
-	pkg: string,
-	options: {log?: Logger} = {},
-): Promise<boolean> => {
-	const info = await get_package_info(pkg, options);
-	return info !== null;
-};

package/src/lib/operations.ts

@@ -2,7 +2,8 @@
  * Operations interfaces for dependency injection.
  *
  * This is the core pattern enabling testability without mocks.
- * All side effects (git, npm, fs, process) are abstracted into interfaces.
+ * All side effects (git, npm, fs, process, build, and the `repos` binary) are
+ * abstracted into interfaces.
  *
  * **Design principles:**
  * - All operations accept a single `options` object parameter
@@ -13,35 +14,42 @@
  *
  * **Production usage:**
  * ```typescript
- * import {default_gitops_operations} from './operations_defaults.js';
- * const result = await ops.git.current_branch_name({cwd: '/path'});
+ * import {default_gitops_operations} from './operations_defaults.ts';
+ * const ops = default_gitops_operations;
+ * const result = await ops.git.current_commit_hash({cwd: '/path'});
  * if (!result.ok) {
  *   throw new TaskError(result.message);
  * }
- * const branch = result.value;
+ * const commit = result.value;
  * ```
  *
  * **Test usage:**
  * ```typescript
- * const mock_ops = create_mock_operations();
- * const result = await publish_repos(repos, {...options, ops: mock_ops});
+ * import {create_mock_gitops_ops} from './test_helpers.ts';
+ * const ops = create_mock_gitops_ops({
+ *   changeset: {has_changesets: async () => ({ok: true, value: false})}
+ * });
+ * const result = await publish_repos(repos, {...options, ops});
  * // Assert on result without any real git/npm calls
  * ```
  *
- * See `operations_defaults.ts` for real implementations.
- * See test files (`*.test.ts`) for mock implementations.
+ * See `operations_defaults.ts` for real implementations, and the test-side mock
+ * factories: `create_mock_gitops_ops` in `src/test/test_helpers.ts` (plain
+ * objects with per-group overrides) and `create_fixture_gitops_ops` in
+ * `src/test/fixtures/mock_operations.ts` (a fixture's changesets over
+ * `create_mock_gitops_ops`, its fs empty).
  *
  * @module
  */
 
-import type {Result} from '@fuzdev/fuz_util/result.ts';
-import type {FsError} from '@fuzdev/fuz_util/fs.ts';
-import type {Logger} from '@fuzdev/fuz_util/log.ts';
-import type {LocalRepo} from './local_repo.ts';
-import type {ChangesetInfo} from './changeset_reader.ts';
-import type {BumpType} from './version_utils.ts';
-import type {PreflightOptions, PreflightResult} from './preflight_checks.ts';
-import type {WaitOptions} from './npm_registry.ts';
+import type { Result } from '@fuzdev/fuz_util/result.ts';
+import type { FsError } from '@fuzdev/fuz_util/fs.ts';
+import type { Logger } from '@fuzdev/fuz_util/log.ts';
+import type { LocalRepo } from './local_repo.ts';
+import type { ChangesetInfo } from './changeset_reader.ts';
+import type { BumpType } from './version_utils.ts';
+import type { PreflightResult, RunPreflightChecksOptions } from './preflight_checks.ts';
+import type { WaitOptions } from './npm_registry.ts';
 
 /**
  * Changeset operations for reading and predicting versions from `.changeset/*.md` files.
@@ -53,7 +61,7 @@ export interface ChangesetOperations {
 	 */
 	has_changesets: (options: {
 		repo: LocalRepo;
-	}) => Promise<Result<{value: boolean}, {message: string}>>;
+	}) => Promise<Result<{ value: boolean }, { message: string }>>;
 
 	/**
 	 * Reads all changeset files from a repo.
@@ -62,7 +70,7 @@ export interface ChangesetOperations {
 	read_changesets: (options: {
 		repo: LocalRepo;
 		log?: Logger;
-	}) => Promise<Result<{value: Array<ChangesetInfo>}, {message: string}>>;
+	}) => Promise<Result<{ value: Array<ChangesetInfo> }, { message: string }>>;
 
 	/**
 	 * Predicts the next version based on changesets.
@@ -72,66 +80,22 @@ export interface ChangesetOperations {
 	predict_next_version: (options: {
 		repo: LocalRepo;
 		log?: Logger;
-	}) => Promise<Result<{version: string; bump_type: BumpType}, {message: string}> | null>;
+	}) => Promise<Result<{ version: string; bump_type: BumpType }, { message: string }> | null>;
 }
 
 /**
- * Git operations for branch management, commits, tags, and workspace state.
- * All operations return `Result` instead of throwing errors.
+ * Git operations the publishing executor authors with: staging and committing
+ * dependency updates and auto-changesets, and reading the commit it published.
+ * All operations return `Result` instead of throwing errors. Where each repo
+ * sits (branch, dirt, relation to origin) is `ReposOperations`'s to report.
  */
 export interface GitOperations {
-	/**
-	 * Gets the current branch name.
-	 */
-	current_branch_name: (options?: {
-		cwd?: string;
-	}) => Promise<Result<{value: string}, {message: string}>>;
-
 	/**
 	 * Gets the current commit hash.
 	 */
 	current_commit_hash: (options?: {
-		branch?: string;
 		cwd?: string;
-	}) => Promise<Result<{value: string}, {message: string}>>;
-
-	/**
-	 * Checks if the workspace is clean (no uncommitted changes).
-	 */
-	check_clean_workspace: (options?: {
-		cwd?: string;
-	}) => Promise<Result<{value: boolean}, {message: string}>>;
-
-	/**
-	 * Checks out a branch.
-	 */
-	checkout: (options: {branch: string; cwd?: string}) => Promise<Result<object, {message: string}>>;
-
-	/**
-	 * Pulls changes from remote.
-	 */
-	pull: (options?: {
-		origin?: string;
-		branch?: string;
-		cwd?: string;
-	}) => Promise<Result<object, {message: string}>>;
-
-	/**
-	 * Switches to a branch, optionally pulling.
-	 */
-	switch_branch: (options: {
-		branch: string;
-		pull?: boolean;
-		cwd?: string;
-	}) => Promise<Result<object, {message: string}>>;
-
-	/**
-	 * Checks if a remote exists.
-	 */
-	has_remote: (options?: {
-		remote?: string;
-		cwd?: string;
-	}) => Promise<Result<{value: boolean}, {message: string}>>;
+	}) => Promise<Result<{ value: string }, { message: string }>>;
 
 	/**
 	 * Stages files for commit.
@@ -139,88 +103,75 @@ export interface GitOperations {
 	add: (options: {
 		files: string | Array<string>;
 		cwd?: string;
-	}) => Promise<Result<object, {message: string}>>;
-
-	/**
-	 * Creates a commit.
-	 */
-	commit: (options: {message: string; cwd?: string}) => Promise<Result<object, {message: string}>>;
+	}) => Promise<Result<object, { message: string }>>;
 
 	/**
-	 * Stages files and creates a commit.
+	 * Commits `files` alone (`git commit -- <files>`), leaving anything else
+	 * staged out of the commit; `files` must be non-empty.
 	 */
-	add_and_commit: (options: {
-		files: string | Array<string>;
+	commit: (options: {
 		message: string;
+		files: Array<string>;
 		cwd?: string;
-	}) => Promise<Result<object, {message: string}>>;
-
-	/**
-	 * Checks whether the working tree has any changes — staged, unstaged, or
-	 * untracked (`git status --porcelain`). Broader than `list_uncommitted_files`,
-	 * which reports only tracked working-tree changes relative to HEAD.
-	 */
-	has_changes: (options?: {cwd?: string}) => Promise<Result<{value: boolean}, {message: string}>>;
-
-	/**
-	 * Lists uncommitted files in the working tree (`git diff --name-only HEAD`),
-	 * i.e. working-tree changes relative to HEAD (not a diff between two refs).
-	 */
-	list_uncommitted_files: (options?: {
-		cwd?: string;
-	}) => Promise<Result<{value: Array<string>}, {message: string}>>;
-
-	/**
-	 * Creates a git tag.
-	 */
-	tag: (options: {
-		tag_name: string;
-		message?: string;
-		cwd?: string;
-	}) => Promise<Result<object, {message: string}>>;
+	}) => Promise<Result<object, { message: string }>>;
+}
 
+/**
+ * Process operations for the commands the publishing executor runs in a repo
+ * (`gro publish`, `gro deploy`).
+ */
+export interface ProcessOperations {
 	/**
-	 * Pushes a tag to remote.
+	 * Runs a command in the foreground and waits for it to exit: stdin is the
+	 * terminal's, so a prompt (npm's 2FA one-time password) can be answered, and
+	 * the child's output shows live — its stdout on ours, or on our stderr when
+	 * `stdout` says so, and its stderr on ours. A failure carries the end of
+	 * what the child wrote to stderr, bounded in lines and characters.
 	 */
-	push_tag: (options: {
-		tag_name: string;
-		origin?: string;
+	run_interactive: (options: {
+		cmd: string;
+		args: Array<string>;
 		cwd?: string;
-	}) => Promise<Result<object, {message: string}>>;
-
-	/**
-	 * Stashes uncommitted changes.
-	 */
-	stash: (options?: {message?: string; cwd?: string}) => Promise<Result<object, {message: string}>>;
-
-	/**
-	 * Pops the most recent stash.
-	 */
-	stash_pop: (options?: {cwd?: string}) => Promise<Result<object, {message: string}>>;
+		/**
+		 * Where the child's stdout goes: our stdout, or our stderr when our stdout
+		 * carries a machine-readable stream (JSON-lines events, a JSON or markdown
+		 * report) the child's output would corrupt.
+		 *
+		 * @default 'stdout'
+		 */
+		stdout?: 'stdout' | 'stderr';
+	}) => Promise<Result<object, { message: string; stderr_tail?: string }>>;
+}
 
-	/**
-	 * Checks if a specific file changed between two commits.
-	 */
-	has_file_changed: (options: {
-		from_commit: string;
-		to_commit: string;
-		file_path: string;
-		cwd?: string;
-	}) => Promise<Result<{value: boolean}, {message: string}>>;
+/**
+ * What a `repos` command printed and how it exited, unparsed.
+ */
+export interface ReposCommandOutput {
+	stdout: string;
+	stderr: string;
+	/** `0` for a report, `2` for an error document, `1` for a fatal I/O error (maybe no JSON). */
+	exit_code: number;
 }
 
 /**
- * Process spawning operations for running shell commands.
+ * Operations running the Rust `repos` binary, which owns fleet git state.
+ * Parsing its output is `repos_status_load.ts`'s, not the runner's.
  */
-export interface ProcessOperations {
+export interface ReposOperations {
 	/**
-	 * Spawns a child process and waits for completion.
+	 * Runs `repos [--registry <path>] status [--fetch] <keys…> --json` in the
+	 * process's cwd and returns what it printed, whatever its exit code. With
+	 * `fetch`, `repos` fetches each entry from origin first, which writes
+	 * remote-tracking refs and nothing else. Fails only when the binary didn't
+	 * run to an exit: `not_found` when it isn't on `PATH`.
 	 */
-	spawn: (options: {
-		cmd: string;
-		args: Array<string>;
-		cwd?: string;
-	}) => Promise<Result<{stdout?: string; stderr?: string}, {message: string; stderr?: string}>>;
+	status: (options: {
+		keys: Array<string>;
+		registry?: string;
+		fetch?: boolean;
+	}) => Promise<
+		Result<{ output: ReposCommandOutput }, { kind: 'not_found' | 'failed'; message: string }>
+	>;
 }
 
 /**
@@ -232,8 +183,7 @@ export interface BuildOperations {
 	 */
 	build_package: (options: {
 		repo: LocalRepo;
-		log?: Logger;
-	}) => Promise<Result<object, {message: string; output?: string}>>;
+	}) => Promise<Result<object, { message: string; output?: string }>>;
 }
 
 /**
@@ -250,42 +200,29 @@ export interface NpmOperations {
 		version: string;
 		wait_options?: WaitOptions;
 		log?: Logger;
-	}) => Promise<Result<object, {message: string; timeout?: boolean}>>;
+	}) => Promise<Result<object, { message: string }>>;
 
 	/**
 	 * Checks npm authentication status.
 	 */
-	check_auth: () => Promise<Result<{username: string}, {message: string}>>;
+	check_auth: () => Promise<Result<{ username: string }, { message: string }>>;
 
 	/**
 	 * Checks if npm registry is reachable.
 	 */
-	check_registry: () => Promise<Result<object, {message: string}>>;
-
-	/**
-	 * Installs npm dependencies.
-	 */
-	install: (options?: {
-		cwd?: string;
-	}) => Promise<Result<object, {message: string; stderr?: string}>>;
+	check_registry: () => Promise<Result<object, { message: string }>>;
 }
 
 /**
- * Preflight validation operations to ensure repos are ready for publishing.
- * Validates workspace state, branches, builds, and npm authentication.
+ * Preflight validation operations run before publishing: building every
+ * package the plan publishes, and npm authentication. Repo git state is the
+ * readiness gate's, before preflight (see `repo_readiness.ts`).
  */
 export interface PreflightOperations {
 	/**
 	 * Runs preflight validation checks before publishing.
 	 */
-	run_preflight_checks: (options: {
-		repos: Array<LocalRepo>;
-		preflight_options: PreflightOptions;
-		git_ops?: GitOperations;
-		npm_ops?: NpmOperations;
-		build_ops?: BuildOperations;
-		changeset_ops?: ChangesetOperations;
-	}) => Promise<PreflightResult>;
+	run_preflight_checks: (options: RunPreflightChecksOptions) => Promise<PreflightResult>;
 }
 
 /**
@@ -302,22 +239,22 @@ export interface FsOperations {
 	readFile: (options: {
 		path: string;
 		encoding: BufferEncoding;
-	}) => Promise<Result<{value: string}, FsError>>;
+	}) => Promise<Result<{ value: string }, FsError>>;
 
 	/**
 	 * Writes a file to the file system.
 	 */
-	writeFile: (options: {path: string; content: string}) => Promise<Result<object, FsError>>;
+	writeFile: (options: { path: string; content: string }) => Promise<Result<object, FsError>>;
 
 	/**
 	 * Creates a directory, optionally with recursive creation.
 	 */
-	mkdir: (options: {path: string; recursive?: boolean}) => Promise<Result<object, FsError>>;
+	mkdir: (options: { path: string; recursive?: boolean }) => Promise<Result<object, FsError>>;
 
 	/**
 	 * Checks if a path exists on the file system.
 	 */
-	exists: (options: {path: string}) => Promise<boolean>;
+	exists: (options: { path: string }) => Promise<boolean>;
 }
 
 /**
@@ -332,4 +269,6 @@ export interface GitopsOperations {
 	preflight: PreflightOperations;
 	fs: FsOperations;
 	build: BuildOperations;
+	/** `repos status`, for the executor's re-check of each repo right before its publish. */
+	repos: ReposOperations;
 }