@kici-dev/shared 0.0.0 → 0.1.1

package/dist/idempotency-files.js

@@ -0,0 +1,190 @@
+import "./chunk-gOLHoazu.js";
+import { createTwoFilesPatch } from "diff";
+//#region src/idempotency-files.ts
+/**
+* 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".
+*/
+const ANSI_RED = "\x1B[31m";
+const ANSI_GREEN = "\x1B[32m";
+const ANSI_CYAN = "\x1B[36m";
+const ANSI_BOLD = "\x1B[1m";
+const ANSI_RESET = "\x1B[0m";
+/**
+* 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)
+*/
+function parseItemizeLine(line) {
+	if (line.length < 13) return null;
+	const code = line.slice(0, 11);
+	const rest = line.slice(11);
+	if (!rest.startsWith(" ")) return null;
+	const relativePath = rest.slice(1).trimEnd();
+	if (relativePath.length === 0) return null;
+	if (!/^[<>.ch*]$/.test(code[0])) return null;
+	if (!/^[fdLDS]$/.test(code[1])) return null;
+	if (code[1] === "d") return null;
+	if (code[0] === "*") return null;
+	if (code.slice(2, 11) === "+++++++++") return {
+		itemizeCode: code,
+		relativePath,
+		category: "new"
+	};
+	const c = code[2];
+	const s = code[3];
+	const t = code[4];
+	const p = code[5];
+	const o = code[6];
+	const g = code[7];
+	const u = code[8];
+	const a = code[9];
+	const x = code[10];
+	if (c !== "." || s !== ".") return {
+		itemizeCode: code,
+		relativePath,
+		category: "content"
+	};
+	if (p !== "." || o !== "." || g !== "." || u !== "." || a !== "." || x !== ".") return {
+		itemizeCode: code,
+		relativePath,
+		category: "mode"
+	};
+	if (t !== ".") return {
+		itemizeCode: code,
+		relativePath,
+		category: "time-only"
+	};
+	return null;
+}
+const CATEGORY_DISPLAY = {
+	new: "NEW",
+	content: "CONTENT",
+	mode: "MODE",
+	"time-only": "TIME"
+};
+const CATEGORY_ORDER = [
+	"new",
+	"content",
+	"mode",
+	"time-only"
+];
+const SKIP_REASON_DISPLAY = {
+	binary: "(binary file changed — no inline diff)",
+	"too-large": "(file too large for inline diff)",
+	"read-failed": "(content read failed — no inline diff)",
+	sensitive: "(sensitive content — diff suppressed)"
+};
+/**
+* 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.
+*/
+function renderFileDriftWithDiff(entry, opts = {}) {
+	if (entry.category === "mode" || entry.category === "time-only") return [];
+	if (entry.contentSkipped) return [SKIP_REASON_DISPLAY[entry.contentSkipped]];
+	const color = opts.color ?? false;
+	const maxLines = opts.maxLines ?? 200;
+	const before = entry.category === "new" ? "" : entry.remoteContent ?? "";
+	const after = entry.localContent ?? "";
+	if (before === "" && after === "" && entry.category !== "new") return [];
+	const rawLines = createTwoFilesPatch(`a/${entry.localPath}`, `b/${entry.localPath}`, before, after, void 0, void 0, { context: 3 }).split("\n");
+	const headerIdx = rawLines.findIndex((l) => l.startsWith("--- "));
+	const body = headerIdx >= 0 ? rawLines.slice(headerIdx) : rawLines;
+	const truncated = body.length > maxLines;
+	const lines = (truncated ? body.slice(0, maxLines) : body).map((line) => colorize(line, color));
+	if (truncated) lines.push(`… (${body.length - maxLines} more lines truncated; raw patch in log file)`);
+	return lines;
+}
+function colorize(line, color) {
+	if (!color) return line;
+	if (line.startsWith("+++") || line.startsWith("---")) return `${ANSI_BOLD}${line}${ANSI_RESET}`;
+	if (line.startsWith("@@")) return `${ANSI_CYAN}${line}${ANSI_RESET}`;
+	if (line.startsWith("+")) return `${ANSI_GREEN}${line}${ANSI_RESET}`;
+	if (line.startsWith("-")) return `${ANSI_RED}${line}${ANSI_RESET}`;
+	return line;
+}
+/**
+* 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.
+*/
+function renderFileDrifts(entries, opts = {}) {
+	if (entries.length === 0) return [];
+	const counts = {};
+	for (const e of entries) counts[e.category] = (counts[e.category] ?? 0) + 1;
+	const summary = CATEGORY_ORDER.filter((c) => counts[c]).map((c) => `${counts[c]} ${c}`).join(", ");
+	const widest = Math.max(...entries.map((e) => CATEGORY_DISPLAY[e.category].length));
+	const sorted = [...entries].sort((a, b) => {
+		const ai = CATEGORY_ORDER.indexOf(a.category);
+		const bi = CATEGORY_ORDER.indexOf(b.category);
+		if (ai !== bi) return ai - bi;
+		return a.localPath.localeCompare(b.localPath);
+	});
+	const lines = [`${entries.length} file(s) drifted: ${summary}`];
+	for (const e of sorted) {
+		const label = CATEGORY_DISPLAY[e.category].padEnd(widest);
+		lines.push(`  ${label}  ${e.localPath}`);
+		if (opts.withContent) {
+			const diff = renderFileDriftWithDiff(e, {
+				color: opts.color,
+				maxLines: opts.maxLines
+			});
+			for (const dl of diff) lines.push(`      ${dl}`);
+		}
+	}
+	return lines;
+}
+//#endregion
+export { parseItemizeLine, renderFileDriftWithDiff, renderFileDrifts };
+
+//# sourceMappingURL=idempotency-files.js.map

