@kici-dev/shared 0.0.0 → 0.1.1

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

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

package/dist/db.d.ts

@@ -0,0 +1,14 @@
+import pg from 'pg';
+import { Kysely } from 'kysely';
+/**
+ * Create PostgreSQL connection pool.
+ */
+export declare function createPool(databaseUrl: string): pg.Pool;
+/**
+ * Create Kysely database instance (PostgreSQL only).
+ *
+ * Generic over the database type so each consumer can provide
+ * its own schema type (e.g., orchestrator Database vs Platform Database).
+ */
+export declare function createDb<T>(pool: pg.Pool): Kysely<T>;
+//# sourceMappingURL=db.d.ts.map

package/dist/db.js

@@ -0,0 +1,23 @@
+import "./chunk-gOLHoazu.js";
+import pg from "pg";
+import { Kysely, PostgresDialect } from "kysely";
+//#region src/db.ts
+/**
+* Create PostgreSQL connection pool.
+*/
+function createPool(databaseUrl) {
+	return new pg.Pool({ connectionString: databaseUrl });
+}
+/**
+* Create Kysely database instance (PostgreSQL only).
+*
+* Generic over the database type so each consumer can provide
+* its own schema type (e.g., orchestrator Database vs Platform Database).
+*/
+function createDb(pool) {
+	return new Kysely({ dialect: new PostgresDialect({ pool }) });
+}
+//#endregion
+export { createDb, createPool };
+
+//# sourceMappingURL=db.js.map

