@fuzdev/fuz_gitops 0.68.0 → 0.70.0

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 = '..';

package/src/lib/preflight_checks.ts

@@ -51,7 +51,7 @@ export interface RunPreflightChecksOptions {
  * Performs comprehensive pre-flight validation:
  * - Clean workspaces (100% clean required - no uncommitted changes)
  * - Correct branch (usually main)
- * - Changesets present (unless skip_changesets=true)
+ * - Changesets present (unless `skip_changesets`=true)
  * - Builds successful (fail-fast to prevent broken state)
  * - Git remote reachability
  * - NPM authentication with username
@@ -60,7 +60,7 @@ export interface RunPreflightChecksOptions {
  * 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 and detailed status
  */
 export const run_preflight_checks = async ({
 	repos,
@@ -91,7 +91,7 @@ export const run_preflight_checks = async ({
 	// 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}); // eslint-disable-line no-await-in-loop
+		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;
@@ -99,7 +99,7 @@ export const run_preflight_checks = async ({
 
 		if (!clean_result.value) {
 			// Get list of changed files for better error message
-			const files_result = await git_ops.get_changed_files({cwd: repo.repo_dir}); // eslint-disable-line no-await-in-loop
+			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;
@@ -118,7 +118,7 @@ export const run_preflight_checks = async ({
 	// 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}); // eslint-disable-line no-await-in-loop
+		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;
@@ -135,7 +135,7 @@ export const run_preflight_checks = async ({
 	if (!skip_changesets) {
 		log?.info('  Checking for changesets...');
 		for (const repo of repos) {
-			const has_result = await changeset_ops.has_changesets({repo}); // eslint-disable-line no-await-in-loop
+			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;
@@ -164,7 +164,7 @@ export const run_preflight_checks = async ({
 			log?.info(
 				st('dim', `    [${i + 1}/${repos_to_build.length}] Building ${repo.library.name}...`),
 			);
-			const build_result = await build_ops.build_package({repo, log}); // eslint-disable-line no-await-in-loop
+			const build_result = await build_ops.build_package({repo, log});
 			if (!build_result.ok) {
 				errors.push(
 					`${repo.library.name} failed to build: ${build_result.output || build_result.message || 'unknown error'}`,

package/src/lib/publishing_plan.ts

@@ -179,7 +179,7 @@ export const generate_publishing_plan = async (
 		if (!repo) continue;
 
 		// Check for changesets
-		const has_result = await ops.has_changesets({repo}); // eslint-disable-line no-await-in-loop
+		const has_result = await ops.has_changesets({repo});
 
 		if (!has_result.ok) {
 			errors.push(`Failed to check changesets for ${pkg_name}: ${has_result.message}`);
@@ -188,7 +188,7 @@ export const generate_publishing_plan = async (
 
 		if (has_result.value) {
 			// Predict version from changesets
-			const prediction = await ops.predict_next_version({repo, log}); // eslint-disable-line no-await-in-loop
+			const prediction = await ops.predict_next_version({repo, log});
 
 			if (!prediction) {
 				// No changesets found - this shouldn't happen since has_changesets returned true
@@ -202,7 +202,7 @@ export const generate_publishing_plan = async (
 
 			// Capture changeset details for verbose output
 			if (verbose) {
-				const changesets_result = await ops.read_changesets({repo, log}); // eslint-disable-line no-await-in-loop
+				const changesets_result = await ops.read_changesets({repo, log});
 				if (changesets_result.ok) {
 					const files = changesets_result.value
 						.filter((cs) => cs.packages.some((p) => p.name === pkg_name))
@@ -445,7 +445,7 @@ export const generate_publishing_plan = async (
 	for (const repo of repos) {
 		const has_version_change = version_changes.some((vc) => vc.package_name === repo.library.name);
 		if (!has_version_change) {
-			const has_result = await ops.has_changesets({repo}); // eslint-disable-line no-await-in-loop
+			const has_result = await ops.has_changesets({repo});
 			if (has_result.ok && !has_result.value) {
 				info.push(repo.library.name);
 			}

package/src/lib/publishing_plan_helpers.ts

@@ -1,7 +1,7 @@
 /**
  * Helper functions for publishing plan calculations.
  *
- * Extracted from publishing_plan.ts to reduce file size.
+ * Extracted from `publishing_plan.ts` to reduce file size.
  *
  * @module
  */

package/src/lib/repo.svelte.ts

@@ -1,7 +1,6 @@
 import {create_context} from '@fuzdev/fuz_ui/context_helpers.js';
-import type {LibraryJson} from '@fuzdev/fuz_util/library_json.js';
+import type {LibraryJson, SourceJson} from '@fuzdev/fuz_util/library_json.js';
 import type {PackageJson} from '@fuzdev/fuz_util/package_json.js';
-import type {SourceJson} from '@fuzdev/fuz_util/source_json.js';
 import type {Url} from '@fuzdev/fuz_util/url.js';
 import {Library} from '@fuzdev/fuz_ui/library.svelte.js';
 import type {Module} from '@fuzdev/fuz_ui/module.svelte.js';
@@ -9,7 +8,7 @@ import type {Module} from '@fuzdev/fuz_ui/module.svelte.js';
 import {GithubCheckRunsItem, type GithubPullRequest} from './github.js';
 
 /**
- * Serialized repo data as stored in repos.ts (JSON).
+ * Serialized repo data as stored in `repos.ts` (JSON).
  */
 export interface RepoJson {
 	library_json: LibraryJson;
@@ -18,9 +17,9 @@ export interface RepoJson {
 }
 
 /**
- * Runtime repo with Library composition for package metadata.
+ * Runtime repo with `Library` composition for package metadata.
  *
- * Wraps a Library instance and adds GitHub-specific data (CI status, PRs).
+ * Wraps a `Library` instance and adds GitHub-specific data (CI status, PRs).
  * Convenience getters delegate to `this.library.*` for common properties.
  */
 export class Repo {

package/src/lib/repo_ops.ts

@@ -6,7 +6,7 @@
  * - Walking files in repos with sensible exclusions
  * - Common exclusion patterns for node/svelte projects
  *
- * For full git sync/clone functionality, use `get_gitops_ready()` from gitops_task_helpers.
+ * For full git sync/clone functionality, use `get_gitops_ready()` from `gitops_task_helpers`.
  *
  * @module
  */
@@ -83,8 +83,8 @@ export interface RepoPath {
  * Get repo paths from gitops config without full git sync.
  * Lighter weight than `get_gitops_ready()` - just resolves paths.
  *
- * @param config_path Path to gitops.config.ts (defaults to `./gitops.config.ts`)
- * @returns Array of repo info with name, path, and url
+ * @param config_path - path to `gitops.config.ts` (defaults to `./gitops.config.ts`)
+ * @returns array of repo info with name, path, and url
  */
 export const get_repo_paths = async (config_path?: string): Promise<Array<RepoPath>> => {
 	const resolved_config_path = resolve(config_path ?? GITOPS_CONFIG_PATH_DEFAULT);
@@ -152,8 +152,8 @@ export const should_exclude_path = (file_path: string, options?: WalkOptions): b
  * Walk files in a directory, respecting common exclusions.
  * Yields absolute paths to files (and optionally directories).
  *
- * @param dir Directory to walk
- * @param options Walk options for exclusions and filtering
+ * @param dir - directory to walk
+ * @param options - walk options for exclusions and filtering
  */
 export async function* walk_repo_files(
 	dir: string,
@@ -186,7 +186,7 @@ export async function* walk_repo_files(
 			} else if (entry.isFile()) {
 				// Check file size
 				try {
-					const file_stat = await stat(full_path); // eslint-disable-line no-await-in-loop
+					const file_stat = await stat(full_path);
 					if (file_stat.size <= max_file_size) {
 						yield full_path;
 					}
@@ -201,7 +201,7 @@ export async function* walk_repo_files(
 }
 
 /**
- * Collect all files from walk_repo_files into an array.
+ * Collect all files from `walk_repo_files` into an array.
  * Convenience function for when you need all paths upfront.
  */
 export const collect_repo_files = async (

package/src/lib/version_utils.ts

@@ -25,7 +25,7 @@ export const get_version_prefix = (version: string): string => {
  * Normalizes version string for comparison.
  *
  * Strips prefixes (^, ~, >=) to get bare version number.
- * Handles wildcards as-is. Used by needs_update to compare versions.
+ * Handles wildcards as-is. Used by `needs_update` to compare versions.
  *
  * @example
  * ```ts
@@ -74,7 +74,7 @@ export const needs_update = (current: string, new_version: string): boolean => {
  *
  * This preserves user intent while handling wildcard replacements sensibly.
  *
- * @param default_strategy prefix to use when no existing prefix found
+ * @param default_strategy - prefix to use when no existing prefix found
  */
 export const get_update_prefix = (
 	current_version: string,