@kici-dev/shared 0.1.13 → 0.1.15

package/README.md

@@ -1 +1,13 @@
-TBD
+# @kici-dev/shared
+
+Shared utilities for the KiCI CI/CD stack — logging, zx setup, crypto, telemetry, health and metrics routes. No business logic. Re-exports `@kici-dev/core`.
+
+This is an internal support library — other `@kici-dev` packages depend on it; it is not meant to be installed directly.
+
+Part of [KiCI](https://kici.dev) — CI/CD workflows as TypeScript code: author them with full language power, dry-run them locally, and run them on your own infrastructure.
+
+## Links
+
+- Documentation: <https://docs.kici.dev/architecture/overview/>
+- Source: <https://github.com/kici-dev/kici-public/tree/main/packages/shared>
+- License: Apache-2.0

package/dist/cold-store/chunk-encoder.js

@@ -1,5 +1,5 @@
 import "../chunk-gOLHoazu.js";
-import { sha256 } from "../crypto.js";
+import { sha256 } from "@kici-dev/core";
 import { gzipSync } from "node:zlib";
 //#region src/cold-store/chunk-encoder.ts
 /**

package/dist/cold-store/chunk-id.js

@@ -1,5 +1,5 @@
 import "../chunk-gOLHoazu.js";
-import { sha256 } from "../crypto.js";
+import { sha256 } from "@kici-dev/core";
 //#region src/cold-store/chunk-id.ts
 /**
 * Deterministic chunk ID computation.

package/dist/cold-store/cold-store.js

@@ -1,5 +1,4 @@
 import "../chunk-gOLHoazu.js";
-import { sha256 } from "../crypto.js";
 import { createS3Client } from "../s3-client.js";
 import { chunkObjectKey, encodeKeySegment, tablePrefix, tenantDayPrefix } from "./key.js";
 import { coldDaysToBucket, isLongerColdRetention } from "./bucket.js";
@@ -7,6 +6,7 @@ import { computeChunkId } from "./chunk-id.js";
 import { decodeChunk, encodeChunk } from "./chunk-encoder.js";
 import { parseManifest, serializeManifest } from "./manifest.js";
 import { coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal } from "./metrics.js";
+import { sha256 } from "@kici-dev/core";
 import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand } from "@aws-sdk/client-s3";
 //#region src/cold-store/cold-store.ts
 /**

package/dist/db-admin.d.ts

@@ -60,6 +60,16 @@ export interface EnsureDatabaseOpts {
      * grant is a no-op).
      */
     revokeConnectFromPublic?: boolean;
+    /**
+     * After creating (or finding) the database — and after the optional
+     * `REVOKE CONNECT … FROM PUBLIC` — `GRANT CONNECT ON DATABASE "<name>"
+     * TO "<role>"` for each role here. Pairs with `revokeConnectFromPublic`
+     * to re-grant CONNECT to the specific non-PUBLIC roles that legitimately
+     * need it once the default PUBLIC grant is revoked. Idempotent (GRANT on
+     * an already-present grant is a no-op). Each name is validated as a SQL
+     * identifier before interpolation.
+     */
+    grantConnectToRoles?: string[];
 }
 /**
  * CREATE DATABASE IF NOT EXISTS (idempotent). With no `opts`, the URL's
@@ -177,6 +187,7 @@ export interface SeedEnvironmentOpts {
     waitTimerSeconds?: number | null;
     holdExpirySeconds?: number | null;
     minimumTrust?: string | null;
+    globPattern?: string | null;
 }
 export interface SeedEnvironmentResult {
     envId: string;
@@ -188,6 +199,24 @@ export interface SeedEnvironmentResult {
  * are JSON-serialised server-side; pass them as plain arrays or objects.
  */
 export declare function seedEnvironmentDirect(databaseUrl: string, opts: SeedEnvironmentOpts): Promise<SeedEnvironmentResult>;