package/dist/idempotency-files.test.d.ts

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

package/dist/idempotency.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Idempotent-step primitive: a check / prompt / apply runner that is
+ * UI-agnostic and embeddable across the product.
+ *
+ * The pattern: every destructive operation on shared state (prod infra,
+ * npm, git remotes, DNS, TF state, workflow step side effects) is wrapped
+ * as an IdempotentStep whose check() returns a typed drift value or null.
+ * Null means the system is already in the desired state — the runner
+ * silently skips, optionally invoking whenInSync() to surface the
+ * already-satisfied resource (e.g. an existing resource id). A non-null
+ * drift means apply() would change state — the runner asks the caller's
+ * confirm() before invoking apply(), unless yes or dryRun overrides are
+ * set. apply() returns the typed result of the change for the caller.
+ *
+ * The runner has no UI dependency. CLI consumers pass an inquirer-backed
+ * confirm; future SDK / agent consumers pass their own policy function.
+ * See `.claude/rules/idempotency.md` for the full rule and adopters.
+ */
+export interface IdempotentStep<TDrift, TInSync = void, TApplied = void> {
+    /** Human-readable name; appears in logs and the confirm prompt. */
+    name: string;
+    /** Read-only inspection. Returns drift value if apply() would change
+     *  state, or null if the system is already in the desired state. */
+    check: () => Promise<TDrift | null>;
+    /** Multi-line description of what apply() would do, given drift. */
+    summarize: (drift: TDrift) => string;
+    /** Destructive action that brings the system into the desired state.
+     *  Its return value is surfaced in StepResult.result on the 'applied'
+     *  outcome. */
+    apply: (drift: TDrift) => Promise<TApplied>;
+    /** Optional: runs when check() returns null. Use this to fetch the
+     *  already-satisfied resource (e.g. read the existing id when a
+     *  create-if-missing was already done). Return value is surfaced in
+     *  StepResult.result on the 'skipped' outcome. */
+    whenInSync?: () => Promise<TInSync>;
+}
+export type ConfirmFn = (message: string) => Promise<boolean>;
+export interface RunOptions {
+    /** Pluggable confirm. Required unless `yes` or `dryRun` is set. */
+    confirm?: ConfirmFn;
+    /** Breakglass: skip prompts, apply on drift. The CALLER prints any
+     *  loud "auto-confirm" banner before invoking the runner. */
+    yes?: boolean;
+    /** Report only; bypass confirm; never call apply(). */
+    dryRun?: boolean;
+    /** Sink for `name`-prefixed status lines. Defaults to console.log. */
+    log?: (line: string) => void;
+}
+export type StepOutcome = 'skipped' | 'applied' | 'declined' | 'dry-run';
+export type StepResult<TDrift, TInSync = void, TApplied = void> = {
+    outcome: 'skipped';
+    drift: null;
+    result: TInSync;
+} | {
+    outcome: 'applied';
+    drift: TDrift;
+    result: TApplied;
+} | {
+    outcome: 'declined';
+    drift: TDrift;
+    result: undefined;
+} | {
+    outcome: 'dry-run';
+    drift: TDrift;
+    result: undefined;
+};
+export declare function runIdempotentStep<TDrift, TInSync = void, TApplied = void>(step: IdempotentStep<TDrift, TInSync, TApplied>, opts?: RunOptions): Promise<StepResult<TDrift, TInSync, TApplied>>;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/idempotency.js

