@fuzdev/fuz_gitops 0.78.0 → 0.79.0

package/dist/gitops_publish.task.js

@@ -1,13 +1,15 @@
 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 { execute_publishing_plan, } 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 { gate_publish_readiness, get_gitops_ready, log_readiness_block } from './gitops_task_helpers.js';
+import { default_gitops_operations, default_repos_operations } from './operations_defaults.js';
+import { execute_publishing_plan } from './multi_repo_publisher.js';
+import { mask_secrets, masking_handler, redact_secrets, stdout_handler } from './publishing_event_handler.js';
+import { generate_publishing_plan } from './publishing_plan.js';
+import { log_publishing_plan } from './publishing_plan_logging.js';
 import { derive_publish_steps, format_publish_steps } from './publish_steps.js';
 import { decide_publish_gate, publish_run_failed } from './publish_gate.js';
-import { format_and_output } from './output_helpers.js';
+import { format_and_output, output_is_machine, route_human_output } from './output_helpers.js';
 import { GITOPS_CONFIG_PATH_DEFAULT, GITOPS_NPM_WAIT_TIMEOUT_DEFAULT } from './gitops_constants.js';
 /** @nodocs */
 export const Args = z.strictObject({
@@ -15,20 +17,29 @@ 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(),
     peer_strategy: z
-        .enum(['exact', 'caret', 'tilde'])
-        .meta({ description: 'version strategy for peer dependencies' })
+        .enum(['exact', 'caret', 'tilde', 'gte'])
+        .meta({
+        description: 'range prefix for a rewritten dependency of any type whose range has none (an existing prefix is kept; a wildcard becomes ^)'
+    })
         .default('caret'),
     wetrun: z.boolean().meta({ description: 'actually publish (default is dry run)' }).default(false),
     format: z
         .enum(['stdout', 'json', 'markdown'])
         .meta({ description: 'output format' })
         .default('stdout'),
-    deploy: z.boolean().meta({ description: 'deploy all repos after publishing' }).default(false),
+    deploy: z
+        .boolean()
+        .meta({
+        description: 'deploy each repo the run changed (published, or any dependency updated) after publishing'
+    })
+        .default(false),
     plan: z
         .boolean()
         .meta({ description: 'show the plan and confirm before publishing; --no-plan to skip' })
@@ -42,121 +53,198 @@ export const Args = z.strictObject({
         .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
+    verbose: 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',
-    })
+        .meta({ description: 'show additional details in plan output' })
         .default(false),
     preview: z
         .boolean()
         .meta({ description: 'show the ordered side-effects a --wetrun would perform' })
-        .default(false),
+        .default(false)
 });
 /** @nodocs */
 export const task = {
-    summary: 'publish all repos in dependency order',
+    summary: 'publish the packages the plan publishes, in dependency order (a dry run unless --wetrun)',
     Args,
     run: async ({ args, log }) => {
-        const { config, dir, peer_strategy, wetrun, format, deploy, plan, max_wait, emit_json, outfile, verbose, sync, preview, } = args;
-        // 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,
-        });
-        // 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'));
-            log_publishing_plan(publishing_plan, log, { verbose });
+        const outcome = await run_gitops_publish(args, log);
+        if (outcome === 'cancelled') {
+            process.exit(0);
         }
-        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.'));
-            process.stdout.write('Continue with publishing? (y/n): ');
-            const confirmed = await prompt_for_confirmation();
-            if (!confirmed) {
-                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 = {
-            wetrun,
-            version_strategy: peer_strategy,
-            deploy,
-            max_wait,
-            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)
-        let result;
-        let fatal_error = null;
-        try {
-            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));
-            result = {
-                ok: false,
-                published: [],
-                // 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,
-            };
+        else if (outcome === 'failed') {
+            process.exit(1);
         }