+export interface DeleteEnvironmentOpts {
+    orgId: string;
+    name: string;
+}
+/**
+ * Delete an environment keyed by (org_id, name). Returns whether a row was
+ * removed. The `environment_bindings`, `environment_variables`, and
+ * `environment_source_overrides` children all carry
+ * `FOREIGN KEY (environment_id) REFERENCES environments(id) ON DELETE CASCADE`,
+ * so a single DELETE on `environments` cascades to those children. The
+ * `held_runs` FK uses `ON DELETE SET NULL`, so terminal held-run history
+ * survives the delete with a null environment reference. Pending held runs
+ * still reference the environment, so this helper pre-checks their count and
+ * throws before issuing the DELETE — approve or reject them first.
+ */
+export declare function deleteEnvironmentDirect(databaseUrl: string, opts: DeleteEnvironmentOpts): Promise<{
+    deleted: boolean;
+}>;
 export interface SeedEnvironmentBindingOpts {
     orgId: string;
     envName: string;
@@ -209,6 +238,7 @@ export interface SetEnvironmentPolicyOpts {
     holdExpirySeconds?: number | null;
     minimumTrust?: string | null;
     enabled?: boolean;
+    allowLocalExecution?: boolean;
 }
 /**
  * UPDATE only the policy fields that were explicitly provided. Columns that
@@ -1452,5 +1482,14 @@ export declare function clearPeerCredentialsRevokedAtByIdsDirect(databaseUrl: st
 export declare function countActivePeerCredentialsByInstanceDirect(databaseUrl: string, opts: {
     instanceId: string;
 }): Promise<number>;
+/**
+ * Terminate every idle backend of the connecting user except our own
+ * connection. Mirrors what a Postgres leader demotion does to idle pooled
+ * connections — used by resilience tests to verify the pg pool error
+ * handlers absorb the termination without a process restart.
+ *
+ * Returns the number of backends terminated.
+ */
+export declare function terminateIdleDbBackendsDirect(databaseUrl: string): Promise<number>;
 export {};
 //# sourceMappingURL=db-admin.d.ts.map

package/dist/db-admin.js

@@ -111,6 +111,10 @@ async function ensureDatabase(databaseUrl, opts = {}) {
 			outcome = "created";
 		}
 		if (opts.revokeConnectFromPublic) await pool.query(`REVOKE CONNECT ON DATABASE "${dbName}" FROM PUBLIC`);
+		for (const role of opts.grantConnectToRoles ?? []) {
+			assertValidIdentifier(role, "grant-connect role");
+			await pool.query(`GRANT CONNECT ON DATABASE "${dbName}" TO "${role}"`);
+		}
 		return outcome;
 	});
 }
@@ -347,7 +351,8 @@ const ENV_POLICY_COLUMNS = new Set([
 	"wait_timer_seconds",
 	"hold_expiry_seconds",
 	"minimum_trust",
-	"enabled"
+	"enabled",
+	"allow_local_execution"
 ]);
 /**
 * Upsert an environment row keyed by (org_id, name). Returns the env id and
@@ -366,9 +371,9 @@ async function seedEnvironmentDirect(databaseUrl, opts) {
 		const reviewersJson = opts.requiredReviewers === void 0 ? null : JSON.stringify(opts.requiredReviewers);
 		const row = (await pool.query(`INSERT INTO environments
           (org_id, name, type, enabled, branch_restrictions, required_reviewers,
-           wait_timer_seconds, hold_expiry_seconds, minimum_trust)
+           wait_timer_seconds, hold_expiry_seconds, minimum_trust, glob_pattern)
         VALUES ($1, $2, COALESCE($3, 'fixed'), COALESCE($4, true), $5::jsonb, $6::jsonb,
-                $7, COALESCE($8, 86400), $9)
+                $7, COALESCE($8, 86400), $9, $10)
         ON CONFLICT (org_id, name) DO UPDATE SET
           type = COALESCE(EXCLUDED.type, environments.type),
           enabled = EXCLUDED.enabled,
@@ -377,6 +382,7 @@ async function seedEnvironmentDirect(databaseUrl, opts) {
           wait_timer_seconds = EXCLUDED.wait_timer_seconds,
           hold_expiry_seconds = EXCLUDED.hold_expiry_seconds,
           minimum_trust = EXCLUDED.minimum_trust,
+          glob_pattern = COALESCE(EXCLUDED.glob_pattern, environments.glob_pattern),
           updated_at = now()
         RETURNING id, (xmax = 0) AS inserted`, [
 			opts.orgId,
@@ -387,7 +393,8 @@ async function seedEnvironmentDirect(databaseUrl, opts) {
 			reviewersJson,
 			opts.waitTimerSeconds ?? null,
 			opts.holdExpirySeconds ?? null,
-			opts.minimumTrust ?? null
+			opts.minimumTrust ?? null,
+			opts.globPattern ?? null
 		])).rows[0];
 		if (!row) throw new Error(`environment: upsert returned no row for ${opts.name}`);
 		return {
@@ -399,6 +406,33 @@ async function seedEnvironmentDirect(databaseUrl, opts) {
 	}
 }
 /**
+* Delete an environment keyed by (org_id, name). Returns whether a row was
+* removed. The `environment_bindings`, `environment_variables`, and
+* `environment_source_overrides` children all carry
+* `FOREIGN KEY (environment_id) REFERENCES environments(id) ON DELETE CASCADE`,
+* so a single DELETE on `environments` cascades to those children. The
+* `held_runs` FK uses `ON DELETE SET NULL`, so terminal held-run history
+* survives the delete with a null environment reference. Pending held runs
+* still reference the environment, so this helper pre-checks their count and
+* throws before issuing the DELETE — approve or reject them first.
+*/
+async function deleteEnvironmentDirect(databaseUrl, opts) {
+	const pool = new pg.Pool({
+		connectionString: databaseUrl,
+		max: 1
+	});
+	try {
+		const pending = await pool.query(`SELECT count(*)::text AS count FROM held_runs hr
+         JOIN environments e ON e.id = hr.environment_id
+        WHERE e.org_id = $1 AND e.name = $2 AND hr.status = 'pending'`, [opts.orgId, opts.name]);
+		const pendingCount = Number(pending.rows[0]?.count ?? 0);
+		if (pendingCount > 0) throw new Error(`environment has ${pendingCount} pending held run(s) — approve or reject them first`);
+		return { deleted: (await pool.query(`DELETE FROM environments WHERE org_id = $1 AND name = $2 RETURNING id`, [opts.orgId, opts.name])).rows.length > 0 };
+	} finally {
+		await pool.end();
+	}
+}
+/**
 * Upsert an `environment_bindings` row connecting `envName` to `scopePattern`.
 * Throws if the environment does not exist.
 */
