@kici-dev/shared 0.1.3 → 0.1.6

package/dist/db-admin.d.ts

@@ -41,10 +41,32 @@ export declare function dropDatabaseDirect(databaseUrl: string): Promise<void>;
  * existing backend connections so the DROP doesn't block.
  */
 export declare function dropAndCreateDatabase(databaseUrl: string): Promise<void>;
+export interface EnsureDatabaseOpts {
+    /**
+     * DB owner role. Defaults to the URL's username. Pass when the admin
+     * connection user is privileged (e.g. Patroni superuser) but the new
+     * database should be owned by a separate, non-privileged role — the
+     * cross-owner case for provisioning shared-cluster databases like
+     * Keycloak's on the Platform Patroni cluster.
+     */
+    owner?: string;
+    /**
+     * After creating (or finding) the database, run
+     * `REVOKE CONNECT ON DATABASE "<name>" FROM PUBLIC`. Recommended for
+     * shared Patroni clusters where multiple unrelated databases coexist
+     * (Platform + Keycloak today, more tomorrow) — the default `PUBLIC`
+     * CONNECT grant otherwise lets any role with LOGIN on the cluster
+     * reach the new database. Idempotent (REVOKE on an already-revoked
+     * grant is a no-op).
+     */
+    revokeConnectFromPublic?: boolean;
+}
 /**
- * CREATE DATABASE IF NOT EXISTS (idempotent). Uses the URL's username as owner.
+ * CREATE DATABASE IF NOT EXISTS (idempotent). With no `opts`, the URL's
+ * username is the owner. Pass `owner` to override and
+ * `revokeConnectFromPublic` to lock down the default CONNECT grant.
  */
-export declare function ensureDatabase(databaseUrl: string): Promise<'created' | 'exists'>;
+export declare function ensureDatabase(databaseUrl: string, opts?: EnsureDatabaseOpts): Promise<'created' | 'exists'>;
 /**
  * CREATE ROLE ... LOGIN [CREATEDB] (idempotent — updates password if role
  * already exists).
@@ -582,6 +604,18 @@ export declare function platformConnectionExistsDirect(databaseUrl: string, conn
  * by Platform migration 017 actually fires when the parent
  * `platform_connections` row is deleted.
  */
+/**
+ * Look up a Platform-side `webhook_sources` row by routing key. Returns the
+ * row (org_id + provider + connection) or null. Used by E2E to assert that a
+ * source added at runtime on the orchestrator propagated to the Platform's
+ * `webhook_sources` table (the dashboard-visible source list) without a
+ * restart.
+ */
+export declare function getWebhookSourceByRoutingKeyDirect(databaseUrl: string, routingKey: string): Promise<{
+    routing_key: string;
+    org_id: string;
+    provider: string;
+} | null>;
 export declare function countWebhookSourcesByConnectionIdDirect(databaseUrl: string, connectionId: string): Promise<number>;
 /**
  * Find a `user_api_keys.id` preferring rows scoped to `preferredOrgId`, else
@@ -1350,7 +1384,7 @@ export declare function resolvePlatformWebhookSourceRoutingKeyDirect(platformDbU
  */
 export declare function ensureOrgOwnerMemberDirect(platformDbUrl: string, opts: {
     orgId: string;
-    zitadelSub: string;
+    idpSub: string;
     email: string;
     displayName: string;
 }): Promise<{

package/dist/db-admin.js

@@ -93,16 +93,25 @@ async function dropAndCreateDatabase(databaseUrl) {
 	});
 }
 /**
-* CREATE DATABASE IF NOT EXISTS (idempotent). Uses the URL's username as owner.
+* CREATE DATABASE IF NOT EXISTS (idempotent). With no `opts`, the URL's
+* username is the owner. Pass `owner` to override and
+* `revokeConnectFromPublic` to lock down the default CONNECT grant.
 */
