@kici-dev/shared 0.1.12 → 0.1.14

package/dist/ts-loader-hook.js

@@ -1,48 +1,3 @@
 import "./chunk-gOLHoazu.js";
-import { readFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { transformSync } from "oxc-transform";
-//#region src/ts-loader-hook.ts
-function resolve(specifier, context, nextResolve) {
-	if (specifier.endsWith(".js") && (specifier.startsWith("./") || specifier.startsWith("../"))) try {
-		if (context.parentURL) {
-			if (!existsSync(fileURLToPath(new URL(specifier, context.parentURL)))) {
-				const tsSpecifier = specifier.slice(0, -3) + ".ts";
-				if (existsSync(fileURLToPath(new URL(tsSpecifier, context.parentURL)))) return nextResolve(tsSpecifier, context);
-			}
-		}
-	} catch {}
-	return nextResolve(specifier, context);
-}
-async function load(url, context, nextLoad) {
-	if (!url.startsWith("file:")) return nextLoad(url, context);
-	const bareUrl = url.split("?")[0].split("#")[0];
-	const isTs = bareUrl.endsWith(".ts");
-	const isTsx = bareUrl.endsWith(".tsx");
-	if (!isTs && !isTsx) return nextLoad(url, context);
-	const filePath = fileURLToPath(bareUrl);
-	const result = transformSync(filePath, await readFile(filePath, "utf8"), {
-		lang: isTsx ? "tsx" : "ts",
-		sourcemap: true,
-		typescript: { allowNamespaces: true }
-	});
-	if (result.errors.length) {
-		const msg = result.errors.map((e) => e.message).join("\n");
-		throw new Error(`oxc-transform failed for ${filePath}:\n${msg}`);
-	}
-	let code = result.code;
-	if (result.map) {
-		const b64 = Buffer.from(JSON.stringify(result.map)).toString("base64");
-		code += `\n//# sourceMappingURL=data:application/json;base64,${b64}\n`;
-	}
-	return {
-		format: "module",
-		source: code,
-		shortCircuit: true
-	};
-}
-//#endregion
-export { load, resolve };
-
-//# sourceMappingURL=ts-loader-hook.js.map
+export * from "@kici-dev/core/ts-loader-hook";
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/shared",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Shared utilities for the KiCI CI/CD stack — logging, zx setup, crypto, telemetry, health and metrics routes. No business logic.",
   "keywords": [
     "kici",
@@ -95,7 +95,8 @@
     "winston-daily-rotate-file": "^5.0.0",
     "yaml": "^2.8.3",
     "zod": "^4.3.6",
-    "zx": "^8.8.5"
+    "zx": "^8.8.5",
+    "@kici-dev/core": "0.1.14"
   },
   "devDependencies": {
     "@opentelemetry/sdk-trace-base": "^2.7.0",

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.12",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fshared/0.1.12/1172a492-36f2-4dec-92a9-62941a834899",
+  "name": "@kici-dev/shared@0.1.14",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fshared/0.1.14/a35018ec-f363-4930-96e3-4e308475eca8",
   "creationInfo": {
-    "created": "2026-05-27T16:57:23Z",
+    "created": "2026-05-30T03:05:47Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -944,10 +944,30 @@
       "description": "javascript standard data structure library which benchmark against C++ STL",
       "homepage": "https://js-sdsl.org"
     },
+    {
+      "SPDXID": "SPDXRef-Package--kici-dev-core-0.1.14",
+      "name": "@kici-dev/core",
+      "versionInfo": "0.1.14",
+      "downloadLocation": "NOASSERTION",
+      "filesAnalyzed": false,
+      "licenseConcluded": "NOASSERTION",
+      "licenseDeclared": "Apache-2.0",
+      "copyrightText": "NOASSERTION",
+      "supplier": "NOASSERTION",
+      "externalRefs": [
+        {
+          "referenceCategory": "PACKAGE-MANAGER",
+          "referenceType": "purl",
+          "referenceLocator": "pkg:npm/%40kici-dev/core@0.1.14"
+        }
+      ],
+      "description": "Light shared utilities for the KiCI stack (logging, errors, formatting, crypto, zx init, the TypeScript ESM loader hook). No server-side dependencies.",
+      "homepage": "https://kici.dev"
+    },
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/shared",
-      "versionInfo": "0.1.12",
+      "versionInfo": "0.1.14",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -958,7 +978,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/shared@0.1.12"
+          "referenceLocator": "pkg:npm/%40kici-dev/shared@0.1.14"
         }
       ],
       "description": "Shared utilities for the KiCI CI/CD stack — logging, zx setup, crypto, telemetry, health and metrics routes. No business logic.",