@@ -0,0 +1,49 @@
+import "./chunk-gOLHoazu.js";
+//#region src/idempotency.ts
+async function runIdempotentStep(step, opts = {}) {
+	const log = opts.log ?? ((line) => console.log(line));
+	const drift = await step.check();
+	if (drift === null) {
+		log(`✓ ${step.name} — in sync, skipping`);
+		return {
+			outcome: "skipped",
+			drift: null,
+			result: step.whenInSync ? await step.whenInSync() : void 0
+		};
+	}
+	log(`! ${step.name} — drift detected:`);
+	for (const line of step.summarize(drift).split("\n")) log(`    ${line}`);
+	if (opts.dryRun) {
+		log(`  (dry-run; would apply)`);
+		return {
+			outcome: "dry-run",
+			drift,
+			result: void 0
+		};
+	}
+	let approved;
+	if (opts.yes) approved = true;
+	else {
+		if (!opts.confirm) throw new Error(`runIdempotentStep(${step.name}): drift detected but no confirm callback provided and yes/dryRun not set. Pass opts.confirm, opts.yes, or opts.dryRun.`);
+		approved = await opts.confirm(`Apply ${step.name}?`);
+	}
+	if (!approved) {
+		log(`  declined; skipping`);
+		return {
+			outcome: "declined",
+			drift,
+			result: void 0
+		};
+	}
+	const appliedResult = await step.apply(drift);
+	log(`✓ ${step.name} — applied`);
+	return {
+		outcome: "applied",
+		drift,
+		result: appliedResult
+	};
+}
+//#endregion
+export { runIdempotentStep };
+
+//# sourceMappingURL=idempotency.js.map

