@fuzdev/fuz_gitops 0.71.0 → 0.73.0

package/src/lib/dependency_graph.ts

@@ -66,7 +66,7 @@ export class DependencyGraph {
 				repo,
 				dependencies: new Map(),
 				dependents: new Set(),
-				publishable: !!library.package_json.private === false, // eslint-disable-line @typescript-eslint/no-unnecessary-boolean-literal-compare
+				publishable: !library.package_json.private,
 			};
 
 			// Extract dependencies

package/src/lib/git_operations.ts

@@ -84,6 +84,11 @@ export const git_push_tag = async (
 	}
 };
 
+/**
+ * Returns `true` if the working tree has any changes — staged, unstaged, or
+ * untracked (`git status --porcelain`). Broader than `git_list_uncommitted_files`,
+ * which reports only tracked working-tree changes relative to HEAD.
+ */
 export const git_has_changes = async (options?: SpawnOptions): Promise<boolean> => {
 	const {stdout} = await spawn_out('git', ['status', '--porcelain'], options);
 	return stdout ? stdout.trim().length > 0 : false;

package/src/lib/gitops_analyze.task.ts

@@ -4,9 +4,9 @@ import {styleText as st} from 'node:util';
 import type {Logger} from '@fuzdev/fuz_util/log.js';
 
 import {get_gitops_ready} from './gitops_task_helpers.js';
-import {type DependencyGraph, DependencyGraphBuilder} from './dependency_graph.js';
+import type {DependencyGraph} from './dependency_graph.js';
 import type {LocalRepo} from './local_repo.js';
-import {validate_dependency_graph} from './graph_validation.js';
+import {analyze_repos, type DependencyAnalysis} from './graph_validation.js';
 import {
 	format_wildcard_dependencies,
 	format_dev_cycles,
@@ -30,6 +30,13 @@ export const Args = z.strictObject({
 		.meta({description: 'output format'})
 		.default('stdout'),
 	outfile: z.string().meta({description: 'write output to file instead of logging'}).optional(),
+	sync: z
+		.boolean()
+		.meta({
+			description:
+				'sync repos (switch branch, pull, install) before analyzing instead of reading the working tree as-is',
+		})
+		.default(false),
 });
 export type Args = z.infer<typeof Args>;
 
@@ -38,25 +45,13 @@ export const task: Task<Args> = {
 	Args,
 	summary: 'analyze dependency structure and relationships across repos',
 	run: async ({args, log}) => {
-		const {config, dir, format, outfile} = args;
+		const {config, dir, format, outfile, sync} = args;
 
-		// Get repos ready (without downloading)
-		const {local_repos} = await get_gitops_ready({config, dir, download: false, log});
+		// Get repos ready (without downloading); read the working tree as-is unless `--sync`
+		const {local_repos} = await get_gitops_ready({config, dir, download: false, sync, log});
 
-		// Build dependency graph and validate (but don't throw on cycles for analyze)
-		const {graph, publishing_order: order} = validate_dependency_graph(local_repos, {
-			log,
-			throw_on_prod_cycles: false, // Analyze should report, not throw
-			log_cycles: false, // We'll show cycles in our formatted output
-			log_order: false, // We'll show order in our formatted output
-		});
-
-		// Perform additional analysis
-		const builder = new DependencyGraphBuilder();
-		const analysis = builder.analyze(graph);
-
-		// Publishing order (may be null if prod cycles exist)
-		const publishing_order = order.length > 0 ? order : null;
+		// Build the dependency graph and analyze cycles/wildcards (tolerating cycles)
+		const {graph, analysis, publishing_order} = analyze_repos(local_repos);
 
 		// Format and output using output_helpers
 		const data = {
@@ -74,7 +69,7 @@ export const task: Task<Args> = {
 interface AnalysisData {
 	repos: Array<LocalRepo>;
 	graph: DependencyGraph;
-	analysis: ReturnType<DependencyGraphBuilder['analyze']>;
+	analysis: DependencyAnalysis;
 	publishing_order: Array<string> | null;
 }
 
@@ -102,7 +97,7 @@ const calculate_stats = (graph: DependencyGraph) => {
 
 const format_json = (
 	graph: DependencyGraph,
-	analysis: ReturnType<DependencyGraphBuilder['analyze']>,
+	analysis: DependencyAnalysis,
 	publishing_order: Array<string> | null,
 ): string => {
 	const output = {
@@ -116,7 +111,7 @@ const format_json = (
 const format_markdown = (
 	repos: Array<LocalRepo>,
 	graph: DependencyGraph,
-	analysis: ReturnType<DependencyGraphBuilder['analyze']>,
+	analysis: DependencyAnalysis,
 	publishing_order: Array<string> | null,
 ): Array<string> => {
 	const lines: Array<string> = ['# Dependency Analysis'];
@@ -192,7 +187,7 @@ const format_markdown = (
 const format_stdout = (
 	repos: Array<LocalRepo>,
 	graph: DependencyGraph,
-	analysis: ReturnType<DependencyGraphBuilder['analyze']>,
+	analysis: DependencyAnalysis,
 	publishing_order: Array<string> | null,
 	log: Logger,
 ): void => {

package/src/lib/gitops_plan.task.ts

@@ -28,6 +28,13 @@ export const Args = z.strictObject({
 		.default('stdout'),
 	outfile: z.string().meta({description: 'write output to file instead of logging'}).optional(),
 	verbose: z.boolean().meta({description: 'show additional details'}).default(false),
+	sync: z
+		.boolean()
+		.meta({
+			description:
+				'sync repos (switch branch, pull, install) before planning instead of reading the working tree as-is',
+		})
+		.default(false),
 });
 export type Args = z.infer<typeof Args>;
 
@@ -46,15 +53,16 @@ export const task: Task<Args> = {
 	summary: 'generate a publishing plan based on changesets',
 	Args,
 	run: async ({args, log}): Promise<void> => {
-		const {dir, config, format, outfile, verbose} = args;
+		const {dir, config, format, outfile, verbose, sync} = args;
 
 		log.info(st('cyan', 'Generating multi-repo publishing plan...'));
 
-		// Load local repos
+		// Load local repos; read the working tree as-is unless `--sync`
 		const {local_repos} = await get_gitops_ready({
 			config,
 			dir,
 			download: false, // Don't download if missing
+			sync,
 			log,
 		});
 

package/src/lib/gitops_publish.task.ts

@@ -1,15 +1,19 @@
 import type {Task} from '@fuzdev/gro';
+import type {Logger} from '@fuzdev/fuz_util/log.js';
 import {z} from 'zod';
 import {createInterface} from 'node:readline/promises';
 import {styleText as st} from 'node:util';
 
 import {get_gitops_ready} from './gitops_task_helpers.js';
 import {
-	publish_repos,
+	execute_publishing_plan,
 	type PublishingOptions,
 	type PublishingResult,
 } from './multi_repo_publisher.js';
+import {stdout_handler} from './publishing_event_handler.js';
 import {generate_publishing_plan, log_publishing_plan} from './publishing_plan.js';
+import {derive_publish_steps, format_publish_steps, type PublishStep} from './publish_steps.js';
+import {decide_publish_gate, publish_run_failed} from './publish_gate.js';
 import {format_and_output, type OutputFormatters} from './output_helpers.js';
 import {GITOPS_CONFIG_PATH_DEFAULT, GITOPS_NPM_WAIT_TIMEOUT_DEFAULT} from './gitops_constants.js';
 
@@ -33,21 +37,31 @@ export const Args = z.strictObject({
 		.meta({description: 'output format'})
 		.default('stdout'),
 	deploy: z.boolean().meta({description: 'deploy all repos after publishing'}).default(false),
-	plan: z.boolean().meta({description: 'dual of no-plan'}).default(true),
-	'no-plan': z
+	plan: z
 		.boolean()
-		.meta({description: 'skip plan confirmation before publishing'})
-		.default(false),
+		.meta({description: 'show the plan and confirm before publishing; --no-plan to skip'})
+		.default(true),
 	max_wait: z
 		.number()
 		.meta({description: 'max time to wait for npm propagation in ms'})
 		.default(GITOPS_NPM_WAIT_TIMEOUT_DEFAULT),
-	skip_install: z
+	emit_json: z
 		.boolean()
-		.meta({description: 'skip npm install after dependency updates'})
+		.meta({description: 'stream structured publishing events as JSON-lines to stdout'})
 		.default(false),
 	outfile: z.string().meta({description: 'write output to file instead of logging'}).optional(),
 	verbose: z.boolean().meta({description: 'show additional details in plan output'}).default(false),
+	sync: z
+		.boolean()
+		.meta({
+			description:
+				'sync repos (switch branch, pull, install) before the dry run instead of reading the working tree as-is; always on for --wetrun',
+		})
+		.default(false),
+	preview: z
+		.boolean()
+		.meta({description: 'show the ordered side-effects a --wetrun would perform'})
+		.default(false),
 });
 export type Args = z.infer<typeof Args>;
 
@@ -65,28 +79,42 @@ export const task: Task<Args> = {
 			deploy,
 			plan,
 			max_wait,
-			skip_install,
+			emit_json,
 			outfile,
 			verbose,
+			sync,
+			preview,
 		} = args;
 
-		// Load repos
+		// Load repos. A dry run reads the working tree as-is unless `--sync`;
+		// a real publish (`--wetrun`) always syncs so preflight sees the canonical branches.
 		const {local_repos: repos} = await get_gitops_ready({
 			config,
 			dir,
 			download: false, // Don't download if missing
+			sync: sync || wetrun,
 			log,
 		});
 
-		// Show plan if requested (skip for dry runs)
-		if (plan && wetrun) {
+		// Generate the plan once; the executor consumes this exact plan (no second pass).
+		const publishing_plan = await generate_publishing_plan(repos, {verbose});
+		const preview_steps = preview ? derive_publish_steps(publishing_plan, {deploy}) : null;
+
+		// Decide whether to show the plan + confirm, block, or proceed (the decision table lives
+		// in `decide_publish_gate`; readline + exit stay here at the edge).
+		const gate = decide_publish_gate({wetrun, show_plan: plan, plan: publishing_plan});
+
+		// A real publish that shows its plan prints it first — including before a `blocked` throw,
+		// so the operator sees the errors that blocked it.
+		if (gate.action !== 'proceed') {
 			log.info(st('cyan', 'Publishing Plan'));
-			const plan_result = await generate_publishing_plan(repos, {log, verbose});
-			log_publishing_plan(plan_result, log, {verbose});
+			log_publishing_plan(publishing_plan, log, {verbose});
+		}
 
-			if (plan_result.errors.length > 0) {
-				throw new Error('Cannot proceed with publishing due to errors');
-			}
+		if (gate.action === 'blocked') {
+			throw new Error(gate.message);
+		} else if (gate.action === 'confirm') {
+			if (preview_steps) log_preview(preview_steps, log);
 
 			// Ask for confirmation
 			log.info(st('yellow', '⚠️  This will publish the packages shown above.'));
@@ -96,17 +124,22 @@ export const task: Task<Args> = {
 				log.info('Publishing cancelled');
 				process.exit(0);
 			}
+		} else if (preview_steps && format === 'stdout') {
+			// proceed (dry run or --no-plan): only render to stdout for the human format;
+			// json/markdown carry the preview in their structured output, so logging here too
+			// would corrupt that stream.
+			log_preview(preview_steps, log);
 		}
 
 		// Publishing options
 		const options: PublishingOptions = {
 			wetrun,
-			update_deps: true, // Always update dependencies
 			version_strategy: peer_strategy,
 			deploy,
 			max_wait,
-			skip_install,
 			log,
+			// Live JSON-lines stream when requested; events also surface on the result.
+			events: emit_json ? stdout_handler() : undefined,
 		};
 
 		// Execute publishing (may throw on fatal errors like circular dependencies)
@@ -114,7 +147,7 @@ export const task: Task<Args> = {
 		let fatal_error: Error | null = null;
 
 		try {
-			result = await publish_repos(repos, options);
+			result = await execute_publishing_plan(repos, publishing_plan, options);
 		} catch (error) {
 			// Construct a failure result for fatal errors so output can still be generated
 			fatal_error = error instanceof Error ? error : new Error(String(error));
@@ -124,13 +157,17 @@ export const task: Task<Args> = {
 				// Note: FATAL_ERROR is a placeholder - only fatal_error.message is displayed in output
 				failed: [{name: 'FATAL_ERROR', error: fatal_error}],
 				duration: 0,
+				events: [],
+				summary: {total: 0, published: 0, failed: 1, skipped: 0, duration: 0},
+				plan_errors: publishing_plan.errors,
+				plan_warnings: publishing_plan.warnings,
 			};
 		}
 
 		// Format and output result (always runs, even on fatal errors)
-		// Note: stdout format is handled by publish_repos function's logging
+		// Note: stdout format is handled by the executor's logging
 		if (format !== 'stdout') {
-			await format_and_output({result, fatal_error}, create_publish_formatters(), {
+			await format_and_output({result, fatal_error, preview_steps}, create_publish_formatters(), {
 				format,
 				outfile,
 				log,
@@ -138,7 +175,7 @@ export const task: Task<Args> = {
 		}
 
 		// Exit with error if failed
-		if (!result.ok || fatal_error) {
+		if (publish_run_failed(result, fatal_error)) {
 			process.exit(1);
 		}
 	},
@@ -147,21 +184,36 @@ export const task: Task<Args> = {
 interface PublishResultData {
 	result: PublishingResult;
 	fatal_error: Error | null;
+	preview_steps: Array<PublishStep> | null;
 }
 
 const create_publish_formatters = (): OutputFormatters<PublishResultData> => ({
-	json: (data) => JSON.stringify(data.result, null, 2),
-	markdown: (data) => format_result_markdown(data.result, data.fatal_error),
+	json: (data) =>
+		JSON.stringify(
+			data.preview_steps ? {...data.result, preview: data.preview_steps} : data.result,
+			null,
+			2,
+		),
+	markdown: (data) => format_result_markdown(data.result, data.fatal_error, data.preview_steps),
 	stdout: () => {
-		// stdout format is handled by publish_repos function's logging
+		// stdout format is handled by the executor's logging
 		// This should never be called due to early return in task
 	},
 });
 
+/** Logs the ordered side-effect preview to stdout. */
+const log_preview = (steps: Array<PublishStep>, log: Logger): void => {
+	log.info(st('cyan', '\nSide-effect preview (what a real publish would perform):'));
+	for (const line of format_publish_steps(steps)) {
+		log.info(st('dim', `  ${line}`));
+	}
+};
+
 // Format the publishing result as markdown
 const format_result_markdown = (
 	result: PublishingResult,
 	fatal_error: Error | null,
+	preview_steps: Array<PublishStep> | null,
 ): Array<string> => {
 	const lines: Array<string> = [];
 
@@ -205,6 +257,29 @@ const format_result_markdown = (
 		}
 	}
 
+	if (result.plan_warnings.length > 0) {
+		lines.push('');
+		lines.push('## Plan Warnings');
+		lines.push('');
+		for (const warning of result.plan_warnings) lines.push(`- ${warning}`);
+	}
+
+	if (result.plan_errors.length > 0) {
+		lines.push('');
+		lines.push('## Plan Errors');
+		lines.push('');
+		for (const plan_error of result.plan_errors) lines.push(`- ${plan_error}`);
+	}
+
+	if (preview_steps) {
+		lines.push('');
+		lines.push('## Side-Effect Preview');
+		lines.push('');
+		lines.push('```');
+		for (const line of format_publish_steps(preview_steps)) lines.push(line);
+		lines.push('```');
+	}
+
 	return lines;
 };
 

package/src/lib/gitops_run.task.ts

@@ -2,6 +2,7 @@ import {TaskError, type Task} from '@fuzdev/gro';
 import {z} from 'zod';
 import {map_concurrent_settled} from '@fuzdev/fuz_util/async.js';
 import {spawn_out} from '@fuzdev/fuz_util/process.js';
+import {writeFile} from 'node:fs/promises';
 import {styleText as st} from 'node:util';
 import {resolve} from 'node:path';
 
@@ -9,7 +10,9 @@ import {get_repo_paths} from './repo_ops.js';
 import {GITOPS_CONCURRENCY_DEFAULT, GITOPS_CONFIG_PATH_DEFAULT} from './gitops_constants.js';
 
 export const Args = z.strictObject({
-	command: z.string().meta({description: 'shell command to run in each repo'}),
+	// Positional rest args (gro convention) so `gro gitops_run "npm test"` works;
+	// joined with spaces and passed to `sh -c`, so quote commands that contain flags.
+	_: z.array(z.string()).meta({description: 'shell command to run in each repo'}).default([]),
 	config: z
 		.string()
 		.meta({description: 'path to the gitops config file'})
@@ -21,6 +24,10 @@ export const Args = z.strictObject({
 		.meta({description: 'maximum number of repos to run in parallel'})
 		.default(GITOPS_CONCURRENCY_DEFAULT),
 	format: z.enum(['text', 'json']).meta({description: 'output format'}).default('text'),
+	outfile: z
+		.string()
+		.meta({description: 'with --format json, write clean JSON to this file instead of stdout'})
+		.optional(),
 });
 export type Args = z.infer<typeof Args>;
 
@@ -39,7 +46,12 @@ export const task: Task<Args> = {
 	Args,
 	summary: 'run a shell command across all repos in parallel',
 	run: async ({args, log}) => {
-		const {command, config, concurrency, format} = args;
+		const {_, config, concurrency, format, outfile} = args;
+
+		const command = _.join(' ').trim();
+		if (!command) {
+			throw new TaskError('No command provided, e.g. `gro gitops_run "npm test"`');
+		}
 
 		// Get repo paths (lightweight, no library-metadata loading needed)
 		const config_path = resolve(config);
@@ -140,18 +152,38 @@ export const task: Task<Args> = {
 					duration_ms: Math.round(total_duration_ms),
 				},
 			};
-			// eslint-disable-next-line no-console
-			console.log(JSON.stringify(json_output, null, 2));
+			const json = JSON.stringify(json_output, null, 2);
+			if (outfile) {
+				// Clean machine-readable output, free of gro's logging prefixes.
+				await writeFile(outfile, json);
+				log.info(`wrote JSON output to ${outfile}`);
+			} else {
+				// eslint-disable-next-line no-console
+				console.log(json);
+			}
 		} else {
 			// Text format
 			log.info(''); // blank line
 
-			// Show successes
+			// Show successes, including the command's output so read-only commands
+			// (`git rev-parse`, `cat package.json`, …) are useful without `--format json`.
 			if (successes.length > 0) {
 				log.info(st('green', `✓ ${successes.length} succeeded:`));
 				for (const result of successes) {
-					const duration = `${Math.round(result.duration_ms)}ms`;
-					log.info(st('gray', `  ${result.repo_name} ${st('blue', `(${duration})`)}`));
+					const duration = st('blue', `(${Math.round(result.duration_ms)}ms)`);
+					const label = st('gray', `  ${result.repo_name}`);
+					const out = result.stdout.trim();
+					const out_lines = out ? out.split('\n') : [];
+					if (out_lines.length <= 1) {
+						// single-line (or empty) output inline after the repo name
+						log.info(out ? `${label} ${out} ${duration}` : `${label} ${duration}`);
+					} else {
+						// multi-line output indented under the repo
+						log.info(`${label} ${duration}`);
+						for (const line of out_lines) {
+							log.info(st('gray', `    ${line}`));
+						}
+					}
 				}
 			}
 

package/src/lib/gitops_sync.task.ts

@@ -35,6 +35,13 @@ export const Args = z.strictObject({
 		.boolean()
 		.meta({description: 'check repos are ready without fetching remote data'})
 		.default(false),
+	allow_dirty: z
+		.boolean()
+		.meta({
+			description:
+				'sync (switch branch, pull) tolerating uncommitted changes instead of failing on a dirty workspace',
+		})
+		.default(false),
 });
 export type Args = z.infer<typeof Args>;
 
@@ -47,9 +54,17 @@ export const task: Task<Args> = {
 	Args,
 	summary: 'syncs local repos and generates UI data from repo metadata',
 	run: async ({args, log, svelte_config, invoke_task}) => {
-		const {config, dir, outdir = svelte_config.routes_path, download, check} = args;
-
-		const {local_repos} = await get_gitops_ready({config, dir, download, log});
+		const {config, dir, outdir = svelte_config.routes_path, download, check, allow_dirty} = args;
+
+		// `gitops_sync` is the task whose job is to mutate working trees, so it always syncs.
+		const {local_repos} = await get_gitops_ready({
+			config,
+			dir,
+			download,
+			sync: true,
+			allow_dirty,
+			log,
+		});
 
 		const outfile_json = resolve(outdir, 'repos.json');
 		const outfile_ts = resolve(outdir, 'repos.ts');

package/src/lib/gitops_task_helpers.ts

@@ -37,6 +37,14 @@ export interface GetGitopsReadyOptions {
 	npm_ops?: NpmOperations;
 	parallel?: boolean;
 	concurrency?: number;
+	/**
+	 * Sync each repo's working tree to its configured branch before loading
+	 * (switch branch, pull, install). When `false`, repos load exactly as they
+	 * sit on disk — the safe default for read-only diagnostics. Defaults to `true`.
+	 */
+	sync?: boolean;
+	/** When syncing, tolerate uncommitted changes instead of throwing. Defaults to `false`. */
+	allow_dirty?: boolean;
 }
 
 /**
@@ -45,8 +53,12 @@ export interface GetGitopsReadyOptions {
  * Initialization sequence:
  * 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
+ * 3. If `sync`, switches branches and pulls latest changes (in parallel by default)
+ * 4. If `sync`, auto-installs deps if `package.json` changed during pull
+ *
+ * With `sync: false` (the default for read-only diagnostics), steps 3-4 are
+ * skipped and repos are loaded exactly as checked out — no branch switch, pull,
+ * install, or clean-workspace check.
  *
  * Priority for path resolution:
  * - `dir` argument (explicit override)
@@ -57,6 +69,8 @@ export interface GetGitopsReadyOptions {
  * @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.sync - sync working trees before loading (default: true)
+ * @param options.allow_dirty - when syncing, tolerate uncommitted changes (default: false)
  * @returns initialized config and fully loaded repos ready for operations
  * @throws {TaskError} if config loading or repo resolution fails
  */
@@ -68,7 +82,8 @@ export const get_gitops_ready = async (
 	gitops_config: GitopsConfig;
 	local_repos: Array<LocalRepo>;
 }> => {
-	const {config, dir, download, log, git_ops, npm_ops, parallel, concurrency} = options;
+	const {config, dir, download, log, git_ops, npm_ops, parallel, concurrency, sync, allow_dirty} =
+		options;
 	const config_path = resolve(config);
 	const gitops_config = await import_gitops_config(config_path);
 
@@ -101,6 +116,8 @@ export const get_gitops_ready = async (
 		npm_ops,
 		parallel,
 		concurrency,
+		sync,
+		allow_dirty,
 	});
 
 	return {config_path, repos_dir, gitops_config, local_repos};