@kici-dev/shared 0.0.0 → 0.1.0

package/dist/env/env-rule-allowlist.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=env-rule-allowlist.test.d.ts.map

package/dist/env/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @kici-dev/shared/env — env schema helpers shared across services.
+ *
+ * Subpath export so server-side packages can `import { defineEnv } from
+ * '@kici-dev/shared/env'`. This subpath is intentionally NOT re-exported
+ * from the package root: it pulls Zod and is only meaningful in Node-side
+ * config loaders, not from browser code.
+ */
+export { defineEnv, validateUnknownKiciVars, RESERVED_NON_SCHEMA_KICI_VARS, RESERVED_NON_SCHEMA_KICI_PREFIXES, type DefineEnvOptions, type DefineEnvResult, type EnvFieldSpec, type EnvMap, type EnvMapValue, type ValidateUnknownKiciVarsOptions, } from './define-env.js';
+export { LoggerEnvSchema, LOGGER_ENV_VARS, LOGGER_ENV_FIELD_SPECS } from './logger-env.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/env/index.js

@@ -0,0 +1,4 @@
+import "../chunk-gOLHoazu.js";
+import { RESERVED_NON_SCHEMA_KICI_PREFIXES, RESERVED_NON_SCHEMA_KICI_VARS, defineEnv, validateUnknownKiciVars } from "./define-env.js";
+import { LOGGER_ENV_FIELD_SPECS, LOGGER_ENV_VARS, LoggerEnvSchema } from "./logger-env.js";
+export { LOGGER_ENV_FIELD_SPECS, LOGGER_ENV_VARS, LoggerEnvSchema, RESERVED_NON_SCHEMA_KICI_PREFIXES, RESERVED_NON_SCHEMA_KICI_VARS, defineEnv, validateUnknownKiciVars };

