@kici-dev/shared 0.1.13 → 0.1.14

package/dist/logger.js

@@ -1,181 +0,0 @@
-import "./chunk-gOLHoazu.js";
-import { toErrorMessage } from "./error.js";
-import { getRequestContext } from "./request-context.js";
-import winston from "winston";
-import pc from "picocolors";
-import DailyRotateFile from "winston-daily-rotate-file";
-//#region src/logger.ts
-let _serviceName;
-/**
-* Tracked set of loggers still waiting for the service name so they can
-* add their rotated-file transport with the right filename. Module-level
-* `createLogger()` calls resolve before the service's `setServiceName()`
-* runs; if we built the file transport eagerly, every such logger would
-* write to `kici-<instanceId>-*.log` (undefined service name) instead of
-* `<service>-<instanceId>-*.log`. Holding them here lets setServiceName
-* attach the correct transport once, in one place.
-*/
-const _pendingFileTransportLoggers = /* @__PURE__ */ new Set();
-function buildFileTransport() {
-	const dir = process.env.KICI_LOG_DIR;
-	if (!dir || dir === "undefined") return void 0;
-	return new DailyRotateFile({
-		dirname: dir,
-		filename: buildLogFilename(_serviceName),
-		datePattern: "YYYY-MM-DD",
-		maxSize: process.env.KICI_LOG_MAX_SIZE ?? "500m",
-		maxFiles: `${process.env.KICI_LOG_RETENTION_DAYS ?? "7"}d`,
-		format: winston.format.combine(winston.format.timestamp(), winston.format((info) => {
-			if (_serviceName) info["service"] = _serviceName;
-			const ctx = getRequestContext();
-			if (ctx.requestId) info["requestId"] = ctx.requestId;
-			if (ctx.runId) info["runId"] = ctx.runId;
-			if (ctx.jobId) info["jobId"] = ctx.jobId;
-			if (ctx.routingKey) info["routingKey"] = ctx.routingKey;
-			if (ctx.traceId) info["traceId"] = ctx.traceId;
-			if (ctx.spanId) info["spanId"] = ctx.spanId;
-			return info;
-		})(), winston.format.json()),
-		zippedArchive: true
-	});
-}
-/** Set the service name for all loggers in this process. Call once at startup. */
-function setServiceName(name) {
-	_serviceName = name;
-	for (const logger of _pendingFileTransportLoggers) {
-		const transport = buildFileTransport();
-		if (transport) logger.add(transport);
-	}
-	_pendingFileTransportLoggers.clear();
-}
-/** Get the current service name (for testing/inspection). */
-function getServiceName() {
-	return _serviceName;
-}
-/**
-* Build the rotated log filename. When a stable instance ID is available in the
-* environment, append it so multiple processes (e.g. several orchestrators or
-* agents) can safely share one KICI_LOG_DIR without racing on the same file.
-*
-* Precedence matches the tier that owns each variable:
-* orchestrator (KICI_CLUSTER_INSTANCE_ID) > agent (KICI_AGENT_ID) > platform
-* (KICI_PLATFORM_INSTANCE_ID). Sanitize defensively to filesystem-safe characters.
-*/
-function buildLogFilename(serviceName) {
-	const base = serviceName ?? "kici";
-	const suffix = (process.env.KICI_CLUSTER_INSTANCE_ID || process.env.KICI_AGENT_ID || process.env.KICI_PLATFORM_INSTANCE_ID || "").replace(/[^A-Za-z0-9_.-]+/g, "_");
-	return suffix ? `${base}-${suffix}-%DATE%.log` : `${base}-%DATE%.log`;
-}
-/**
-* Pick the default JSON-vs-plain selection for `createLogger` callers that do
-* not pass an explicit `json` option. Honours the operator-controlled
-* `KICI_LOG_FORMAT` env var (`json` / `plain` / `auto`); anything else
-* (including typos and unset) falls back to TTY detection so a piped CLI
-* still produces machine-readable JSON.
-*/
-function pickJsonDefault() {
-	const envFormat = process.env.KICI_LOG_FORMAT;
-	if (envFormat === "json") return true;
-	if (envFormat === "plain") return false;
-	return !process.stdout.isTTY;
-}
-/**
-* Create a winston logger instance.
-*
-* @param options - Logger configuration options
-* @returns Configured winston logger
-*/
-function createLogger(options = {}) {
-	const { json = pickJsonDefault(), level = "info", prefix } = options;
-	const TOKEN_MASK_RE = /kat_[0-9a-f]{64}/gi;
-	const maskTokens = (value) => {
-		if (typeof value === "string") return value.replace(TOKEN_MASK_RE, "kat_***");
-		if (Array.isArray(value)) return value.map(maskTokens);
-		if (value !== null && typeof value === "object") {
-			const masked = {};
-			for (const [k, v] of Object.entries(value)) masked[k] = maskTokens(v);
-			return masked;
-		}
-		return value;
-	};
-	const tokenMaskFormat = winston.format((info) => {
-		if (typeof info.message === "string") info.message = info.message.replace(TOKEN_MASK_RE, "kat_***");
-		for (const key of Object.keys(info)) {
-			if (key === "level" || key === "message") continue;
-			info[key] = maskTokens(info[key]);
-		}
-		return info;
-	});
-	const traceContextFormat = winston.format((info) => {
-		if (_serviceName) info["service"] = _serviceName;
-		const ctx = getRequestContext();
-		if (ctx.requestId) info["requestId"] = ctx.requestId;
-		if (ctx.runId) info["runId"] = ctx.runId;
-		if (ctx.jobId) info["jobId"] = ctx.jobId;
-		if (ctx.routingKey) info["routingKey"] = ctx.routingKey;
-		if (ctx.traceId) info["traceId"] = ctx.traceId;
-		if (ctx.spanId) info["spanId"] = ctx.spanId;
-		return info;
-	});
-	const prettyFormat = winston.format.printf(({ level, message, requestId }) => {
-		const traceStr = typeof requestId === "string" ? `${pc.dim(`[${requestId.slice(0, 8)}]`)} ` : "";
-		const prefixStr = prefix ? `${prefix} ` : "";
-		if (level === "info") return `${traceStr}${prefixStr}${message}`;
-		let coloredLevel;
-		switch (level) {
-			case "error":
-				coloredLevel = pc.red(level);
-				break;
-			case "warn":
-				coloredLevel = pc.yellow(level);
-				break;
-			case "debug":
-				coloredLevel = pc.gray(level);
-				break;
-			default: coloredLevel = level;
-		}
-		return `${traceStr}${coloredLevel}: ${prefixStr}${message}`;
-	});
-	const jsonFormat = winston.format.combine(winston.format.timestamp(), traceContextFormat(), tokenMaskFormat(), winston.format.json());
-	const prettyPipeline = winston.format.combine(traceContextFormat(), tokenMaskFormat(), prettyFormat);
-	const loggerInstance = winston.createLogger({
-		level,
-		format: json ? jsonFormat : prettyPipeline,
-		transports: [new winston.transports.Console()]
-	});
-	if (process.env.KICI_LOG_DIR) if (_serviceName) {
-		const transport = buildFileTransport();
-		if (transport) loggerInstance.add(transport);
-	} else _pendingFileTransportLoggers.add(loggerInstance);
-	return loggerInstance;
-}
-/**
-* Default singleton logger instance for simple use cases. If KICI_LOG_DIR is
-* set but setServiceName() hasn't been called yet (CLI tools, scripts),
-* the file transport stays deferred and is attached only once a service
-* name is known — protecting against writing to `kici-<instanceId>-*.log`.
-*/
-const logger = createLogger();
-/**
-* Wrap an async startup function so that any thrown error is logged
-* through the structured (JSON-aware) logger before the process exits.
-*
-* Without this guard, a top-level `await` rejection in an ESM entry
-* point is printed by Node.js's default handler (multi-line, not JSON),
-* which breaks log aggregators like ELK.
-*/
-async function guardStartup(log, fn) {
-	try {
-		await fn();
-	} catch (error) {
-		log.error("Fatal startup error", {
-			error: toErrorMessage(error),
-			stack: error instanceof Error ? error.stack : void 0
-		});
-		process.exit(1);
-	}
-}
-//#endregion
-export { buildLogFilename, createLogger, getServiceName, guardStartup, logger, setServiceName };
-
-//# sourceMappingURL=logger.js.map

