@fuzdev/fuz_gitops 0.78.0 → 0.79.0

package/src/lib/operations_defaults.ts

@@ -1,38 +1,22 @@
 /**
  * Production implementations of operations interfaces.
  *
- * Provides real git, npm, fs, and build operations for production use.
+ * Provides real git, npm, fs, build, and `repos` operations for production use.
  * For interface definitions and dependency injection pattern, see `operations.ts`.
  *
  * @module
  */
 
-import {spawn_out} from '@fuzdev/fuz_util/process.ts';
-import {readFile, writeFile, mkdir, stat} from 'node:fs/promises';
-import {git_checkout, type GitBranch, type GitOrigin} from '@fuzdev/fuz_util/git.ts';
-import {fs_classify_error} from '@fuzdev/fuz_util/fs.ts';
-import {EMPTY_OBJECT} from '@fuzdev/fuz_util/object.ts';
+import { spawn_out, spawn_process, spawn_result_to_message } from '@fuzdev/fuz_util/process.ts';
+import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
+import { stripVTControlCharacters } from 'node:util';
+import { fs_classify_error } from '@fuzdev/fuz_util/fs.ts';
+import { EMPTY_OBJECT } from '@fuzdev/fuz_util/object.ts';
 
-import {has_changesets, read_changesets, predict_next_version} from './changeset_reader.ts';
-import {wait_for_package} from './npm_registry.ts';
-import {run_preflight_checks} from './preflight_checks.ts';
-import {
-	git_add,
-	git_commit,
-	git_add_and_commit,
-	git_tag,
-	git_push_tag,
-	git_has_changes,
-	git_list_uncommitted_files,
-	git_has_file_changed,
-	git_stash,
-	git_stash_pop,
-	git_switch_branch,
-	git_current_branch_name_required,
-	git_current_commit_hash_required,
-	git_check_clean_workspace_as_boolean,
-	git_has_remote,
-} from './git_operations.ts';
+import { has_changesets, read_changesets, predict_next_version } from './changeset_reader.ts';
+import { wait_for_package } from './npm_registry.ts';
+import { run_preflight_checks } from './preflight_checks.ts';
+import { git_add, git_commit, git_current_commit_hash_required } from './git_operations.ts';
 import type {
 	ChangesetOperations,
 	GitOperations,
@@ -42,199 +26,181 @@ import type {
 	FsOperations,
 	BuildOperations,
 	GitopsOperations,
+	ReposOperations
 } from './operations.ts';
 
 /** Wrap an async function that returns a value */
 const wrap_with_value = async <T>(
-	fn: () => Promise<T>,
-): Promise<{ok: true; value: T} | {ok: false; message: string}> => {
+	fn: () => Promise<T>
+): Promise<{ ok: true; value: T } | { ok: false; message: string }> => {
 	try {
 		const value = await fn();
-		return {ok: true, value};
+		return { ok: true, value };
 	} catch (error) {
-		return {ok: false, message: String(error)};
+		return { ok: false, message: String(error) };
 	}
 };
 
 /** Wrap an async function, ignoring its return value */
 const wrap_void = async (
-	fn: () => Promise<unknown>,
-): Promise<{ok: true} | {ok: false; message: string}> => {
+	fn: () => Promise<unknown>
+): Promise<{ ok: true } | { ok: false; message: string }> => {
 	try {
 		await fn();
-		return {ok: true};
+		return { ok: true };
 	} catch (error) {
-		return {ok: false, message: String(error)};
+		return { ok: false, message: String(error) };
 	}
 };
 
 export const default_changeset_operations: ChangesetOperations = {
 	has_changesets: async (options) => {
-		const {repo} = options;
+		const { repo } = options;
 		return wrap_with_value(() => has_changesets(repo));
 	},
 
 	read_changesets: async (options) => {
-		const {repo, log} = options;
+		const { repo, log } = options;
 		return wrap_with_value(() => read_changesets(repo, log));
 	},
 
 	predict_next_version: async (options) => {
-		const {repo, log} = options;
+		const { repo, log } = options;
 		try {
 			const result = await predict_next_version(repo, log);
 			if (result === null) {
 				return null;
 			}
-			return {ok: true, ...result};
+			return { ok: true, ...result };
 		} catch (error) {
-			return {ok: false, message: String(error)};
+			return { ok: false, message: String(error) };
 		}
-	},
+	}
 };
 
 export const default_git_operations: GitOperations = {
-	// Core git info
-	current_branch_name: async (options) => {
-		const {cwd} = options ?? EMPTY_OBJECT;
-		return wrap_with_value(() => git_current_branch_name_required(cwd ? {cwd} : undefined));
-	},
-
 	current_commit_hash: async (options) => {
-		const {branch, cwd} = options ?? EMPTY_OBJECT;
-		return wrap_with_value(() => git_current_commit_hash_required(branch, cwd ? {cwd} : undefined));
-	},
-
-	check_clean_workspace: async (options) => {
-		const {cwd} = options ?? EMPTY_OBJECT;
-		return wrap_with_value(() => git_check_clean_workspace_as_boolean(cwd ? {cwd} : undefined));
-	},
-
-	// Branch operations
-	checkout: async (options) => {
-		const {branch, cwd} = options;
-		return wrap_void(() => git_checkout(branch, cwd ? {cwd} : undefined));
+		const { cwd } = options ?? EMPTY_OBJECT;
+		return wrap_with_value(() => git_current_commit_hash_required(cwd ? { cwd } : undefined));
 	},
 
-	pull: async (options) => {
-		const {origin, branch, cwd} = options ?? EMPTY_OBJECT;
-		try {
-			// Omit the branch arg when absent: a trailing `''` makes git pull the remote's
-			// default branch (origin/HEAD) instead of the current branch's upstream.
-			const spawned = await spawn_out(
-				'git',
-				['pull', origin || 'origin', ...(branch ? [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) => {
-		const {branch, pull, cwd} = options;
-		return wrap_void(() => git_switch_branch(branch as GitBranch, pull, cwd ? {cwd} : undefined));
-	},
-
-	has_remote: async (options) => {
-		const {remote, cwd} = options ?? EMPTY_OBJECT;
-		return wrap_with_value(() => git_has_remote(remote, cwd ? {cwd} : undefined));
-	},
-
-	// Staging and committing
 	add: async (options) => {
-		const {files, cwd} = options;
-		return wrap_void(() => git_add(files, cwd ? {cwd} : undefined));
+		const { files, cwd } = options;
+		return wrap_void(() => git_add(files, cwd ? { cwd } : undefined));
 	},
 
 	commit: async (options) => {
-		const {message, cwd} = options;
-		return wrap_void(() => git_commit(message, cwd ? {cwd} : undefined));
-	},
-
-	add_and_commit: async (options) => {
-		const {files, message, cwd} = options;
-		return wrap_void(() => git_add_and_commit(files, message, cwd ? {cwd} : undefined));
-	},
-
-	has_changes: async (options) => {
-		const {cwd} = options ?? EMPTY_OBJECT;
-		return wrap_with_value(() => git_has_changes(cwd ? {cwd} : undefined));
-	},
-
-	list_uncommitted_files: async (options) => {
-		const {cwd} = options ?? EMPTY_OBJECT;
-		return wrap_with_value(() => git_list_uncommitted_files(cwd ? {cwd} : undefined));
-	},
-
-	// Tagging
-	tag: async (options) => {
-		const {tag_name, message, cwd} = options;
-		return wrap_void(() => git_tag(tag_name, message, cwd ? {cwd} : undefined));
-	},
+		const { message, files, cwd } = options;
+		return wrap_void(() => git_commit(message, files, cwd ? { cwd } : undefined));
+	}
+};
 
-	push_tag: async (options) => {
-		const {tag_name, origin, cwd} = options;
-		return wrap_void(() => git_push_tag(tag_name, origin as GitOrigin, cwd ? {cwd} : undefined));
-	},
+/** The most lines of a child's stderr a failure carries. */
+export const OUTPUT_TAIL_MAX_LINES = 20;
 
-	// Stashing
-	stash: async (options) => {
-		const {message, cwd} = options ?? EMPTY_OBJECT;
-		return wrap_void(() => git_stash(message, cwd ? {cwd} : undefined));
-	},
+/** The most characters of a child's stderr a failure carries. */
+export const OUTPUT_TAIL_MAX_CHARS = 4096;
 
-	stash_pop: async (options) => {
-		const {cwd} = options ?? EMPTY_OBJECT;
-		return wrap_void(() => git_stash_pop(cwd ? {cwd} : undefined));
-	},
-
-	// File change detection
-	has_file_changed: async (options) => {
-		const {from_commit, to_commit, file_path, cwd} = options;
-		return wrap_with_value(() =>
-			git_has_file_changed(from_commit, to_commit, file_path, cwd ? {cwd} : undefined),
-		);
-	},
+/**
+ * The end of a process's output, for a failure message: its last lines, then
+ * its last characters, with terminal escape sequences stripped and trailing
+ * whitespace trimmed.
+ *
+ * @param text - the output, or as much of its end as was kept
+ * @param max_lines - the most lines to keep
+ * @param max_chars - the most characters to keep, applied after `max_lines`
+ */
+export const output_tail = (
+	text: string,
+	max_lines: number = OUTPUT_TAIL_MAX_LINES,
+	max_chars: number = OUTPUT_TAIL_MAX_CHARS
+): string => {
+	const lines = stripVTControlCharacters(text).replace(/\r\n?/g, '\n').trimEnd().split('\n');
+	const tail = lines.slice(-max_lines).join('\n');
+	if (tail.length <= max_chars) return drop_leading_blank_lines(tail);
+	// a character cut can split a line, and with it a secret masking would no longer
+	// recognize, so the partial first line goes
+	const cut = tail.slice(-max_chars);
+	if (tail[tail.length - max_chars - 1] === '\n') return drop_leading_blank_lines(cut);
+	const nl = cut.indexOf('\n');
+	return nl === -1 ? '' : drop_leading_blank_lines(cut.slice(nl + 1));
 };
 
+// not `trimStart`, which would strip the first line's indentation
+const drop_leading_blank_lines = (text: string): string => text.replace(/^\n+/, '');
+
 export const default_process_operations: ProcessOperations = {
-	spawn: async (options) => {
-		const {cmd, args, cwd} = options;
+	run_interactive: async (options) => {
+		const { cmd, args, cwd, stdout = 'stdout' } = options;
 		try {
-			const spawned = await spawn_out(cmd, args, cwd ? {cwd} : undefined);
-			if (spawned.result.ok) {
-				return {
-					ok: true,
-					stdout: spawned.stdout || undefined,
-					stderr: spawned.stderr || undefined,
-				};
-			} else {
-				return {
-					ok: false,
-					message: 'Command failed',
-					stderr: spawned.stderr || undefined,
-				};
-			}
+			// stdin and stdout go straight to the child (fd 2 for stdout routed to our stderr), so
+			// they stay a TTY when ours are — npm prompts for a one-time password only on a TTY.
+			// Only stderr is piped, to keep its end for the failure message while echoing it live.
+			const { child, closed } = spawn_process(cmd, args, {
+				cwd,
+				stdio: ['inherit', stdout === 'stderr' ? 2 : 'inherit', 'pipe']
+			});
+			// a rolling window over stderr's end, bounded however much the child writes
+			let kept = '';
+			child.stderr?.setEncoding('utf8');
+			child.stderr?.on('data', (chunk: string) => {
+				process.stderr.write(chunk);
+				kept += chunk;
+				if (kept.length > OUTPUT_TAIL_MAX_CHARS * 4) kept = kept.slice(-OUTPUT_TAIL_MAX_CHARS * 2);
+			});
+			const result = await closed;
+			if (result.ok) return { ok: true };
+			const stderr_tail = output_tail(kept);
+			return {
+				ok: false,
+				message: `\`${[cmd, ...args].join(' ')}\` failed (${spawn_result_to_message(result)})`,
+				stderr_tail: stderr_tail || undefined
+			};
 		} catch (error) {
-			return {ok: false, message: String(error)};
+			return { ok: false, message: String(error) };
 		}
-	},
+	}
+};
+
+export const default_repos_operations: ReposOperations = {
+	status: async (options) => {
+		const { keys, registry, fetch } = options;
+		const args = [...(registry === undefined ? [] : ['--registry', registry]), 'status'];
+		if (fetch) args.push('--fetch');
+		// `--` so a key can never read as a flag
+		args.push('--json', '--', ...keys);
+		const spawned = await spawn_out('repos', args);
+		const { result } = spawned;
+		if (result.kind === 'error') {
+			const not_found = (result.error as NodeJS.ErrnoException).code === 'ENOENT';
+			return {
+				ok: false,
+				kind: not_found ? 'not_found' : 'failed',
+				message: result.error.message
+			};
+		}
+		if (result.kind === 'signaled') {
+			return { ok: false, kind: 'failed', message: `repos was killed by ${result.signal}` };
+		}
+		return {
+			ok: true,
+			output: {
+				stdout: spawned.stdout ?? '',
+				stderr: spawned.stderr ?? '',
+				exit_code: result.code
+			}
+		};
+	}
 };
 
 export const default_npm_operations: NpmOperations = {
 	wait_for_package: async (options) => {
-		const {pkg, version, wait_options, log} = options;
+		const { pkg, version, wait_options, log } = options;
 		try {
-			await wait_for_package(pkg, version, {...wait_options, log});
-			return {ok: true};
+			await wait_for_package(pkg, version, { ...wait_options, log });
+			return { ok: true };
 		} catch (error) {
-			return {ok: false, message: String(error), timeout: true};
+			return { ok: false, message: String(error) };
 		}
 	},
 
@@ -244,76 +210,66 @@ export const default_npm_operations: NpmOperations = {
 			if (result.stdout) {
 				const username = result.stdout.trim();
 				if (username) {
-					return {ok: true, username};
+					return { ok: true, username };
 				}
 			}
-			return {ok: false, message: 'Not logged in to npm'};
+			return { ok: false, message: 'Not logged in to npm' };
 		} catch (error) {
-			return {ok: false, message: String(error)};
+			return { ok: false, message: String(error) };
 		}
 	},
 
 	check_registry: async () => {
 		try {
-			const result = await spawn_out('npm', ['ping']);
-			if (result.stdout) {
-				return {ok: true};
-			}
-			return {ok: false, message: 'Failed to ping npm registry'};
-		} catch (error) {
-			return {ok: false, message: String(error)};
-		}
-	},
-
-	install: async (options) => {
-		const {cwd} = options ?? EMPTY_OBJECT;
-		try {
-			const spawned = await spawn_out('npm', ['install'], cwd ? {cwd} : undefined);
-			if (spawned.result.ok) {
-				return {ok: true};
-			} else {
-				return {ok: false, message: 'Install failed', stderr: spawned.stderr || undefined};
+			// the exit status alone: `npm ping` reports on stderr, writing nothing to stdout
+			const { result } = await spawn_out('npm', ['ping']);
+			if (result.ok) {
+				return { ok: true };
 			}
+			return {
+				ok: false,
+				message: `Failed to ping npm registry (${spawn_result_to_message(result)})`
+			};
 		} catch (error) {
-			return {ok: false, message: String(error)};
+			return { ok: false, message: String(error) };
 		}
-	},
+	}
 };
 
 export const default_preflight_operations: PreflightOperations = {
 	run_preflight_checks: async (options) => {
 		return run_preflight_checks(options);
-	},
+	}
 };
 
 export const default_fs_operations: FsOperations = {
 	readFile: async (options) => {
-		const {path, encoding} = options;
+		const { path, encoding } = options;
 		try {
 			const value = await readFile(path, encoding);
-			return {ok: true, value};
+			return { ok: true, value };
 		} catch (error) {
-			return {ok: false, ...fs_classify_error(error)};
+			return { ok: false, ...fs_classify_error(error) };
 		}
 	},
 
 	writeFile: async (options) => {
-		const {path, content} = options;
+		const { path, content } = options;
 		try {
 			await writeFile(path, content);
-			return {ok: true};
+			return { ok: true };
 		} catch (error) {
-			return {ok: false, ...fs_classify_error(error)};
+			return { ok: false, ...fs_classify_error(error) };
 		}
 	},
 
 	mkdir: async (options) => {
-		const {path, recursive} = options;
+		const { path, recursive } = options;
 		try {
-			await mkdir(path, {recursive});
-			return {ok: true};
+			await mkdir(path, { recursive });
+			return { ok: true };
 		} catch (error) {
-			return {ok: false, ...fs_classify_error(error)};
+			return { ok: false, ...fs_classify_error(error) };
 		}
 	},
 
@@ -324,28 +280,27 @@ export const default_fs_operations: FsOperations = {
 		} catch {
 			return false;
 		}
-	},
+	}
 };
 
 export const default_build_operations: BuildOperations = {
 	build_package: async (options) => {
-		const {repo, log} = options;
+		const { repo } = options;
 		try {
-			log?.info(`  Building ${repo.library.name}...`);
-			const spawned = await spawn_out('gro', ['build'], {cwd: repo.repo_dir});
+			const spawned = await spawn_out('gro', ['build'], { cwd: repo.repo_dir });
 			if (spawned.result.ok) {
-				return {ok: true};
+				return { ok: true };
 			} else {
 				return {
 					ok: false,
 					message: 'Build failed',
-					output: spawned.stderr || spawned.stdout || 'Build failed',
+					output: spawned.stderr || spawned.stdout || 'Build failed'
 				};
 			}
 		} catch (error) {
-			return {ok: false, message: String(error)};
+			return { ok: false, message: String(error) };
 		}
-	},
+	}
 };
 
 /**
@@ -359,4 +314,5 @@ export const default_gitops_operations: GitopsOperations = {
 	preflight: default_preflight_operations,
 	fs: default_fs_operations,
 	build: default_build_operations,
+	repos: default_repos_operations
 };

package/src/lib/output_helpers.ts

@@ -1,12 +1,26 @@
-import type {Logger} from '@fuzdev/fuz_util/log.ts';
-import {writeFile} from 'node:fs/promises';
+import type { Logger } from '@fuzdev/fuz_util/log.ts';
+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.
  *
@@ -31,9 +81,9 @@ export interface OutputFormatters<T> {
 export const format_and_output = async <T>(
 	data: T,
 	formatters: OutputFormatters<T>,
-	options: OutputOptions,
+	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);