@@ -6421,11 +6441,46 @@
       "relatedSpdxElement": "SPDXRef-Package-yargs-17.7.2",
       "relationshipType": "DEPENDS_ON"
     },
+    {
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.14",
+      "relatedSpdxElement": "SPDXRef-Package-oxc-transform-0.128.0",
+      "relationshipType": "DEPENDS_ON"
+    },
+    {
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.14",
+      "relatedSpdxElement": "SPDXRef-Package-picocolors-1.1.1",
+      "relationshipType": "DEPENDS_ON"
+    },
+    {
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.14",
+      "relatedSpdxElement": "SPDXRef-Package-winston-daily-rotate-file-5.0.0",
+      "relationshipType": "DEPENDS_ON"
+    },
+    {
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.14",
+      "relatedSpdxElement": "SPDXRef-Package-winston-3.19.0",
+      "relationshipType": "DEPENDS_ON"
+    },
+    {
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.14",
+      "relatedSpdxElement": "SPDXRef-Package-zod-4.3.6",
+      "relationshipType": "DEPENDS_ON"
+    },
+    {
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.14",
+      "relatedSpdxElement": "SPDXRef-Package-zx-8.8.5",
+      "relationshipType": "DEPENDS_ON"
+    },
     {
       "spdxElementId": "SPDXRef-RootPackage",
       "relatedSpdxElement": "SPDXRef-Package--aws-sdk-client-s3-3.1038.0",
       "relationshipType": "DEPENDS_ON"
     },
