@kici-dev/shared 0.1.3 → 0.1.6

package/dist/logger.js

@@ -17,9 +17,10 @@ let _serviceName;
 */
 const _pendingFileTransportLoggers = /* @__PURE__ */ new Set();
 function buildFileTransport() {
-	if (!process.env.KICI_LOG_DIR) return void 0;
+	const dir = process.env.KICI_LOG_DIR;
+	if (!dir || dir === "undefined") return void 0;
 	return new DailyRotateFile({
-		dirname: process.env.KICI_LOG_DIR,
+		dirname: dir,
 		filename: buildLogFilename(_serviceName),
 		datePattern: "YYYY-MM-DD",
 		maxSize: process.env.KICI_LOG_MAX_SIZE ?? "500m",
@@ -66,13 +67,26 @@ function buildLogFilename(serviceName) {
 	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 = !process.stdout.isTTY, level = "info", prefix } = 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_***");
@@ -103,13 +117,10 @@ function createLogger(options = {}) {
 		if (ctx.spanId) info["spanId"] = ctx.spanId;
 		return info;
 	});
-	const prettyFormat = winston.format.printf(({ level, message, timestamp, requestId }) => {
-		const time = new Date(timestamp).toLocaleTimeString("en-US", {
-			hour12: false,
-			hour: "2-digit",
-			minute: "2-digit",
-			second: "2-digit"
-		});
+	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":
@@ -118,20 +129,15 @@ function createLogger(options = {}) {
 			case "warn":
 				coloredLevel = pc.yellow(level);
 				break;
-			case "info":
-				coloredLevel = pc.cyan(level);
-				break;
 			case "debug":
 				coloredLevel = pc.gray(level);
 				break;
 			default: coloredLevel = level;
 		}
-		const traceStr = typeof requestId === "string" ? ` ${pc.dim(`[${requestId.slice(0, 8)}]`)}` : "";
-		const prefixStr = prefix ? `${prefix} ` : "";
-		return `${pc.dim(`[${time}]`)}${traceStr} ${coloredLevel}: ${prefixStr}${message}`;
+		return `${traceStr}${coloredLevel}: ${prefixStr}${message}`;
 	});
 	const jsonFormat = winston.format.combine(winston.format.timestamp(), traceContextFormat(), tokenMaskFormat(), winston.format.json());
-	const prettyPipeline = winston.format.combine(winston.format.timestamp(), traceContextFormat(), tokenMaskFormat(), prettyFormat);
+	const prettyPipeline = winston.format.combine(traceContextFormat(), tokenMaskFormat(), prettyFormat);
 	const loggerInstance = winston.createLogger({
 		level,
 		format: json ? jsonFormat : prettyPipeline,

package/dist/telemetry/index.d.ts

@@ -1,3 +1,3 @@
-export { initTelemetry, getPrometheusExporter, type TelemetryConfig } from './init.js';
+export { initTelemetry, getPrometheusExporter, collectRuntimeMetricNames, type TelemetryConfig, } from './init.js';
 export { createMeter } from './metrics.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.js

@@ -1,4 +1,4 @@
 import "../chunk-gOLHoazu.js";
-import { getPrometheusExporter, initTelemetry } from "./init.js";
+import { collectRuntimeMetricNames, getPrometheusExporter, initTelemetry } from "./init.js";
 import { createMeter } from "./metrics.js";
-export { createMeter, getPrometheusExporter, initTelemetry };
+export { collectRuntimeMetricNames, createMeter, getPrometheusExporter, initTelemetry };

package/dist/telemetry/init.d.ts

@@ -17,4 +17,14 @@ export interface TelemetryConfig {
 export declare function initTelemetry(config: TelemetryConfig): NodeSDK;
 /** Get the PrometheusExporter instance created by initTelemetry(). */
 export declare function getPrometheusExporter(): PrometheusExporter | undefined;
+/**
+ * Boot `RuntimeNodeInstrumentation` standalone, exercise the event loop and
+ * garbage collector, collect once, and return the set of dotted instrument
+ * names it emitted. This is the ground truth for the curated runtime-metrics
+ * catalog drift guard (`scripts/generate-prometheus.ts`). It deliberately
+ * does NOT touch the singleton `_prometheusExporter` — it spins up an
+ * isolated SDK so it can be called from tooling without affecting a running
+ * service's telemetry.
+ */
+export declare function collectRuntimeMetricNames(): Promise<string[]>;
 //# sourceMappingURL=init.d.ts.map

package/dist/telemetry/init.js

@@ -36,7 +36,38 @@ function initTelemetry(config) {
 function getPrometheusExporter() {
 	return _prometheusExporter;
 }
+/**
+* Boot `RuntimeNodeInstrumentation` standalone, exercise the event loop and
+* garbage collector, collect once, and return the set of dotted instrument
+* names it emitted. This is the ground truth for the curated runtime-metrics
+* catalog drift guard (`scripts/generate-prometheus.ts`). It deliberately
+* does NOT touch the singleton `_prometheusExporter` — it spins up an
+* isolated SDK so it can be called from tooling without affecting a running
+* service's telemetry.
+*/
+async function collectRuntimeMetricNames() {
+	const exporter = new PrometheusExporter({ preventServerStart: true });
+	const sdk = new NodeSDK({
+		resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: "runtime-metrics-drift-guard" }),
+		metricReader: exporter,
+		instrumentations: [new RuntimeNodeInstrumentation({ monitoringPrecision: 100 })]
+	});
+	sdk.start();
+	for (let round = 0; round < 5; round++) {
+		const junk = [];
+		for (let i = 0; i < 100; i++) junk.push(new Array(1e4).fill(i));
+		junk.length;
+		await new Promise((r) => setTimeout(r, 300));
+	}
+	if (typeof global.gc === "function") global.gc();
+	await new Promise((r) => setTimeout(r, 500));
+	const names = /* @__PURE__ */ new Set();
+	const { resourceMetrics } = await exporter.collect();
+	for (const scopeMetrics of resourceMetrics.scopeMetrics) for (const metric of scopeMetrics.metrics) names.add(metric.descriptor.name);
+	await sdk.shutdown();
+	return [...names].sort();
+}
 //#endregion
-export { getPrometheusExporter, initTelemetry };
+export { collectRuntimeMetricNames, getPrometheusExporter, initTelemetry };
 
 //# sourceMappingURL=init.js.map

package/dist/tool-check.js

@@ -1,6 +1,6 @@
 import "./chunk-gOLHoazu.js";
-import { execFileSync } from "node:child_process";
 import { accessSync, constants } from "node:fs";
+import { delimiter, join } from "node:path";
 //#region src/tool-check.ts
 /**
 * Startup validation for required external tools and binaries.
@@ -40,19 +40,39 @@ function validateRequiredTools(requirements) {
 }
 /**
 * Check if a binary is available on PATH.
-* Uses `where` on Windows, `which` on Unix.
+*
+* Walks the directories in `process.env.PATH` and tests each candidate via
+* `accessSync(..., X_OK)`. Pure-Node implementation — no `which` / `where`
+* dependency, so the check works on minimal base images (Docker Hardened
+* Images, distroless, alpine variants) that strip the `which` binary even
+* when `debianutils` is technically installed.
+*
+* Windows: tries `name` + `name.exe`/`.cmd`/`.bat`/`.com` extensions (mirrors
+* PATHEXT defaults) so `git` resolves to `git.exe` without the caller having
+* to pre-suffix.
 */
 function isBinaryOnPath(name) {
-	const cmd = process.platform === "win32" ? "where" : "which";
-	try {
-		execFileSync(cmd, [name], {
-			stdio: "pipe",
-			timeout: 5e3
-		});
-		return true;
-	} catch {
-		return false;
+	const pathEnv = process.env.PATH;
+	if (!pathEnv) return false;
+	const dirs = pathEnv.split(delimiter);
+	const exts = process.platform === "win32" ? [
+		"",
+		".exe",
+		".cmd",
+		".bat",
+		".com"
+	] : [""];
+	for (const dir of dirs) {
+		if (!dir) continue;
+		for (const ext of exts) {
+			const candidate = join(dir, name + ext);
+			try {
+				accessSync(candidate, constants.X_OK);
+				return true;
+			} catch {}
+		}
 	}
+	return false;
 }
 //#endregion
 export { validateRequiredTools };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/shared",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "Shared utilities for the KiCI CI/CD stack — logging, zx setup, crypto, telemetry, health and metrics routes. No business logic.",
   "keywords": [
     "kici",
@@ -53,6 +53,18 @@
     "./idempotency-files": {
       "import": "./dist/idempotency-files.js",
       "types": "./dist/idempotency-files.d.ts"
+    },
+    "./idempotency-env-diff": {
+      "import": "./dist/idempotency-env-diff.js",
+      "types": "./dist/idempotency-env-diff.d.ts"
+    },
+    "./idempotency-yaml-diff": {
+      "import": "./dist/idempotency-yaml-diff.js",
+      "types": "./dist/idempotency-yaml-diff.d.ts"
+    },
+    "./db-collation": {
+      "import": "./dist/db-collation.js",
+      "types": "./dist/db-collation.d.ts"
     }
   },
   "dependencies": {
@@ -73,6 +85,7 @@
     "picocolors": "^1.1.1",
     "winston": "^3.19.0",
     "winston-daily-rotate-file": "^5.0.0",
+    "yaml": "^2.8.3",
     "zod": "^4.3.6",
     "zx": "^8.8.5"
   },

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@kici-dev/shared@0.1.3",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fshared/0.1.3/166084de-5305-4703-8b1b-51cc4b1cd5b8",
+  "name": "@kici-dev/shared@0.1.6",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fshared/0.1.6/04b549ae-92dc-4b0c-b014-f325f8eb99d0",
   "creationInfo": {
-    "created": "2026-05-15T14:16:47Z",
+    "created": "2026-05-26T05:00:00Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -947,7 +947,7 @@
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/shared",
-      "versionInfo": "0.1.3",
+      "versionInfo": "0.1.6",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -958,7 +958,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/shared@0.1.3"
+          "referenceLocator": "pkg:npm/%40kici-dev/shared@0.1.6"
         }
       ],
       "description": "Shared utilities for the KiCI CI/CD stack — logging, zx setup, crypto, telemetry, health and metrics routes. No business logic.",
@@ -6506,6 +6506,11 @@
       "relatedSpdxElement": "SPDXRef-Package-winston-3.19.0",
       "relationshipType": "DEPENDS_ON"
     },
+    {
+      "spdxElementId": "SPDXRef-RootPackage",
+      "relatedSpdxElement": "SPDXRef-Package-yaml-2.8.3",
+      "relationshipType": "DEPENDS_ON"
+    },
     {
       "spdxElementId": "SPDXRef-RootPackage",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.3.6",