package/dist/idempotency.test.d.ts

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

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export { RingBuffer } from './ring-buffer.js';
+export { toErrorMessage, serializeError } from './error.js';
+export { createPool, createDb } from './db.js';
+export { parseDatabaseUrl, maskDatabaseUrl, dropAndCreateDatabase, dropDatabaseDirect, ensureDatabase, createDbRole, createReadOnlyDbUser, computeMigrationsHash, storeMigrationContentHash, readStoredMigrationContentHash, isSchemaCurrent, clearDispatchQueueDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, purgeScopedSecretsDirect, seedEnvironmentDirect, seedEnvironmentBindingDirect, setEnvironmentPolicyDirect, listEnvironmentsDirect, showEnvironmentDirect, createEnvironmentTemplateDirect, setEnvironmentSecretDirect, listQueueDirect, showQueueEntryDirect, listExecutionRunsDirect, showExecutionRunDirect, listExecutionJobsDirect, listRegistrationsDirect, showRegistrationDirect, registerWorkflowManualDirect, resetRaftStateDirect, emitKiciEventDirect, seedGenericWebhookSourceDirect, purgeSecretBackendsDirect, apiKeyExistsDirect, seedApiKeyInlineDirect, platformConnectionExistsDirect, countWebhookSourcesByConnectionIdDirect, findAnyUserApiKeyIdDirect, seedSyntheticGithubSourceDirect, seedWebhookSecretDirect, seedSourcePrivateKeyDirect, bumpRegistryVersionDirect, pollKiciEventsDirect, waitForPostgresDirect, waitForRunCompletionDirect, cleanupExecutionRowsDirect, isSchemaCurrentFromFilesDirect, storeMigrationContentHashInTableDirect, createJoinTokenDirect, updateSourceRoutingKeyDirect, prunePeerCredentialsDirect, waitForPlatformRegistrationsDirect, seedUniversalGitSourceDirect, seedCiSecurityFixturesDirect, waitForExecutionRunStatusSinceDirect, latestExecutionRunByStatusDirect, waitForLatestExecutionJobStatusDirect, describeTableColumnsDirect, tableExistsDirect, insertKiciEventRawDirect, showKiciEventDirect, listKiciEventsDirect, deleteKiciEventsDirect, verifyKiciEventNotifyDirect, seedCrossRepoTrustDirect, listCrossRepoTrustBySourceRoutingKeyDirect, deleteCrossRepoTrustDirect, insertCrossRepoTrustStrictDirect, deleteWorkflowRegistrationsDirect, getWorkflowRegistrationByIdDirect, listRegistrationsByRoutingKeyDirect, waitForRegistrationsByRoutingKeyDirect, waitForRegistrationsUpdatedAtAdvanceDirect, updateWorkflowRegistrationCommitShaDirect, insertWorkflowRegistrationRawDirect, insertWorkflowRegistrationStrictDirect, getRegistryVersionDirect, bumpRegistryVersionSimpleDirect, upsertCronLastFiredDirect, countCronLastFiredDirect, insertCronLastFiredNowDirect, deleteCronLastFiredDirect, deleteExecutionRunsByWorkflowNameDirect, getGenericWebhookSourceByRoutingKeyDirect, listActiveGenericWebhookSourcesDirect, updateGenericWebhookVerificationConfigDirect, deleteGenericWebhookSourcesByNameDirect, restoreSoftDeletedGenericWebhookSourceDirect, upsertOrgSettingsGlobalWorkflowsDirect, updateOrgSettingsDeniedReposDirect, deleteOrgSettingsByCustomerIdDirect, getExecutionRunSecurityDirect, getHeldRunByIdDirect, countHeldRunsByRunIdDirect, waitForPlatformExecutionRunStatusDirect, waitForPlatformEventLogDistinctRoutedDirect, waitForEventLogRowByDeliveryIdDirect, resolvePlatformWebhookSourceRoutingKeyDirect, ensureOrgOwnerMemberDirect, deletePeerCredentialsByInstanceIdLikeDirect, insertPeerCredentialExpiredDirect, getPeerCredentialRevokedAtDirect, listActivePeerCredentialsExcludingDirect, clearPeerCredentialsRevokedAtByIdsDirect, countActivePeerCredentialsByInstanceDirect, type ColumnInfo, type KiciEventRow, type CrossRepoTrustRow, type WorkflowRegistrationFullRow, type RegistrationsScopedResult, type LatestExecutionRunResult, type WaitForLatestJobResult, type ExecutionRunSecurityRow, type HeldRunSecurityRow, type EventLogRow as PlatformEventLogRow, type UpsertOrgSettingsOpts, type OrgSettingsRepoPatternEntry, type InsertKiciEventRawOpts, type EmitKiciEventOpts, type SeedGenericWebhookSourceOpts, REGISTERABLE_TRIGGER_TYPES, MIGRATION_HASH_TABLE, type PurgeStaleExecutionResult, type PurgeStaleSourcesResult, type SeedEnvironmentOpts, type SeedEnvironmentResult, type SeedEnvironmentBindingOpts, type SetEnvironmentPolicyOpts, type EnvironmentRow, type EnvironmentVariableRow, type EnvironmentBindingRow, type ShowEnvironmentResult, type CreateEnvironmentTemplateOpts, type SetEnvironmentSecretOpts, type DispatchQueueRow, type ListQueueOpts, type ExecutionRunRow, type ExecutionJobRow, type ListExecutionRunsOpts, type WorkflowRegistrationRow, type ListRegistrationsOpts, type ListRegistrationsResult, type ShowRegistrationResult, type RegisterWorkflowManualOpts, type RegisterWorkflowManualResult, } from './db-admin.js';
+export { createMetricsRoutes, type MetricsRoutesDeps } from './routes/metrics.js';
+export { createHealthRoutes, type HealthRoutesDeps } from './routes/health.js';
+export { initZx } from './zx.js';
+export { createLogger, guardStartup, logger, setServiceName, type LogLevel, type Logger, } from './logger.js';
+export { requestContext, getRequestContext, enrichRequestContext, type RequestContext, } from './request-context.js';
+export { getReconnectDelay } from './reconnect-delay.js';
+export { formatBytes } from './format-bytes.js';
+export { formatDuration, formatUptime } from './format-duration.js';
+export { sha256, sha256File, deriveSharedSecret, normalizeLineEndings } from './crypto.js';
+export { initTelemetry, getPrometheusExporter, createMeter, type TelemetryConfig, } from './telemetry/index.js';
+export { setupGracefulShutdown, type ShutdownStep, type ShutdownLogger, type ShutdownHandle, type GracefulShutdownOptions, } from './graceful-shutdown.js';
+export { validateRequiredTools, type ToolRequirement } from './tool-check.js';
+export { createS3Client, type CreateS3ClientOptions, type SharedS3Config } from './s3-client.js';
+export { BaseColdStore, ChunkLru, COLD_BUCKET_NAMES, DEFAULT_TABLE_CONFIG, chunkObjectKey, coldDaysToBucket, coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal, computeChunkId, decodeChunk, encodeChunk, encodeKeySegment, isLongerColdRetention, parseManifest, resolveTableConfig, serializeManifest, tablePrefix, tenantDayBucketPrefix, tenantDayPrefix, type ArchiveCycleSummary, type BaseColdStoreDeps, type ChunkCommitMetadata, type ChunkLruOptions, type ChunkManifest, type ColdBucketName, type ColdRetention, type ColdStore, type ColdStoreConfig, type ColdStoreFetchRangeArgs, type ColdStoreReplayChunkArgs, type ColdStoreReplayResult, type ColdStoreReplayRowArgs, type ColdStoreTableConfig, type DbKind, type DecodeChunkArgs, type EligiblePartition, type EncodeChunkArgs, type EncodedChunk, type PurgeableChunk, type PurgeChunkResult, type PurgeExpiredChunksOpts, type PurgeExpiredChunksSummary, type TableAdapter, } from './cold-store/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,31 @@
+import "./chunk-gOLHoazu.js";
+import { deriveSharedSecret, normalizeLineEndings, sha256, sha256File } from "./crypto.js";
+import { createDb, createPool } from "./db.js";
+import { MIGRATION_HASH_TABLE, REGISTERABLE_TRIGGER_TYPES, apiKeyExistsDirect, bumpRegistryVersionDirect, bumpRegistryVersionSimpleDirect, cleanupExecutionRowsDirect, clearDispatchQueueDirect, clearPeerCredentialsRevokedAtByIdsDirect, computeMigrationsHash, countActivePeerCredentialsByInstanceDirect, countCronLastFiredDirect, countHeldRunsByRunIdDirect, countWebhookSourcesByConnectionIdDirect, createDbRole, createEnvironmentTemplateDirect, createJoinTokenDirect, createReadOnlyDbUser, deleteCronLastFiredDirect, deleteCrossRepoTrustDirect, deleteExecutionRunsByWorkflowNameDirect, deleteGenericWebhookSourcesByNameDirect, deleteKiciEventsDirect, deleteOrgSettingsByCustomerIdDirect, deletePeerCredentialsByInstanceIdLikeDirect, deleteWorkflowRegistrationsDirect, describeTableColumnsDirect, dropAndCreateDatabase, dropDatabaseDirect, emitKiciEventDirect, ensureDatabase, ensureOrgOwnerMemberDirect, findAnyUserApiKeyIdDirect, getExecutionRunSecurityDirect, getGenericWebhookSourceByRoutingKeyDirect, getHeldRunByIdDirect, getPeerCredentialRevokedAtDirect, getRegistryVersionDirect, getWorkflowRegistrationByIdDirect, insertCronLastFiredNowDirect, insertCrossRepoTrustStrictDirect, insertKiciEventRawDirect, insertPeerCredentialExpiredDirect, insertWorkflowRegistrationRawDirect, insertWorkflowRegistrationStrictDirect, isSchemaCurrent, isSchemaCurrentFromFilesDirect, latestExecutionRunByStatusDirect, listActiveGenericWebhookSourcesDirect, listActivePeerCredentialsExcludingDirect, listCrossRepoTrustBySourceRoutingKeyDirect, listEnvironmentsDirect, listExecutionJobsDirect, listExecutionRunsDirect, listKiciEventsDirect, listQueueDirect, listRegistrationsByRoutingKeyDirect, listRegistrationsDirect, maskDatabaseUrl, parseDatabaseUrl, platformConnectionExistsDirect, pollKiciEventsDirect, prunePeerCredentialsDirect, purgeScopedSecretsDirect, purgeSecretBackendsDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, readStoredMigrationContentHash, registerWorkflowManualDirect, resetRaftStateDirect, resolvePlatformWebhookSourceRoutingKeyDirect, restoreSoftDeletedGenericWebhookSourceDirect, seedApiKeyInlineDirect, seedCiSecurityFixturesDirect, seedCrossRepoTrustDirect, seedEnvironmentBindingDirect, seedEnvironmentDirect, seedGenericWebhookSourceDirect, seedSourcePrivateKeyDirect, seedSyntheticGithubSourceDirect, seedUniversalGitSourceDirect, seedWebhookSecretDirect, setEnvironmentPolicyDirect, setEnvironmentSecretDirect, showEnvironmentDirect, showExecutionRunDirect, showKiciEventDirect, showQueueEntryDirect, showRegistrationDirect, storeMigrationContentHash, storeMigrationContentHashInTableDirect, tableExistsDirect, updateGenericWebhookVerificationConfigDirect, updateOrgSettingsDeniedReposDirect, updateSourceRoutingKeyDirect, updateWorkflowRegistrationCommitShaDirect, upsertCronLastFiredDirect, upsertOrgSettingsGlobalWorkflowsDirect, verifyKiciEventNotifyDirect, waitForEventLogRowByDeliveryIdDirect, waitForExecutionRunStatusSinceDirect, waitForLatestExecutionJobStatusDirect, waitForPlatformEventLogDistinctRoutedDirect, waitForPlatformExecutionRunStatusDirect, waitForPlatformRegistrationsDirect, waitForPostgresDirect, waitForRegistrationsByRoutingKeyDirect, waitForRegistrationsUpdatedAtAdvanceDirect, waitForRunCompletionDirect } from "./db-admin.js";
+import { serializeError, toErrorMessage } from "./error.js";
+import { formatBytes } from "./format-bytes.js";
+import { formatDuration, formatUptime } from "./format-duration.js";
+import { setupGracefulShutdown } from "./graceful-shutdown.js";
+import { RingBuffer } from "./ring-buffer.js";
+import { createMetricsRoutes } from "./routes/metrics.js";
+import { createHealthRoutes } from "./routes/health.js";
+import { initZx } from "./zx.js";
+import { enrichRequestContext, getRequestContext, requestContext } from "./request-context.js";
+import { createLogger, guardStartup, logger, setServiceName } from "./logger.js";
+import { getReconnectDelay } from "./reconnect-delay.js";
+import { getPrometheusExporter, initTelemetry } from "./telemetry/init.js";
+import { createMeter } from "./telemetry/metrics.js";
+import "./telemetry/index.js";
+import { validateRequiredTools } from "./tool-check.js";
+import { createS3Client } from "./s3-client.js";
+import { chunkObjectKey, encodeKeySegment, tablePrefix, tenantDayBucketPrefix, tenantDayPrefix } from "./cold-store/key.js";
+import { COLD_BUCKET_NAMES, coldDaysToBucket, isLongerColdRetention } from "./cold-store/bucket.js";
+import { computeChunkId } from "./cold-store/chunk-id.js";
+import { decodeChunk, encodeChunk } from "./cold-store/chunk-encoder.js";
+import { parseManifest, serializeManifest } from "./cold-store/manifest.js";
+import { coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal } from "./cold-store/metrics.js";
+import { BaseColdStore } from "./cold-store/cold-store.js";
+import { ChunkLru } from "./cold-store/lru.js";
+import { DEFAULT_TABLE_CONFIG, resolveTableConfig } from "./cold-store/config.js";
+import "./cold-store/index.js";
+export { BaseColdStore, COLD_BUCKET_NAMES, ChunkLru, DEFAULT_TABLE_CONFIG, MIGRATION_HASH_TABLE, REGISTERABLE_TRIGGER_TYPES, RingBuffer, apiKeyExistsDirect, bumpRegistryVersionDirect, bumpRegistryVersionSimpleDirect, chunkObjectKey, cleanupExecutionRowsDirect, clearDispatchQueueDirect, clearPeerCredentialsRevokedAtByIdsDirect, coldDaysToBucket, coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal, computeChunkId, computeMigrationsHash, countActivePeerCredentialsByInstanceDirect, countCronLastFiredDirect, countHeldRunsByRunIdDirect, countWebhookSourcesByConnectionIdDirect, createDb, createDbRole, createEnvironmentTemplateDirect, createHealthRoutes, createJoinTokenDirect, createLogger, createMeter, createMetricsRoutes, createPool, createReadOnlyDbUser, createS3Client, decodeChunk, deleteCronLastFiredDirect, deleteCrossRepoTrustDirect, deleteExecutionRunsByWorkflowNameDirect, deleteGenericWebhookSourcesByNameDirect, deleteKiciEventsDirect, deleteOrgSettingsByCustomerIdDirect, deletePeerCredentialsByInstanceIdLikeDirect, deleteWorkflowRegistrationsDirect, deriveSharedSecret, describeTableColumnsDirect, dropAndCreateDatabase, dropDatabaseDirect, emitKiciEventDirect, encodeChunk, encodeKeySegment, enrichRequestContext, ensureDatabase, ensureOrgOwnerMemberDirect, findAnyUserApiKeyIdDirect, formatBytes, formatDuration, formatUptime, getExecutionRunSecurityDirect, getGenericWebhookSourceByRoutingKeyDirect, getHeldRunByIdDirect, getPeerCredentialRevokedAtDirect, getPrometheusExporter, getReconnectDelay, getRegistryVersionDirect, getRequestContext, getWorkflowRegistrationByIdDirect, guardStartup, initTelemetry, initZx, insertCronLastFiredNowDirect, insertCrossRepoTrustStrictDirect, insertKiciEventRawDirect, insertPeerCredentialExpiredDirect, insertWorkflowRegistrationRawDirect, insertWorkflowRegistrationStrictDirect, isLongerColdRetention, isSchemaCurrent, isSchemaCurrentFromFilesDirect, latestExecutionRunByStatusDirect, listActiveGenericWebhookSourcesDirect, listActivePeerCredentialsExcludingDirect, listCrossRepoTrustBySourceRoutingKeyDirect, listEnvironmentsDirect, listExecutionJobsDirect, listExecutionRunsDirect, listKiciEventsDirect, listQueueDirect, listRegistrationsByRoutingKeyDirect, listRegistrationsDirect, logger, maskDatabaseUrl, normalizeLineEndings, parseDatabaseUrl, parseManifest, platformConnectionExistsDirect, pollKiciEventsDirect, prunePeerCredentialsDirect, purgeScopedSecretsDirect, purgeSecretBackendsDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, readStoredMigrationContentHash, registerWorkflowManualDirect, requestContext, resetRaftStateDirect, resolvePlatformWebhookSourceRoutingKeyDirect, resolveTableConfig, restoreSoftDeletedGenericWebhookSourceDirect, seedApiKeyInlineDirect, seedCiSecurityFixturesDirect, seedCrossRepoTrustDirect, seedEnvironmentBindingDirect, seedEnvironmentDirect, seedGenericWebhookSourceDirect, seedSourcePrivateKeyDirect, seedSyntheticGithubSourceDirect, seedUniversalGitSourceDirect, seedWebhookSecretDirect, serializeError, serializeManifest, setEnvironmentPolicyDirect, setEnvironmentSecretDirect, setServiceName, setupGracefulShutdown, sha256, sha256File, showEnvironmentDirect, showExecutionRunDirect, showKiciEventDirect, showQueueEntryDirect, showRegistrationDirect, storeMigrationContentHash, storeMigrationContentHashInTableDirect, tableExistsDirect, tablePrefix, tenantDayBucketPrefix, tenantDayPrefix, toErrorMessage, updateGenericWebhookVerificationConfigDirect, updateOrgSettingsDeniedReposDirect, updateSourceRoutingKeyDirect, updateWorkflowRegistrationCommitShaDirect, upsertCronLastFiredDirect, upsertOrgSettingsGlobalWorkflowsDirect, validateRequiredTools, verifyKiciEventNotifyDirect, waitForEventLogRowByDeliveryIdDirect, waitForExecutionRunStatusSinceDirect, waitForLatestExecutionJobStatusDirect, waitForPlatformEventLogDistinctRoutedDirect, waitForPlatformExecutionRunStatusDirect, waitForPlatformRegistrationsDirect, waitForPostgresDirect, waitForRegistrationsByRoutingKeyDirect, waitForRegistrationsUpdatedAtAdvanceDirect, waitForRunCompletionDirect };

