@fuzdev/fuz_gitops 0.78.1 → 0.79.0

package/src/lib/gitops_sync.task.ts

@@ -2,17 +2,29 @@ import { TaskError, type Task } from '@fuzdev/gro';
 import { z } from 'zod';
 import { readFile, writeFile } from 'node:fs/promises';
 import { format_file } from '@fuzdev/gro/format_file.ts';
-import { basename, resolve } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 import { print_path } from '@fuzdev/gro/paths.ts';
 import { load_from_env } from '@fuzdev/gro/env.ts';
 import { package_json_load } from '@fuzdev/gro/package_json.ts';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { styleText as st } from 'node:util';
+import type { Logger } from '@fuzdev/fuz_util/log.ts';
 import { compactReplacer } from 'svelte-docinfo';
 
 import { fetch_repo_data } from './fetch_repo_data.ts';
 import { create_fs_fetch_value_cache } from './fs_fetch_value_cache.ts';
-import { get_gitops_ready } from './gitops_task_helpers.ts';
+import { resolve_gitops_repos } from './gitops_task_helpers.ts';
 import { GITOPS_CONFIG_PATH_DEFAULT } from './gitops_constants.ts';
+import {
+	local_repos_load,
+	local_repos_resolve,
+	type LocalRepo,
+	type LocalRepoPath
+} from './local_repo.ts';
+import { load_repos_status, to_repos_command } from './repos_status_load.ts';
+import { check_gen_readiness } from './repo_readiness.ts';
+import type { ReposOperations } from './operations.ts';
+import { default_repos_operations } from './operations_defaults.ts';
 
 // TODO add flag to ignore or invalidate cache -- no-cache? clean?
 
