@fuzdev/fuz_gitops 0.71.0 → 0.72.0

package/dist/publishing_event.js

@@ -0,0 +1,149 @@
+/**
+ * Structured events for multi-repo publishing.
+ *
+ * Publishing emits a stream of tagged events alongside its human-readable logging,
+ * so machine consumers (CI, dashboards) can follow a run step by step. Every run
+ * opens with a `run_started` event carrying `wetrun`: when `false`, the run is a dry
+ * run and every `package_completed` is a prediction (its `commit` is `'simulated'`)
+ * rather than an applied change. A run's `run_finished` summary is derived from the
+ * same event list via `summarize_events`, so the stream and the summary never drift.
+ *
+ * Events are consumed through a `PublishingEventHandler` sink (see
+ * `publishing_event_handler.ts`).
+ *
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * Coarse triage classification for a failed package. Lets consumers branch on
+ * failure kind without parsing the message.
+ */
+export const PublishingErrorCode = z.enum([
+    'publish',
+    'network',
+    'auth',
+    'dependency',
+    'build',
+    'other',
+]);
+/** Tallied outcome of a publishing run, derived from its events via `summarize_events`. */
+export const PublishingRunSummary = z.strictObject({
+    total: z.number().meta({ description: 'packages in the publishing order (the candidate set)' }),
+    published: z.number().meta({ description: 'packages published (or, in a dry run, predicted)' }),
+    failed: z.number(),
+    skipped: z.number(),
+    duration: z.number().meta({ description: 'wall-clock duration in milliseconds' }),
+});
+/**
+ * A single structured event emitted during a publishing run. Tagged on `event` so the
+ * union serializes as one self-describing JSON object per event (JSON-lines on the wire).
+ */
+export const PublishingEvent = z.discriminatedUnion('event', [
+    z.strictObject({
+        event: z.literal('run_started'),
+        wetrun: z.boolean().meta({ description: 'false means every package_completed is a prediction' }),
+        total: z.number(),
+    }),
+    z.strictObject({
+        event: z.literal('iteration_started'),
+        iteration: z.number(),
+        max: z.number(),
+    }),
+    z.strictObject({
+        event: z.literal('iteration_finished'),
+        iteration: z.number(),
+        published_count: z.number(),
+        converged: z.boolean(),
+    }),
+    z.strictObject({
+        event: z.literal('package_skipped'),
+        name: z.string(),
+        reason: z.string(),
+    }),
+    z.strictObject({
+        event: z.literal('package_completed'),
+        name: z.string(),
+        old_version: z.string(),
+        new_version: z.string(),
+        // mirrors `BumpType` from `semver.ts`; inline so the event schema is self-contained
+        bump_type: z.enum(['major', 'minor', 'patch']),
+        breaking: z.boolean(),
+        commit: z.string().meta({ description: "'simulated' in a dry run, otherwise the commit hash" }),
+        tag: z.string(),
+    }),
+    z.strictObject({
+        event: z.literal('package_failed'),
+        name: z.string(),
+        error: z.string(),
+        code: PublishingErrorCode,
+    }),
+    z.strictObject({
+        event: z.literal('dependency_updated'),
+        dependent: z.string(),
+        dependency: z.string(),
+        version: z.string(),
+    }),
+    z.strictObject({
+        event: z.literal('install_started'),
+        name: z.string(),
+    }),
+    z.strictObject({
+        event: z.literal('install_completed'),
+        name: z.string(),
+    }),
+    z.strictObject({
+        event: z.literal('install_failed'),
+        name: z.string(),
+        error: z.string(),
+    }),
+    z.strictObject({
+        event: z.literal('deploy_started'),
+        name: z.string(),
+    }),
+    z.strictObject({
+        event: z.literal('deploy_completed'),
+        name: z.string(),
+    }),
+    z.strictObject({
+        event: z.literal('deploy_failed'),
+        name: z.string(),
+        error: z.string(),
+    }),
+    z.strictObject({
+        event: z.literal('run_finished'),
+        summary: PublishingRunSummary,
+    }),
+]);
+/**
+ * Derives a run summary from the captured event list — the single canonical path from
+ * events to summary, so the `run_finished` summary always agrees with the stream.
+ * Call before emitting `run_finished` (which is not itself counted).
+ *
+ * @param events - the events captured so far this run
+ * @param duration - wall-clock duration in milliseconds
+ */
+export const summarize_events = (events, duration) => {
+    let total = 0;
+    let published = 0;
+    let failed = 0;
+    let skipped = 0;
+    for (const event of events) {
+        switch (event.event) {
+            case 'run_started':
+                total = event.total;
+                break;
+            case 'package_completed':
+                published++;
+                break;
+            case 'package_failed':
+                failed++;
+                break;
+            case 'package_skipped':
+                skipped++;
+                break;
+            default:
+                break;
+        }
+    }
+    return { total, published, failed, skipped, duration };
+};