-async function ensureDatabase(databaseUrl) {
+async function ensureDatabase(databaseUrl, opts = {}) {
 	const { adminUrl, dbName, dbOwner } = parseDatabaseUrl(databaseUrl);
+	const finalOwner = opts.owner ?? dbOwner;
 	assertValidIdentifier(dbName, "database name");
-	assertValidIdentifier(dbOwner, "database owner");
+	assertValidIdentifier(finalOwner, "database owner");
 	return withAdminPool(adminUrl, async (pool) => {
-		if ((await pool.query("SELECT 1 FROM pg_database WHERE datname = $1", [dbName])).rows.length > 0) return "exists";
-		await pool.query(`CREATE DATABASE "${dbName}" OWNER "${dbOwner}"`);
-		return "created";
+		const check = await pool.query("SELECT 1 FROM pg_database WHERE datname = $1", [dbName]);
+		let outcome;
+		if (check.rows.length > 0) outcome = "exists";
+		else {
+			await pool.query(`CREATE DATABASE "${dbName}" OWNER "${finalOwner}"`);
+			outcome = "created";
+		}
+		if (opts.revokeConnectFromPublic) await pool.query(`REVOKE CONNECT ON DATABASE "${dbName}" FROM PUBLIC`);
+		return outcome;
 	});
 }
 /**
@@ -1115,6 +1124,29 @@ async function platformConnectionExistsDirect(databaseUrl, connectionId) {
 * by Platform migration 017 actually fires when the parent
 * `platform_connections` row is deleted.
 */
+/**
+* Look up a Platform-side `webhook_sources` row by routing key. Returns the
+* row (org_id + provider + connection) or null. Used by E2E to assert that a
+* source added at runtime on the orchestrator propagated to the Platform's
+* `webhook_sources` table (the dashboard-visible source list) without a
+* restart.
+*/
+async function getWebhookSourceByRoutingKeyDirect(databaseUrl, routingKey) {
+	const pool = createPool(databaseUrl);
+	try {
+		const row = (await pool.query(`SELECT routing_key, org_id, provider
+         FROM webhook_sources
+         WHERE routing_key = $1
+         LIMIT 1`, [routingKey])).rows[0];
+		return row ? {
+			routing_key: String(row.routing_key),
+			org_id: String(row.org_id),
+			provider: String(row.provider)
+		} : null;
+	} finally {
+		await pool.end();
+	}
+}
 async function countWebhookSourcesByConnectionIdDirect(databaseUrl, connectionId) {
 	const pool = createPool(databaseUrl);
 	try {
@@ -2402,19 +2434,19 @@ async function ensureOrgOwnerMemberDirect(platformDbUrl, opts) {
 		const ownerRole = await pool.query(`SELECT id FROM roles WHERE org_id = $1 AND is_owner = true LIMIT 1`, [opts.orgId]);
 		if (ownerRole.rows.length === 0) throw new Error(`ensureOrgOwnerMemberDirect: no owner role found for org ${opts.orgId}`);
 		const ownerRoleId = ownerRole.rows[0].id;
-		await pool.query(`INSERT INTO users (zitadel_sub, email, display_name)
+		await pool.query(`INSERT INTO users (idp_sub, email, display_name)
          VALUES ($1, $2, $3)
-         ON CONFLICT (zitadel_sub) DO NOTHING`, [
-			opts.zitadelSub,
+         ON CONFLICT (idp_sub) DO NOTHING`, [
+			opts.idpSub,
 			opts.email,
 			opts.displayName
 		]);
-		await pool.query(`INSERT INTO org_members (org_id, user_id) VALUES ($1, $2) ON CONFLICT DO NOTHING`, [opts.orgId, opts.zitadelSub]);
+		await pool.query(`INSERT INTO org_members (org_id, user_id) VALUES ($1, $2) ON CONFLICT DO NOTHING`, [opts.orgId, opts.idpSub]);
 		await pool.query(`INSERT INTO role_assignments (org_id, user_id, role_id, assigned_by)
          VALUES ($1, $2, $3, $2)
          ON CONFLICT (org_id, user_id, role_id) DO NOTHING`, [
 			opts.orgId,
-			opts.zitadelSub,
+			opts.idpSub,
 			ownerRoleId
 		]);
 		return { ownerRoleId };
@@ -2520,6 +2552,6 @@ async function countActivePeerCredentialsByInstanceDirect(databaseUrl, opts) {
 	}
 }
 //#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, 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, 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 };
 
 //# sourceMappingURL=db-admin.js.map

package/dist/db-collation.d.ts

@@ -0,0 +1,60 @@
+import pg from 'pg';
+/**
+ * Collation-drift helpers shared between `kici-admin` (orchestrator DB) and
+ * `kici-platform-admin` (Platform DB).
+ *
+ * Background: `pg_database.datcollversion` records the libc collation version
+ * at database-bootstrap time. B-tree indexes on text columns were built under
+ * those collation rules. When the running Postgres process's libc collation
+ * version differs (commonly after a container image rebuild on a newer libc
+ * base), indexes can silently misindex non-ASCII data — `LIKE 'foo%'` may miss
+ * rows, `ORDER BY` becomes unstable, rule-equivalent duplicates can sneak past
+ * unique constraints.
+ *
+ * Detection compares `datcollversion` (the version stamped at bootstrap)
+ * against `pg_database_collation_actual_version(oid)` (the version the running
+ * libc reports). Healing is a two-step operator action:
+ *
+ * 1. `REINDEX DATABASE CONCURRENTLY <name>` — rebuild every index under the
+ *    running libc rules. Non-blocking (short locks per index); needs ~2× temp
+ *    disk while parallel indexes coexist.
+ * 2. `ALTER DATABASE <name> REFRESH COLLATION VERSION` — bump the metadata
+ *    stamp so future probes report clean.
+ *
+ * All callers pass a `pg.Pool`. The helpers do not own pool lifecycle — the
+ * CLI / probe layer creates and ends pools using the standard
+ * `createPool` / `pool.end()` pattern from `db.js`.
+ */
+export interface CollationDrift {
+    /** Version stamped into pg_database.datcollversion at bootstrap. */
+    stamped: string;
+    /** Version the running libc reports via pg_database_collation_actual_version. */
+    actual: string;
+}
+/**
+ * Read `pg_database.datcollversion` and
+ * `pg_database_collation_actual_version(oid)` for `dbName` and return drift
+ * details when they differ. Returns `null` when stamped === actual OR when
+ * stamped is null (Postgres marks template0-style locked databases that way —
+ * benign, no drift to report).
+ */
+export declare function getDatabaseCollationDrift(pool: pg.Pool, dbName: string): Promise<CollationDrift | null>;
+/**
+ * Issue `REINDEX DATABASE CONCURRENTLY <quoted_db>`. Rebuilds every index in
+ * the database under the running libc collation rules.
+ *
+ * Identifier escaping uses `pg.escapeIdentifier` so a database name containing
+ * a double-quote (legal in Postgres) is quoted correctly.
+ *
+ * REINDEX DATABASE CONCURRENTLY refuses to run inside a transaction block, so
+ * the helper issues the query directly via `pool.query` (no explicit BEGIN);
+ * `node-postgres` does not start an implicit transaction.
+ */
+export declare function reindexDatabaseConcurrently(pool: pg.Pool, dbName: string): Promise<void>;
+/**
+ * Issue `ALTER DATABASE <quoted_db> REFRESH COLLATION VERSION`. Updates
+ * `pg_database.datcollversion` to match the running libc's reported version.
+ * Metadata-only; safe to run any time after a REINDEX has rebuilt the indexes.
+ */
+export declare function refreshDatabaseCollationVersion(pool: pg.Pool, dbName: string): Promise<void>;
+//# sourceMappingURL=db-collation.d.ts.map

package/dist/db-collation.js

@@ -0,0 +1,52 @@
+import "./chunk-gOLHoazu.js";
+import pg from "pg";
+//#region src/db-collation.ts
+/**
+* Read `pg_database.datcollversion` and
+* `pg_database_collation_actual_version(oid)` for `dbName` and return drift
+* details when they differ. Returns `null` when stamped === actual OR when
+* stamped is null (Postgres marks template0-style locked databases that way —
+* benign, no drift to report).
+*/
+async function getDatabaseCollationDrift(pool, dbName) {
+	const row = (await pool.query(`SELECT datcollversion AS stamped,
+            pg_database_collation_actual_version(oid) AS actual
+       FROM pg_database
+      WHERE datname = $1`, [dbName])).rows[0];
+	if (!row) throw new Error(`getDatabaseCollationDrift: database not found: ${dbName}`);
+	if (row.stamped === null) return null;
+	if (row.actual === null) throw new Error(`getDatabaseCollationDrift: pg_database_collation_actual_version returned null for ${dbName}`);
+	if (row.stamped === row.actual) return null;
+	return {
+		stamped: row.stamped,
+		actual: row.actual
+	};
+}
+/**
+* Issue `REINDEX DATABASE CONCURRENTLY <quoted_db>`. Rebuilds every index in
+* the database under the running libc collation rules.
+*
+* Identifier escaping uses `pg.escapeIdentifier` so a database name containing
+* a double-quote (legal in Postgres) is quoted correctly.
+*
+* REINDEX DATABASE CONCURRENTLY refuses to run inside a transaction block, so
+* the helper issues the query directly via `pool.query` (no explicit BEGIN);
+* `node-postgres` does not start an implicit transaction.
+*/
+async function reindexDatabaseConcurrently(pool, dbName) {
+	const quoted = pg.escapeIdentifier(dbName);
+	await pool.query(`REINDEX DATABASE CONCURRENTLY ${quoted}`);
+}
+/**
+* Issue `ALTER DATABASE <quoted_db> REFRESH COLLATION VERSION`. Updates
+* `pg_database.datcollversion` to match the running libc's reported version.
+* Metadata-only; safe to run any time after a REINDEX has rebuilt the indexes.
+*/
+async function refreshDatabaseCollationVersion(pool, dbName) {
+	const quoted = pg.escapeIdentifier(dbName);
+	await pool.query(`ALTER DATABASE ${quoted} REFRESH COLLATION VERSION`);
+}
+//#endregion
+export { getDatabaseCollationDrift, refreshDatabaseCollationVersion, reindexDatabaseConcurrently };
+
+//# sourceMappingURL=db-collation.js.map

package/dist/db-collation.test.d.ts

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

package/dist/env/allowlist.d.ts

@@ -53,12 +53,12 @@
  *   - Forgejo dev server  — FORGEJO_URL, FORGEJO_CONTAINER (read by the
  *                           staging Forgejo bootstrap script; conventional
  *                           names owned by Forgejo, not KiCI).
- *   - Zitadel SDK config  — ZITADEL_* (canonical names for the staging
- *                           Zitadel client config: issuer, project ID,
- *                           CLI client ID, test/admin user SUBs, the
- *                           staging Terraform PAT, and the management
- *                           API base URL). NOT aliases of `KICI_OIDC_*` —
- *                           these are the names Zitadel itself uses.
+ *   - Keycloak admin CLI  — KEYCLOAK_* (Keycloak's own admin tooling and
+ *                           docs use unprefixed `KEYCLOAK_BASE_URL`,
+ *                           `KEYCLOAK_ADMIN_CLIENT_ID`,
+ *                           `KEYCLOAK_ADMIN_CLIENT_SECRET`, etc. — the
+ *                           E2E admin helpers honour those names as a
+ *                           fallback after `KICI_KEYCLOAK_*`).
  *   - Vite client config  — VITE_* (Vite reserves this prefix for env
  *                           vars exposed to client bundles; `VITE_BASE`
  *                           and `VITE_DOCS_BASE_URL` flow through this

package/dist/env/allowlist.js

@@ -55,12 +55,12 @@ import "../chunk-gOLHoazu.js";
 *   - Forgejo dev server  — FORGEJO_URL, FORGEJO_CONTAINER (read by the
 *                           staging Forgejo bootstrap script; conventional
 *                           names owned by Forgejo, not KiCI).
-*   - Zitadel SDK config  — ZITADEL_* (canonical names for the staging
-*                           Zitadel client config: issuer, project ID,
-*                           CLI client ID, test/admin user SUBs, the
-*                           staging Terraform PAT, and the management
-*                           API base URL). NOT aliases of `KICI_OIDC_*` —
-*                           these are the names Zitadel itself uses.
+*   - Keycloak admin CLI  — KEYCLOAK_* (Keycloak's own admin tooling and
+*                           docs use unprefixed `KEYCLOAK_BASE_URL`,
+*                           `KEYCLOAK_ADMIN_CLIENT_ID`,
+*                           `KEYCLOAK_ADMIN_CLIENT_SECRET`, etc. — the
+*                           E2E admin helpers honour those names as a
+*                           fallback after `KICI_KEYCLOAK_*`).
 *   - Vite client config  — VITE_* (Vite reserves this prefix for env
 *                           vars exposed to client bundles; `VITE_BASE`
 *                           and `VITE_DOCS_BASE_URL` flow through this
@@ -70,7 +70,7 @@ import "../chunk-gOLHoazu.js";
 *                           the dev proxy), HEADED (Playwright convention
 *                           for `--headed` runs).
 */
-const OS_SDK_ALLOWLIST_REGEX = /^(KICI_.*|NODE_ENV|HOME|PATH|TZ|LANG|TMPDIR|USER|USERNAME|SHELL|COMSPEC|PWD|OLDPWD|HOSTNAME|COLUMNS|LINES|TERM|COLORTERM|DISPLAY|WAYLAND_DISPLAY|LOCALAPPDATA|XDG_CACHE_HOME|XDG_CONFIG_HOME|XDG_DATA_HOME|XDG_RUNTIME_DIR|XDG_STATE_HOME|INIT_CWD|npm_.*|SSH_.*|CI|GITHUB_ACTIONS|GITHUB_ENV|GITHUB_OUTPUT|GITHUB_PATH|GITHUB_STEP_SUMMARY|GITLAB_CI|AWS_.*|REDIS_.*|OTEL_.*|STRIPE_.*|DOCKER_.*|CONTAINER_HOST|container|PGHOST|PGPORT|PGUSER|PGPASSWORD|PGDATABASE|PGSERVICEFILE|PGSSLMODE|FORGEJO_URL|FORGEJO_CONTAINER|ZITADEL_.*|VITE_.*|PLAYWRIGHT|HEADED)$/;
+const OS_SDK_ALLOWLIST_REGEX = /^(KICI_.*|NODE_ENV|HOME|PATH|TZ|LANG|TMPDIR|USER|USERNAME|SHELL|COMSPEC|PWD|OLDPWD|HOSTNAME|COLUMNS|LINES|TERM|COLORTERM|DISPLAY|WAYLAND_DISPLAY|LOCALAPPDATA|XDG_CACHE_HOME|XDG_CONFIG_HOME|XDG_DATA_HOME|XDG_RUNTIME_DIR|XDG_STATE_HOME|INIT_CWD|npm_.*|SSH_.*|CI|GITHUB_ACTIONS|GITHUB_ENV|GITHUB_OUTPUT|GITHUB_PATH|GITHUB_STEP_SUMMARY|GITLAB_CI|AWS_.*|REDIS_.*|OTEL_.*|STRIPE_.*|DOCKER_.*|CONTAINER_HOST|container|PGHOST|PGPORT|PGUSER|PGPASSWORD|PGDATABASE|PGSERVICEFILE|PGSSLMODE|FORGEJO_URL|FORGEJO_CONTAINER|KEYCLOAK_.*|VITE_.*|PLAYWRIGHT|HEADED)$/;
 /**
 * Returns true when `name` is allowed under the KiCI env-var convention:
 * it matches the OS/SDK allowlist regex (which includes the `KICI_*`

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

@@ -19,12 +19,17 @@ export declare const LoggerEnvSchema: z.ZodObject<{
     KICI_LOG_DIR: z.ZodOptional<z.ZodString>;
     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";
+    }>>;
     KICI_CLUSTER_INSTANCE_ID: z.ZodOptional<z.ZodString>;
     KICI_AGENT_ID: z.ZodOptional<z.ZodString>;
     KICI_PLATFORM_INSTANCE_ID: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /** All env vars the logger reads, for the unknown-KICI-var scanner. */
-export declare const LOGGER_ENV_VARS: readonly ["KICI_LOG_DIR", "KICI_LOG_MAX_SIZE", "KICI_LOG_RETENTION_DAYS", "KICI_CLUSTER_INSTANCE_ID", "KICI_AGENT_ID", "KICI_PLATFORM_INSTANCE_ID"];
+export declare const LOGGER_ENV_VARS: readonly ["KICI_LOG_DIR", "KICI_LOG_MAX_SIZE", "KICI_LOG_RETENTION_DAYS", "KICI_LOG_FORMAT", "KICI_CLUSTER_INSTANCE_ID", "KICI_AGENT_ID", "KICI_PLATFORM_INSTANCE_ID"];
 /** Doc-friendly description map (consumed by the env-reference generator). */
 export declare const LOGGER_ENV_FIELD_SPECS: EnvFieldSpec[];
 //# sourceMappingURL=logger-env.d.ts.map

package/dist/env/logger-env.js

@@ -20,6 +20,17 @@ const LoggerEnvSchema = z.object({
 	KICI_LOG_DIR: z.string().optional(),
 	KICI_LOG_MAX_SIZE: z.string().default("500m"),
 	KICI_LOG_RETENTION_DAYS: z.coerce.number().default(7),
+	/**
+	* Output format selection: `auto` (default — JSON when stdout is piped,
+	* plain text when stdout is a TTY), `plain` (always pretty), or `json`
+	* (always structured). Runtime services pin this to `json` so a stray
+	* journal-attached PTY can never flip them into plain mode.
+	*/
+	KICI_LOG_FORMAT: z.enum([
+		"auto",
+		"plain",
+		"json"
+	]).default("auto"),
 	/** Set by the orchestrator process; used as a filename suffix. */
 	KICI_CLUSTER_INSTANCE_ID: z.string().optional(),
 	/** Set by the agent process; used as a filename suffix. */
@@ -32,6 +43,7 @@ const LOGGER_ENV_VARS = [
 	"KICI_LOG_DIR",
 	"KICI_LOG_MAX_SIZE",
 	"KICI_LOG_RETENTION_DAYS",
+	"KICI_LOG_FORMAT",
 	"KICI_CLUSTER_INSTANCE_ID",
 	"KICI_AGENT_ID",
 	"KICI_PLATFORM_INSTANCE_ID"
@@ -62,6 +74,15 @@ const LOGGER_ENV_FIELD_SPECS = [
 		type: "string",
 		description: "Directory for rotated JSON log files. When unset, the logger only writes to stdout/stderr."
 	},
+	{
+		envVar: "KICI_LOG_FORMAT",
+		aliases: [],
+		fieldPath: "KICI_LOG_FORMAT",
+		required: false,
+		defaultValue: "\"auto\"",
+		type: "enum:auto|plain|json",
+		description: "Output format for stdout/stderr. `auto` (default) emits JSON when stdout is piped and plain coloured text when stdout is a TTY. `plain` and `json` force the corresponding format regardless of TTY. Runtime services (orchestrator, agent, platform, dashboard SSR) pin `json` so a journal-attached PTY cannot flip them into plain mode."
+	},
 	{
 		envVar: "KICI_LOG_MAX_SIZE",
 		aliases: [],

package/dist/idempotency-env-diff.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Env-file semantic diff for the idempotent-step preview path.
+ *
+ * Inputs are the raw byte strings of two env files (local generated +
+ * remote-cat'd). Output is a sorted list of `EnvDiffEntry` records — one
+ * per key that was added, removed, or changed (plus an unchanged count).
+ *
+ * The renderer masks every value by default: an env file is sops-derived
+ * credential material in the deploy-prod context, and the confirm prompt
+ * is tee'd to `release-prod.log.<ts>`. Operators who need to see the
+ * actual values pass `--reveal-env-values` end-to-end (CLI flag → env var
+ * `KICI_REVEAL_ENV_VALUES=1` → `reveal: true` on this renderer). Without
+ * the flag the rendered output carries only the key name + classification.
+ */
+export type EnvDiffKind = 'added' | 'removed' | 'changed' | 'unchanged';
+export interface EnvDiffEntry {
+    key: string;
+    kind: EnvDiffKind;
+    /** Only populated for `changed` / `removed` kinds. */
+    oldValue?: string;
+    /** Only populated for `added` / `changed` kinds. */
+    newValue?: string;
+}
+/**
+ * Parse an env-file body into a `Map<string, string>`. The shape matches
+ * what Docker / systemd `EnvironmentFile=` / Keycloak's env loader consume:
+ *
+ *   - Blank lines and `#`-prefixed comments are skipped.
+ *   - The first `=` splits key and value; values may contain further `=`.
+ *   - Surrounding single or double quotes on the value are stripped when
+ *     they are balanced; otherwise the literal bytes are preserved.
+ *   - Duplicate keys: last write wins (POSIX shell semantics).
+ *   - Whitespace is stripped from the key only — values keep their bytes
+ *     verbatim so a trailing space in a credential is detected as drift.
+ */
+export declare function parseEnvLines(content: string): Map<string, string>;
+/**
+ * Diff two env-file bodies. Returns one entry per key in the union of
+ * both inputs. Entry order: `added`, `changed`, `removed`, `unchanged`,
+ * alphabetically inside each group.
+ *
+ * `local` is the new-side bytes (what the deploy would ship), `remote`
+ * is the old-side bytes (what's currently on the box). The convention
+ * matches `previewRsyncFileToBox`'s `localContent` / `remoteContent`
+ * field names.
+ */
+export declare function diffEnvFiles(local: string, remote: string): EnvDiffEntry[];
+export interface EnvDiffRenderOpts {
+    /** When true, show old + new values inline. Default false (masked output). */
+    reveal?: boolean;
+    /** When true, color the kind label with ANSI red/green/cyan. */
+    color?: boolean;
+}
+/**
+ * Render the env-semantic diff body lines. The returned array carries
+ * NO surrounding indentation — the caller (e.g. `renderFileDrifts`)
+ * decides how to nest each line under its containing per-file row.
+ *
+ * Masked layout (default):
+ *
+ *   KEY_A: changed
+ *   KEY_B: added
+ *   KEY_C: removed
+ *   3 other key(s) unchanged
+ *
+ * Revealed layout (`reveal: true`):
+ *
+ *   KEY_A: changed
+ *     - old=hunter2
+ *     + new=tr0ub4dor
+ *   KEY_B: added
+ *     + new=AKIA…
+ *   KEY_C: removed
+ *     - old=zzz
+ *   3 other key(s) unchanged
+ *
+ * When there are no changed / added / removed entries (every key matches
+ * byte-for-byte), the function returns a single "N key(s) unchanged"
+ * line so the operator gets a positive "in sync at the env level"
+ * confirmation rather than an empty body.
+ */
+export declare function renderEnvDiff(entries: EnvDiffEntry[], opts?: EnvDiffRenderOpts): string[];
+//# sourceMappingURL=idempotency-env-diff.d.ts.map

package/dist/idempotency-env-diff.js

@@ -0,0 +1,163 @@
+import "./chunk-gOLHoazu.js";
+//#region src/idempotency-env-diff.ts
+/**
+* Env-file semantic diff for the idempotent-step preview path.
+*
+* Inputs are the raw byte strings of two env files (local generated +
+* remote-cat'd). Output is a sorted list of `EnvDiffEntry` records — one
+* per key that was added, removed, or changed (plus an unchanged count).
+*
+* The renderer masks every value by default: an env file is sops-derived
+* credential material in the deploy-prod context, and the confirm prompt
+* is tee'd to `release-prod.log.<ts>`. Operators who need to see the
+* actual values pass `--reveal-env-values` end-to-end (CLI flag → env var
+* `KICI_REVEAL_ENV_VALUES=1` → `reveal: true` on this renderer). Without
+* the flag the rendered output carries only the key name + classification.
+*/
+const ANSI_RED = "\x1B[31m";
+const ANSI_GREEN = "\x1B[32m";
+const ANSI_CYAN = "\x1B[36m";
+const ANSI_RESET = "\x1B[0m";
+/**
+* Parse an env-file body into a `Map<string, string>`. The shape matches
+* what Docker / systemd `EnvironmentFile=` / Keycloak's env loader consume:
+*
+*   - Blank lines and `#`-prefixed comments are skipped.
+*   - The first `=` splits key and value; values may contain further `=`.
+*   - Surrounding single or double quotes on the value are stripped when
+*     they are balanced; otherwise the literal bytes are preserved.
+*   - Duplicate keys: last write wins (POSIX shell semantics).
+*   - Whitespace is stripped from the key only — values keep their bytes
+*     verbatim so a trailing space in a credential is detected as drift.
+*/
+function parseEnvLines(content) {
+	const out = /* @__PURE__ */ new Map();
+	for (const rawLine of content.split("\n")) {
+		const trimmedLeft = rawLine.replace(/\r$/, "").replace(/^[\t ]+/, "");
+		if (trimmedLeft === "") continue;
+		if (trimmedLeft.startsWith("#")) continue;
+		const eqIdx = trimmedLeft.indexOf("=");
+		if (eqIdx < 0) continue;
+		const key = trimmedLeft.slice(0, eqIdx).trim();
+		if (key === "") continue;
+		let value = trimmedLeft.slice(eqIdx + 1);
+		if (value.length >= 2 && (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'"))) value = value.slice(1, -1);
+		out.set(key, value);
+	}
+	return out;
+}
+/**
+* Diff two env-file bodies. Returns one entry per key in the union of
+* both inputs. Entry order: `added`, `changed`, `removed`, `unchanged`,
+* alphabetically inside each group.
+*
+* `local` is the new-side bytes (what the deploy would ship), `remote`
+* is the old-side bytes (what's currently on the box). The convention
+* matches `previewRsyncFileToBox`'s `localContent` / `remoteContent`
+* field names.
+*/
+function diffEnvFiles(local, remote) {
+	const localMap = parseEnvLines(local);
+	const remoteMap = parseEnvLines(remote);
+	const entries = [];
+	const keys = new Set([...localMap.keys(), ...remoteMap.keys()]);
+	for (const key of keys) {
+		const inLocal = localMap.has(key);
+		const inRemote = remoteMap.has(key);
+		const localValue = localMap.get(key);
+		const remoteValue = remoteMap.get(key);
+		if (inLocal && !inRemote) entries.push({
+			key,
+			kind: "added",
+			newValue: localValue
+		});
+		else if (!inLocal && inRemote) entries.push({
+			key,
+			kind: "removed",
+			oldValue: remoteValue
+		});
+		else if (inLocal && inRemote && localValue !== remoteValue) entries.push({
+			key,
+			kind: "changed",
+			oldValue: remoteValue,
+			newValue: localValue
+		});
+		else entries.push({
+			key,
+			kind: "unchanged"
+		});
+	}
+	const ORDER = {
+		added: 0,
+		changed: 1,
+		removed: 2,
+		unchanged: 3
+	};
+	entries.sort((a, b) => {
+		if (ORDER[a.kind] !== ORDER[b.kind]) return ORDER[a.kind] - ORDER[b.kind];
+		return a.key.localeCompare(b.key);
+	});
+	return entries;
+}
+/**
+* Render the env-semantic diff body lines. The returned array carries
+* NO surrounding indentation — the caller (e.g. `renderFileDrifts`)
+* decides how to nest each line under its containing per-file row.
+*
+* Masked layout (default):
+*
+*   KEY_A: changed
+*   KEY_B: added
+*   KEY_C: removed
+*   3 other key(s) unchanged
+*
+* Revealed layout (`reveal: true`):
+*
+*   KEY_A: changed
+*     - old=hunter2
+*     + new=tr0ub4dor
+*   KEY_B: added
+*     + new=AKIA…
+*   KEY_C: removed
+*     - old=zzz
+*   3 other key(s) unchanged
+*
+* When there are no changed / added / removed entries (every key matches
+* byte-for-byte), the function returns a single "N key(s) unchanged"
+* line so the operator gets a positive "in sync at the env level"
+* confirmation rather than an empty body.
+*/
+function renderEnvDiff(entries, opts = {}) {
+	const reveal = opts.reveal ?? false;
+	const color = opts.color ?? false;
+	const lines = [];
+	const changedish = entries.filter((e) => e.kind !== "unchanged");
+	let unchangedCount = entries.length - changedish.length;
+	for (const entry of changedish) {
+		lines.push(`${entry.key}: ${colorizeKind(entry.kind, color)}`);
+		if (reveal) {
+			if (entry.kind === "changed" || entry.kind === "removed") lines.push(`  ${colorize("- old=" + (entry.oldValue ?? ""), "old", color)}`);
+			if (entry.kind === "changed" || entry.kind === "added") lines.push(`  ${colorize("+ new=" + (entry.newValue ?? ""), "new", color)}`);
+		}
+	}
+	if (unchangedCount > 0) lines.push(`${unchangedCount} other key(s) unchanged`);
+	else if (lines.length === 0) lines.push(`0 key(s) drifted (env content matches)`);
+	return lines;
+}
+function colorizeKind(kind, color) {
+	if (!color) return kind;
+	switch (kind) {
+		case "added": return `${ANSI_GREEN}${kind}${ANSI_RESET}`;
+		case "removed": return `${ANSI_RED}${kind}${ANSI_RESET}`;
+		case "changed": return `${ANSI_CYAN}${kind}${ANSI_RESET}`;
+		case "unchanged": return kind;
+	}
+}
+function colorize(text, side, color) {
+	if (!color) return text;
+	return side === "new" ? `${ANSI_GREEN}${text}${ANSI_RESET}` : `${ANSI_RED}${text}${ANSI_RESET}`;
+}
+//#endregion
+export { diffEnvFiles, parseEnvLines, renderEnvDiff };
+
+//# sourceMappingURL=idempotency-env-diff.js.map

package/dist/idempotency-env-diff.test.d.ts

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