package/dist/logger.d.ts

@@ -0,0 +1,57 @@
+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-detect based on TTY) */
+    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

package/dist/logger.js

@@ -0,0 +1,175 @@
+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() {
+	if (!process.env.KICI_LOG_DIR) return void 0;
+	return new DailyRotateFile({
+		dirname: process.env.KICI_LOG_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`;
+}
+/**
+* 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 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, timestamp, requestId }) => {
+		const time = new Date(timestamp).toLocaleTimeString("en-US", {
+			hour12: false,
+			hour: "2-digit",
+			minute: "2-digit",
+			second: "2-digit"
+		});
+		let coloredLevel;
+		switch (level) {
+			case "error":
+				coloredLevel = pc.red(level);
+				break;
+			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}`;
+	});
+	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 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

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

package/dist/reconnect-delay.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Calculate reconnection delay with exponential backoff and jitter.
+ *
+ * Formula: baseDelay * multiplier^attempts * (1.0 + random * 0.5)
+ * - Initial delay: 1000ms
+ * - Multiplier: 1.5x per attempt
+ * - Jitter: 0-50% additional randomness
+ * - Max delay: capped at maxDelayMs
+ */
+export declare function getReconnectDelay(attempts: number, maxDelayMs: number): number;
+//# sourceMappingURL=reconnect-delay.d.ts.map

package/dist/reconnect-delay.js

@@ -0,0 +1,22 @@
+import "./chunk-gOLHoazu.js";
+//#region src/reconnect-delay.ts
+/**
+* Calculate reconnection delay with exponential backoff and jitter.
+*
+* Formula: baseDelay * multiplier^attempts * (1.0 + random * 0.5)
+* - Initial delay: 1000ms
+* - Multiplier: 1.5x per attempt
+* - Jitter: 0-50% additional randomness
+* - Max delay: capped at maxDelayMs
+*/
+function getReconnectDelay(attempts, maxDelayMs) {
+	const baseDelay = 1e3;
+	const multiplier = 1.5;
+	const jitterFactor = 1 + Math.random() * .5;
+	const delay = baseDelay * Math.pow(multiplier, attempts) * jitterFactor;
+	return Math.min(delay, maxDelayMs);
+}
+//#endregion
+export { getReconnectDelay };
+
+//# sourceMappingURL=reconnect-delay.js.map