package/dist/env/allowlist.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Source of truth for the env-var allowlist.
+ *
+ * KiCI's naming convention:
+ *
+ *   > Every env var read by KiCI's own code MUST start with `KICI_`,
+ *   > except for a fixed allowlist of OS / SDK names that KiCI consumes
+ *   > but does not own (PATH, AWS_*, REDIS_*, OTEL_*, etc.).
+ *
+ * Two artefacts read this file:
+ *
+ *   1. `packages/shared/src/env/env-rule-allowlist.test.ts` — a runtime
+ *      backstop that walks the source tree and matches every
+ *      `process[.]env[.]NAME` access against `IS_ALLOWED_ENV_NAME(NAME)`.
+ *      Catches any read that the inline ESLint rule missed. The backstop
+ *      strips template-literal contents before scanning, so workflow
+ *      source code embedded in fixture-emitting helpers does NOT
+ *      contribute to the read set.
+ *   2. `eslint.config.js` — an inline `no-restricted-syntax` rule that
+ *      mirrors the same regex at lint time. The eslint config builds the
+ *      regex INLINE (it can't import from a TS file at lint init), so any
+ *      change here MUST also be reflected there. The backstop test fails
+ *      loudly if the two drift.
+ *
+ * The phased rename that introduced this rule (P0–P8) is complete: the
+ * `MIGRATING_ENV_VARS` ratchet is gone and `KICI_*` is the only accepted
+ * project-internal namespace. New env vars MUST use `KICI_*` — see
+ * `.claude/rules/env-vars.md` for the convention and how to add one
+ * (always `KICI_*`, register in the relevant package's `defineEnv`
+ * envMap, regenerate `docs/operator/env-reference.md`, done).
+ */
+/**
+ * Anchored regex matching the OS / SDK / external-system env var names
+ * that KiCI is the *consumer* of. KiCI does not own these names, so it
+ * can't prefix them. Plus the `KICI_*` prefix itself for everything we
+ * do own.
+ *
+ * Categories:
+ *   - `KICI_*`            — every project-internal env var.
+ *   - OS basics           — NODE_ENV, HOME, PATH, TZ, LANG, TMPDIR,
+ *                           USER, USERNAME, SHELL, COMSPEC, PWD, OLDPWD,
+ *                           HOSTNAME.
+ *   - Terminal / display  — COLUMNS, LINES, TERM, COLORTERM, DISPLAY,
+ *                           WAYLAND_DISPLAY, LOCALAPPDATA.
+ *   - XDG basedir spec    — XDG_*.
+ *   - npm / SSH wrappers  — INIT_CWD, npm_*, SSH_*.
+ *   - CI provider hints   — CI, GITHUB_ACTIONS, GITHUB_ENV, GITHUB_OUTPUT,
+ *                           GITHUB_PATH, GITHUB_STEP_SUMMARY, GITLAB_CI.
+ *   - Cloud / SDK names   — AWS_*, REDIS_*, OTEL_*, STRIPE_*, DOCKER_*,
+ *                           CONTAINER_HOST.
+ *   - Postgres libpq      — PGHOST, PGPORT, PGUSER, PGPASSWORD,
+ *                           PGDATABASE, PGSERVICEFILE, PGSSLMODE.
+ *   - 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.
+ *   - 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
+ *                           channel).
+ *   - Playwright runtime  — PLAYWRIGHT (test-runner-set switch the
+ *                           dashboard's vite.config consults to disable
+ *                           the dev proxy), HEADED (Playwright convention
+ *                           for `--headed` runs).
+ */
+export declare const OS_SDK_ALLOWLIST_REGEX: RegExp;
+/**
+ * Returns true when `name` is allowed under the KiCI env-var convention:
+ * it matches the OS/SDK allowlist regex (which includes the `KICI_*`
+ * prefix). The phased migration is complete; there is no longer a
+ * separate "migrating" set.
+ */
+export declare function IS_ALLOWED_ENV_NAME(name: string): boolean;
+//# sourceMappingURL=allowlist.d.ts.map

package/dist/env/allowlist.js

@@ -0,0 +1,86 @@
+import "../chunk-gOLHoazu.js";
+//#region src/env/allowlist.ts
+/**
+* Source of truth for the env-var allowlist.
+*
+* KiCI's naming convention:
+*
+*   > Every env var read by KiCI's own code MUST start with `KICI_`,
+*   > except for a fixed allowlist of OS / SDK names that KiCI consumes
+*   > but does not own (PATH, AWS_*, REDIS_*, OTEL_*, etc.).
+*
+* Two artefacts read this file:
+*
+*   1. `packages/shared/src/env/env-rule-allowlist.test.ts` — a runtime
+*      backstop that walks the source tree and matches every
+*      `process[.]env[.]NAME` access against `IS_ALLOWED_ENV_NAME(NAME)`.
+*      Catches any read that the inline ESLint rule missed. The backstop
+*      strips template-literal contents before scanning, so workflow
+*      source code embedded in fixture-emitting helpers does NOT
+*      contribute to the read set.
+*   2. `eslint.config.js` — an inline `no-restricted-syntax` rule that
+*      mirrors the same regex at lint time. The eslint config builds the
+*      regex INLINE (it can't import from a TS file at lint init), so any
+*      change here MUST also be reflected there. The backstop test fails
+*      loudly if the two drift.
+*
+* The phased rename that introduced this rule (P0–P8) is complete: the
+* `MIGRATING_ENV_VARS` ratchet is gone and `KICI_*` is the only accepted
+* project-internal namespace. New env vars MUST use `KICI_*` — see
+* `.claude/rules/env-vars.md` for the convention and how to add one
+* (always `KICI_*`, register in the relevant package's `defineEnv`
+* envMap, regenerate `docs/operator/env-reference.md`, done).
+*/
+/**
+* Anchored regex matching the OS / SDK / external-system env var names
+* that KiCI is the *consumer* of. KiCI does not own these names, so it
+* can't prefix them. Plus the `KICI_*` prefix itself for everything we
+* do own.
+*
+* Categories:
+*   - `KICI_*`            — every project-internal env var.
+*   - OS basics           — NODE_ENV, HOME, PATH, TZ, LANG, TMPDIR,
+*                           USER, USERNAME, SHELL, COMSPEC, PWD, OLDPWD,
+*                           HOSTNAME.
+*   - Terminal / display  — COLUMNS, LINES, TERM, COLORTERM, DISPLAY,
+*                           WAYLAND_DISPLAY, LOCALAPPDATA.
+*   - XDG basedir spec    — XDG_*.
+*   - npm / SSH wrappers  — INIT_CWD, npm_*, SSH_*.
+*   - CI provider hints   — CI, GITHUB_ACTIONS, GITHUB_ENV, GITHUB_OUTPUT,
+*                           GITHUB_PATH, GITHUB_STEP_SUMMARY, GITLAB_CI.
+*   - Cloud / SDK names   — AWS_*, REDIS_*, OTEL_*, STRIPE_*, DOCKER_*,
+*                           CONTAINER_HOST.
+*   - Postgres libpq      — PGHOST, PGPORT, PGUSER, PGPASSWORD,
+*                           PGDATABASE, PGSERVICEFILE, PGSSLMODE.
+*   - 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.
+*   - 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
+*                           channel).
+*   - Playwright runtime  — PLAYWRIGHT (test-runner-set switch the
+*                           dashboard's vite.config consults to disable
+*                           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)$/;
+/**
+* Returns true when `name` is allowed under the KiCI env-var convention:
+* it matches the OS/SDK allowlist regex (which includes the `KICI_*`
+* prefix). The phased migration is complete; there is no longer a
+* separate "migrating" set.
+*/
+function IS_ALLOWED_ENV_NAME(name) {
+	return OS_SDK_ALLOWLIST_REGEX.test(name);
+}
+//#endregion
+export { IS_ALLOWED_ENV_NAME, OS_SDK_ALLOWLIST_REGEX };
+
+//# sourceMappingURL=allowlist.js.map

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

@@ -0,0 +1,172 @@
+/**
+ * defineEnv — small helper that ties a Zod schema to its env-var mapping so
+ * services can:
+ *   1. parse process.env into a typed config (the existing pattern, just
+ *      centralised),
+ *   2. reject unknown KICI_* env vars (typo catcher),
+ *   3. emit machine-readable field metadata for docs/operator/env-reference.md.
+ *
+ * The helper deliberately stays small. Each service still owns its schema
+ * (defaults, refinements, cross-field rules); we only standardise the boring
+ * env-name <-> field-name plumbing and the "did you mean ...?" UX.
+ *
+ * `envMap` accepts:
+ *   - a string: the single env var that backs this top-level field, OR
+ *   - a string[]: multiple aliases, first non-undefined wins (legacy
+ *     pattern; the only historical user was the agent's
+ *     KICI_JOB_HEARTBEAT_INTERVAL_MS alias, collapsed in P3 of the
+ *     env-var standardization plan). OR
+ *   - an object: nested map for fields that are themselves z.object(...)
+ *     (orchestrator's `cluster: { instanceId: '...', ... }`). Nested objects
+ *     can recurse arbitrarily, but in practice we only need one level.
+ *
+ * The schema may be a plain z.object(...) OR a `.superRefine`'d composition
+ * built on top of one (orchestrator does this for cross-field rules). We keep
+ * the input type as `z.ZodType` so both shapes are accepted; we reach into
+ * `.shape` only when the caller asks for `describe()` output.
+ */
+import { z } from 'zod';
+/** Recursive env-var map. Leaf is the env var name (or array of aliases). */
+export type EnvMapValue = string | string[] | EnvMap;
+export interface EnvMap {
+    [field: string]: EnvMapValue;
+}
+/** Description of a single env var, suitable for docs generation. */
+export interface EnvFieldSpec {
+    /** Env var name (the canonical one when there are aliases). */
+    envVar: string;
+    /** Aliases (other env vars that map to the same field). */
+    aliases: string[];
+    /** Dotted JS path inside the parsed config (e.g. `cluster.instanceId`). */
+    fieldPath: string;
+    /** Whether the field is required (no default, not optional). */
+    required: boolean;
+    /** Default value, if present, formatted as a string. */
+    defaultValue?: string;
+    /** Type label (e.g. `string`, `number`, `enum:a|b`, `boolean`). */
+    type: string;
+    /** Description from the schema's `.describe()`, or an explicit override. */
+    description?: string;
+}
+export interface DefineEnvOptions<TShape extends z.ZodRawShape> {
+    /** Service identifier (free-form, used for docs grouping + error messages). */
+    service: string;
+    /**
+     * The Zod object schema. Pass the underlying ZodObject before any
+     * `.superRefine(...)` chain so we can walk `.shape` for docs metadata. The
+     * returned `parse()` runs the full schema (with refinements) — pass that as
+     * the `parser`.
+     */
+    schema: z.ZodObject<TShape>;
+    /** Optional outer schema (e.g., `schema.superRefine(...)` for cross-field). */
+    parser?: z.ZodType;
+    /** Mapping from field name (or nested path) to env var(s). */
+    envMap: EnvMap;
+    /** Optional per-field description override (keyed by dotted path). */
+    descriptions?: Record<string, string>;
+}
+export interface DefineEnvResult<T> {
+    /** Parse `env` (defaults to `process.env`) into a typed config. */
+    parse(env?: NodeJS.ProcessEnv): T;
+    /** Machine-readable field specs for docs generation. */
+    describe(): EnvFieldSpec[];
+    /** Flat list of every env var the schema reads (for the unknown-var scanner). */
+    listKnownEnvVars(): string[];
+    /** Subset of `listKnownEnvVars()` starting with `KICI_`. */
+    listKnownKiciVars(): string[];
+}
+/**
+ * Build a `defineEnv` helper for a service.
+ *
+ * Example:
+ *   const envDef = defineEnv({
+ *     service: 'agent',
+ *     schema: configSchema,
+ *     envMap: {
+ *       orchestratorUrl: 'KICI_ORCHESTRATOR_URL',
+ *       cluster: { instanceId: 'KICI_CLUSTER_INSTANCE_ID' },
+ *     },
+ *   });
+ *   const config = envDef.parse();
+ */
+export declare function defineEnv<TShape extends z.ZodRawShape>(opts: DefineEnvOptions<TShape>): DefineEnvResult<z.infer<z.ZodObject<TShape>>>;
+/**
+ * `KICI_*` env vars that are NOT part of any service's config schema but are
+ * legitimately set by packaging / tooling / dev shims. The scanner always
+ * allowlists these so the typo-catcher doesn't false-positive on them.
+ *
+ * - `KICI_CACHE`: set by the packaged CLI shim (packages/… .cmd and the
+ *   POSIX equivalent emitted by scripts/package.mjs) to point at the cached
+ *   Node.js binary. Inherited by the orchestrator/agent process on Windows
+ *   (on POSIX it's a shell-local var that doesn't leak).
+ * - `KICI_DEV`: the dev-mode toggle itself — read by the scanner to flip
+ *   to warn-only, so it must not trip the scanner.
+ *
+ * Keep this list small and well-justified. Every addition is a typo we can
+ * no longer catch, so only list things that are (a) actually set in the
+ * wild by our own tooling and (b) could never be a config typo.
+ */
+export declare const RESERVED_NON_SCHEMA_KICI_VARS: readonly string[];
+/**
+ * `KICI_*` prefixes that are entirely outside the service-config namespace —
+ * usually set by our own test / dev tooling and inherited into a child
+ * orchestrator/agent/platform process by mistake of inheritance rather than
+ * design. Any env var starting with one of these prefixes is treated as
+ * known, regardless of the specific suffix.
+ *
+ * - `KICI_E2E_`: the E2E framework's namespace (`KICI_E2E_PROVIDER`,
+ *   `KICI_E2E_MODE`, future E2E toggles). Set by `e2e/vitest.*.config.ts`
+ *   files. The native orchestrator spawn in `e2e/helpers/deploy.ts`
+ *   inherits the test runner's process.env, so these leak in.
+ * - `KICI_AGENT_ENV_`: the agent-env forwarding namespace (see
+ *   `@kici-dev/engine` → `KICI_AGENT_ENV_PREFIX`). Any env var set on the
+ *   orchestrator process with this prefix is stripped and forwarded into
+ *   the spawned agent (bare-metal, container, or Firecracker MMDS). The
+ *   suffix is by design arbitrary and user-controlled, so it cannot be
+ *   enumerated in the schema.
+ *
+ * As with RESERVED_NON_SCHEMA_KICI_VARS, keep this short — each prefix
+ * widens the set of names we can no longer catch as typos.
+ */
+export declare const RESERVED_NON_SCHEMA_KICI_PREFIXES: readonly string[];
+/**
+ * `KICI_*` suffix patterns that mark vars outside the service-config namespace.
+ * A var is treated as known when its name ends with any listed suffix
+ * (or the suffix appears as a boundary segment — matching
+ * `${suffix}$|${suffix}_`, same rule as the agent's probe collector).
+ *
+ * - `_ENV_PROBE`: diagnostic probe vars (see `packages/agent/src/server.ts` —
+ *   the agent collects every `KICI_*_ENV_PROBE` var and logs its value in
+ *   "Agent startup env probes (diagnostic)"). The E2E firecracker-pipeline
+ *   test uses `KICI_AGENT_ENV_KICI_FC_ENV_PROBE=fc-probe-value` which flows
+ *   through the scaler's env-forwarding path and lands in the agent's
+ *   process.env as `KICI_FC_ENV_PROBE`. Without this suffix allowlist the
+ *   validator rejects it as an unknown KICI_* var and the agent refuses to
+ *   start — defeating the test's entire purpose.
+ *
+ * As with RESERVED_NON_SCHEMA_KICI_VARS / _PREFIXES, keep this short. Every
+ * suffix widens the set of names we can no longer catch as typos.
+ */
+export declare const RESERVED_NON_SCHEMA_KICI_SUFFIXES: readonly string[];
+export interface ValidateUnknownKiciVarsOptions {
+    /** Extra env-var names to treat as known (not all consumers can be migrated in one go). */
+    extraKnown?: string[];
+    /**
+     * When `true` (default in dev mode), unknown KICI_* vars only log a warning
+     * via `onWarn`. When `false`, throw — the production behaviour.
+     */
+    warnOnly?: boolean;
+    /** Logger callback for warn-mode (defaults to `console.warn`). */
+    onWarn?: (msg: string) => void;
+}
+/**
+ * Inspect `env` for KICI_* keys that are not in `known`. Throws (or warns,
+ * see options) with a single combined message listing every unknown var and
+ * its closest legitimate match (when the Levenshtein distance is small).
+ *
+ * Production mode (the default): throws — staging deploys should never reach
+ * runtime with a typo'd KICI_* variable. Set `KICI_DEV=true` (or pass
+ * `warnOnly: true`) to downgrade to a warning during local development.
+ */
+export declare function validateUnknownKiciVars(known: string[], options?: ValidateUnknownKiciVarsOptions, env?: NodeJS.ProcessEnv): void;
+//# sourceMappingURL=define-env.d.ts.map

package/dist/env/define-env.js

@@ -0,0 +1,295 @@
+import "../chunk-gOLHoazu.js";
+//#region src/env/define-env.ts
+/** Read an env value following the alias precedence (first non-undefined wins). */
+function readEnv(envMap, env) {
+	if (typeof envMap === "string") return env[envMap];
+	if (Array.isArray(envMap)) {
+		for (const name of envMap) {
+			const v = env[name];
+			if (v !== void 0) return v;
+		}
+		return;
+	}
+	const result = {};
+	for (const [k, v] of Object.entries(envMap)) result[k] = readEnv(v, env);
+	return result;
+}
+/** Walk an EnvMap and yield every leaf env var name. */
+function* walkEnvNames(envMap) {
+	for (const value of Object.values(envMap)) if (typeof value === "string") yield value;
+	else if (Array.isArray(value)) for (const name of value) yield name;
+	else yield* walkEnvNames(value);
+}
+/** Best-effort type label for docs. Walks through default / optional / pipe / transform wrappers. */
+function describeType(field) {
+	let t = field;
+	for (let i = 0; i < 8; i++) {
+		const def = t.def;
+		if (!def) return "unknown";
+		switch (def.type) {
+			case "string": return "string";
+			case "number": return "number";
+			case "boolean": return "boolean";
+			case "enum": return `enum:${(def.entries ? Object.keys(def.entries) : def.values ?? []).join("|")}`;
+			case "object": return "object";
+			case "optional":
+			case "default":
+			case "nullable":
+				if (def.innerType) {
+					t = def.innerType;
+					continue;
+				}
+				return def.type ?? "unknown";
+			case "pipe":
+				if (def.in) {
+					t = def.in;
+					continue;
+				}
+				return "string";
+			case "transform": return "string";
+			case "union": return "union";
+			default: return def.type ?? "unknown";
+		}
+	}
+	return "unknown";
+}
+/** Best-effort default value extraction for docs. Recurses into pipe/transform wrappers. */
+function extractDefault(field) {
+	let t = field;
+	for (let i = 0; i < 6; i++) {
+		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);
+		}
+		if (def.in) {
+			t = def.in;
+			continue;
+		}
+		if (def.innerType) {
+			t = def.innerType;
+			continue;
+		}
+		return;
+	}
+}
+function isOptional(field) {
+	let t = 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.in) {
+			t = def.in;
+			continue;
+		}
+		if (def.innerType) {
+			t = def.innerType;
+			continue;
+		}
+		return false;
+	}
+	return false;
+}
+function describeFieldRecursive(shape, envMap, fieldPath, descriptions, out) {
+	for (const [name, field] of Object.entries(shape)) {
+		const path = fieldPath ? `${fieldPath}.${name}` : name;
+		const mapping = envMap[name];
+		if (mapping === void 0) continue;
+		if (typeof mapping === "string" || Array.isArray(mapping)) {
+			const aliases = Array.isArray(mapping) ? mapping : [mapping];
+			const explicitDesc = descriptions?.[path];
+			const zodDesc = field.description;
+			const def2 = field.def;
+			out.push({
+				envVar: aliases[0],
+				aliases: aliases.slice(1),
+				fieldPath: path,
+				required: !isOptional(field) && extractDefault(field) === void 0,
+				defaultValue: extractDefault(field),
+				type: describeType(field),
+				description: explicitDesc ?? zodDesc ?? def2?.description
+			});
+		} else {
+			const nested = field;
+			const innerShape = nested.shape ?? nested.def?.shape;
+			if (innerShape) describeFieldRecursive(innerShape, mapping, path, descriptions, out);
+		}
+	}
+}
+/**
+* Build a `defineEnv` helper for a service.
+*
+* Example:
+*   const envDef = defineEnv({
+*     service: 'agent',
+*     schema: configSchema,
+*     envMap: {
+*       orchestratorUrl: 'KICI_ORCHESTRATOR_URL',
+*       cluster: { instanceId: 'KICI_CLUSTER_INSTANCE_ID' },
+*     },
+*   });
+*   const config = envDef.parse();
+*/
+function defineEnv(opts) {
+	const parserSchema = opts.parser ?? opts.schema;
+	function parse(env = process.env) {
+		const raw = readEnv(opts.envMap, env);
+		const result = parserSchema.safeParse(raw);
+		if (!result.success) {
+			const errors = result.error.issues.map((err) => `  - ${err.path.join(".")}: ${err.message}`).join("\n");
+			throw new Error(`Configuration validation failed:\n${errors}`);
+		}
+		return result.data;
+	}
+	function describe() {
+		const out = [];
+		describeFieldRecursive(opts.schema.shape, opts.envMap, "", opts.descriptions, out);
+		return out.sort((a, b) => a.envVar.localeCompare(b.envVar));
+	}
+	function listKnownEnvVars() {
+		return [...new Set(walkEnvNames(opts.envMap))].sort();
+	}
+	function listKnownKiciVars() {
+		return listKnownEnvVars().filter((n) => n.startsWith("KICI_"));
+	}
+	return {
+		parse,
+		describe,
+		listKnownEnvVars,
+		listKnownKiciVars
+	};
+}
+/**
+* Levenshtein distance between two strings. Small + dependency-free; we only
+* use it to suggest alternates for unknown KICI_* env vars at boot. O(n*m) is
+* fine because both strings are short env var names.
+*/
+function levenshtein(a, b) {
+	if (a === b) return 0;
+	if (!a.length) return b.length;
+	if (!b.length) return a.length;
+	const prev = new Array(b.length + 1);
+	const curr = new Array(b.length + 1);
+	for (let j = 0; j <= b.length; j++) prev[j] = j;
+	for (let i = 1; i <= a.length; i++) {
+		curr[0] = i;
+		for (let j = 1; j <= b.length; j++) {
+			const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+			curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+		}
+		for (let j = 0; j <= b.length; j++) prev[j] = curr[j];
+	}
+	return prev[b.length];
+}
+function suggestClosest(name, candidates) {
+	let best;
+	for (const c of candidates) {
+		const d = levenshtein(name, c);
+		if (best === void 0 || d < best.dist) best = {
+			name: c,
+			dist: d
+		};
+	}
+	if (best && best.dist <= Math.max(2, Math.floor(name.length / 4))) return best.name;
+}
+/**
+* `KICI_*` env vars that are NOT part of any service's config schema but are
+* legitimately set by packaging / tooling / dev shims. The scanner always
+* allowlists these so the typo-catcher doesn't false-positive on them.
+*
+* - `KICI_CACHE`: set by the packaged CLI shim (packages/… .cmd and the
+*   POSIX equivalent emitted by scripts/package.mjs) to point at the cached
+*   Node.js binary. Inherited by the orchestrator/agent process on Windows
+*   (on POSIX it's a shell-local var that doesn't leak).
+* - `KICI_DEV`: the dev-mode toggle itself — read by the scanner to flip
+*   to warn-only, so it must not trip the scanner.
+*
+* Keep this list small and well-justified. Every addition is a typo we can
+* no longer catch, so only list things that are (a) actually set in the
+* wild by our own tooling and (b) could never be a config typo.
+*/
+const RESERVED_NON_SCHEMA_KICI_VARS = ["KICI_CACHE", "KICI_DEV"];
+/**
+* `KICI_*` prefixes that are entirely outside the service-config namespace —
+* usually set by our own test / dev tooling and inherited into a child
+* orchestrator/agent/platform process by mistake of inheritance rather than
+* design. Any env var starting with one of these prefixes is treated as
+* known, regardless of the specific suffix.
+*
+* - `KICI_E2E_`: the E2E framework's namespace (`KICI_E2E_PROVIDER`,
+*   `KICI_E2E_MODE`, future E2E toggles). Set by `e2e/vitest.*.config.ts`
+*   files. The native orchestrator spawn in `e2e/helpers/deploy.ts`
+*   inherits the test runner's process.env, so these leak in.
+* - `KICI_AGENT_ENV_`: the agent-env forwarding namespace (see
+*   `@kici-dev/engine` → `KICI_AGENT_ENV_PREFIX`). Any env var set on the
+*   orchestrator process with this prefix is stripped and forwarded into
+*   the spawned agent (bare-metal, container, or Firecracker MMDS). The
+*   suffix is by design arbitrary and user-controlled, so it cannot be
+*   enumerated in the schema.
+*
+* As with RESERVED_NON_SCHEMA_KICI_VARS, keep this short — each prefix
+* widens the set of names we can no longer catch as typos.
+*/
+const RESERVED_NON_SCHEMA_KICI_PREFIXES = ["KICI_E2E_", "KICI_AGENT_ENV_"];
+/**
+* `KICI_*` suffix patterns that mark vars outside the service-config namespace.
+* A var is treated as known when its name ends with any listed suffix
+* (or the suffix appears as a boundary segment — matching
+* `${suffix}$|${suffix}_`, same rule as the agent's probe collector).
+*
+* - `_ENV_PROBE`: diagnostic probe vars (see `packages/agent/src/server.ts` —
+*   the agent collects every `KICI_*_ENV_PROBE` var and logs its value in
+*   "Agent startup env probes (diagnostic)"). The E2E firecracker-pipeline
+*   test uses `KICI_AGENT_ENV_KICI_FC_ENV_PROBE=fc-probe-value` which flows
+*   through the scaler's env-forwarding path and lands in the agent's
+*   process.env as `KICI_FC_ENV_PROBE`. Without this suffix allowlist the
+*   validator rejects it as an unknown KICI_* var and the agent refuses to
+*   start — defeating the test's entire purpose.
+*
+* As with RESERVED_NON_SCHEMA_KICI_VARS / _PREFIXES, keep this short. Every
+* suffix widens the set of names we can no longer catch as typos.
+*/
+const RESERVED_NON_SCHEMA_KICI_SUFFIXES = ["_ENV_PROBE"];
+/**
+* Inspect `env` for KICI_* keys that are not in `known`. Throws (or warns,
+* see options) with a single combined message listing every unknown var and
+* its closest legitimate match (when the Levenshtein distance is small).
+*
+* Production mode (the default): throws — staging deploys should never reach
+* runtime with a typo'd KICI_* variable. Set `KICI_DEV=true` (or pass
+* `warnOnly: true`) to downgrade to a warning during local development.
+*/
+function validateUnknownKiciVars(known, options = {}, env = process.env) {
+	const knownSet = new Set([
+		...known,
+		...options.extraKnown ?? [],
+		...RESERVED_NON_SCHEMA_KICI_VARS
+	]);
+	const unknown = [];
+	for (const key of Object.keys(env)) {
+		if (!key.startsWith("KICI_")) continue;
+		if (knownSet.has(key)) continue;
+		if (RESERVED_NON_SCHEMA_KICI_PREFIXES.some((p) => key.startsWith(p))) continue;
+		if (RESERVED_NON_SCHEMA_KICI_SUFFIXES.some((s) => key.endsWith(s) || key.includes(`${s}_`))) continue;
+		unknown.push({
+			name: key,
+			suggestion: suggestClosest(key, [...knownSet])
+		});
+	}
+	if (unknown.length === 0) return;
+	const header = `Unknown KICI_* env var(s) detected — refusing to start.
+Set KICI_DEV=true to downgrade this check to a warning.
+Unknown vars:\n${unknown.map(({ name, suggestion }) => suggestion ? `  - ${name}    (did you mean ${suggestion}?)` : `  - ${name}    (no close match in the schema)`).join("\n")}`;
+	if (options.warnOnly ?? env.KICI_DEV === "true") {
+		(options.onWarn ?? console.warn)(header);
+		return;
+	}
+	throw new Error(header);
+}
+//#endregion
+export { RESERVED_NON_SCHEMA_KICI_PREFIXES, RESERVED_NON_SCHEMA_KICI_SUFFIXES, RESERVED_NON_SCHEMA_KICI_VARS, defineEnv, validateUnknownKiciVars };
+
+//# sourceMappingURL=define-env.js.map

package/dist/env/define-env.test.d.ts

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