package/dist/logger.test.d.ts

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

package/dist/package-manager.test.d.ts

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

package/dist/request-context.d.ts

@@ -1,42 +0,0 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-/** Trace context fields propagated through the request lifecycle. */
-export interface RequestContext {
-    /** Unique trace ID for a webhook event (UUIDv4). Always present once set. */
-    requestId: string;
-    /** Workflow run ID, set when a workflow run is created. */
-    runId?: string;
-    /** Job ID, set when processing a specific job. */
-    jobId?: string;
-    /** Routing key (e.g. "github:12345"), set when handling a webhook for a source. */
-    routingKey?: string;
-    /** OTel trace ID, set when telemetry is active. */
-    traceId?: string;
-    /** OTel span ID, set when telemetry is active. */
-    spanId?: string;
-}
-/**
- * AsyncLocalStorage instance for propagating request context
- * through async call chains without explicit parameter passing.
- *
- * Usage:
- * ```ts
- * requestContext.run({ requestId: crypto.randomUUID() }, async () => {
- *   // All code in this callback (and its async descendants) can read the context
- *   log.info('Processing webhook'); // auto-enriched with requestId
- * });
- * ```
- */
-export declare const requestContext: AsyncLocalStorage<RequestContext>;
-/**
- * Get the current request context, or an empty object if outside a `run()` scope.
- * Safe to call anywhere -- never throws.
- */
-export declare function getRequestContext(): Partial<RequestContext>;
-/**
- * Merge additional fields into the current request context.
- * No-op if called outside a `run()` scope.
- *
- * @param fields - Partial context fields to merge into the current store
- */
-export declare function enrichRequestContext(fields: Partial<RequestContext>): void;
-//# sourceMappingURL=request-context.d.ts.map