-        // Format and output result (always runs, even on fatal errors)
-        // Note: stdout format is handled by the executor's logging
-        if (format !== 'stdout') {
-            await format_and_output({ result, fatal_error, preview_steps }, create_publish_formatters(), {
-                format,
-                outfile,
+    }
+};
+const default_gitops_publish_deps = {
+    load_repos: get_gitops_ready,
+    repos_ops: default_repos_operations,
+    ops: default_gitops_operations,
+    confirm: async () => {
+        process.stderr.write('Continue with publishing? (y/n): ');
+        return prompt_for_confirmation();
+    }
+};
+/**
+ * Runs `gro gitops_publish`, in order: load the repos as they sit,
+ * generate the plan, and — for `--wetrun` — run the readiness gate
+ * (`gate_publish_readiness`, read-only: `repos status --fetch`) before
+ * printing the plan and asking to confirm, so a refusal or a "no" changes
+ * nothing. Then preflight and the executor. A dry run skips the gate and
+ * prints the diagnostics' readiness block instead. Under `--emit_json`, or
+ * `--format json` or `markdown` without `--outfile`, the log goes to stderr
+ * and stdout carries the events or the report alone (`route_human_output`).
+ *
+ * @returns `cancelled` when the operator declines, `failed` when the run failed (its output already written), else `done`
+ * @throws {TaskError} when the readiness gate refuses or loading fails
+ * @nodocs
+ */
+export const run_gitops_publish = async (args, log, deps = {}) => {
+    const { load_repos, repos_ops, ops, confirm } = { ...default_gitops_publish_deps, ...deps };
+    const { config, registry, peer_strategy, wetrun, format, deploy, plan, max_wait, emit_json, outfile, verbose, preview } = args;
+    // With a machine-readable stdout, every human line goes to stderr: the log (the plan, the
+    // readiness block and gate, the executor's progress) and, in `confirm`, the prompt
+    const write_stdout = route_human_output(log, to_child_stdout(args) === 'stderr');
+    // Load repos as they sit; a real publish gates on their state below rather than moving them
+    const { local_repos: repos } = await load_repos({ config, registry, log });
+    // Generate the plan once; the executor consumes this exact plan (no second pass).
+    const publishing_plan = await generate_publishing_plan(repos, { verbose, ops: ops.changeset });
+    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 at the edge).
+    const gate = decide_publish_gate({ wetrun, show_plan: plan, plan: publishing_plan });
+    if (wetrun) {
+        // The readiness gate: fetch, then refuse unless every npm repo is ready. Read-only, and
+        // before the prompt and any side effect. A plan with errors is refused without fetching:
+        // below when the plan is shown, else by the executor before anything else it does.
+        if (publishing_plan.errors.length === 0) {
+            await gate_publish_readiness({
+                local_repos: repos,
+                registry,
+                publishing: new Set(publishing_plan.version_changes.map((vc) => vc.package_name)),
                 log,
+                repos_ops
             });
         }
-        // Exit with error if failed
-        if (publish_run_failed(result, fatal_error)) {
-            process.exit(1);
+    }
+    else {
+        log_readiness_block(repos, log);
+    }
+    // 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'));
+        log_publishing_plan(publishing_plan, log, { verbose });
+    }
+    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.'));
+        const confirmed = await confirm();
+        if (!confirmed) {
+            log.info('Publishing cancelled');
+            return 'cancelled';
         }
-    },
+    }
+    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 = {
+        wetrun,
+        version_strategy: peer_strategy,
+        deploy,
+        max_wait,
+        log,
+        ops,
+        registry,
+        // Live JSON-lines stream when requested, secrets masked since failure messages carry
+        // npm's stderr; events also surface on the result.
+        events: emit_json ? masking_handler(stdout_handler(write_stdout)) : undefined,
+        child_stdout: to_child_stdout(args)
+    };
+    // Execute publishing (may throw on fatal errors like circular dependencies)
+    let result;
+    let fatal_error = null;
+    try {
+        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));
+        result = {
+            ok: false,
+            published: [],
+            // 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 the executor's logging
+    if (format !== 'stdout') {
+        await format_and_output({ result, fatal_error, preview_steps }, create_publish_formatters(), {
+            format,
+            outfile,
+            log,
+            write_stdout
+        });
+    }
+    return publish_run_failed(result, fatal_error) ? 'failed' : 'done';
+};
+/**
+ * Where `gro publish` and `gro deploy`, streaming live, show their stdout: on
+ * our stderr when our stdout carries a machine-readable stream — the
+ * `--emit_json` events, or a JSON or markdown report not sent to `--outfile` —
+ * so their output can't corrupt it, else on our stdout. The same test sends
+ * the task's own log and prompt to stderr.
+ *
+ * @nodocs
+ */
+export const to_child_stdout = (args) => args.emit_json || output_is_machine(args.format, args.outfile) ? 'stderr' : 'stdout';
+/**
+ * A failed package's markdown: the message's first line on the bullet, and the
+ * rest — the end of a command's stderr — in an indented fenced block, its fence
+ * longer than any backtick run inside so stderr can't close it.
+ *
+ * @param name - the package name
+ * @param message - the failure message
+ * @nodocs
+ */
+export const format_failure_markdown = (name, message) => {
+    const [head, ...rest] = message.split('\n');
+    const lines = [`- \`${name}\`: ${head}`];
+    if (rest.length === 0)
+        return lines;
+    const longest_run = Math.max(0, ...(rest.join('\n').match(/`+/g) ?? []).map((r) => r.length));
+    const fence = '`'.repeat(Math.max(3, longest_run + 1));
+    lines.push('', `  ${fence}`, ...rest.map((l) => `  ${l}`), `  ${fence}`);
+    return lines;
 };
 const create_publish_formatters = () => ({
-    json: (data) => JSON.stringify(data.preview_steps ? { ...data.result, preview: data.preview_steps } : data.result, null, 2),
+    json: (data) => {
+        // the result's events are the executor's unmasked capture; mask them as the live stream is
+        const result = { ...data.result, events: data.result.events.map(mask_secrets) };
+        return JSON.stringify(data.preview_steps ? { ...result, preview: data.preview_steps } : result, null, 2);
+    },
     markdown: (data) => format_result_markdown(data.result, data.fatal_error, data.preview_steps),
     stdout: () => {
         // 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. */
+/** Logs the ordered side-effect preview. */
 const log_preview = (steps, log) => {
     log.info(st('cyan', '\nSide-effect preview (what a real publish would perform):'));
     for (const line of format_publish_steps(steps)) {
@@ -172,7 +260,7 @@ const format_result_markdown = (result, fatal_error, preview_steps) => {
     if (fatal_error) {
         lines.push('## ❌ Fatal Error');
         lines.push('');
-        lines.push(`**Error**: ${fatal_error.message}`);
+        lines.push(`**Error**: ${redact_secrets(fatal_error.message)}`);
         lines.push('');
         lines.push('Publishing could not proceed due to the error above.');
         lines.push('');
@@ -197,7 +285,7 @@ const format_result_markdown = (result, fatal_error, preview_steps) => {
         lines.push('## Failed Packages');
         lines.push('');
         for (const { name, error } of result.failed) {
-            lines.push(`- \`${name}\`: ${error.message}`);
+            lines.push(...format_failure_markdown(name, redact_secrets(error.message)));
         }
     }
     if (result.plan_warnings.length > 0) {
@@ -232,7 +320,7 @@ const format_result_markdown = (result, fatal_error, preview_steps) => {
 const prompt_for_confirmation = async () => {
     const rl = createInterface({
         input: process.stdin,
-        output: process.stdout,
+        output: process.stderr
     });
     const answer = await rl.question('');
     rl.close();

package/dist/gitops_run.task.d.ts

@@ -1,8 +1,12 @@
 import { type Task } from '@fuzdev/gro';
+import type { Logger } from '@fuzdev/fuz_util/log.ts';
 import { z } from 'zod';
+import type { ReposOperations } from './operations.js';
+/** @nodocs */
 export declare const Args: z.ZodObject<{
     _: z.ZodDefault<z.ZodArray<z.ZodString>>;
     config: z.ZodDefault<z.ZodString>;
+    registry: z.ZodOptional<z.ZodString>;
     concurrency: z.ZodDefault<z.ZodNumber>;
     format: z.ZodDefault<z.ZodEnum<{
         text: "text";
@@ -11,5 +15,75 @@ export declare const Args: z.ZodObject<{
     outfile: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type Args = z.infer<typeof Args>;
+/**
+ * How a command run in one repo ended: it exited with a code, a signal killed
+ * it, or it never started.
+ *
+ * @nodocs
+ */
+export type GitopsRunOutcome = {
+    kind: 'exited';
+    code: number;
+} | {
+    kind: 'signaled';
+    signal: string;
+} | {
+    kind: 'error';
+    message: string;
+};
+/**
+ * What a command run in one repo printed, and how it ended.
+ *
+ * @nodocs
+ */
+export interface GitopsRunCommandOutput {
+    outcome: GitopsRunOutcome;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * One repo's result, as the JSON output carries it.
+ *
+ * @nodocs
+ */
+export interface GitopsRunResult {
+    repo_name: string;
+    repo_dir: string;
+    status: 'success' | 'failure';
+    /** The command's exit code; `null` when a signal killed it or it never started. */
+    exit_code: number | null;
+    /** The signal that killed the command, else `null`. */
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+    duration_ms: number;
+    /** Why the command never started. */
+    error?: string;
+}
+/**
+ * The side effects `run_gitops_run` reaches through, injectable for tests.
+ *
+ * @nodocs
+ */
+export interface GitopsRunDeps {
+    /** Runs `repos status` to resolve the config's repos. */
+    repos_ops: ReposOperations;
+    /** Runs `command` through `sh -c` in `cwd`, capturing its output. */
+    run_command: (options: {
+        command: string;
+        cwd: string;
+    }) => Promise<GitopsRunCommandOutput>;
+}
+/** @nodocs */
 export declare const task: Task<Args>;
+/**
+ * Runs `gro gitops_run`: resolves the config's repos through `repos status`,
+ * refusing a missing one, runs the command in each, `concurrency` at a time,
+ * and reports every result. Under `--format json` without `--outfile`, the log
+ * goes to stderr and stdout carries the JSON alone (`route_human_output`).
+ *
+ * @throws {TaskError} when no command is given, resolving the repos fails, or the command fails in any repo (after reporting)
+ * @nodocs
+ */
+export declare const run_gitops_run: (args: Args, log: Logger, deps?: Partial<GitopsRunDeps>) => Promise<void>;
 //# sourceMappingURL=gitops_run.task.d.ts.map

package/dist/gitops_run.task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gitops_run.task.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/gitops_run.task.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,IAAI,EAAC,MAAM,aAAa,CAAC;AACjD,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAUtB,eAAO,MAAM,IAAI;;;;;;;;;kBAmBf,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;AAaxC,eAAO,MAAM,IAAI,EAAE,IAAI,CAAC,IAAI,CAyM3B,CAAC"}
+{"version":3,"file":"gitops_run.task.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/gitops_run.task.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAIvD,cAAc;AACd,eAAO,MAAM,IAAI;;;;;;;;;;kBA0Bf,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;AAExC;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GACzB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;IAC9B,mFAAmF;IACnF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,uDAAuD;IACvD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,yDAAyD;IACzD,SAAS,EAAE,eAAe,CAAC;IAC3B,qEAAqE;IACrE,WAAW,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAC;CAC5F;AAiBD,cAAc;AACd,eAAO,MAAM,IAAI,EAAE,IAAI,CAAC,IAAI,CAM3B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAC1B,MAAM,IAAI,EACV,KAAK,MAAM,EACX,OAAM,OAAO,CAAC,aAAa,CAAM,KAC/B,OAAO,CAAC,IAAI,CAkGd,CAAC"}