@fuzdev/fuz_gitops 0.78.0 → 0.79.0

package/src/lib/gitops_task_helpers.ts

@@ -1,156 +1,212 @@
 /**
  * Shared initialization logic for all gitops tasks.
  *
- * Provides `get_gitops_ready()` which orchestrates:
- * - Config loading and normalization
- * - Repo resolution (local path discovery)
- * - Branch switching and syncing
- * - Dependency installation
+ * `resolve_gitops_repos()` loads the config's registry keys, runs
+ * `repos status <keys…> --json`, and resolves each key to its checkout.
+ * `get_gitops_ready()` then loads each repo's library as its working tree
+ * sits. `gate_publish_readiness()` is the read-only gate a real publish runs
+ * before its prompt, and `log_readiness_block()` the diagnostics' report of
+ * repos not at rest (both over `repo_readiness.ts`).
  *
  * Used by: `gitops_sync.task.ts`, `gitops_analyze.task.ts`, `gitops_plan.task.ts`,
- * `gitops_publish.task.ts`, and `gitops_validate.task.ts`.
+ * `gitops_publish.task.ts`, `gitops_validate.task.ts`, and `gitops_run.task.ts`.
  *
- * Accepts `git_ops` and `npm_ops` parameters to support testing via operations pattern
- * (see `operations.ts` for dependency injection details).
+ * Accepts `repos_ops` to support testing via the operations pattern (see
+ * `operations.ts` for dependency injection details).
  *
  * @module
  */
 
-import {TaskError} from '@fuzdev/gro';
-import {styleText as st} from 'node:util';
-import {resolve, dirname} from 'node:path';
-import {print_path} from '@fuzdev/gro/paths.ts';
-import type {Logger} from '@fuzdev/fuz_util/log.ts';
+import { TaskError } from '@fuzdev/gro';
+import { styleText as st } from 'node:util';
+import { resolve } from 'node:path';
+import type { Logger } from '@fuzdev/fuz_util/log.ts';
+import { to_error_message } from '@fuzdev/fuz_util/error.ts';
 
-import {load_gitops_config, type GitopsConfig} from './gitops_config.ts';
-import {local_repos_load, local_repos_ensure, type LocalRepo} from './local_repo.ts';
-import {resolve_gitops_config} from './resolved_gitops_config.ts';
-import {DEFAULT_REPOS_DIR} from './paths.ts';
-import type {GitOperations, NpmOperations} from './operations.ts';
+import { load_gitops_config, type GitopsConfig } from './gitops_config.ts';
+import {
+	local_repos_load,
+	local_repos_resolve,
+	repo_is_npm,
+	type LocalRepo,
+	type LocalRepoPath
+} from './local_repo.ts';
+import { load_repos_status, to_repos_command } from './repos_status_load.ts';
+import {
+	check_publish_readiness,
+	format_readiness_ahead,
+	format_readiness_block,
+	repos_not_at_rest
+} from './repo_readiness.ts';
+import type { ReposStatusReport } from './repos_status.ts';
+import type { ReposOperations } from './operations.ts';
+import { default_repos_operations } from './operations_defaults.ts';
 
