@voltro/env 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,352 @@
+import { Schema } from 'effect';
+
+/**
+ * The type-erased field shape, used where the value type is irrelevant (the
+ * declared map, iteration). It is NOT `EnvFieldSpec<unknown>` because
+ * effect's `Schema` is invariant in its decoded type — a concrete
+ * `EnvFieldSpec<number>` would not widen to that. Typing the schema as
+ * `Schema.Schema.Any` lets any concrete field assign here.
+ */
+export declare interface AnyEnvFieldSpec {
+    readonly kind: EnvFieldKind;
+    readonly access: EnvAccess;
+    readonly schema: Schema.Schema.Any;
+    readonly tsType: string;
+    readonly optional: boolean;
+    readonly default?: string | undefined;
+    readonly description?: string | undefined;
+    readonly example?: string | undefined;
+}
+
+/** Project an app's `defineEnv` contract onto manifest entries. */
+export declare const appEnvEntries: (contract: EnvContract | undefined) => ReadonlyArray<EnvManifestEntry>;
+
+/**
+ * Enforce the public-prefix invariant (t3-env's client-prefix rule,
+ * framework-branded). Returns naming errors to merge with the value errors:
+ *
+ *  - On a WEB app, every `access: 'public'` var (browser-exposed) MUST start
+ *    with the contract's `publicPrefix` (default `VOLTRO_PUBLIC_`).
+ *  - ANY `access: 'secret'` var MUST NOT start with the prefix (the prefix
+ *    marks browser-bound public values; a secret carrying it is a contradiction).
+ *
+ * `publicPrefix: false` opts out. API apps skip the public-prefix requirement
+ * (their public vars are non-sensitive SERVER config, never browser-bound) but
+ * still get the secret-must-not-be-prefixed check.
+ */
+export declare const checkEnvNaming: (contract: EnvContract | undefined, appType: "api" | "web") => ReadonlyArray<EnvResolveError>;
+
+/** A plugin's declared env need — metadata only, NOT a read path. Mirror what
+ *  the plugin actually reads via `options.X ?? process.env.X`. */
+export declare interface DeclaredEnvVar {
+    readonly name: string;
+    readonly required: boolean;
+    readonly secret: boolean;
+    readonly description?: string;
+    readonly example?: string;
+}
+
+/** The framework's default prefix for browser-exposed PUBLIC env vars. */
+export declare const DEFAULT_PUBLIC_PREFIX = "VOLTRO_PUBLIC_";
+
+/**
+ * Declare an app's environment contract. Call this in `app.config.ts` and put
+ * the result on the default export's `env` field:
+ *
+ * ```ts
+ * // app.config.ts
+ * import { defineEnv, envVar } from '@voltro/env'
+ *
+ * export const env = defineEnv({
+ *   SENTRY_DSN: envVar.string({ access: 'public' }),
+ *   STRIPE_KEY: envVar.string({ access: 'secret' }),
+ * })
+ *
+ * export default { type: 'api', name: 'myApi', env }
+ * ```
+ *
+ * The returned contract is the single source of truth: the CLI reads it to
+ * validate `process.env` at boot, to bake the public subset into the web
+ * bundle, to generate the typed `@voltro/env/server` + `@voltro/env/public`
+ * accessors, and to emit `.env.example` + the inspect manifest.
+ *
+ * You do NOT read values off the contract directly — read `serverEnv` /
+ * `getSecret` from `@voltro/env/server` (server) or `publicEnv` from
+ * `@voltro/env/public` (browser).
+ *
+ * `M` is inferred from the literal map, so the contract's phantom value types
+ * are exact (`{ SENTRY_DSN: string; STRIPE_KEY: string }` above).
+ */
+export declare const defineEnv: <const M extends EnvSchemaMap>(vars: M, options?: DefineEnvOptions) => EnvContract<M>;
+
+export declare interface DefineEnvOptions {
+    /**
+     * Required name prefix for browser-exposed public vars. Default
+     * `VOLTRO_PUBLIC_`. Pass a different string to brand it your own way, or
+     * `false` to disable the prefix invariant entirely.
+     */
+    readonly publicPrefix?: string | false;
+}
+
+declare const ENV_CONTRACT_BRAND: unique symbol;
+
+/** Whether a variable may cross the browser boundary. */
+export declare type EnvAccess = 'public' | 'secret';
+
+/**
+ * The frozen result of `defineEnv(...)`. Carries the declaration the CLI
+ * reads at boot, plus phantom type members the framework's codegen uses to
+ * derive the typed `@voltro/env/server` + `@voltro/env/public` accessors.
+ *
+ * You reference it from `app.config.ts` (`export const env = defineEnv(...)`,
+ * then `env` on the default export). You do NOT read values off it directly —
+ * read `serverEnv` / `getSecret` (server) or `publicEnv` (browser).
+ */
+export declare interface EnvContract<M extends EnvSchemaMap = EnvSchemaMap> {
+    readonly [ENV_CONTRACT_BRAND]: true;
+    /** The declared variables, keyed by env-var name. */
+    readonly vars: M;
+    /**
+     * Required name prefix for BROWSER-EXPOSED public vars (default
+     * `VOLTRO_PUBLIC_`). On a web app, every `access: 'public'` var (which ships
+     * to the browser) MUST carry this prefix, and no `access: 'secret'` var may —
+     * so the name and the access tag can never silently disagree (t3-env's
+     * client-prefix invariant, framework-branded). `false` opts out of the check.
+     */
+    readonly publicPrefix: string | false;
+    /** Phantom — resolved server value shape (never present at runtime). */
+    readonly _values?: EnvValues<M>;
+    /** Phantom — browser-visible (public) value shape. */
+    readonly _public?: PublicEnvValues<M>;
+}
+
+/** The concrete coercion a field performs on the raw string env value. */
+export declare type EnvFieldKind = 'string' | 'number' | 'boolean' | 'enum' | 'url' | 'port';
+
+/**
+ * A single declared environment variable. Produced by the `envVar.*`
+ * builders — you never construct this by hand. `A` is the decoded value
+ * type; `Optional` lifts "may be absent" to the type level so the inferred
+ * accessor is `A | undefined` for optional vars and `A` otherwise.
+ */
+export declare interface EnvFieldSpec<A = unknown, Optional extends boolean = boolean> {
+    readonly kind: EnvFieldKind;
+    /** Browser boundary classification — mandatory, no default. */
+    readonly access: EnvAccess;
+    /** effect/Schema that decodes the RAW string env value → typed `A`. */
+    readonly schema: Schema.Schema<A, string>;
+    /**
+     * TypeScript type literal for the codegen'd typed accessors — e.g.
+     * `"string"`, `"number"`, `"'dev' | 'prod'"`. Bounded to what the
+     * builders emit, so the generated `.d.ts` augmentation is precise.
+     */
+    readonly tsType: string;
+    /** When true, an unset var (no value, no default) is allowed → `A | undefined`. */
+    readonly optional: Optional;
+    /** Fallback applied (in raw string form) when the env var is unset. */
+    readonly default?: string | undefined;
+    /** One-line description — surfaced in `.env.example` + the inspect manifest. */
+    readonly description?: string | undefined;
+    /** Example value for `.env.example`. NEVER a real secret — a placeholder. */
+    readonly example?: string | undefined;
+}
+
+export declare interface EnvManifestEntry {
+    readonly key: string;
+    readonly owner: EnvOwner;
+    /** `'secret'` → never print the value (sensitive: token / password / URL
+     *  with credentials). `'public'` → a non-sensitive knob. For app vars this
+     *  is also the browser-bundle boundary. */
+    readonly access: EnvAccess;
+    /** Required (no default, not optional). Drives `.env.example` ordering +
+     *  the "missing required" boot report. */
+    readonly required: boolean;
+    readonly description?: string;
+    readonly example?: string;
+    readonly default?: string;
+    /** App fields carry their coercion kind; framework/plugin entries omit it. */
+    readonly kind?: EnvFieldKind;
+    /** Framework grouping for `.env.example` section headers. */
+    readonly group?: string;
+}
+
+export declare type EnvOwner = 'app' | 'framework' | `plugin:${string}`;
+
+export declare interface EnvResolveError {
+    readonly key: string;
+    readonly access: EnvAccess;
+    /** `'missing'` (required but unset) or `'invalid'` (failed the Schema). */
+    readonly reason: 'missing' | 'invalid';
+    readonly message: string;
+}
+
+/** The declared variable map passed to `defineEnv`. */
+export declare type EnvSchemaMap = Record<string, AnyEnvFieldSpec>;
+
+/** The fully-resolved server value shape for a contract (public + secret). */
+export declare type EnvValues<M extends EnvSchemaMap> = {
+    readonly [K in keyof M]: InferEnvValue<M[K]>;
+};
+
+/**
+ * The field-builder surface used inside `defineEnv({...})`.
+ *
+ * ```ts
+ * env: defineEnv({
+ *   SENTRY_DSN:  envVar.string({ access: 'public', description: 'Browser Sentry DSN' }),
+ *   APP_TITLE:   envVar.string({ access: 'public', default: 'Voltro' }),
+ *   PORT:        envVar.port({ access: 'public', default: '4000' }),
+ *   FEATURE_X:   envVar.boolean({ access: 'public', default: 'false' }),
+ *   LOG_LEVEL:   envVar.enum(['debug', 'info', 'warn'], { access: 'public', default: 'info' }),
+ *   STRIPE_KEY:  envVar.string({ access: 'secret' }),
+ *   WEBHOOK_URL: envVar.url({ access: 'secret', optional: true }),
+ * })
+ * ```
+ */
+export declare const envVar: {
+    /** A plain string. */
+    readonly string: <O extends boolean = false>(opts: FieldOptions<O>) => EnvFieldSpec<string, O>;
+    /** A number, coerced from its string form (`"5"` → `5`). */
+    readonly number: <O extends boolean = false>(opts: FieldOptions<O>) => EnvFieldSpec<number, O>;
+    /** A TCP port — number in `1..65535`, coerced from string. */
+    readonly port: <O extends boolean = false>(opts: FieldOptions<O>) => EnvFieldSpec<number, O>;
+    /** A boolean, coerced from `true/false/1/0/yes/no/on/off`. */
+    readonly boolean: <O extends boolean = false>(opts: FieldOptions<O>) => EnvFieldSpec<boolean, O>;
+    /** A URL string, validated with the `URL` constructor. */
+    readonly url: <O extends boolean = false>(opts: FieldOptions<O>) => EnvFieldSpec<string, O>;
+    /** A string constrained to a closed set — typed as the literal union. */
+    readonly enum: <const T extends readonly [string, ...string[]], O extends boolean = false>(values: T, opts: FieldOptions<O>) => EnvFieldSpec<T[number], O>;
+};
+
+/** Common options every field accepts. `O` lifts `optional` to the type level. */
+export declare interface FieldOptions<O extends boolean = false> {
+    /** Browser boundary classification — MANDATORY. `'public'` is bundled into
+     *  the browser; `'secret'` stays server-only. There is no default. */
+    readonly access: EnvAccess;
+    /** Allow the variable to be absent (no value, no default). Makes the
+     *  accessor type `A | undefined`. Use `default` instead when there is a
+     *  sensible fallback. */
+    readonly optional?: O;
+    /** Fallback (raw string) applied when the env var is unset. With a default
+     *  the value is always present, so the accessor type stays `A`. */
+    readonly default?: string;
+    /** One-line description — shown in `.env.example` + the inspect manifest. */
+    readonly description?: string;
+    /** Example value for `.env.example`. Never a real secret — a placeholder. */
+    readonly example?: string;
+}
+
+/**
+ * Render aggregated errors into a single multi-line message for a boot abort.
+ * Mirrors the per-plugin config-decode failure shape so the boot log reads
+ * consistently across config validation surfaces.
+ */
+export declare const formatEnvErrors: (errors: ReadonlyArray<EnvResolveError>) => string;
+
+/**
+ * The framework's own user-facing env vars. Curated, not exhaustive — the
+ * goal is "what an operator configures", not every internal/test knob. This
+ * is the single source for the `.env.example` framework section + the turbo
+ * `globalPassThroughEnv` list. Add new operator-facing framework vars HERE.
+ */
+export declare const FRAMEWORK_ENV_CATALOG: ReadonlyArray<EnvManifestEntry>;
+
+/** Just the framework var NAMES — the source for turbo `globalPassThroughEnv`. */
+export declare const frameworkEnvNames: () => ReadonlyArray<string>;
+
+/** True once the boot gate has installed a snapshot. */
+export declare const hasEnvSnapshot: () => boolean;
+
+/** Lift a field's optionality + value type to the accessor's value type. */
+export declare type InferEnvValue<F> = F extends EnvFieldSpec<infer A, infer O> ? (O extends true ? A | undefined : A) : never;
+
+/** Install the boot-resolved value map. Called once by the CLI after the
+ *  env-validation gate passes. Idempotent: a second install replaces the
+ *  first (a supervised dev restart re-resolves cleanly). */
+export declare const installEnvSnapshot: (values: Record<string, unknown>) => void;
+
+/** Runtime type guard: is `value` an `EnvContract`? Used by the CLI loader,
+ *  which sees the app.config default export as `unknown`. */
+export declare const isEnvContract: (value: unknown) => value is EnvContract;
+
+export declare interface PluginEnv {
+    /** The declared variables — assign this to the plugin's `declaredEnv`. */
+    readonly declared: ReadonlyArray<DeclaredEnvVar>;
+    /**
+     * Read a DECLARED env var: `override ?? process.env[name]`. Throws if `name`
+     * is not in the declaration — so a typo or an undeclared read fails loudly at
+     * the call site instead of silently drifting from the manifest.
+     */
+    read(name: string, override?: string): string | undefined;
+}
+
+export declare const pluginEnv: (declared: ReadonlyArray<DeclaredEnvVar>) => PluginEnv;
+
+/** Project a plugin's `declaredEnv` onto manifest entries. */
+export declare const pluginEnvEntries: (pluginName: string, declared: ReadonlyArray<DeclaredEnvVar> | undefined) => ReadonlyArray<EnvManifestEntry>;
+
+/** The browser-visible value shape (public fields only). */
+export declare type PublicEnvValues<M extends EnvSchemaMap> = {
+    readonly [K in PublicKeys<M>]: InferEnvValue<M[K]>;
+};
+
+/** Keys of `M` whose field is `access: 'public'`. */
+export declare type PublicKeys<M extends EnvSchemaMap> = {
+    [K in keyof M]: M[K]['access'] extends 'public' ? K : never;
+}[keyof M];
+
+/** Read a resolved value. Returns `undefined` for unknown / unset keys. */
+export declare const readEnvValue: (key: string) => unknown;
+
+/**
+ * Render a grouped `.env.example`. App + plugin entries come first (the things
+ * a developer must fill in), then the framework catalog grouped by area.
+ */
+export declare const renderDotEnvExample: (entries: ReadonlyArray<EnvManifestEntry>, opts?: RenderDotEnvOptions) => string;
+
+export declare interface RenderDotEnvOptions {
+    /** Header comment lines (without the leading `# `). */
+    readonly header?: ReadonlyArray<string>;
+    /** Include the framework catalog section. Default true. */
+    readonly includeFramework?: boolean;
+}
+
+/**
+ * Read a resolved value, throwing a clear error if the snapshot is missing.
+ * The missing-snapshot case means env was read before the boot gate ran (e.g.
+ * at module-import time in a context the framework doesn't drive) — almost
+ * always a wiring bug, so we fail loudly rather than hand back `undefined`.
+ */
+export declare const requireEnvValue: (key: string) => unknown;
+
+/** Reset the snapshot (tests). */
+export declare const resetEnvSnapshot: () => void;
+
+export declare interface ResolvedEnv {
+    /** Every resolved value (public + secret), keyed by env-var name. Optional
+     *  vars that are absent appear as `undefined`. */
+    readonly values: Record<string, unknown>;
+    /** The public subset only — the exact, secret-free map that may be baked
+     *  into the browser bundle. */
+    readonly publicValues: Record<string, unknown>;
+    /** Decode failures + missing-required, aggregated so the CLI can report
+     *  ALL problems at once instead of crashing on the first. */
+    readonly errors: ReadonlyArray<EnvResolveError>;
+    /** Convenience: `errors.length === 0`. */
+    readonly ok: boolean;
+}
+
+export declare const resolveEnv: (opts: ResolveEnvOptions) => Promise<ResolvedEnv>;
+
+export declare interface ResolveEnvOptions {
+    /** The contract from `app.config.ts`. `undefined` (no `env` field) → an
+     *  empty, OK result, so the gate is a no-op for apps that declare nothing. */
+    readonly contract: EnvContract | undefined;
+    /** Read a raw public value. Defaults to `process.env`. */
+    readonly readEnv?: (key: string) => string | undefined;
+    /** Resolve a raw secret value through the configured backend. Defaults to
+     *  `readEnv` (so without a backend, secrets just come from `process.env`). */
+    readonly resolveSecret?: (key: string) => Promise<string | undefined>;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,169 @@
+import { a as e, i as t, n, r, t as i } from "./snapshot-qX0GrQfx.js";
+import { Either as a, ParseResult as o, Schema as s } from "effect";
+//#region src/define.ts
+var c = "VOLTRO_PUBLIC_", l = (e, t) => Object.freeze({
+	vars: Object.freeze({ ...e }),
+	publicPrefix: t?.publicPrefix ?? "VOLTRO_PUBLIC_"
+}), u = (e) => typeof e == "object" && !!e && "vars" in e && typeof e.vars == "object" && e.vars !== null, d = (e, t, n, r) => ({
+	kind: e,
+	access: r.access,
+	schema: t,
+	tsType: n,
+	optional: r.optional ?? !1,
+	...r.default === void 0 ? {} : { default: r.default },
+	...r.description === void 0 ? {} : { description: r.description },
+	...r.example === void 0 ? {} : { example: r.example }
+}), f = s.transformOrFail(s.String, s.Boolean, {
+	strict: !0,
+	decode: (e, t, n) => {
+		let r = e.trim().toLowerCase();
+		return r === "true" || r === "1" || r === "yes" || r === "on" ? o.succeed(!0) : r === "false" || r === "0" || r === "no" || r === "off" || r === "" ? o.succeed(!1) : o.fail(new o.Type(n, e, `expected a boolean (true/false/1/0/yes/no/on/off), got "${e}"`));
+	},
+	encode: (e) => o.succeed(e ? "true" : "false")
+}), p = (e) => URL.canParse(e), m = {
+	string: (e) => d("string", s.String, "string", e),
+	number: (e) => d("number", s.NumberFromString, "number", e),
+	port: (e) => d("port", s.NumberFromString.pipe(s.int(), s.between(1, 65535)), "number", e),
+	boolean: (e) => d("boolean", f, "boolean", e),
+	url: (e) => d("url", s.String.pipe(s.filter((e) => p(e) || `expected a valid URL, got "${e}"`)), "string", e),
+	enum: (e, t) => d("enum", s.Literal(...e), e.map((e) => `'${e}'`).join(" | "), t)
+}, h = (e, t, n) => {
+	let r = t.schema, i = s.decodeUnknownEither(r)(n);
+	return a.mapLeft(i, (n) => ({
+		key: e,
+		access: t.access,
+		reason: "invalid",
+		message: n.message
+	}));
+}, g = async (e) => {
+	let t = e.readEnv ?? ((e) => process.env[e]), n = e.resolveSecret ?? ((e) => Promise.resolve(t(e))), r = {}, i = {}, o = [], s = e.contract ? Object.entries(e.contract.vars) : [];
+	for (let [e, c] of s) {
+		let s = (c.access === "secret" ? await n(e) : t(e)) ?? c.default;
+		if (s === void 0) {
+			c.optional ? (r[e] = void 0, c.access === "public" && (i[e] = void 0)) : o.push({
+				key: e,
+				access: c.access,
+				reason: "missing",
+				message: `required ${c.access} env var "${e}" is unset` + (c.description ? ` — ${c.description}` : "")
+			});
+			continue;
+		}
+		let l = h(e, c, s);
+		if (a.isLeft(l)) {
+			o.push(l.left);
+			continue;
+		}
+		r[e] = l.right, c.access === "public" && (i[e] = l.right);
+	}
+	return {
+		values: r,
+		publicValues: i,
+		errors: o,
+		ok: o.length === 0
+	};
+}, _ = (e, t) => {
+	let n = e?.publicPrefix;
+	if (!e || typeof n != "string") return [];
+	let r = [];
+	for (let [i, a] of Object.entries(e.vars)) a.access === "secret" && i.startsWith(n) && r.push({
+		key: i,
+		access: "secret",
+		reason: "invalid",
+		message: `secret env var "${i}" must NOT use the public prefix "${n}" — that prefix marks browser-exposed PUBLIC values; a secret carrying it is a contradiction.`
+	}), t === "web" && a.access === "public" && !i.startsWith(n) && r.push({
+		key: i,
+		access: "public",
+		reason: "invalid",
+		message: `public env var "${i}" on a web app ships to the browser and must be named "${n}…" (e.g. "${n}${i}"). Rename it, mark it access:'secret' to keep it server-only, or set publicPrefix:false in defineEnv to opt out.`
+	});
+	return r;
+}, v = (e) => {
+	let t = e.map((e) => `  • ${e.key} (${e.access}, ${e.reason}): ${e.message}`);
+	return `environment validation failed (${e.length} ${e.length === 1 ? "error" : "errors"}):\n${t.join("\n")}`;
+}, y = (e) => e ? Object.entries(e.vars).map(([e, t]) => ({
+	key: e,
+	owner: "app",
+	access: t.access,
+	required: !t.optional && t.default === void 0,
+	...t.description === void 0 ? {} : { description: t.description },
+	...t.example === void 0 ? {} : { example: t.example },
+	...t.default === void 0 ? {} : { default: t.default },
+	kind: t.kind
+})) : [], b = (e, t) => t ? t.map((t) => ({
+	key: t.name,
+	owner: `plugin:${e}`,
+	access: t.secret ? "secret" : "public",
+	required: t.required,
+	...t.description === void 0 ? {} : { description: t.description },
+	...t.example === void 0 ? {} : { example: t.example }
+})) : [], x = (e, t, n, r, i) => ({
+	key: e,
+	owner: "framework",
+	access: n,
+	required: !1,
+	description: r,
+	group: t,
+	...i === void 0 ? {} : { example: i }
+}), S = [
+	x("NODE_ENV", "runtime", "public", "Node environment (development | production).", "development"),
+	x("PORT", "runtime", "public", "Port the api/web server binds to. Overrides app.config `port`.", "4000"),
+	x("VOLTRO_REGION", "runtime", "public", "Region tag for replica locality (else AWS_REGION/FLY_REGION/…).", "us-east-1"),
+	x("VOLTRO_AUTO_MIGRATE", "runtime", "public", "Set 0 to skip boot auto-migrate (CI-applied migrations).", "1"),
+	x("DB_DIALECT", "database", "public", "postgres | mysql | mariadb | mssql | sqlite | memory.", "postgres"),
+	x("DB_URL", "database", "secret", "Connection URL (carries credentials). Preferred over discrete DB_* fields.", "postgres://user:pw@localhost:5432/app"),
+	x("DB_HOST", "database", "public", "Database host (discrete-field form; DB_URL preferred).", "localhost"),
+	x("DB_PORT", "database", "public", "Database port.", "5432"),
+	x("DB_USER", "database", "public", "Database user.", "postgres"),
+	x("DB_PASSWORD", "database", "secret", "Database password."),
+	x("DB_DATABASE", "database", "public", "Database name.", "app"),
+	x("DB_MAX_CONNECTIONS", "database", "public", "Per-process connection pool cap.", "10"),
+	x("DB_REPLICA_URLS", "database", "secret", "Comma-separated read-replica URLs (carry credentials)."),
+	x("DB_REPLICA_REGIONS", "database", "public", "Comma-separated region tags matching DB_REPLICA_URLS order."),
+	x("RYW_STORE", "database", "public", "Read-your-writes position store: memory | redis.", "memory"),
+	x("CACHE_BACKEND", "cache", "public", "@voltro/cache backend: memory | redis.", "memory"),
+	x("CACHE_REDIS_URL", "cache", "secret", "Redis/Valkey/KeyDB/Dragonfly/Upstash URL (may carry credentials).", "redis://localhost:6379"),
+	x("CACHE_REDIS_DRIVER", "cache", "public", "resp (ioredis TCP) | http (Upstash REST, edge).", "resp"),
+	x("CACHE_REDIS_TOKEN", "cache", "secret", "Upstash REST token (http driver)."),
+	x("CACHE_KEY_PREFIX", "cache", "public", "Cache key namespace.", "voltro:cache"),
+	x("REDIS_URL", "cache", "secret", "Generic Redis URL fallback (cache / ryw / ratelimit).", "redis://localhost:6379"),
+	x("VOLTRO_SESSION_SECRET", "security", "secret", "HMAC signing key for session cookies. REQUIRED in production."),
+	x("VOLTRO_INSPECT", "security", "public", "Set off to disable the /_voltro/inspect surface entirely.", "on"),
+	x("VOLTRO_INSPECT_TOKEN", "security", "secret", "Bearer token gating /_voltro/inspect/* on public deploys."),
+	x("VOLTRO_TENANT_ISOLATION", "security", "public", "shared-schema (default) | namespace (physical per-tenant)."),
+	x("FRAMEWORK_TRACING", "observability", "public", "off | console | otlp. Auto-otlp when OTEL_* is set."),
+	x("OTEL_EXPORTER_OTLP_ENDPOINT", "observability", "public", "OTLP/HTTP collector endpoint (traces + metrics).", "http://localhost:4318"),
+	x("OTEL_SERVICE_NAME", "observability", "public", "OTel service name.", "voltro-api"),
+	x("SSR_CACHE", "web", "public", "ISR cache backend for `voltro start`: memory | postgres.", "memory")
+], C = () => S.map((e) => e.key), w = (e) => {
+	let t = [];
+	e.description && t.push(`# ${e.description}`);
+	let n = [
+		e.required ? "required" : "optional",
+		e.access,
+		...e.kind ? [e.kind] : []
+	].join(", ");
+	t.push(`# (${n})`);
+	let r = e.example ?? e.default ?? "";
+	return t.push(`${e.key}=${e.access === "secret" && !e.example ? "" : r}`), t.join("\n");
+}, T = (e, t = {}) => {
+	let n = [], r = t.header ?? ["Environment for this app — generated from app.config.ts `env` + plugin declarations.", "Regenerate with `voltro env sync`. Copy to `.env` and fill in the blanks."];
+	n.push(...r.map((e) => `# ${e}`), "");
+	let i = e.filter((e) => e.owner === "app"), a = e.filter((e) => e.owner.startsWith("plugin:"));
+	if (i.length > 0 && (n.push("# ── App ──────────────────────────────────────────────", ""), n.push(...i.map(w).flatMap((e) => [e, ""]))), a.length > 0 && (n.push("# ── Plugins ──────────────────────────────────────────", ""), n.push(...a.map(w).flatMap((e) => [e, ""]))), t.includeFramework !== !1) {
+		let e = [...new Set(S.map((e) => e.group))];
+		n.push("# ── Framework ────────────────────────────────────────", "");
+		for (let t of e) n.push(`# [${t}]`), n.push(...S.filter((e) => e.group === t).map(w).flatMap((e) => [e, ""]));
+	}
+	return n.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}, E = (e) => {
+	let t = new Set(e.map((e) => e.name));
+	return {
+		declared: e,
+		read: (e, n) => {
+			if (!t.has(e)) throw Error(`@voltro/env: plugin read of undeclared env var "${e}" — add it to the pluginEnv([...]) declaration so the manifest stays in sync.`);
+			return n ?? process.env[e];
+		}
+	};
+};
+//#endregion
+export { c as DEFAULT_PUBLIC_PREFIX, S as FRAMEWORK_ENV_CATALOG, y as appEnvEntries, _ as checkEnvNaming, l as defineEnv, m as envVar, v as formatEnvErrors, C as frameworkEnvNames, i as hasEnvSnapshot, n as installEnvSnapshot, u as isEnvContract, E as pluginEnv, b as pluginEnvEntries, r as readEnvValue, T as renderDotEnvExample, t as requireEnvValue, e as resetEnvSnapshot, g as resolveEnv };

package/dist/public.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Internal: set the public-env literal. The web codegen calls this from the
+ * generated entry so SSR and the browser share one install path. App code
+ * does not call this.
+ */
+export declare const __installPublicEnv: (values: Readonly<Record<string, unknown>>) => void;
+
+declare const PUBLIC_ENV_BRAND: unique symbol;
+
+/**
+ * The typed public env accessor. The framework's web codegen augments this
+ * interface (in `src/voltro-env.d.ts`) with the declared PUBLIC keys, so
+ * `publicEnv.SENTRY_DSN` autocompletes to the declared type — and naming a
+ * SECRET or undeclared key is a **compile error** (it is not in the augmented
+ * surface; there is deliberately NO permissive index signature). Before the
+ * codegen has run (a fresh checkout, pre-`voltro dev`), no public keys are
+ * known yet — run `voltro dev` to generate the augmentation, like
+ * `rpcGroup.generated.ts`.
+ *
+ * The branded member is an internal augmentation anchor; it is never a real key.
+ */
+export declare interface PublicEnv {
+    readonly [PUBLIC_ENV_BRAND]?: never;
+}
+
+/**
+ * Read a PUBLIC env value in the browser.
+ *
+ * ```tsx
+ * import { publicEnv } from '@voltro/env/public'
+ * <Sentry dsn={publicEnv.SENTRY_DSN} />
+ * ```
+ *
+ * Returns the baked value, or `undefined` if the key was not declared
+ * `access: 'public'` (e.g. read before the bundle set the literal, or a
+ * typo). The interface augmentation makes valid keys autocomplete.
+ */
+export declare const publicEnv: PublicEnv;
+
+/**
+ * The raw frozen public-env object (all public keys at once). Prefer
+ * `publicEnv.KEY`; use this when you need to spread or iterate.
+ */
+export declare const publicEnvSnapshot: () => Readonly<Record<string, unknown>>;
+
+export { }

package/dist/public.js

@@ -0,0 +1,15 @@
+//#region src/public.ts
+var e = () => globalThis.__voltro_env__ ?? {}, t = new Proxy({}, {
+	get: (t, n) => typeof n == "string" ? e()[n] : void 0,
+	has: (t, n) => typeof n == "string" && n in e(),
+	ownKeys: () => Reflect.ownKeys(e()),
+	getOwnPropertyDescriptor: (t, n) => typeof n == "string" && n in e() ? {
+		enumerable: !0,
+		configurable: !0,
+		value: e()[n]
+	} : void 0
+}), n = () => e(), r = (e) => {
+	globalThis.__voltro_env__ = Object.freeze({ ...e });
+};
+//#endregion
+export { r as __installPublicEnv, t as publicEnv, n as publicEnvSnapshot };

package/dist/server.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Read a secret by name from the boot snapshot. Identical to `serverEnv[key]`
+ * but signals intent at the call site ("this is a secret"). Typed `string`
+ * for the common case; cast if you declared a coerced secret.
+ *
+ * ```ts
+ * import { getSecret } from '@voltro/env/server'
+ * const key = getSecret('STRIPE_KEY')
+ * ```
+ */
+export declare const getSecret: (key: string) => string | undefined;
+
+/**
+ * Resolve a secret LIVE through the configured backend (Vault / Doppler / http
+ * / env), bypassing the boot snapshot. Use this only when you genuinely need a
+ * post-boot re-read (e.g. a rotated remote secret) — the snapshot is correct
+ * for ~99% of reads and avoids a per-call backend round-trip.
+ */
+export declare const resolveSecretLive: (key: string) => Promise<string | undefined>;
+
+/**
+ * The typed server env accessor. The framework's codegen augments this
+ * interface in a generated `.d.ts` so `serverEnv.MY_VAR` autocompletes to the
+ * exact declared type. Without codegen it falls back to `unknown` per key —
+ * still safe, just untyped.
+ */
+declare const SERVER_ENV_BRAND: unique symbol;
+
+export declare interface ServerEnv {
+    readonly [SERVER_ENV_BRAND]?: never;
+}
+
+/**
+ * Read any server-readable env value (public or secret) by name.
+ *
+ * ```ts
+ * import { serverEnv } from '@voltro/env/server'
+ * const dsn = serverEnv.SENTRY_DSN          // typed via generated augmentation
+ * ```
+ *
+ * Throws if read before the boot env gate ran (a wiring bug — env is only
+ * available inside handlers / loaders / startup hooks, never at import time).
+ */
+export declare const serverEnv: ServerEnv;
+
+export { }

package/dist/server.js

@@ -0,0 +1,12 @@
+import { i as e, r as t } from "./snapshot-qX0GrQfx.js";
+import { resolveSecret as n } from "@voltro/runtime";
+//#region src/server.ts
+var r = new Proxy({}, {
+	get: (t, n) => typeof n == "string" ? e(n) : void 0,
+	has: (e, n) => typeof n == "string" && t(n) !== void 0
+}), i = (t) => {
+	let n = e(t);
+	return n === void 0 ? void 0 : String(n);
+}, a = (e) => n(e);
+//#endregion
+export { i as getSecret, a as resolveSecretLive, r as serverEnv };

package/dist/snapshot-qX0GrQfx.js

@@ -0,0 +1,11 @@
+//#region src/snapshot.ts
+var e = null, t = (t) => {
+	e = Object.freeze({ ...t });
+}, n = () => e !== null, r = (t) => e === null ? void 0 : e[t], i = (t) => {
+	if (e === null) throw Error(`@voltro/env: read of "${t}" before the boot env gate ran. Env values are only available after the framework validates them at startup — read them inside a handler / loader / startup hook, not at module top-level.`);
+	return e[t];
+}, a = () => {
+	e = null;
+};
+//#endregion
+export { a, i, t as n, r, n as t };