package/dist/request-context.js

@@ -1,37 +0,0 @@
-import "./chunk-gOLHoazu.js";
-import { AsyncLocalStorage } from "node:async_hooks";
-//#region src/request-context.ts
-/**
-* AsyncLocalStorage instance for propagating request context
-* through async call chains without explicit parameter passing.
-*
-* Usage:
-* ```ts
-* requestContext.run({ requestId: crypto.randomUUID() }, async () => {
-*   // All code in this callback (and its async descendants) can read the context
-*   log.info('Processing webhook'); // auto-enriched with requestId
-* });
-* ```
-*/
-const requestContext = new AsyncLocalStorage();
-/**
-* Get the current request context, or an empty object if outside a `run()` scope.
-* Safe to call anywhere -- never throws.
-*/
-function getRequestContext() {
-	return requestContext.getStore() ?? {};
-}
-/**
-* Merge additional fields into the current request context.
-* No-op if called outside a `run()` scope.
-*
-* @param fields - Partial context fields to merge into the current store
-*/
-function enrichRequestContext(fields) {
-	const store = requestContext.getStore();
-	if (store) Object.assign(store, fields);
-}
-//#endregion
-export { enrichRequestContext, getRequestContext, requestContext };
-
-//# sourceMappingURL=request-context.js.map

package/dist/zx.d.ts

@@ -1,8 +0,0 @@
-/**
- * Initialize zx for cross-platform execution.
- * Sets the quote function required by zx 8+ on all platforms.
- * On Windows, also configures pwsh as shell.
- * Call this at the start of any script/binary entry point using zx.
- */
-export declare function initZx(): void;
-//# sourceMappingURL=zx.d.ts.map

package/dist/zx.js

@@ -1,78 +0,0 @@
-import "./chunk-gOLHoazu.js";
-import { execSync } from "node:child_process";
-import { $, quote, quotePowerShell, usePwsh } from "zx";
-//#region src/zx.ts
-const PWSH_INSTALL_DOCS = "https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell-on-windows";
-/**
-* Initialize zx for cross-platform execution.
-* Sets the quote function required by zx 8+ on all platforms.
-* On Windows, also configures pwsh as shell.
-* Call this at the start of any script/binary entry point using zx.
-*/
-function initZx() {
-	if (process.platform === "win32") {
-		try {
-			usePwsh();
-		} catch {
-			ensurePwshWindows();
-			usePwsh();
-		}
-		$.quote = quotePowerShell;
-	} else $.quote = quote;
-}
-/**
-* Ensure PowerShell Core (pwsh) is installed on Windows.
-* Attempts automatic installation via winget using the built-in powershell.exe.
-* If winget is unavailable, prints installation instructions and exits.
-*/
-function ensurePwshWindows() {
-	console.error("PowerShell Core (pwsh) is required but not found in PATH.\nKiCI uses pwsh for cross-platform command execution.\n");
-	let hasWinget = false;
-	try {
-		execSync("powershell.exe -NoProfile -Command \"Get-Command winget -ErrorAction Stop\"", {
-			stdio: "ignore",
-			timeout: 1e4
-		});
-		hasWinget = true;
-	} catch {}
-	if (!hasWinget) {
-		console.error(`Automatic installation is not possible (winget not found).
-Please install PowerShell Core manually:
-  ${PWSH_INSTALL_DOCS}\n`);
-		process.exit(1);
-	}
-	console.error("Attempting to install PowerShell Core via winget...\n");
-	try {
-		execSync("powershell.exe -NoProfile -Command \"winget install --id Microsoft.PowerShell --accept-source-agreements --accept-package-agreements -e --silent\"", {
-			stdio: "inherit",
-			timeout: 3e5
-		});
-	} catch {
-		console.error(`
-Automatic installation failed.
-Please install PowerShell Core manually:
-  ${PWSH_INSTALL_DOCS}\n`);
-		process.exit(1);
-	}
-	try {
-		const pwshPath = execSync("powershell.exe -NoProfile -Command \"(Get-Command pwsh -ErrorAction Stop).Source\"", {
-			encoding: "utf-8",
-			timeout: 1e4
-		}).trim();
-		if (pwshPath) {
-			const pwshDir = pwshPath.replace(/\\pwsh\.exe$/i, "");
-			process.env.PATH = `${pwshDir};${process.env.PATH}`;
-		}
-	} catch {
-		console.error(`
-PowerShell Core was installed but cannot be found in PATH.
-Please restart your terminal or add pwsh to PATH manually.
-See: ${PWSH_INSTALL_DOCS}\n`);
-		process.exit(1);
-	}
-	console.error("PowerShell Core installed successfully.\n");
-}
-//#endregion
-export { initZx };
-
-//# sourceMappingURL=zx.js.map