-export interface GetGitopsReadyOptions {
+export interface ResolveGitopsReposOptions {
+	/** Path to the gitops config, absolute or relative to the cwd. */
 	config: string;
-	dir?: string;
-	download: boolean;
-	log?: Logger;
-	git_ops?: GitOperations;
-	npm_ops?: NpmOperations;
-	parallel?: boolean;
-	concurrency?: number;
+	/** A `repos.toml` to use instead of the one `repos` finds walking up from the cwd. */
+	registry?: string;
 	/**
-	 * 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`.
+	 * The package whose generated data the run writes; when it's public, a
+	 * private repo in the config fails the resolve.
 	 */
-	sync?: boolean;
-	/** When syncing, tolerate uncommitted changes instead of throwing. Defaults to `false`. */
-	allow_dirty?: boolean;
+	host?: { name: string; private: boolean };
+	log?: Logger;
+	repos_ops?: ReposOperations;
 }
 
 /**
- * Central initialization function for all gitops tasks.
- *
- * Initialization sequence:
- * 1. Loads and normalizes config from `gitops.config.ts`
- * 2. Resolves local repo paths (creates missing with `--download`)
- * 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)
- * - Config `repos_dir` setting
- * - `DEFAULT_REPOS_DIR` constant
+ * Resolves the gitops config's repos through `repos status`: loads the
+ * config's registry keys, reports on them, and resolves each to its checkout,
+ * in config order. Reads nothing but git state and writes nothing.
  *
- * @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.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
+ * @returns the config, the `repos status` report, and each repo's path and entry
+ * @throws {TaskError} if the config is missing, invalid, or lists no repos, `repos status` fails, or any configured repo is unknown, a reference, missing, not a repo, unprobed, or private under a public `host`
  */
-export const get_gitops_ready = async (
-	options: GetGitopsReadyOptions,
+export const resolve_gitops_repos = async (
+	options: ResolveGitopsReposOptions
 ): Promise<{
 	config_path: string;
-	repos_dir: string;
 	gitops_config: GitopsConfig;
-	local_repos: Array<LocalRepo>;
+	report: ReposStatusReport;
+	local_repo_paths: Array<LocalRepoPath>;
 }> => {
-	const {config, dir, download, log, git_ops, npm_ops, parallel, concurrency, sync, allow_dirty} =
-		options;
+	const { config, registry, host, log, repos_ops = default_repos_operations } = options;
 	const config_path = resolve(config);
 	const gitops_config = await import_gitops_config(config_path);
+	const keys = gitops_config.repos;
+	if (keys.length === 0) {
+		throw new TaskError(`No repos are configured in ${config_path}`);
+	}
 
-	// Priority: explicit dir arg → config repos_dir → default (two dirs up from config)
-	const repos_dir = resolve_gitops_paths({
-		config,
-		dir,
-		config_repos_dir: gitops_config.repos_dir,
-	}).repos_dir;
-
-	log?.info(
-		`resolving gitops configs on the filesystem in ${repos_dir}`,
-		gitops_config.repos.map((r) => r.repo_url),
-	);
-	const resolved_config = resolve_gitops_config(gitops_config, repos_dir);
+	log?.info(`reading the state of ${keys.length} repos from \`repos status\``);
+	log?.debug('repos status targets', keys);
+	const loaded = await load_repos_status({ keys, registry, repos_ops });
+	if (!loaded.ok) {
+		// an unknown key is the config's to fix, so name the config
+		throw new TaskError(
+			loaded.error?.kind === 'unknown_entry' ? `${config_path}: ${loaded.message}` : loaded.message
+		);
+	}
+	const { report } = loaded;
 
-	const local_repo_paths = await local_repos_ensure({
-		resolved_config,
-		repos_dir,
-		gitops_config,
-		download,
-		log,
-		npm_ops,
-	});
+	const resolved = local_repos_resolve({ keys, report, host, registry });
+	if (!resolved.ok) {
+		throw new TaskError(`${config_path}: ${resolved.message}`);
+	}
 
-	const local_repos = await local_repos_load({
-		local_repo_paths,
-		log,
-		git_ops,
-		npm_ops,
-		parallel,
-		concurrency,
-		sync,
-		allow_dirty,
-	});
+	return { config_path, gitops_config, report, local_repo_paths: resolved.value };
+};
 
-	return {config_path, repos_dir, gitops_config, local_repos};
+/**
+ * Central initialization function for the gitops tasks that load libraries:
+ * resolves the config's repos through `repos status` (`resolve_gitops_repos`),
+ * then loads each repo's library as its working tree sits (`local_repos_load`).
+ * Moves no ref; gro caches each library at `.gro/library.json` in its repo, at
+ * a clean commit.
+ *
+ * @returns the loaded repos, in config order
+ * @throws {TaskError} if resolving the repos or loading them fails
+ */
+export const get_gitops_ready = async (
+	options: ResolveGitopsReposOptions
+): Promise<{ local_repos: Array<LocalRepo> }> => {
+	const { local_repo_paths } = await resolve_gitops_repos(options);
+	const local_repos = await local_repos_load({ local_repo_paths, log: options.log });
+	return { local_repos };
 };
 
-export interface ResolveGitopsPathsOptions {
-	config: string;
-	dir?: string;
-	config_repos_dir?: string;
+export interface GatePublishReadinessOptions {
+	/** The loaded repos; the npm ones are gated. */
+	local_repos: ReadonlyArray<LocalRepo>;
+	/** A `repos.toml` to use instead of the one `repos` finds walking up from the cwd. */
+	registry?: string;
+	/**
+	 * The package names the plan publishes, to say whether a repo's commits ahead
+	 * of origin go out with its release or stay unpushed.
+	 */
+	publishing?: ReadonlySet<string>;
+	log?: Logger;
+	repos_ops?: ReposOperations;
 }
 
-export const resolve_gitops_paths = (
-	options: ResolveGitopsPathsOptions,
-): {config_path: string; repos_dir: string} => {
-	const {config, dir, config_repos_dir} = options;
-	const config_path = resolve(config);
-	const config_dir = dirname(config_path);
+/**
+ * The readiness gate `gitops_publish --wetrun` runs before its confirmation
+ * prompt: fetches every npm repo from origin (`repos status <keys…> --fetch
+ * --json`, which writes remote-tracking refs and nothing else) and refuses
+ * unless each is ready (`check_publish_readiness`) — on its registry branch,
+ * clean, idle, in sync with origin or ahead of it, fetched without error, no
+ * other live session in its checkout, and nothing left to a person. Each
+ * ready repo ahead of origin is logged, saying whether its release push
+ * carries those commits or they stay unpushed.
+ *
+ * Every npm repo, not just those the plan publishes or rewrites: the plan
+ * reads each one's working tree (changesets, versions, dependency ranges), so
+ * a repo off its branch or behind origin can hide a changeset and leave the
+ * plan wrong about what to publish. Changes nothing.
+ *
+ * @param options - the loaded repos, the `--registry` if any, the package names the plan publishes, a logger, and the `repos` runner
+ * @throws {TaskError} if `repos status` fails or any npm repo isn't ready, naming each problem and its fix
+ */
+export const gate_publish_readiness = async (
+	options: GatePublishReadinessOptions
+): Promise<void> => {
+	const { local_repos, registry, publishing, log, repos_ops = default_repos_operations } = options;
+	const npm_repos = local_repos.filter(repo_is_npm);
+	const keys = npm_repos.map((r) => r.entry.key);
+	if (keys.length === 0) return;
 
-	// Priority: explicit dir arg → config repos_dir → default (parent of config dir)
-	const repos_dir =
-		dir !== undefined
-			? resolve(dir)
-			: config_repos_dir !== undefined
-				? resolve(config_dir, config_repos_dir)
-				: resolve(config_dir, DEFAULT_REPOS_DIR);
+	log?.info(`fetching ${keys.length} npm repos to check they're ready to publish`);
+	const loaded = await load_repos_status({ keys, registry, fetch: true, repos_ops });
+	if (!loaded.ok) {
+		throw new TaskError(`the readiness check failed: ${loaded.message}`);
+	}
+	const repos_command = to_repos_command(registry);
+	const checked = check_publish_readiness({ report: loaded.report, keys, repos_command });
+	if (!checked.ok) {
+		throw new TaskError(checked.message);
+	}
+	log?.info(st('green', `all ${keys.length} npm repos are ready to publish`));
+	const name_by_key = new Map(npm_repos.map((r) => [r.entry.key, r.library.name] as const));
+	for (const ahead of checked.ahead) {
+		const name = name_by_key.get(ahead.key);
+		const publishes = name !== undefined && publishing?.has(name) === true;
+		log?.info(st('yellow', format_readiness_ahead(ahead, publishes, { repos_command })));
+	}
+};
 
-	return {config_path, repos_dir};
+/**
+ * Logs the diagnostics' readiness block as warnings (stderr, so a `--format
+ * json` or `markdown` document on stdout stays clean): each npm repo not at
+ * rest, and how. Logs nothing when every one is at rest. Reads the entries
+ * `repos status` already reported, from local refs.
+ *
+ * @param local_repos - the loaded repos; the npm ones are reported
+ * @param log - where the warnings go
+ * @param now - the current time in unix seconds (defaults to the clock)
+ */
+export const log_readiness_block = (
+	local_repos: ReadonlyArray<LocalRepo>,
+	log: Logger,
+	now: number = Math.floor(Date.now() / 1000)
+): void => {
+	const not_ready = repos_not_at_rest(local_repos.filter(repo_is_npm).map((r) => r.entry));
+	for (const line of format_readiness_block(not_ready, now)) {
+		log.warn(st('yellow', line));
+	}
 };
 
-export const import_gitops_config = async (config_path: string): Promise<GitopsConfig> => {
-	const gitops_config = await load_gitops_config(config_path);
+const import_gitops_config = async (config_path: string): Promise<GitopsConfig> => {
+	let gitops_config: GitopsConfig | null;
+	try {
+		gitops_config = await load_gitops_config(config_path);
+	} catch (err) {
+		// an invalid config is the user's to fix, not an unexpected task failure
+		throw new TaskError(to_error_message(err));
+	}
 	if (!gitops_config) {
-		throw new TaskError(st('red', `No gitops config found at ${print_path(config_path)}`));
+		throw new TaskError(st('red', `No gitops config found at ${config_path}`));
 	}
 	return gitops_config;
 };

package/src/lib/gitops_validate.task.ts

@@ -1,37 +1,31 @@
-import type {Task} from '@fuzdev/gro';
-import {z} from 'zod';
-import {styleText as st} from 'node:util';
+import type { Task } from '@fuzdev/gro';
+import { z } from 'zod';
+import { styleText as st } from 'node:util';
 
-import {get_gitops_ready} from './gitops_task_helpers.ts';
-import {analyze_repos, type DependencyAnalysis} from './graph_validation.ts';
-import {
-	generate_publishing_plan,
-	log_publishing_plan,
-	type PublishingPlan,
-} from './publishing_plan.ts';
-import {execute_publishing_plan, type PublishingOptions} from './multi_repo_publisher.ts';
-import {log_dependency_analysis} from './log_helpers.ts';
-import {GITOPS_CONFIG_PATH_DEFAULT} from './gitops_constants.ts';
-import {reconcile_ci, repo_has_workflows} from './ci_reconcile.ts';
+import { get_gitops_ready, log_readiness_block } from './gitops_task_helpers.ts';
+import { analyze_repos } from './graph_validation.ts';
+import type { DependencyAnalysis } from './dependency_graph.ts';
+import { generate_publishing_plan, type PublishingPlan } from './publishing_plan.ts';
+import { log_publishing_plan } from './publishing_plan_logging.ts';
+import { execute_publishing_plan, type PublishingOptions } from './multi_repo_publisher.ts';
+import { log_dependency_analysis } from './log_helpers.ts';
+import { GITOPS_CONFIG_PATH_DEFAULT } from './gitops_constants.ts';
+import { reconcile_ci, repo_has_workflows } from './ci_reconcile.ts';
 
 /** @nodocs */
 export const Args = z.strictObject({
 	config: z
 		.string()
-		.meta({description: 'path to the gitops config file, absolute or relative to the cwd'})
+		.meta({ description: 'path to the gitops config file, absolute or relative to the cwd' })
 		.default(GITOPS_CONFIG_PATH_DEFAULT),
-	dir: z
+	registry: z
 		.string()
-		.meta({description: 'path containing the repos, defaults to the parent of the config dir'})
-		.optional(),
-	verbose: z.boolean().meta({description: 'show additional details'}).default(false),
-	sync: z
-		.boolean()
 		.meta({
 			description:
-				'sync repos (switch branch, pull, install) before validating instead of reading the working tree as-is',
+				'path to the repos.toml registry, when `repos` would not find it walking up from the cwd'
 		})
-		.default(false),
+		.optional(),
+	verbose: z.boolean().meta({ description: 'show additional details' }).default(false)
 });
 export type Args = z.infer<typeof Args>;
 
@@ -40,8 +34,8 @@ export const task: Task<Args> = {
 	Args,
 	summary:
 		'validate gitops configuration by running all read-only commands and checking for issues',
-	run: async ({args, log}) => {
-		const {config, dir, verbose, sync} = args;
+	run: async ({ args, log }) => {
+		const { config, registry, verbose } = args;
 
 		log.info(st('cyan', 'Running Gitops Validation Suite'));
 		log.info(st('dim', 'This runs all read-only commands and checks for consistency.'));
@@ -59,17 +53,18 @@ export const task: Task<Args> = {
 
 		const start_time = Date.now();
 
-		// Load repos once (shared by all commands); read the working tree as-is unless `--sync`
+		// Load repos once (shared by all commands), as they sit, and say which aren't at rest
 		log.info(st('dim', 'Loading repositories...'));
-		const {local_repos} = await get_gitops_ready({config, dir, download: false, sync, log});
+		const { local_repos } = await get_gitops_ready({ config, registry, log });
 		log.info(st('dim', `   Found ${local_repos.length} local repos`));
+		log_readiness_block(local_repos, log);
 
 		// 1. Run gitops_analyze
 		log.info(st('yellow', 'Running gitops_analyze...'));
 		const analyze_start = Date.now();
 		try {
 			// Build dependency graph and analyze cycles/wildcards (tolerating cycles)
-			const {analysis} = analyze_repos(local_repos);
+			const { analysis } = analyze_repos(local_repos);
 
 			const analyze_duration = Date.now() - analyze_start;
 
@@ -93,7 +88,7 @@ export const task: Task<Args> = {
 				duration: analyze_duration,
 				warning_details,
 				info_details,
-				analysis,
+				analysis
 			});
 
 			log.info(st('green', `  ✓ gitops_analyze completed in ${analyze_duration}ms`));
@@ -111,7 +106,7 @@ export const task: Task<Args> = {
 				success: false,
 				warnings: 0,
 				errors: 1,
-				duration: analyze_duration,
+				duration: analyze_duration
 			});
 			log.error(st('red', `  ✗ gitops_analyze failed: ${error}`));
 		}
@@ -121,7 +116,7 @@ export const task: Task<Args> = {
 		log.info(st('yellow', 'Running gitops_plan...'));
 		const plan_start = Date.now();
 		try {
-			const plan = await generate_publishing_plan(local_repos, {verbose});
+			const plan = await generate_publishing_plan(local_repos, { verbose });
 			publishing_plan = plan;
 			const plan_duration = Date.now() - plan_start;
 
@@ -133,12 +128,12 @@ export const task: Task<Args> = {
 				success: errors === 0,
 				warnings,
 				errors,
-				duration: plan_duration,
+				duration: plan_duration
 			});
 
 			log.info(st('green', `  ✓ gitops_plan completed in ${plan_duration}ms`));
 			if (verbose) {
-				log_publishing_plan(plan, log, {verbose});
+				log_publishing_plan(plan, log, { verbose });
 			}
 			if (warnings > 0) {
 				log.warn(st('yellow', `  ⚠️  Found ${warnings} warning(s)`));
@@ -153,7 +148,7 @@ export const task: Task<Args> = {
 				success: false,
 				warnings: 0,
 				errors: 1,
-				duration: plan_duration,
+				duration: plan_duration
 			});
 			log.error(st('red', `  ✗ gitops_plan failed: ${error}`));
 		}
@@ -164,14 +159,14 @@ export const task: Task<Args> = {
 		try {
 			const options: PublishingOptions = {
 				wetrun: false,
-				log: undefined, // Silent for validation
+				log: undefined // Silent for validation
 			};
 
 			// Reuse the plan from step 2 (regenerate only if that step failed to produce one).
 			const result = await execute_publishing_plan(
 				local_repos,
-				publishing_plan ?? (await generate_publishing_plan(local_repos, {verbose})),
-				options,
+				publishing_plan ?? (await generate_publishing_plan(local_repos, { verbose })),
+				options
 			);
 			const dry_duration = Date.now() - dry_start;
 
@@ -184,7 +179,7 @@ export const task: Task<Args> = {
 				success: result.ok,
 				warnings: 0,
 				errors,
-				duration: dry_duration,
+				duration: dry_duration
 			});
 
 			log.info(st('green', `  ✓ gitops_publish (dry run) completed in ${dry_duration}ms`));
@@ -198,40 +193,35 @@ export const task: Task<Args> = {
 				success: false,
 				warnings: 0,
 				errors: 1,
-				duration: dry_duration,
+				duration: dry_duration
 			});
 			log.error(st('red', `  ✗ gitops_publish (dry run) failed: ${error}`));
 		}
 
-		// 4. Reconcile each repo's declared `ci` against actual workflow files on disk.
+		// 4. Reconcile each repo's registry-declared `ci` against actual workflow files on disk.
 		log.info(st('yellow', 'Running ci_reconcile...'));
 		const ci_start = Date.now();
 		try {
 			const ci_drift = reconcile_ci(
 				local_repos.map((r) => ({
-					repo_url: r.repo_config.repo_url,
-					ci: r.repo_config.ci,
+					repo_url: r.entry.url,
+					ci: r.entry.ci,
 					has_workflows: repo_has_workflows(r.repo_dir),
-					// TODO: `local_repos` only ever holds checked-out repos — a missing repo
-					// throws in `local_repos_ensure` before we reach here — so `checkable` is
-					// always `true` today. The gate exists for a future caller that loads a
-					// partial set; until then the skip path is inert and untested.
-					checkable: true,
-					archived: r.repo_config.archived,
-				})),
+					archived: r.entry.archived
+				}))
 			);
 			const ci_duration = Date.now() - ci_start;
 			const drift_details = ci_drift.map((d) =>
 				d.kind === 'missing_ci'
 					? `${d.repo_url}: ci=true but no workflow files`
-					: `${d.repo_url}: ci=false but workflow files present`,
+					: `${d.repo_url}: ci=false but workflow files present`
 			);
 			results.push({
 				command: 'ci_reconcile',
 				success: ci_drift.length === 0,
 				warnings: 0,
 				errors: ci_drift.length,
-				duration: ci_duration,
+				duration: ci_duration
 			});
 			if (ci_drift.length === 0) {
 				log.info(st('green', `  ✓ ci_reconcile completed in ${ci_duration}ms`));
@@ -248,7 +238,7 @@ export const task: Task<Args> = {
 				success: false,
 				warnings: 0,
 				errors: 1,
-				duration: ci_duration,
+				duration: ci_duration
 			});
 			log.error(st('red', `  ✗ ci_reconcile failed: ${error}`));
 		}
@@ -295,7 +285,7 @@ export const task: Task<Args> = {
 			log.info(st('green', '✓ All validation checks passed'));
 			if (total_warnings > 0) {
 				log.warn(
-					st('yellow', `⚠️  Note: ${total_warnings} warning(s) found - review output above.`),
+					st('yellow', `⚠️  Note: ${total_warnings} warning(s) found - review output above.`)
 				);
 			}
 		} else {
@@ -305,5 +295,5 @@ export const task: Task<Args> = {
 			log.error(st('red', '❌ Validation failed - review the errors above.'));
 			throw new Error('Validation failed');
 		}
-	},
+	}
 };