package/dist/publishing_event_handler.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Composable sinks for the publishing event stream.
+ *
+ * A `PublishingEventHandler` is anything that can receive a `PublishingEvent`. Handlers
+ * compose: `multi_handler` fans out, `masking_handler` redacts secrets then forwards.
+ * Emission is best-effort and synchronous — an observability sink must never fail or
+ * slow a run. The default sink is `null_handler` (drops everything).
+ *
+ * @module
+ */
+import type { PublishingEvent } from './publishing_event.js';
+/** A sink for publishing events. */
+export interface PublishingEventHandler {
+    emit: (event: PublishingEvent) => void;
+}
+/** A `capture_handler` also exposes the events it has collected. */
+export interface CapturingEventHandler extends PublishingEventHandler {
+    readonly events: Array<PublishingEvent>;
+}
+/** Drops every event. The default when no handler is supplied. */
+export declare const null_handler: () => PublishingEventHandler;
+/** Collects events in memory. Used to build the run report and in tests. */
+export declare const capture_handler: () => CapturingEventHandler;
+/**
+ * Writes each event as one JSON object per line (JSON-lines) to `process.stdout`.
+ * Write failures are swallowed — the stream is observability, not control flow.
+ */
+export declare const stdout_handler: () => PublishingEventHandler;
+/** Fans an event out to every handler in order. */
+export declare const multi_handler: (handlers: Array<PublishingEventHandler>) => PublishingEventHandler;
+/**
+ * Wraps a handler, masking secrets in each event's string fields before forwarding.
+ *
+ * @param inner - the handler to forward masked events to
+ * @param mask - the masking function, defaults to `mask_secrets`
+ */
+export declare const masking_handler: (inner: PublishingEventHandler, mask?: (event: PublishingEvent) => PublishingEvent) => PublishingEventHandler;
+/** Redacts known secret shapes from a string. */
+export declare const redact_secrets: (text: string) => string;
+/** Returns a copy of the event with secrets redacted from its string-valued fields. */
+export declare const mask_secrets: (event: PublishingEvent) => PublishingEvent;
+//# sourceMappingURL=publishing_event_handler.d.ts.map

package/dist/publishing_event_handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publishing_event_handler.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/publishing_event_handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAE3D,oCAAoC;AACpC,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;CACvC;AAED,oEAAoE;AACpE,MAAM,WAAW,qBAAsB,SAAQ,sBAAsB;IACpE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;CACxC;AAED,kEAAkE;AAClE,eAAO,MAAM,YAAY,QAAO,sBAE9B,CAAC;AAEH,4EAA4E;AAC5E,eAAO,MAAM,eAAe,QAAO,qBAQlC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,QAAO,sBAQhC,CAAC;AAEH,mDAAmD;AACnD,eAAO,MAAM,aAAa,GAAI,UAAU,KAAK,CAAC,sBAAsB,CAAC,KAAG,sBAMtE,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAC3B,OAAO,sBAAsB,EAC7B,OAAM,CAAC,KAAK,EAAE,eAAe,KAAK,eAA8B,KAC9D,sBAID,CAAC;AAWH,iDAAiD;AACjD,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,MACgD,CAAC;AAE/F,uFAAuF;AACvF,eAAO,MAAM,YAAY,GAAI,OAAO,eAAe,KAAG,eAMrD,CAAC"}

package/dist/publishing_event_handler.js