package/dist/env/logger-env.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared LoggerEnv schema.
+ *
+ * The logger (packages/shared/src/logger.ts) reads these env vars *before*
+ * the per-service config loads, so we can't include them in the service
+ * schemas the normal way. We still want them in `docs/operator/env-reference.md`
+ * and in `validateUnknownKiciVars()`'s known-var set, so this schema documents
+ * them in one place. Each service includes the keys here when computing its
+ * "known KICI_* vars" list, and the docs generator emits a "Logger / shared"
+ * section from this schema.
+ *
+ * IMPORTANT: do not change the runtime behaviour of `logger.ts` from this
+ * schema — the schema is documentation + the unknown-var allowlist, not the
+ * source of truth for the logger.
+ */
+import { z } from 'zod';
+import type { EnvFieldSpec } from './define-env.js';
+export declare const LoggerEnvSchema: z.ZodObject<{
+    KICI_LOG_DIR: z.ZodOptional<z.ZodString>;
+    KICI_LOG_MAX_SIZE: z.ZodDefault<z.ZodString>;
+    KICI_LOG_RETENTION_DAYS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    KICI_CLUSTER_INSTANCE_ID: z.ZodOptional<z.ZodString>;
+    KICI_AGENT_ID: z.ZodOptional<z.ZodString>;
+    KICI_PLATFORM_INSTANCE_ID: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** All env vars the logger reads, for the unknown-KICI-var scanner. */
+export declare const LOGGER_ENV_VARS: readonly ["KICI_LOG_DIR", "KICI_LOG_MAX_SIZE", "KICI_LOG_RETENTION_DAYS", "KICI_CLUSTER_INSTANCE_ID", "KICI_AGENT_ID", "KICI_PLATFORM_INSTANCE_ID"];
+/** Doc-friendly description map (consumed by the env-reference generator). */
+export declare const LOGGER_ENV_FIELD_SPECS: EnvFieldSpec[];
+//# sourceMappingURL=logger-env.d.ts.map

package/dist/env/logger-env.js

@@ -0,0 +1,95 @@
+import "../chunk-gOLHoazu.js";
+import { z } from "zod";
+//#region src/env/logger-env.ts
+/**
+* Shared LoggerEnv schema.
+*
+* The logger (packages/shared/src/logger.ts) reads these env vars *before*
+* the per-service config loads, so we can't include them in the service
+* schemas the normal way. We still want them in `docs/operator/env-reference.md`
+* and in `validateUnknownKiciVars()`'s known-var set, so this schema documents
+* them in one place. Each service includes the keys here when computing its
+* "known KICI_* vars" list, and the docs generator emits a "Logger / shared"
+* section from this schema.
+*
+* IMPORTANT: do not change the runtime behaviour of `logger.ts` from this
+* schema — the schema is documentation + the unknown-var allowlist, not the
+* source of truth for the logger.
+*/
+const LoggerEnvSchema = z.object({
+	KICI_LOG_DIR: z.string().optional(),
+	KICI_LOG_MAX_SIZE: z.string().default("500m"),
+	KICI_LOG_RETENTION_DAYS: z.coerce.number().default(7),
+	/** Set by the orchestrator process; used as a filename suffix. */
+	KICI_CLUSTER_INSTANCE_ID: z.string().optional(),
+	/** Set by the agent process; used as a filename suffix. */
+	KICI_AGENT_ID: z.string().optional(),
+	/** Set by the platform process; used as a filename suffix. */
+	KICI_PLATFORM_INSTANCE_ID: z.string().optional()
+});
+/** All env vars the logger reads, for the unknown-KICI-var scanner. */
+const LOGGER_ENV_VARS = [
+	"KICI_LOG_DIR",
+	"KICI_LOG_MAX_SIZE",
+	"KICI_LOG_RETENTION_DAYS",
+	"KICI_CLUSTER_INSTANCE_ID",
+	"KICI_AGENT_ID",
+	"KICI_PLATFORM_INSTANCE_ID"
+];
+/** Doc-friendly description map (consumed by the env-reference generator). */
+const LOGGER_ENV_FIELD_SPECS = [
+	{
+		envVar: "KICI_CLUSTER_INSTANCE_ID",
+		aliases: [],
+		fieldPath: "KICI_CLUSTER_INSTANCE_ID",
+		required: false,
+		type: "string",
+		description: "Stable orchestrator identifier; appended to the log filename so multiple instances can share one KICI_LOG_DIR."
+	},
+	{
+		envVar: "KICI_AGENT_ID",
+		aliases: [],
+		fieldPath: "KICI_AGENT_ID",
+		required: false,
+		type: "string",
+		description: "Stable agent identifier; appended to the agent log filename so multiple agents can share one KICI_LOG_DIR."
+	},
+	{
+		envVar: "KICI_LOG_DIR",
+		aliases: [],
+		fieldPath: "KICI_LOG_DIR",
+		required: false,
+		type: "string",
+		description: "Directory for rotated JSON log files. When unset, the logger only writes to stdout/stderr."
+	},
+	{
+		envVar: "KICI_LOG_MAX_SIZE",
+		aliases: [],
+		fieldPath: "KICI_LOG_MAX_SIZE",
+		required: false,
+		defaultValue: "\"500m\"",
+		type: "string",
+		description: "Per-file size cap for rotated logs. Accepts a numeric byte count or a size suffix (`k`, `m`, `g`)."
+	},
+	{
+		envVar: "KICI_LOG_RETENTION_DAYS",
+		aliases: [],
+		fieldPath: "KICI_LOG_RETENTION_DAYS",
+		required: false,
+		defaultValue: "7",
+		type: "number",
+		description: "How many days of rotated logs to keep before deletion."
+	},
+	{
+		envVar: "KICI_PLATFORM_INSTANCE_ID",
+		aliases: [],
+		fieldPath: "KICI_PLATFORM_INSTANCE_ID",
+		required: false,
+		type: "string",
+		description: "Stable Platform identifier; appended to the platform log filename so multiple instances can share one KICI_LOG_DIR."
+	}
+];
+//#endregion
+export { LOGGER_ENV_FIELD_SPECS, LOGGER_ENV_VARS, LoggerEnvSchema };
+
+//# sourceMappingURL=logger-env.js.map

package/dist/error.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Extract a human-readable error message from an unknown thrown value.
+ */
+export declare function toErrorMessage(err: unknown): string;
+/**
+ * Serialize an error into a structured object suitable for logging.
+ *
+ * Captures the message, error type name, common diagnostic fields
+ * (`code`, `status`, response details), and the chained `cause`.
+ * Falls back to a non-empty descriptor when `err.message` is empty —
+ * an empty message field is a debugging dead end (we've hit it on
+ * sync failures where the underlying library throws errors with no
+ * message but populated `.code` / `.response.status`).
+ */
+export declare function serializeError(err: unknown): Record<string, unknown>;
+//# sourceMappingURL=error.d.ts.map

package/dist/error.js

@@ -0,0 +1,58 @@
+import "./chunk-gOLHoazu.js";
+//#region src/error.ts
+/**
+* Extract a human-readable error message from an unknown thrown value.
+*/
+function toErrorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/**
+* Serialize an error into a structured object suitable for logging.
+*
+* Captures the message, error type name, common diagnostic fields
+* (`code`, `status`, response details), and the chained `cause`.
+* Falls back to a non-empty descriptor when `err.message` is empty —
+* an empty message field is a debugging dead end (we've hit it on
+* sync failures where the underlying library throws errors with no
+* message but populated `.code` / `.response.status`).
+*/
+function serializeError(err) {
+	if (err === null || err === void 0) return { message: String(err) };
+	if (typeof err !== "object") return { message: String(err) };
+	const e = err;
+	const out = {};
+	const rawMessage = err instanceof Error ? err.message : e.message;
+	out.message = rawMessage && rawMessage.length > 0 ? rawMessage : `<${describeShape(err)}>`;
+	if (err instanceof Error && err.name && err.name !== "Error") out.name = err.name;
+	if (typeof e.code === "string" || typeof e.code === "number") out.code = e.code;
+	const response = e.response;
+	if (response && typeof response === "object") {
+		if (typeof response.status === "number") out.status = response.status;
+		if (response.statusText) out.statusText = response.statusText;
+		if (response.data !== void 0) out.responseData = trimResponseData(response.data);
+	}
+	if (e.cause !== void 0) out.cause = serializeError(e.cause);
+	return out;
+}
+/**
+* Describe an error's shape when its `.message` is empty so logs
+* still convey something useful (vs. a bare `error: ""`).
+*/
+function describeShape(err) {
+	const ctor = err.constructor?.name;
+	if (ctor && ctor !== "Object") return `${ctor} with empty message`;
+	const keys = Object.keys(err).slice(0, 5).join(",");
+	return keys ? `object{${keys}}` : "empty error";
+}
+/**
+* Cap response payload size to keep logs readable.
+*/
+function trimResponseData(data) {
+	const s = typeof data === "string" ? data : JSON.stringify(data);
+	if (s.length <= 500) return data;
+	return s.slice(0, 500) + `…(+${s.length - 500} chars)`;
+}
+//#endregion
+export { serializeError, toErrorMessage };
+
+//# sourceMappingURL=error.js.map

package/dist/error.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=error.test.d.ts.map

package/dist/format-bytes.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Format bytes to a human-readable string.
+ */
+export declare function formatBytes(bytes: number): string;
+//# sourceMappingURL=format-bytes.d.ts.map

package/dist/format-bytes.js

@@ -0,0 +1,15 @@
+import "./chunk-gOLHoazu.js";
+//#region src/format-bytes.ts
+/**
+* Format bytes to a human-readable string.
+*/
+function formatBytes(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+//#endregion
+export { formatBytes };
+
+//# sourceMappingURL=format-bytes.js.map

package/dist/format-bytes.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=format-bytes.test.d.ts.map

package/dist/format-duration.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Format seconds into human-readable uptime.
+ * Examples: "45s", "3m 12s", "2h 15m", "1d 3h 12m"
+ */
+export declare function formatUptime(seconds: number): string;
+/**
+ * Format a duration in milliseconds to a human-readable string.
+ * Examples: "0s", "0.3s", "12.3s", "1m 23s", "1h 2m 3s"
+ */
+export declare function formatDuration(ms: number): string;
+//# sourceMappingURL=format-duration.d.ts.map

package/dist/format-duration.js

@@ -0,0 +1,32 @@
+import "./chunk-gOLHoazu.js";
+//#region src/format-duration.ts
+/**
+* Format seconds into human-readable uptime.
+* Examples: "45s", "3m 12s", "2h 15m", "1d 3h 12m"
+*/
+function formatUptime(seconds) {
+	if (seconds < 60) return `${seconds}s`;
+	if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+	const hours = Math.floor(seconds / 3600);
+	const mins = Math.floor(seconds % 3600 / 60);
+	if (hours < 24) return `${hours}h ${mins}m`;
+	return `${Math.floor(hours / 24)}d ${hours % 24}h ${mins}m`;
+}
+/**
+* Format a duration in milliseconds to a human-readable string.
+* Examples: "0s", "0.3s", "12.3s", "1m 23s", "1h 2m 3s"
+*/
+function formatDuration(ms) {
+	if (ms < 0) return "0s";
+	const totalSeconds = ms / 1e3;
+	if (totalSeconds < 60) return `${totalSeconds.toFixed(1)}s`;
+	const hours = Math.floor(totalSeconds / 3600);
+	const minutes = Math.floor(totalSeconds % 3600 / 60);
+	const seconds = Math.floor(totalSeconds % 60);
+	if (hours > 0) return `${hours}h ${minutes}m ${seconds}s`;
+	return `${minutes}m ${seconds}s`;
+}
+//#endregion
+export { formatDuration, formatUptime };
+
+//# sourceMappingURL=format-duration.js.map

package/dist/format-duration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=format-duration.test.d.ts.map

package/dist/graceful-shutdown.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A single teardown step in the graceful shutdown sequence.
+ */
+export interface ShutdownStep {
+    /** Human-readable name logged before/after execution. */
+    name: string;
+    /** Teardown function. Runs sequentially; errors are caught per-step. */
+    fn: () => Promise<void> | void;
+}
+/**
+ * Logger interface accepted by {@link setupGracefulShutdown}.
+ * Compatible with Winston and any logger that exposes `info`, `warn`, and `error`
+ * with a structured-metadata second argument.
+ */
+export interface ShutdownLogger {
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+export interface GracefulShutdownOptions {
+    /** Logger used for all shutdown messages. */
+    logger: ShutdownLogger;
+    /** Ordered list of teardown steps executed sequentially. */
+    steps: ShutdownStep[];
+    /** Force-exit timeout in milliseconds (default: 30 000). */
+    timeoutMs?: number;
+    /**
+     * Optional callback invoked when the force-exit timeout fires.
+     * If the callback returns `true`, the default `process.exit(1)` is
+     * suppressed — the callback is responsible for exiting the process.
+     * Use this for last-resort cleanup (e.g., killing child processes
+     * and deferring exit to let abort handlers run).
+     */
+    onForceExit?: () => boolean | void;
+    /**
+     * If `true`, `uncaughtException` and `unhandledRejection` handlers
+     * are NOT registered. Useful when the caller manages those separately.
+     * Default: `false` (handlers are registered).
+     */
+    skipErrorHandlers?: boolean;
+}
+/**
+ * Return value from {@link setupGracefulShutdown} so callers can
+ * trigger shutdown programmatically (e.g., from SIGUSR1 drain handlers).
+ */
+export interface ShutdownHandle {
+    /** Trigger shutdown with the given reason string. */
+    shutdown(signal: string): Promise<void>;
+}
+/**
+ * Wire up SIGTERM / SIGINT (and optionally uncaughtException /
+ * unhandledRejection) handlers that execute the provided teardown
+ * steps sequentially, then `process.exit(0)`.
+ *
+ * A force-exit timer ensures the process terminates even if a step hangs.
+ */
+export declare function setupGracefulShutdown(options: GracefulShutdownOptions): ShutdownHandle;
+//# sourceMappingURL=graceful-shutdown.d.ts.map

package/dist/graceful-shutdown.js

@@ -0,0 +1,71 @@
+import "./chunk-gOLHoazu.js";
+import { toErrorMessage } from "./error.js";
+//#region src/graceful-shutdown.ts
+/**
+* Wire up SIGTERM / SIGINT (and optionally uncaughtException /
+* unhandledRejection) handlers that execute the provided teardown
+* steps sequentially, then `process.exit(0)`.
+*
+* A force-exit timer ensures the process terminates even if a step hangs.
+*/
+function setupGracefulShutdown(options) {
+	const { logger, steps, timeoutMs = 3e4, onForceExit, skipErrorHandlers = false } = options;
+	let isShuttingDown = false;
+	async function gracefulShutdown(signal) {
+		if (isShuttingDown) {
+			logger.warn("Shutdown already in progress, ignoring signal", { signal });
+			return;
+		}
+		isShuttingDown = true;
+		logger.info(`Received ${signal}, starting graceful shutdown...`);
+		const forceExitTimeout = setTimeout(() => {
+			logger.error(`Graceful shutdown timed out after ${timeoutMs / 1e3}s, forcing exit`);
+			if (onForceExit?.() !== true) process.exit(1);
+		}, timeoutMs);
+		try {
+			for (const step of steps) try {
+				logger.info(`${step.name}...`);
+				await step.fn();
+				logger.info(`${step.name} done`);
+			} catch (stepError) {
+				logger.error(`${step.name} failed`, {
+					error: toErrorMessage(stepError),
+					stack: stepError instanceof Error ? stepError.stack : void 0
+				});
+			}
+			clearTimeout(forceExitTimeout);
+			logger.info("Graceful shutdown complete");
+			process.exit(0);
+		} catch (error) {
+			logger.error("Error during graceful shutdown", {
+				error: toErrorMessage(error),
+				stack: error instanceof Error ? error.stack : void 0
+			});
+			clearTimeout(forceExitTimeout);
+			process.exit(1);
+		}
+	}
+	process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
+	process.on("SIGINT", () => gracefulShutdown("SIGINT"));
+	if (!skipErrorHandlers) {
+		process.on("uncaughtException", (error) => {
+			logger.error("Uncaught exception", {
+				error: error.message,
+				stack: error.stack
+			});
+			gracefulShutdown("uncaughtException");
+		});
+		process.on("unhandledRejection", (reason) => {
+			logger.error("Unhandled rejection", {
+				reason: toErrorMessage(reason),
+				stack: reason instanceof Error ? reason.stack : void 0
+			});
+			gracefulShutdown("unhandledRejection");
+		});
+	}
+	return { shutdown: gracefulShutdown };
+}
+//#endregion
+export { setupGracefulShutdown };
+
+//# sourceMappingURL=graceful-shutdown.js.map

package/dist/graceful-shutdown.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=graceful-shutdown.test.d.ts.map

package/dist/idempotency-files.d.ts

@@ -0,0 +1,113 @@
+/**
+ * File-drift preview primitive for idempotent steps that copy or rsync
+ * files to a remote target. Companion to `idempotency.ts`: a `check()`
+ * that ships files can call into the helper layer (e.g. `previewRsync*`
+ * in `packages/ci/src/deploy-prod/remote.ts`) to get a typed list of
+ * per-file changes, then surface those entries inside the step's drift
+ * value so the confirm prompt shows the operator exactly which files
+ * would change and how.
+ *
+ * The source of truth for the categorisation is rsync's own
+ * `--itemize-changes` (`-i`) output, captured under `--dry-run` (`-n`).
+ * Running rsync with the same flags the apply path uses guarantees the
+ * preview and the actual transfer agree.
+ *
+ * The itemize code rsync prints is 11 characters: `YXcstpoguax`.
+ *   Y = update type (`<` sent, `>` received, `.` no transfer, `*` message, `c`/`h`)
+ *   X = file type (`f` file, `d` directory, `L` symlink, …)
+ *   c = checksum mismatch (or `+` block when newly created)
+ *   s = size mismatch
+ *   t = mtime mismatch
+ *   p = perms mismatch
+ *   o = owner mismatch
+ *   g = group mismatch
+ *   u = (sub-second) mtime mismatch
+ *   a = ACL mismatch
+ *   x = xattr mismatch
+ * Newly-created files render as `<f+++++++++` (or `cf+++++++++` for local
+ * creates). See `rsync(1)` § "ITEMIZED OUTPUT".
+ */
+export type FileChangeCategory = 'new' | 'content' | 'mode' | 'time-only';
+export type ContentSkipReason = 'binary' | 'too-large' | 'read-failed' | 'sensitive';
+/**
+ * Per-file drift entry as carried inside a phase's Drift value.
+ * `localPath` and `remotePath` are filled in by the caller that owns the
+ * rsync invocation (the parser only sees the relative path rsync prints).
+ *
+ * `localContent` / `remoteContent` are populated by the caller when the
+ * payload is small UTF-8 text — they drive the inline unified-diff block
+ * in the confirm prompt. `contentSkipped` flags the cases where content
+ * was intentionally not captured (binary, too large, read failure) so
+ * the renderer can show an explicit "no diff available" row instead of
+ * silently dropping the entry.
+ */
+export interface FileDriftEntry {
+    localPath: string;
+    remotePath: string;
+    category: FileChangeCategory;
+    /** Raw 11-char rsync itemize code, kept for `--debug`-style operator output. */
+    itemizeCode: string;
+    /** Local file bytes (UTF-8). Set for category `new` / `content` when content was successfully captured. */
+    localContent?: string;
+    /** Remote file bytes (UTF-8). Set for category `content` when content was successfully captured. Undefined for `new`. */
+    remoteContent?: string;
+    /** Set when content capture was intentionally skipped — used by the renderer to explain the gap. */
+    contentSkipped?: ContentSkipReason;
+}
+/** Low-level parse output: category + the relative path rsync printed. */
+export interface ItemizeRecord {
+    itemizeCode: string;
+    relativePath: string;
+    category: FileChangeCategory;
+}
+/**
+ * Parse one line of `rsync --itemize-changes` output. Returns null for
+ * lines that are not actionable file drift entries:
+ *   - "sending incremental file list" header line
+ *   - blank / whitespace-only lines
+ *   - summary lines ("sent N bytes received M bytes …", "total size is X")
+ *   - directory metadata entries (e.g. `.d..t...... ./`) — directories
+ *     are created by rsync as a side-effect of file entries, no separate
+ *     reporting needed
+ *   - in-sync entries (rsync emits these only at -vv; we run at -v, so
+ *     they normally don't appear — but we filter defensively)
+ */
+export declare function parseItemizeLine(line: string): ItemizeRecord | null;
+export interface RenderDriftOpts {
+    /** When true, append a unified-diff block under each `new`/`content` entry. */
+    withContent?: boolean;
+    /** When true, color the diff with ANSI red/green via picocolors. */
+    color?: boolean;
+    /** Cap on diff body lines per entry (excluding header). Default 200. */
+    maxLines?: number;
+}
+/**
+ * Render the unified-diff block for a single FileDriftEntry. Returns an
+ * array of pre-indented lines (no surrounding indent applied by this
+ * function — the caller decides nesting). The first line is the diff
+ * header (`--- a/path` / `+++ b/path`), followed by hunk bodies.
+ *
+ * `mode` and `time-only` entries return an empty array — no diff to show.
+ * Entries with `contentSkipped` set return a single line explaining the
+ * skip reason. Entries with no content captured (older callers that
+ * didn't fill the fields) also return empty — the caller falls back to
+ * the label-only row.
+ */
+export declare function renderFileDriftWithDiff(entry: FileDriftEntry, opts?: Pick<RenderDriftOpts, 'color' | 'maxLines'>): string[];
+/**
+ * Render a FileDriftEntry[] as an aligned multi-line block suitable for
+ * inclusion in a confirm-prompt summary.
+ *
+ *   3 file(s) drifted: 1 new, 1 content, 1 mode
+ *     NEW      placeholder.html
+ *     CONTENT  haproxy.cfg
+ *     MODE     scripts/certbot-pre-stop.sh
+ *
+ * When `opts.withContent` is true, each `new`/`content` row is followed
+ * by an indented unified-diff block (colored if `opts.color`).
+ *
+ * Returns the rendered lines (no surrounding indent applied). Caller
+ * decides how to nest the block in a wider prompt.
+ */
+export declare function renderFileDrifts(entries: FileDriftEntry[], opts?: RenderDriftOpts): string[];
+//# sourceMappingURL=idempotency-files.d.ts.map