@fuzdev/fuz_gitops 0.68.0 → 0.69.0

package/src/lib/fs_fetch_value_cache.ts

@@ -17,7 +17,7 @@ export interface FetchCache {
 }
 
 /**
- * Creates file-system backed cache for fuz_util's fetch.js API responses.
+ * Creates file-system backed cache for `fuz_util`'s `fetch.js` API responses.
  *
  * Cache invalidation strategy: If cache file can't be read or parsed, entire
  * cache is cleared (delete file) and starts fresh. This handles format changes.
@@ -25,9 +25,9 @@ export interface FetchCache {
  * Uses `structuredClone` to track changes - only writes to disk if data modified.
  * Formatted with Prettier before writing for version control friendliness.
  *
- * @param name cache filename (without .json extension)
- * @param dir cache directory (defaults to `.gro/build/fetch/`)
- * @returns cache object with Map-based data and save() method
+ * @param name - cache filename (without .json extension)
+ * @param dir - cache directory (defaults to `.gro/build/fetch/`)
+ * @returns cache object with Map-based data and `save()` method
  */
 export const create_fs_fetch_value_cache = async (
 	name: string,

package/src/lib/git_operations.ts

@@ -1,4 +1,4 @@
-import {spawn, spawn_out} from '@fuzdev/fuz_util/process.js';
+import {spawn_out, spawn_result_to_message} from '@fuzdev/fuz_util/process.js';
 import type {SpawnOptions} from 'node:child_process';
 import {
 	git_check_clean_workspace as gro_git_check_clean_workspace,
@@ -18,9 +18,11 @@ export const git_add = async (
 	options?: SpawnOptions,
 ): Promise<void> => {
 	const file_list = Array.isArray(files) ? files : [files];
-	const result = await spawn('git', ['add', ...file_list], options);
+	const {result, stderr} = await spawn_out('git', ['add', ...file_list], options);
 	if (!result.ok) {
-		throw Error(`git_add failed with code ${result.code}`);
+		throw Error(
+			`git_add failed with ${spawn_result_to_message(result)}${stderr ? ': ' + stderr.trim() : ''}`,
+		);
 	}
 };
 
@@ -28,9 +30,11 @@ export const git_add = async (
  * Commits staged changes with a message and throws if anything goes wrong.
  */
 export const git_commit = async (message: string, options?: SpawnOptions): Promise<void> => {
-	const result = await spawn('git', ['commit', '-m', message], options);
+	const {result, stderr} = await spawn_out('git', ['commit', '-m', message], options);
 	if (!result.ok) {
-		throw Error(`git_commit failed with code ${result.code}`);
+		throw Error(
+			`git_commit failed with ${spawn_result_to_message(result)}${stderr ? ': ' + stderr.trim() : ''}`,
+		);
 	}
 };
 
@@ -56,9 +60,11 @@ export const git_tag = async (
 ): Promise<void> => {
 	const args = message ? ['tag', '-a', tag_name, '-m', message] : ['tag', tag_name];
 
-	const result = await spawn('git', args, options);
+	const {result, stderr} = await spawn_out('git', args, options);
 	if (!result.ok) {
-		throw Error(`git_tag failed for tag '${tag_name}' with code ${result.code}`);
+		throw Error(
+			`git_tag failed for tag '${tag_name}' with ${spawn_result_to_message(result)}${stderr ? ': ' + stderr.trim() : ''}`,
+		);
 	}
 };
 
@@ -70,9 +76,11 @@ export const git_push_tag = async (
 	origin: GitOrigin = 'origin' as GitOrigin,
 	options?: SpawnOptions,
 ): Promise<void> => {
-	const result = await spawn('git', ['push', origin, tag_name], options);
+	const {result, stderr} = await spawn_out('git', ['push', origin, tag_name], options);
 	if (!result.ok) {
-		throw Error(`git_push_tag failed for tag '${tag_name}' with code ${result.code}`);
+		throw Error(
+			`git_push_tag failed for tag '${tag_name}' with ${spawn_result_to_message(result)}${stderr ? ': ' + stderr.trim() : ''}`,
+		);
 	}
 };
 
@@ -82,9 +90,11 @@ export const git_has_changes = async (options?: SpawnOptions): Promise<boolean>
 };
 
 /**
- * Returns list of changed files compared to HEAD.
+ * Lists uncommitted files in the working tree (`git diff --name-only HEAD`).
  */
-export const git_get_changed_files = async (options?: SpawnOptions): Promise<Array<string>> => {
+export const git_list_uncommitted_files = async (
+	options?: SpawnOptions,
+): Promise<Array<string>> => {
 	const {stdout} = await spawn_out('git', ['diff', '--name-only', 'HEAD'], options);
 	if (!stdout) return [];
 
@@ -114,9 +124,11 @@ export const git_has_file_changed = async (
 export const git_stash = async (message?: string, options?: SpawnOptions): Promise<void> => {
 	const args = message ? ['stash', 'push', '-m', message] : ['stash', 'push'];
 
-	const result = await spawn('git', args, options);
+	const {result, stderr} = await spawn_out('git', args, options);
 	if (!result.ok) {
-		throw Error(`git_stash failed with code ${result.code}`);
+		throw Error(
+			`git_stash failed with ${spawn_result_to_message(result)}${stderr ? ': ' + stderr.trim() : ''}`,
+		);
 	}
 };
 
@@ -124,9 +136,11 @@ export const git_stash = async (message?: string, options?: SpawnOptions): Promi
  * Applies stashed changes and throws if anything goes wrong.
  */
 export const git_stash_pop = async (options?: SpawnOptions): Promise<void> => {
-	const result = await spawn('git', ['stash', 'pop'], options);
+	const {result, stderr} = await spawn_out('git', ['stash', 'pop'], options);
 	if (!result.ok) {
-		throw Error(`git_stash_pop failed with code ${result.code}`);
+		throw Error(
+			`git_stash_pop failed with ${spawn_result_to_message(result)}${stderr ? ': ' + stderr.trim() : ''}`,
+		);
 	}
 };
 
@@ -160,7 +174,7 @@ export const git_switch_branch = async (
 };
 
 /**
- * Wrapper for gro's git_current_branch_name that throws if null.
+ * Wrapper for gro's `git_current_branch_name` that throws if null.
  */
 export const git_current_branch_name_required = async (options?: SpawnOptions): Promise<string> => {
 	const branch = await gro_git_current_branch_name(options);
@@ -171,7 +185,7 @@ export const git_current_branch_name_required = async (options?: SpawnOptions):
 };
 
 /**
- * Wrapper for gro's git_current_commit_hash that throws if null.
+ * Wrapper for gro's `git_current_commit_hash` that throws if null.
  */
 export const git_current_commit_hash_required = async (
 	branch?: string,
@@ -185,7 +199,7 @@ export const git_current_commit_hash_required = async (
 };
 
 /**
- * Wrapper for gro's git_check_clean_workspace that returns a boolean.
+ * Wrapper for gro's `git_check_clean_workspace` that returns a boolean.
  */
 export const git_check_clean_workspace_as_boolean = async (
 	options?: SpawnOptions,

package/src/lib/github.ts

@@ -3,7 +3,7 @@ import {z} from 'zod';
 import {fetch_value, type FetchValueCache} from '@fuzdev/fuz_util/fetch.js';
 
 /**
- * Minimal interface for GitHub API calls - works with both Pkg and Repo.
+ * Minimal interface for GitHub API calls - works with both `Pkg` and `Repo`.
  */
 export interface GithubRepoInfo {
 	owner_name: string | null;

package/src/lib/gitops_plan.task.ts

@@ -36,9 +36,9 @@ export type Args = z.infer<typeof Args>;
  * Shows version changes, dependency updates, and breaking change cascades.
  *
  * Usage:
- *   gro gitops_plan
- *   gro gitops_plan --dir ../repos
- *   gro gitops_plan --config ./custom.config.ts
+ *   `gro gitops_plan`
+ *   `gro gitops_plan --dir ../repos`
+ *   `gro gitops_plan --config ./custom.config.ts`
  *
  * @nodocs
  */

package/src/lib/gitops_run.task.ts

@@ -75,7 +75,7 @@ export const task: Task<Args> = {
 					repo_name,
 					repo_dir,
 					status: success ? 'success' : 'failure',
-					exit_code: spawned.result.code ?? 0,
+					exit_code: spawned.result.kind === 'exited' ? spawned.result.code : 0,
 					stdout: spawned.stdout || '',
 					stderr: spawned.stderr || '',
 					duration_ms,

package/src/lib/gitops_task_helpers.ts

@@ -46,17 +46,17 @@ export interface GetGitopsReadyOptions {
  * 1. Loads and normalizes config from `gitops.config.ts`
  * 2. Resolves local repo paths (creates missing with `--download`)
  * 3. Switches branches and pulls latest changes (in parallel by default)
- * 4. Auto-installs deps if package.json changed during pull
+ * 4. Auto-installs deps if `package.json` changed during pull
  *
  * Priority for path resolution:
  * - `dir` argument (explicit override)
  * - Config `repos_dir` setting
  * - `DEFAULT_REPOS_DIR` constant
  *
- * @param options.git_ops for testing (defaults to real git operations)
- * @param options.npm_ops for testing (defaults to real npm operations)
- * @param options.parallel whether to load repos in parallel (default: true)
- * @param options.concurrency max concurrent repo loads (default: 5)
+ * @param options.git_ops - for testing (defaults to real git operations)
+ * @param options.npm_ops - for testing (defaults to real npm operations)
+ * @param options.parallel - whether to load repos in parallel (default: true)
+ * @param options.concurrency - max concurrent repo loads (default: 5)
  * @returns initialized config and fully loaded repos ready for operations
  * @throws {TaskError} if config loading or repo resolution fails
  */

package/src/lib/graph_validation.ts

@@ -30,13 +30,13 @@ export interface GraphValidationResult {
 
 /**
  * Shared utility for building dependency graph, detecting cycles, and computing publishing order.
- * This centralizes logic that was duplicated across multi_repo_publisher, publishing_plan, and gitops_analyze.
+ * This centralizes logic that was duplicated across `multi_repo_publisher`, `publishing_plan`, and `gitops_analyze`.
  *
- * @param options.throw_on_prod_cycles whether to throw an error if production cycles are detected (default: true)
- * @param options.log_cycles whether to log cycle information (default: true)
- * @param options.log_order whether to log publishing order (default: true)
+ * @param options.throw_on_prod_cycles - whether to throw an error if production cycles are detected (default: true)
+ * @param options.log_cycles - whether to log cycle information (default: true)
+ * @param options.log_order - whether to log publishing order (default: true)
  * @returns graph validation result with graph, publishing order, and detected cycles
- * @throws {TaskError} if production cycles detected and throw_on_prod_cycles is true
+ * @throws {TaskError} if production cycles detected and `throw_on_prod_cycles` is true
  */
 export const validate_dependency_graph = (
 	repos: Array<LocalRepo>,

package/src/lib/local_repo.ts

@@ -5,7 +5,7 @@ import {existsSync} from 'node:fs';
 import {join} from 'node:path';
 import {TaskError} from '@fuzdev/gro';
 import type {Logger} from '@fuzdev/fuz_util/log.js';
-import {spawn} from '@fuzdev/fuz_util/process.js';
+import {spawn_out} from '@fuzdev/fuz_util/process.js';
 import {map_concurrent_settled} from '@fuzdev/fuz_util/async.js';
 import type {GitOperations, NpmOperations} from './operations.js';
 import {default_git_operations, default_npm_operations} from './operations_defaults.js';
@@ -15,8 +15,8 @@ import type {ResolvedGitopsConfig} from './resolved_gitops_config.js';
 import {GITOPS_CONCURRENCY_DEFAULT} from './gitops_constants.js';
 
 /**
- * Fully loaded local repo with Library and extracted dependency data.
- * Does not extend LocalRepoPath - Library is source of truth for name/repo_url/etc.
+ * Fully loaded local repo with `Library` and extracted dependency data.
+ * Does not extend `LocalRepoPath` - `Library` is source of truth for name/repo_url/etc.
  */
 export interface LocalRepo {
 	library: Library;
@@ -61,14 +61,14 @@ export interface LocalRepoMissing {
  * 2. Switches to target branch if needed (requires clean workspace)
  * 3. Pulls latest changes from remote (skipped for local-only repos)
  * 4. Validates workspace is clean after pull
- * 5. Auto-installs dependencies if package.json changed
- * 6. Imports library_json from src/routes/library.ts
- * 7. Creates Library and extracts dependency maps
+ * 5. Auto-installs dependencies if `package.json` changed
+ * 6. Imports `library_json` from `src/routes/library.ts`
+ * 7. Creates `Library` and extracts dependency maps
  *
  * This ensures repos are always in sync with their configured branch
  * before being used by gitops commands.
  *
- * @throws {TaskError} if workspace dirty, branch switch fails, install fails, or library.ts missing
+ * @throws {TaskError} if workspace dirty, branch switch fails, install fails, or `library.ts` missing
  */
 export const local_repo_load = async ({
 	local_repo_path,
@@ -296,7 +296,7 @@ export const local_repos_load = async ({
 		// Sequential loading (original behavior)
 		const loaded: Array<LocalRepo> = [];
 		for (const local_repo_path of local_repo_paths) {
-			loaded.push(await local_repo_load({local_repo_path, log, git_ops, npm_ops})); // eslint-disable-line no-await-in-loop
+			loaded.push(await local_repo_load({local_repo_path, log, git_ops, npm_ops}));
 		}
 		return loaded;
 	}
@@ -383,14 +383,21 @@ const download_repos = async ({
 	const resolved: Array<LocalRepoPath> = [];
 	for (const {repo_config, repo_git_ssh_url} of local_repos_missing) {
 		log?.info(`cloning repo ${repo_git_ssh_url} to ${repos_dir}`);
-		await spawn('git', ['clone', repo_git_ssh_url], {cwd: repos_dir}); // eslint-disable-line no-await-in-loop
+		const clone_result = await spawn_out('git', ['clone', repo_git_ssh_url], {cwd: repos_dir});
+		if (!clone_result.result.ok) {
+			throw new TaskError(
+				`Failed to clone repo ${repo_git_ssh_url} to ${repos_dir}${clone_result.stderr ? ': ' + clone_result.stderr.trim() : ''}`,
+			);
+		}
 		const local_repo = local_repo_locate({repo_config, repos_dir});
 		if (local_repo.type === 'local_repo_missing') {
-			throw new TaskError(`Failed to clone repo ${repo_git_ssh_url} to ${repos_dir}`);
+			throw new TaskError(
+				`Failed to clone repo ${repo_git_ssh_url} to ${repos_dir}: directory not found after clone`,
+			);
 		}
 		// Always install dependencies after cloning
 		log?.info(`installing dependencies for newly cloned repo ${local_repo.repo_dir}`);
-		const install_result = await npm_ops.install({cwd: local_repo.repo_dir}); // eslint-disable-line no-await-in-loop
+		const install_result = await npm_ops.install({cwd: local_repo.repo_dir});
 		if (!install_result.ok) {
 			throw new TaskError(
 				`Failed to install dependencies in ${local_repo.repo_dir}: ${install_result.message}${install_result.stderr ? `\n${install_result.stderr}` : ''}`,

package/src/lib/multi_repo_publisher.ts

@@ -16,8 +16,6 @@ import {
 } from './gitops_constants.js';
 import {install_with_cache_healing} from './npm_install_helpers.js';
 
-/* eslint-disable no-await-in-loop */
-
 export interface PublishingOptions {
 	wetrun: boolean;
 	update_deps: boolean;
@@ -337,7 +335,7 @@ export const publish_repos = async (
 				const deploy_result = await ops.process.spawn({
 					cmd: 'gro',
 					args: ['deploy', '--no-build'],
-					spawn_options: {cwd: repo.repo_dir},
+					cwd: repo.repo_dir,
 				});
 
 				if (deploy_result.ok) {
@@ -377,11 +375,11 @@ export const publish_repos = async (
 };
 
 /**
- * Publishes a single repo using gro publish.
+ * Publishes a single repo using `gro publish`.
  *
  * Dry run mode: Predicts version from changesets without side effects.
  * Real mode: Runs `gro publish --no-build` (builds already validated in preflight),
- * reads new version from package.json, and returns metadata.
+ * reads new version from `package.json`, and returns metadata.
  *
  * @throws {Error} if changeset prediction fails (dry run) or publish fails (real)
  */
@@ -426,7 +424,7 @@ const publish_single_repo = async (
 	const publish_result = await ops.process.spawn({
 		cmd: 'gro',
 		args: ['publish', '--no-build'],
-		spawn_options: {cwd: repo.repo_dir},
+		cwd: repo.repo_dir,
 	});
 
 	if (!publish_result.ok) {

package/src/lib/npm_install_helpers.ts

@@ -34,9 +34,9 @@ const is_etarget_error = (message: string, stderr: string): boolean => {
  * npm's local cache may still have stale "404" metadata. This healing
  * strategy clears the cache to force fresh metadata fetch.
  *
- * @param repo - The repository to install dependencies for
- * @param ops - Gitops operations (for dependency injection)
- * @param log - Optional logger
+ * @param repo - the repository to install dependencies for
+ * @param ops - gitops operations (for dependency injection)
+ * @param log - optional logger
  * @throws Error if install fails (with details about cache healing attempts)
  */
 export const install_with_cache_healing = async (

package/src/lib/npm_registry.ts

@@ -48,10 +48,10 @@ export const check_package_available = async (
  * Critical for multi-repo publishing: ensures published packages are available
  * before updating dependent packages.
  *
- * @param options.max_attempts max poll attempts (default 30)
- * @param options.initial_delay starting delay in ms (default 1000)
- * @param options.max_delay max delay between attempts (default 60000)
- * @param options.timeout total timeout in ms (default 300000 = 5min)
+ * @param options.max_attempts - max poll attempts (default 30)
+ * @param options.initial_delay - starting delay in ms (default 1000)
+ * @param options.max_delay - max delay between attempts (default 60000)
+ * @param options.timeout - total timeout in ms (default 300000 = 5min)
  * @throws {Error} if timeout reached or max attempts exceeded
  */
 export const wait_for_package = async (
@@ -80,7 +80,7 @@ export const wait_for_package = async (
 		}
 
 		// Check if package is available
-		// eslint-disable-next-line no-await-in-loop
+
 		if (await check_package_available(pkg, version, {log})) {
 			log?.info(st('green', `    ✓ ${pkg}@${version} is now available on NPM`));
 			return;
@@ -94,7 +94,7 @@ export const wait_for_package = async (
 		// 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); // eslint-disable-line no-await-in-loop
+		await wait(actual_delay);
 
 		// Exponential backoff
 		delay = Math.min(delay * 1.5, max_delay);

package/src/lib/operations.ts

@@ -29,14 +29,14 @@
  * ```
  *
  * See `operations_defaults.ts` for real implementations.
- * See test files (*.test.ts) for mock implementations.
+ * See test files (`*.test.ts`) for mock implementations.
  *
  * @module
  */
 
 import type {Result} from '@fuzdev/fuz_util/result.js';
+import type {FsError} from '@fuzdev/fuz_util/fs.js';
 import type {Logger} from '@fuzdev/fuz_util/log.js';
-import type {SpawnOptions} from 'node:child_process';
 import type {LocalRepo} from './local_repo.js';
 import type {ChangesetInfo} from './changeset_reader.js';
 import type {BumpType} from './semver.js';
@@ -67,7 +67,7 @@ export interface ChangesetOperations {
 	/**
 	 * Predicts the next version based on changesets.
 	 * Returns null if no changesets found (expected, not an error).
-	 * Returns error Result if changesets exist but can't be read/parsed.
+	 * Returns error `Result` if changesets exist but can't be read/parsed.
 	 */
 	predict_next_version: (options: {
 		repo: LocalRepo;
@@ -161,9 +161,13 @@ export interface GitOperations {
 	has_changes: (options?: {cwd?: string}) => Promise<Result<{value: boolean}, {message: string}>>;
 
 	/**
-	 * Gets a list of changed files.
+	 * Lists uncommitted files in the working tree (`git diff --name-only HEAD`).
+	 *
+	 * Renamed from `get_changed_files` in 2026-04 because "changed files" collided
+	 * with mageguild's `get_changed_files` which diffs two refs. This one reports
+	 * uncommitted working-tree changes relative to HEAD.
 	 */
-	get_changed_files: (options?: {
+	list_uncommitted_files: (options?: {
 		cwd?: string;
 	}) => Promise<Result<{value: Array<string>}, {message: string}>>;
 
@@ -216,7 +220,7 @@ export interface ProcessOperations {
 	spawn: (options: {
 		cmd: string;
 		args: Array<string>;
-		spawn_options?: SpawnOptions;
+		cwd?: string;
 	}) => Promise<Result<{stdout?: string; stderr?: string}, {message: string; stderr?: string}>>;
 }
 
@@ -225,7 +229,7 @@ export interface ProcessOperations {
  */
 export interface BuildOperations {
 	/**
-	 * Builds a package using gro build.
+	 * Builds a package using `gro build`.
 	 */
 	build_package: (options: {
 		repo: LocalRepo;
@@ -302,6 +306,10 @@ export interface PreflightOperations {
 
 /**
  * File system operations for reading and writing files.
+ *
+ * Errors are typed via `FsError` (`not_found | permission_denied |
+ * already_exists | io_error`) so callers can branch on `kind` instead of
+ * regex-matching `message`. See `@fuzdev/fuz_util/fs.js`.
  */
 export interface FsOperations {
 	/**
@@ -310,28 +318,22 @@ export interface FsOperations {
 	readFile: (options: {
 		path: string;
 		encoding: BufferEncoding;
-	}) => Promise<Result<{value: string}, {message: string}>>;
+	}) => Promise<Result<{value: string}, FsError>>;
 
 	/**
 	 * Writes a file to the file system.
 	 */
-	writeFile: (options: {
-		path: string;
-		content: string;
-	}) => Promise<Result<object, {message: string}>>;
+	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, {message: string}>>;
+	mkdir: (options: {path: string; recursive?: boolean}) => Promise<Result<object, FsError>>;
 
 	/**
 	 * Checks if a path exists on the file system.
 	 */
-	exists: (options: {path: string}) => boolean;
+	exists: (options: {path: string}) => Promise<boolean>;
 }
 
 /**

package/src/lib/operations_defaults.ts

@@ -7,10 +7,10 @@
  * @module
  */
 
-import {spawn, spawn_out} from '@fuzdev/fuz_util/process.js';
-import {readFile, writeFile, mkdir} from 'node:fs/promises';
-import {existsSync} from 'node:fs';
+import {spawn_out} from '@fuzdev/fuz_util/process.js';
+import {readFile, writeFile, mkdir, stat} from 'node:fs/promises';
 import {git_checkout, type GitBranch, type GitOrigin} from '@fuzdev/fuz_util/git.js';
+import {fs_classify_error} from '@fuzdev/fuz_util/fs.js';
 import {EMPTY_OBJECT} from '@fuzdev/fuz_util/object.js';
 
 import {has_changesets, read_changesets, predict_next_version} from './changeset_reader.js';
@@ -23,7 +23,7 @@ import {
 	git_tag,
 	git_push_tag,
 	git_has_changes,
-	git_get_changed_files,
+	git_list_uncommitted_files,
 	git_has_file_changed,
 	git_stash,
 	git_stash_pop,
@@ -118,9 +118,20 @@ export const default_git_operations: GitOperations = {
 
 	pull: async (options) => {
 		const {origin, branch, cwd} = options ?? EMPTY_OBJECT;
-		return wrap_void(() =>
-			spawn('git', ['pull', origin || 'origin', branch || ''], cwd ? {cwd} : undefined),
-		);
+		try {
+			const spawned = await spawn_out(
+				'git',
+				['pull', origin || 'origin', branch || ''],
+				cwd ? {cwd} : undefined,
+			);
+			if (spawned.result.ok) {
+				return {ok: true};
+			} else {
+				return {ok: false, message: spawned.stderr || 'Pull failed'};
+			}
+		} catch (error) {
+			return {ok: false, message: String(error)};
+		}
 	},
 
 	switch_branch: async (options) => {
@@ -154,9 +165,9 @@ export const default_git_operations: GitOperations = {
 		return wrap_with_value(() => git_has_changes(cwd ? {cwd} : undefined));
 	},
 
-	get_changed_files: async (options) => {
+	list_uncommitted_files: async (options) => {
 		const {cwd} = options ?? EMPTY_OBJECT;
-		return wrap_with_value(() => git_get_changed_files(cwd ? {cwd} : undefined));
+		return wrap_with_value(() => git_list_uncommitted_files(cwd ? {cwd} : undefined));
 	},
 
 	// Tagging
@@ -192,9 +203,9 @@ export const default_git_operations: GitOperations = {
 
 export const default_process_operations: ProcessOperations = {
 	spawn: async (options) => {
-		const {cmd, args, spawn_options} = options;
+		const {cmd, args, cwd} = options;
 		try {
-			const spawned = await spawn_out(cmd, args, spawn_options);
+			const spawned = await spawn_out(cmd, args, cwd ? {cwd} : undefined);
 			if (spawned.result.ok) {
 				return {
 					ok: true,
@@ -294,21 +305,41 @@ export const default_preflight_operations: PreflightOperations = {
 export const default_fs_operations: FsOperations = {
 	readFile: async (options) => {
 		const {path, encoding} = options;
-		return wrap_with_value(() => readFile(path, encoding));
+		try {
+			const value = await readFile(path, encoding);
+			return {ok: true, value};
+		} catch (error) {
+			return {ok: false, ...fs_classify_error(error)};
+		}
 	},
 
 	writeFile: async (options) => {
 		const {path, content} = options;
-		return wrap_void(() => writeFile(path, content));
+		try {
+			await writeFile(path, content);
+			return {ok: true};
+		} catch (error) {
+			return {ok: false, ...fs_classify_error(error)};
+		}
 	},
 
 	mkdir: async (options) => {
 		const {path, recursive} = options;
-		return wrap_void(() => mkdir(path, {recursive}));
+		try {
+			await mkdir(path, {recursive});
+			return {ok: true};
+		} catch (error) {
+			return {ok: false, ...fs_classify_error(error)};
+		}
 	},
 
-	exists: (options) => {
-		return existsSync(options.path);
+	exists: async (options) => {
+		try {
+			await stat(options.path);
+			return true;
+		} catch {
+			return false;
+		}
 	},
 };
 

package/src/lib/output_helpers.ts

@@ -22,11 +22,11 @@ export interface OutputFormatters<T> {
  * Formats data and outputs to file or stdout based on options.
  *
  * Supports three formats:
- * - stdout: Uses logger for colored/styled output (cannot use with --outfile)
+ * - stdout: Uses logger for colored/styled output (cannot use with `--outfile`)
  * - json: Stringified JSON
  * - markdown: Formatted markdown text
  *
- * @throws {Error} if stdout format used with outfile, or if logger missing for stdout
+ * @throws {Error} if stdout format used with `outfile`, or if logger missing for stdout
  */
 export const format_and_output = async <T>(
 	data: T,

package/src/lib/paths.ts

@@ -6,6 +6,6 @@ export const GITOPS_OUTPUT_DIR = '.gro/fuz_gitops';
 /**
  * Default repos directory relative to gitops config file.
  * Resolves to the parent of the directory with the config
- * (e.g., ~/dev/repo/gitops.config.ts resolves to ~/dev/).
+ * (e.g., `~/dev/repo/gitops.config.ts` resolves to `~/dev/`).
  */
 export const DEFAULT_REPOS_DIR = '..';