+    {
+      "spdxElementId": "SPDXRef-RootPackage",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.14",
+      "relationshipType": "DEPENDS_ON"
+    },
     {
       "spdxElementId": "SPDXRef-RootPackage",
       "relatedSpdxElement": "SPDXRef-Package--opentelemetry-api-1.9.1",

package/dist/crypto.d.ts

@@ -1,33 +0,0 @@
-/** Compute SHA-256 hex digest of a string or Buffer. */
-export declare function sha256(input: string | Buffer): string;
-/** Compute SHA-256 hex digest of a file's contents. */
-export declare function sha256File(filePath: string): Promise<string>;
-/**
- * Normalize line endings to LF so hashes computed on different platforms agree.
- *
- * Git for Windows ships with `core.autocrlf=true` in the system gitconfig, so a
- * `git clone` of a Linux-authored repo on a Windows host checks out text files
- * with CRLF in the working tree. The compiler hashed the LF source on Linux,
- * but the agent on Windows reads CRLF and computes a different hash — every
- * dispatch fails with a "lock file is out of date" error even though the
- * semantic content is identical.
- *
- * Applied at the boundaries where source / asset content enters the hash:
- *   - raw workflow source (`.kici/workflows/*.ts`) at hash time, in both the
- *     compiler (lockfile generation) and the agent (drift verification).
- *   - file content portions of the asset digest (`hashFiles` resolution) on
- *     both sides.
- *
- * Standalone `\r` is also collapsed to `\n` for safety against legacy
- * Mac-style endings, though TypeScript source files essentially never carry
- * those in practice.
- */
-export declare function normalizeLineEndings(input: string): string;
-/**
- * Derive an AES-256 key from an X25519 ECDH shared secret using HKDF.
- *
- * Used by the compiler (encrypt) and agent (decrypt) for tarball uploads.
- * Keys must be DER-encoded (PKCS8 for private, SPKI for public).
- */
-export declare function deriveSharedSecret(ourPrivateKey: Buffer, theirPublicKey: Buffer): Buffer;
-//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.js

@@ -1,67 +0,0 @@
-import "./chunk-gOLHoazu.js";
-import crypto, { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
-//#region src/crypto.ts
-/** Compute SHA-256 hex digest of a string or Buffer. */
-function sha256(input) {
-	return createHash("sha256").update(input).digest("hex");
-}
-/** Compute SHA-256 hex digest of a file's contents. */
-async function sha256File(filePath) {
-	return sha256(await readFile(filePath));
-}
-/**
-* Normalize line endings to LF so hashes computed on different platforms agree.
-*
-* Git for Windows ships with `core.autocrlf=true` in the system gitconfig, so a
-* `git clone` of a Linux-authored repo on a Windows host checks out text files
-* with CRLF in the working tree. The compiler hashed the LF source on Linux,
-* but the agent on Windows reads CRLF and computes a different hash — every
-* dispatch fails with a "lock file is out of date" error even though the
-* semantic content is identical.
-*
-* Applied at the boundaries where source / asset content enters the hash:
-*   - raw workflow source (`.kici/workflows/*.ts`) at hash time, in both the
-*     compiler (lockfile generation) and the agent (drift verification).
-*   - file content portions of the asset digest (`hashFiles` resolution) on
-*     both sides.
-*
-* Standalone `\r` is also collapsed to `\n` for safety against legacy
-* Mac-style endings, though TypeScript source files essentially never carry
-* those in practice.
-*/
-function normalizeLineEndings(input) {
-	return input.replace(/\r\n?/g, "\n");
-}
-/** HKDF info string for ECDH-derived AES keys (upload encryption). */
-const HKDF_INFO = "kici-upload-encryption";
-/** Empty salt — ECDH output is already high entropy. */
-const HKDF_SALT = Buffer.alloc(0);
-/**
-* Derive an AES-256 key from an X25519 ECDH shared secret using HKDF.
-*
-* Used by the compiler (encrypt) and agent (decrypt) for tarball uploads.
-* Keys must be DER-encoded (PKCS8 for private, SPKI for public).
-*/
-function deriveSharedSecret(ourPrivateKey, theirPublicKey) {
-	const ourKeyObj = crypto.createPrivateKey({
-		key: ourPrivateKey,
-		format: "der",
-		type: "pkcs8"
-	});
-	const theirKeyObj = crypto.createPublicKey({
-		key: theirPublicKey,
-		format: "der",
-		type: "spki"
-	});
-	const sharedSecret = crypto.diffieHellman({
-		publicKey: theirKeyObj,
-		privateKey: ourKeyObj
-	});
-	const derivedKey = crypto.hkdfSync("sha256", sharedSecret, HKDF_SALT, HKDF_INFO, 32);
-	return Buffer.from(derivedKey);
-}
-//#endregion
-export { deriveSharedSecret, normalizeLineEndings, sha256, sha256File };
-
-//# sourceMappingURL=crypto.js.map

package/dist/error.d.ts

@@ -1,16 +0,0 @@
-/**
- * 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

@@ -1,58 +0,0 @@
-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

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

package/dist/format-bytes.d.ts

@@ -1,5 +0,0 @@
-/**
- * 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

@@ -1,15 +0,0 @@
-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

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

package/dist/format-duration.d.ts

@@ -1,11 +0,0 @@
-/**
- * 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

@@ -1,32 +0,0 @@
-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

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

package/dist/idempotency.test.d.ts

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

package/dist/logger.d.ts

@@ -1,60 +0,0 @@
-import winston from 'winston';
-/** Set the service name for all loggers in this process. Call once at startup. */
-export declare function setServiceName(name: 'platform' | 'orchestrator' | 'agent'): void;
-/** Get the current service name (for testing/inspection). */
-export declare function getServiceName(): string | undefined;
-/**
- * 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.
- */
-export declare function buildLogFilename(serviceName: string | undefined): string;
-/** Log level type */
-export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
-/** Minimal logger interface for dependency injection (avoids coupling to winston). */
-export interface Logger {
-    info(message: string, meta?: Record<string, unknown>): void;
-    warn(message: string, meta?: Record<string, unknown>): void;
-    error(message: string, meta?: Record<string, unknown>): void;
-}
-/** Logger creation options */
-interface LoggerOptions {
-    /**
-     * Use JSON format (default: auto-detected from KICI_LOG_FORMAT env var, with
-     * a TTY fallback). Passing an explicit boolean wins over the env var.
-     */
-    json?: boolean;
-    /** Log level (default: 'info') */
-    level?: LogLevel;
-    /** Optional prefix for all messages */
-    prefix?: string;
-}
-/**
- * Create a winston logger instance.
- *
- * @param options - Logger configuration options
- * @returns Configured winston logger
- */
-export declare function createLogger(options?: LoggerOptions): winston.Logger;
-/**
- * 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`.
- */
-export declare const logger: winston.Logger;
-/**
- * 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.
- */
-export declare function guardStartup(log: winston.Logger, fn: () => Promise<void>): Promise<void>;
-export {};
-//# sourceMappingURL=logger.d.ts.map