@@ -22,85 +34,85 @@ export const Args = z.strictObject({
 		.string()
 		.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' })
+		.meta({
+			description:
+				'path to the repos.toml registry, when `repos` would not find it walking up from the cwd'
+		})
 		.optional(),
 	outdir: z
 		.string()
 		.meta({ description: 'path to the directory for the generated files, defaults to $routes/' })
 		.optional(),
-	download: z.boolean().meta({ description: 'download all missing local repos' }).default(false),
 	check: z
 		.boolean()
-		.meta({ description: 'check repos are ready without fetching remote data' })
+		.meta({
+			description:
+				'report whether the repos are ready to generate from, as of the local refs, and exit non-zero if a real run would refuse; fetches nothing, needs no token, and writes nothing'
+		})
 		.default(false),
 	allow_dirty: z
 		.boolean()
 		.meta({
 			description:
-				'sync (switch branch, pull) tolerating uncommitted changes instead of failing on a dirty workspace'
+				'read repos off their registry branch, dirty, or mid-operation as they sit, warning instead of refusing'
 		})
 		.default(false)
 });
 export type Args = z.infer<typeof Args>;
 
 /**
- * This is a task not a `.gen.` file because it makes network calls.
+ * Generates the dashboard's site data (`repos.json` and `repos.ts`) from each
+ * configured repo's working tree and its GitHub CI status and pull requests.
+ * It never moves a repo: see `prepare_gitops_sync` for what it reads and
+ * refuses. This is a task not a `.gen.` file because it makes network calls.
  *
  * @nodocs
  */
 export const task: Task<Args> = {
 	Args,
-	summary: 'syncs local repos and generates UI data from repo metadata',
+	summary: 'generates UI data from repo metadata, reading each repo as it sits',
 	run: async (ctx) => {
 		const { args, log, invoke_task } = ctx;
 		// `ctx.svelte_config` is a lazy getter, so it's only read when `outdir` isn't provided
 		const {
 			config,
-			dir,
+			registry,
 			outdir = (await ctx.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({
+		// The generated `repos.json` is the host project's site data, so a public host
+		// must never carry a private repo's metadata: `host` refuses the private repos
+		// the registry declares, before any fetch.
+		const package_json = await package_json_load();
+
+		const prepared = await prepare_gitops_sync({
 			config,
-			dir,
-			download,
-			sync: true,
+			registry,
+			host: { name: package_json.name, private: package_json.private === true },
+			check,
 			allow_dirty,
 			log
 		});
+		if (!prepared) return;
+		const { local_repos, token } = prepared;
 
 		const outfile_json = resolve(outdir, 'repos.json');
 		const outfile_ts = resolve(outdir, 'repos.ts');
 
-		// This searches the parent directory for the env var, so we don't use SvelteKit's $env imports
-		const token = load_from_env('SECRET_GITHUB_API_TOKEN');
-		if (!token) {
-			throw new TaskError('the env var SECRET_GITHUB_API_TOKEN was not found');
-		}
-
-		// Exit early if only checking repo readiness
-		if (check) {
-			log.info('repos are ready');
-			return;
-		}
-
 		const cache = await create_fs_fetch_value_cache('repos');
 
 		log.info('fetching remote repo data');
-		const repos_json = await fetch_repo_data(local_repos, token, cache.data, log);
+		const repos_json = await fetch_repo_data({ local_repos, token, cache: cache.data, log });
 
 		// TODO should package_json be provided in the Gro task/gen contexts? check if it's always loaded
-		const package_json = await package_json_load();
 		const repo_specifier =
 			package_json.name === '@fuzdev/fuz_gitops'
-				? '$lib/repo.svelte.js'
-				: '@fuzdev/fuz_gitops/repo.svelte.js';
+				? '$lib/repo.svelte.ts'
+				: '@fuzdev/fuz_gitops/repo.svelte.ts';
 
 		log.info(`generating ${outfile_json} and ${outfile_ts}`);
 
@@ -153,3 +165,166 @@ export const task: Task<Args> = {
 		}
 	}
 };
+
+/**
+ * The side effects `prepare_gitops_sync` reaches through, injectable for tests.
+ *
+ * @nodocs
+ */
+export interface GitopsSyncDeps {
+	/** Runs `repos status`. */
+	repos_ops: ReposOperations;
+	/** Loads each resolved repo's library as it sits (`local_repos_load`). */
+	load_repos: (options: {
+		local_repo_paths: Array<LocalRepoPath>;
+		log?: Logger;
+	}) => Promise<Array<LocalRepo>>;
+	/** Reads `SECRET_GITHUB_API_TOKEN`; `undefined` when it isn't set. */
+	load_token: () => string | undefined;
+	/** Whether a path exists, for the analysis-setup warning. */
+	exists: (path: string) => boolean;
+	/** Reads a file as UTF-8, for the analysis-setup warning. */
+	read_file: (path: string) => string;
+}
+
+const default_gitops_sync_deps: GitopsSyncDeps = {
+	repos_ops: default_repos_operations,
+	load_repos: local_repos_load,
+	// this searches the parent directory for the env var, so we don't use SvelteKit's $env imports
+	load_token: () => load_from_env('SECRET_GITHUB_API_TOKEN') || undefined,
+	exists: existsSync,
+	read_file: (path) => readFileSync(path, 'utf8')
+};
+
+/**
+ * Everything `gitops_sync` does before it fetches from GitHub, in order:
+ *
+ * 1. resolves the config's repos from `repos status <keys…> --json` (local
+ *    refs), refusing a private repo when the host package is public
+ * 2. checks each repo is ready to generate from (`check_gen_readiness`): on
+ *    its registry branch, clean, and idle, unless `allow_dirty` — refusing
+ *    before any network. With `check`, that report is the whole run: its
+ *    warnings are logged, and it throws when a real run would refuse
+ * 3. reads `SECRET_GITHUB_API_TOKEN`
+ * 4. fetches the repos from origin (`repos status <keys…> --fetch --json`,
+ *    which writes remote-tracking refs and nothing else) and checks them
+ *    again, warning on a followed branch not in sync with origin and a
+ *    failed fetch
+ * 5. warns on each npm repo the library analysis can't fully read: no
+ *    `node_modules`, or no `.svelte-kit/tsconfig.json` when its tsconfig
+ *    extends it (external types then read as `any`) — it installs nothing
+ * 6. loads each repo's library as it sits
+ *
+ * @returns the loaded repos and the token, or `null` when `check` passed
+ * @throws {TaskError} if resolving fails, a repo isn't ready, or the token is missing
+ * @nodocs
+ */
+export const prepare_gitops_sync = async (
+	options: {
+		config: string;
+		registry?: string;
+		host?: { name: string; private: boolean };
+		check?: boolean;
+		allow_dirty?: boolean;
+		log: Logger;
+	},
+	deps: Partial<GitopsSyncDeps> = {}
+): Promise<{ local_repos: Array<LocalRepo>; token: string } | null> => {
+	const { config, registry, host, check = false, allow_dirty = false, log } = options;
+	const { repos_ops, load_repos, load_token, exists, read_file } = {
+		...default_gitops_sync_deps,
+		...deps
+	};
+	const repos_command = to_repos_command(registry);
+
+	const { config_path, gitops_config, report } = await resolve_gitops_repos({
+		config,
+		registry,
+		host,
+		log,
+		repos_ops
+	});
+	const keys = gitops_config.repos;
+
+	const local = check_gen_readiness({ report, keys, allow_dirty, repos_command });
+	if (check) {
+		log_gen_warnings(local.warnings, log);
+		if (!local.ok) throw new TaskError(local.message);
+		log.info(st('green', `all ${keys.length} repos are ready to generate the site data from`));
+		return null;
+	}
+	if (!local.ok) throw new TaskError(local.message);
+
+	const token = load_token();
+	if (!token) {
+		throw new TaskError('the env var SECRET_GITHUB_API_TOKEN was not found');
+	}
+
+	log.info(`fetching ${keys.length} repos from origin`);
+	const fetched = await load_repos_status({ keys, registry, fetch: true, repos_ops });
+	if (!fetched.ok) {
+		throw new TaskError(`fetching the repos failed: ${fetched.message}`);
+	}
+	const resolved = local_repos_resolve({ keys, report: fetched.report, host, registry });
+	if (!resolved.ok) {
+		throw new TaskError(`${config_path}: ${resolved.message}`);
+	}
+	const checked = check_gen_readiness({
+		report: fetched.report,
+		keys,
+		allow_dirty,
+		repos_command
+	});
+	log_gen_warnings(checked.warnings, log);
+	if (!checked.ok) throw new TaskError(checked.message);
+
+	const local_repo_paths = resolved.value;
+	const gaps = local_repo_paths
+		.map((p) => ({ key: p.repo_name, missing: analysis_setup_gaps(p.repo_dir, exists, read_file) }))
+		.filter((g) => g.missing.length > 0);
+	if (gaps.length > 0) {
+		log.warn(
+			st(
+				'yellow',
+				"the library analysis reads these repos without their dependencies' types, so external types read as `any` — `npm install` and `gro sync` in each fixes it:"
+			)
+		);
+		for (const { key, missing } of gaps) {
+			log.warn(st('yellow', `  ${key}: no ${missing.join(' or ')}`));
+		}
+	}
+
+	const local_repos = await load_repos({ local_repo_paths, log });
+	return { local_repos, token };
+};
+
+const log_gen_warnings = (warnings: Array<string>, log: Logger): void => {
+	if (warnings.length === 0) return;
+	log.warn(st('yellow', "read as they sit, beside origin's CI:"));
+	for (const line of warnings) log.warn(st('yellow', `  ${line}`));
+};
+
+/**
+ * What an npm repo lacks for the library analysis to resolve its dependencies'
+ * types: `node_modules`, and `.svelte-kit/tsconfig.json` when its
+ * `tsconfig.json` extends it. Empty for a repo without a `package.json`.
+ */
+const analysis_setup_gaps = (
+	repo_dir: string,
+	exists: (path: string) => boolean,
+	read_file: (path: string) => string
+): Array<string> => {
+	if (!exists(join(repo_dir, 'package.json'))) return [];
+	const missing: Array<string> = [];
+	if (!exists(join(repo_dir, 'node_modules'))) missing.push('`node_modules`');
+	const tsconfig_path = join(repo_dir, 'tsconfig.json');
+	const svelte_kit_tsconfig = '.svelte-kit/tsconfig.json';
+	if (
+		exists(tsconfig_path) &&
+		read_file(tsconfig_path).includes(svelte_kit_tsconfig) &&
+		!exists(join(repo_dir, svelte_kit_tsconfig))
+	) {
+		missing.push(`\`${svelte_kit_tsconfig}\``);
+	}
+	return missing;
+};

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 { 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 {
+	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;
 };