@@ -0,0 +1,75 @@
+/**
+ * Composable sinks for the publishing event stream.
+ *
+ * A `PublishingEventHandler` is anything that can receive a `PublishingEvent`. Handlers
+ * compose: `multi_handler` fans out, `masking_handler` redacts secrets then forwards.
+ * Emission is best-effort and synchronous — an observability sink must never fail or
+ * slow a run. The default sink is `null_handler` (drops everything).
+ *
+ * @module
+ */
+/** Drops every event. The default when no handler is supplied. */
+export const null_handler = () => ({
+    emit: () => { },
+});
+/** Collects events in memory. Used to build the run report and in tests. */
+export const capture_handler = () => {
+    const events = [];
+    return {
+        events,
+        emit: (event) => {
+            events.push(event);
+        },
+    };
+};
+/**
+ * Writes each event as one JSON object per line (JSON-lines) to `process.stdout`.
+ * Write failures are swallowed — the stream is observability, not control flow.
+ */
+export const stdout_handler = () => ({
+    emit: (event) => {
+        try {
+            process.stdout.write(JSON.stringify(event) + '\n');
+        }
+        catch {
+            // best-effort: a logging sink must never fail a run
+        }
+    },
+});
+/** Fans an event out to every handler in order. */
+export const multi_handler = (handlers) => ({
+    emit: (event) => {
+        for (const handler of handlers) {
+            handler.emit(event);
+        }
+    },
+});
+/**
+ * Wraps a handler, masking secrets in each event's string fields before forwarding.
+ *
+ * @param inner - the handler to forward masked events to
+ * @param mask - the masking function, defaults to `mask_secrets`
+ */
+export const masking_handler = (inner, mask = mask_secrets) => ({
+    emit: (event) => {
+        inner.emit(mask(event));
+    },
+});
+// Minimal redaction rules: npm auth tokens (bare or registry-scoped), `SECRET_*`
+// env-style assignments, and `npm_`-prefixed tokens. Deliberately lean — error
+// strings can carry npm/git output; a fuller secret catalog is deferred.
+const SECRET_RULES = [
+    [/((?:\/\/[^\s:]+:)?_authToken\s*=\s*)\S+/gi, '$1[redacted]'],
+    [/(SECRET_[A-Z0-9_]+\s*[=:]\s*)\S+/g, '$1[redacted]'],
+    [/(npm_[A-Za-z0-9]{4})[A-Za-z0-9]{12,}/g, '$1[redacted]'],
+];
+/** Redacts known secret shapes from a string. */
+export const redact_secrets = (text) => SECRET_RULES.reduce((acc, [pattern, replacement]) => acc.replace(pattern, replacement), text);
+/** Returns a copy of the event with secrets redacted from its string-valued fields. */
+export const mask_secrets = (event) => {
+    const masked = {};
+    for (const [key, value] of Object.entries(event)) {
+        masked[key] = typeof value === 'string' ? redact_secrets(value) : value;
+    }
+    return masked;
+};

package/dist/repo_ops.d.ts

@@ -35,7 +35,7 @@ export interface RepoPath {
  * Get repo paths from gitops config without full git sync.
  * Lighter weight than `get_gitops_ready()` - just resolves paths.
  *
- * @param config_path - path to `gitops.config.ts` (defaults to `./gitops.config.ts`)
+ * @param config_path - path to the gitops config file (defaults to `gitops.config.ts`)
  * @returns array of repo info with name, path, and url
  */
 export declare const get_repo_paths: (config_path?: string) => Promise<Array<RepoPath>>;

package/dist/repo_ops.js

@@ -59,7 +59,7 @@ export const DEFAULT_EXCLUDE_EXTENSIONS = [
  * Get repo paths from gitops config without full git sync.
  * Lighter weight than `get_gitops_ready()` - just resolves paths.
  *
- * @param config_path - path to `gitops.config.ts` (defaults to `./gitops.config.ts`)
+ * @param config_path - path to the gitops config file (defaults to `gitops.config.ts`)
  * @returns array of repo info with name, path, and url
  */
 export const get_repo_paths = async (config_path) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_gitops",
-  "version": "0.71.0",
+  "version": "0.72.0",
   "description": "a tool for managing many repos",
   "glyph": "🪄",
   "logo": "logo.svg",
@@ -31,7 +31,7 @@
   "peerDependencies": {
     "@fuzdev/fuz_css": ">=0.61.0",
     "@fuzdev/fuz_ui": ">=0.198.0",
-    "@fuzdev/fuz_util": ">=0.63.0",
+    "@fuzdev/fuz_util": ">=0.63.1",
     "@fuzdev/gro": ">=0.200.0",
     "@sveltejs/kit": "^2",
     "svelte": "^5",
@@ -43,7 +43,7 @@
     "@fuzdev/fuz_code": "^0.45.1",
     "@fuzdev/fuz_css": "^0.61.1",
     "@fuzdev/fuz_ui": "^0.198.0",
-    "@fuzdev/fuz_util": "^0.63.0",
+    "@fuzdev/fuz_util": "^0.63.1",
     "@fuzdev/gro": "^0.200.0",
     "@jridgewell/trace-mapping": "^0.3.31",
     "@ryanatkn/eslint-config": "^0.12.1",

package/src/lib/gitops_publish.task.ts

@@ -9,6 +9,7 @@ import {
 	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 {format_and_output, type OutputFormatters} from './output_helpers.js';
 import {GITOPS_CONFIG_PATH_DEFAULT, GITOPS_NPM_WAIT_TIMEOUT_DEFAULT} from './gitops_constants.js';
@@ -46,6 +47,10 @@ export const Args = z.strictObject({
 		.boolean()
 		.meta({description: 'skip npm install after dependency updates'})
 		.default(false),
+	emit_json: z
+		.boolean()
+		.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),
 });
@@ -66,6 +71,7 @@ export const task: Task<Args> = {
 			plan,
 			max_wait,
 			skip_install,
+			emit_json,
 			outfile,
 			verbose,
 		} = args;
@@ -107,6 +113,8 @@ export const task: Task<Args> = {
 			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)
@@ -124,6 +132,8 @@ 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},
 			};
 		}