@@ -445,6 +479,7 @@ async function setEnvironmentPolicyDirect(databaseUrl, opts) {
 	if (opts.holdExpirySeconds !== void 0) addSet("hold_expiry_seconds", opts.holdExpirySeconds);
 	if (opts.minimumTrust !== void 0) addSet("minimum_trust", opts.minimumTrust);
 	if (opts.enabled !== void 0) addSet("enabled", opts.enabled);
+	if (opts.allowLocalExecution !== void 0) addSet("allow_local_execution", opts.allowLocalExecution);
 	if (setClauses.length === 0) throw new Error("environment: setEnvironmentPolicy requires at least one policy field");
 	const pool = new pg.Pool({
 		connectionString: databaseUrl,
@@ -2551,7 +2586,27 @@ async function countActivePeerCredentialsByInstanceDirect(databaseUrl, opts) {
 		await pool.end();
 	}
 }
+/**
+* Terminate every idle backend of the connecting user except our own
+* connection. Mirrors what a Postgres leader demotion does to idle pooled
+* connections — used by resilience tests to verify the pg pool error
+* handlers absorb the termination without a process restart.
+*
+* Returns the number of backends terminated.
+*/
+async function terminateIdleDbBackendsDirect(databaseUrl) {
+	const pool = createPool(databaseUrl);
+	try {
+		return (await pool.query(`SELECT pg_terminate_backend(pid)
+       FROM pg_stat_activity
+       WHERE pid <> pg_backend_pid()
+         AND usename = current_user
+         AND state = 'idle'`)).rowCount ?? 0;
+	} finally {
+		await pool.end();
+	}
+}
 //#endregion
-export { MIGRATION_HASH_TABLE, PROVIDER_HASH_KEY, 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, getWebhookSourceByRoutingKeyDirect, 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 };
+export { MIGRATION_HASH_TABLE, PROVIDER_HASH_KEY, REGISTERABLE_TRIGGER_TYPES, apiKeyExistsDirect, bumpRegistryVersionDirect, bumpRegistryVersionSimpleDirect, cleanupExecutionRowsDirect, clearDispatchQueueDirect, clearPeerCredentialsRevokedAtByIdsDirect, computeMigrationsHash, countActivePeerCredentialsByInstanceDirect, countCronLastFiredDirect, countHeldRunsByRunIdDirect, countWebhookSourcesByConnectionIdDirect, createDbRole, createEnvironmentTemplateDirect, createJoinTokenDirect, createReadOnlyDbUser, deleteCronLastFiredDirect, deleteCrossRepoTrustDirect, deleteEnvironmentDirect, deleteExecutionRunsByWorkflowNameDirect, deleteGenericWebhookSourcesByNameDirect, deleteKiciEventsDirect, deleteOrgSettingsByCustomerIdDirect, deletePeerCredentialsByInstanceIdLikeDirect, deleteWorkflowRegistrationsDirect, describeTableColumnsDirect, dropAndCreateDatabase, dropDatabaseDirect, emitKiciEventDirect, ensureDatabase, ensureOrgOwnerMemberDirect, findAnyUserApiKeyIdDirect, getExecutionRunSecurityDirect, getGenericWebhookSourceByRoutingKeyDirect, getHeldRunByIdDirect, getPeerCredentialRevokedAtDirect, getRegistryVersionDirect, getWebhookSourceByRoutingKeyDirect, 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, terminateIdleDbBackendsDirect, updateGenericWebhookVerificationConfigDirect, updateOrgSettingsDeniedReposDirect, updateSourceRoutingKeyDirect, updateWorkflowRegistrationCommitShaDirect, upsertCronLastFiredDirect, upsertOrgSettingsGlobalWorkflowsDirect, verifyKiciEventNotifyDirect, waitForEventLogRowByDeliveryIdDirect, waitForExecutionRunStatusSinceDirect, waitForLatestExecutionJobStatusDirect, waitForPlatformEventLogDistinctRoutedDirect, waitForPlatformExecutionRunStatusDirect, waitForPlatformRegistrationsDirect, waitForPostgresDirect, waitForRegistrationsByRoutingKeyDirect, waitForRegistrationsUpdatedAtAdvanceDirect, waitForRunCompletionDirect };
 
 //# sourceMappingURL=db-admin.js.map

package/dist/db.d.ts

@@ -1,9 +1,28 @@
 import pg from 'pg';
 import { Kysely } from 'kysely';
+/** Where a pg connection error surfaced. */
+export type PgPoolErrorSource = 'idle-pool' | 'client';
+export interface CreatePoolOptions {
+    /** Extra pg.Pool config merged over the connection string (e.g. max, connectionTimeoutMillis). */
+    config?: Omit<pg.PoolConfig, 'connectionString'>;
+    /**
+     * Optional hook invoked after the built-in log line on every absorbed
+     * connection error (e.g. to increment a metrics counter). Additive — it
+     * never replaces the log.
+     */
+    onError?: (err: Error, source: PgPoolErrorSource) => void;
+}
 /**
  * Create PostgreSQL connection pool.
+ *
+ * Always attaches error handlers for both idle pooled clients (the pool's
+ * own 'error' event) and checked-out clients (per-client 'error' via the
+ * 'connect' hook). Without them, a terminated backend — e.g. a Postgres
+ * leader switchover — escalates to an uncaughtException and a full process
+ * restart. The broken connection is logged and discarded; pg replaces it on
+ * the next acquire. In-flight query failures still reject to their callers.
  */
-export declare function createPool(databaseUrl: string): pg.Pool;
+export declare function createPool(databaseUrl: string, options?: CreatePoolOptions): pg.Pool;
 /**
  * Create Kysely database instance (PostgreSQL only).
  *

package/dist/db.js

@@ -1,12 +1,44 @@
 import "./chunk-gOLHoazu.js";
 import pg from "pg";
 import { Kysely, PostgresDialect } from "kysely";
+import { createLogger } from "@kici-dev/core";
 //#region src/db.ts
+let poolLogger;
+function getPoolLogger() {
+	poolLogger ??= createLogger({ prefix: "pg-pool" });
+	return poolLogger;
+}
 /**
 * Create PostgreSQL connection pool.
+*
+* Always attaches error handlers for both idle pooled clients (the pool's
+* own 'error' event) and checked-out clients (per-client 'error' via the
+* 'connect' hook). Without them, a terminated backend — e.g. a Postgres
+* leader switchover — escalates to an uncaughtException and a full process
+* restart. The broken connection is logged and discarded; pg replaces it on
+* the next acquire. In-flight query failures still reject to their callers.
 */
-function createPool(databaseUrl) {
-	return new pg.Pool({ connectionString: databaseUrl });
+function createPool(databaseUrl, options) {
+	const pool = new pg.Pool({
+		connectionString: databaseUrl,
+		...options?.config
+	});
+	const seen = /* @__PURE__ */ new WeakSet();
+	const handle = (err, source) => {
+		if (seen.has(err)) return;
+		seen.add(err);
+		getPoolLogger().warn("Discarded broken pg connection", {
+			source,
+			error: err.message,
+			stack: err.stack
+		});
+		options?.onError?.(err, source);
+	};
+	pool.on("error", (err) => handle(err, "idle-pool"));
+	pool.on("connect", (client) => {
+		client.on("error", (err) => handle(err, "client"));
+	});
+	return pool;
 }
 /**
 * Create Kysely database instance (PostgreSQL only).

package/dist/db.test.d.ts

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

package/dist/env/define-env.js

@@ -60,9 +60,11 @@ function extractDefault(field) {
 		const def = t.def;
 		if (!def) return void 0;
 		if (def.type === "default" && def.defaultValue !== void 0) {
-			const v = typeof def.defaultValue === "function" ? "<computed>" : def.defaultValue;
-			if (v === "" || v === void 0) return void 0;
-			return JSON.stringify(v);
+			const probe1 = def.defaultValue;
+			const probe2 = def.defaultValue;
+			if (typeof probe1 === "function" || probe1 !== probe2) return "\"<computed>\"";
+			if (probe1 === "" || probe1 === void 0) return void 0;
+			return JSON.stringify(probe1);
 		}
 		if (def.in) {
 			t = def.in;
@@ -80,7 +82,7 @@ function isOptional(field) {
 	for (let i = 0; i < 6; i++) {
 		const def = t.def;
 		if (!def) return false;
-		if (def.type === "optional" || def.type === "default") return true;
+		if (def.type === "optional" || def.type === "default" || def.type === "prefault") return true;
 		if (def.in) {
 			t = def.in;
 			continue;
@@ -93,6 +95,26 @@ function isOptional(field) {
 	}
 	return false;
 }
+/**
+* Walk through `.optional()` / `.default(...)` / `.prefault(...)` wrappers to
+* find a nested ZodObject's `.shape`. Returns undefined if `field` does not
+* (eventually) wrap a ZodObject. Mirrors the unwrap loop in
+* `extractDefault` / `isOptional` so that a nested object can be wrapped in
+* any of the common compositional modifiers and still be walked for docs.
+*/
+function findInnerShape(field) {
+	let t = field;
+	for (let i = 0; i < 8; i++) {
+		const node = t;
+		if (node.shape) return node.shape;
+		if (node.def?.shape) return node.def.shape;
+		if (node.def?.innerType) {
+			t = node.def.innerType;
+			continue;
+		}
+		return;
+	}
+}
 function describeFieldRecursive(shape, envMap, fieldPath, descriptions, out) {
 	for (const [name, field] of Object.entries(shape)) {
 		const path = fieldPath ? `${fieldPath}.${name}` : name;
@@ -113,8 +135,7 @@ function describeFieldRecursive(shape, envMap, fieldPath, descriptions, out) {
 				description: explicitDesc ?? zodDesc ?? def2?.description
 			});
 		} else {
-			const nested = field;
-			const innerShape = nested.shape ?? nested.def?.shape;
+			const innerShape = findInnerShape(field);
 			if (innerShape) describeFieldRecursive(innerShape, mapping, path, descriptions, out);
 		}
 	}

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

@@ -20,9 +20,9 @@ export declare const LoggerEnvSchema: z.ZodObject<{
     KICI_LOG_MAX_SIZE: z.ZodDefault<z.ZodString>;
     KICI_LOG_RETENTION_DAYS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     KICI_LOG_FORMAT: z.ZodDefault<z.ZodEnum<{
-        plain: "plain";
         json: "json";
         auto: "auto";
+        plain: "plain";
     }>>;
     KICI_CLUSTER_INSTANCE_ID: z.ZodOptional<z.ZodString>;
     KICI_AGENT_ID: z.ZodOptional<z.ZodString>;

package/dist/graceful-shutdown.d.ts

@@ -50,9 +50,21 @@ export interface ShutdownHandle {
 /**
  * Wire up SIGTERM / SIGINT (and optionally uncaughtException /
  * unhandledRejection) handlers that execute the provided teardown
- * steps sequentially, then `process.exit(0)`.
+ * steps sequentially, then exit.
+ *
+ * Exit codes: signal-triggered and programmatic shutdowns exit 0;
+ * shutdowns triggered by uncaughtException / unhandledRejection exit 1 so
+ * `Restart=on-failure`-style supervisor policies and exit-code alerting
+ * see the fatal cause. Escalation is sticky — a fatal trigger arriving
+ * while a clean shutdown is already in progress still raises the final
+ * exit code to 1.
  *
  * A force-exit timer ensures the process terminates even if a step hangs.
+ * The force-exit honors the same sticky exit code as a clean completion: a
+ * slow SIGTERM/SIGINT stop that merely overran the grace period still exits 0,
+ * so systemd records an intentional stop rather than marking the unit `failed`
+ * (which would break `systemctl restart` recovery). Only a fatal trigger
+ * (uncaughtException / unhandledRejection) raises the force-exit code to 1.
  */
 export declare function setupGracefulShutdown(options: GracefulShutdownOptions): ShutdownHandle;
 //# sourceMappingURL=graceful-shutdown.d.ts.map

package/dist/graceful-shutdown.js

@@ -1,17 +1,31 @@
 import "./chunk-gOLHoazu.js";
-import { toErrorMessage } from "./error.js";
+import { toErrorMessage } from "@kici-dev/core";
 //#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)`.
+* steps sequentially, then exit.
+*
+* Exit codes: signal-triggered and programmatic shutdowns exit 0;
+* shutdowns triggered by uncaughtException / unhandledRejection exit 1 so
+* `Restart=on-failure`-style supervisor policies and exit-code alerting
+* see the fatal cause. Escalation is sticky — a fatal trigger arriving
+* while a clean shutdown is already in progress still raises the final
+* exit code to 1.
 *
 * A force-exit timer ensures the process terminates even if a step hangs.
+* The force-exit honors the same sticky exit code as a clean completion: a
+* slow SIGTERM/SIGINT stop that merely overran the grace period still exits 0,
+* so systemd records an intentional stop rather than marking the unit `failed`
+* (which would break `systemctl restart` recovery). Only a fatal trigger
+* (uncaughtException / unhandledRejection) raises the force-exit code to 1.
 */
 function setupGracefulShutdown(options) {
 	const { logger, steps, timeoutMs = 3e4, onForceExit, skipErrorHandlers = false } = options;
 	let isShuttingDown = false;
-	async function gracefulShutdown(signal) {
+	let exitCode = 0;
+	async function gracefulShutdown(signal, code = 0) {
+		exitCode = Math.max(exitCode, code);
 		if (isShuttingDown) {
 			logger.warn("Shutdown already in progress, ignoring signal", { signal });
 			return;
@@ -19,8 +33,8 @@ function setupGracefulShutdown(options) {
 		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);
+			logger.error(`Graceful shutdown timed out after ${timeoutMs / 1e3}s, forcing exit`, { exitCode });
+			if (onForceExit?.() !== true) process.exit(exitCode);
 		}, timeoutMs);
 		try {
 			for (const step of steps) try {
@@ -34,8 +48,8 @@ function setupGracefulShutdown(options) {
 				});
 			}
 			clearTimeout(forceExitTimeout);
-			logger.info("Graceful shutdown complete");
-			process.exit(0);
+			logger.info("Graceful shutdown complete", { exitCode });
+			process.exit(exitCode);
 		} catch (error) {
 			logger.error("Error during graceful shutdown", {
 				error: toErrorMessage(error),
@@ -53,17 +67,17 @@ function setupGracefulShutdown(options) {
 				error: error.message,
 				stack: error.stack
 			});
-			gracefulShutdown("uncaughtException");
+			gracefulShutdown("uncaughtException", 1);
 		});
 		process.on("unhandledRejection", (reason) => {
 			logger.error("Unhandled rejection", {
 				reason: toErrorMessage(reason),
 				stack: reason instanceof Error ? reason.stack : void 0
 			});
-			gracefulShutdown("unhandledRejection");
+			gracefulShutdown("unhandledRejection", 1);
 		});
 	}
-	return { shutdown: gracefulShutdown };
+	return { shutdown: (signal) => gracefulShutdown(signal) };
 }
 //#endregion
 export { setupGracefulShutdown };

package/dist/idempotency.d.ts

@@ -1,68 +1,2 @@
-/**
- * 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>>;
+export * from '@kici-dev/core/idempotency';
 //# sourceMappingURL=idempotency.d.ts.map

package/dist/idempotency.js

@@ -1,49 +1,3 @@
 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
+export * from "@kici-dev/core/idempotency";
+export {};