ocel 0.0.1-alpha.1 → 0.0.1

package/dist/env/definition.js

@@ -0,0 +1,164 @@
+import { EnvDefinitionError } from "./errors.js";
+import { scopeProblem } from "./scope.js";
+import { parse } from "./standard.js";
+/** A set of variables an app takes together: every member is reached through the group and
+ * nowhere else, and `{ optional: true }` reads the whole group as `undefined` until a value
+ * is delivered for one of its members. */
+export function group(definitions, options) {
+    return {
+        definitions,
+        optional: (options?.optional === true),
+        ...(options?.description === undefined ? {} : { description: options.description }),
+    };
+}
+export function flattenDefinitions(definitions) {
+    const flat = {};
+    for (const [key, definition] of Object.entries(definitions)) {
+        if ("definitions" in definition) {
+            for (const [member, nested] of Object.entries(definition.definitions)) {
+                if ("definitions" in nested)
+                    throw new EnvDefinitionError(`group '${key}' nests another group. Groups nest one level only.`);
+                claim(flat, member, key);
+                flat[member] = {
+                    ...nested,
+                    group: key,
+                    groupOptional: definition.optional,
+                    groupDescription: definition.description,
+                };
+            }
+            continue;
+        }
+        claim(flat, key);
+        flat[key] = definition;
+    }
+    return flat;
+}
+function claim(flat, key, group) {
+    const existing = flat[key];
+    if (!existing)
+        return;
+    const inside = [existing.group, group].filter((name) => name !== undefined);
+    if (inside.length === 0) {
+        throw new EnvDefinitionError(`'${key}' is declared twice in the same call.`);
+    }
+    throw new EnvDefinitionError(`'${key}' is declared twice in the same call, once inside ${inside
+        .map((name) => `group '${name}'`)
+        .join(" and once inside ")}.`);
+}
+const LIVE_CLASSES = new Set(["secret"]);
+export function isLive(definition) {
+    return LIVE_CLASSES.has(definition.class);
+}
+const BARE_KEY_CLASSES = new Set(["plain"]);
+const RESERVED_PREFIXES = ["OCEL_"];
+export const URL_KEY = "OCEL_URL";
+export const CLIENT_URL_KEY = "NEXT_PUBLIC_OCEL_URL";
+const RESERVED_KEYS = new Map([
+    [URL_KEY, "every app"],
+    [CLIENT_URL_KEY, "every JavaScript app"],
+]);
+const KEY_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
+export function isUsableKey(key) {
+    return KEY_PATTERN.test(key);
+}
+const owner = new Map();
+export function validateDefinitions(definitions, source) {
+    for (const [key, definition] of Object.entries(definitions)) {
+        if ("definitions" in definition)
+            validateGroup(key, definition);
+    }
+    const flat = flattenDefinitions(definitions);
+    for (const [key, definition] of Object.entries(flat)) {
+        validateDefinition(key, definition, source);
+        owner.set(key, source);
+    }
+    return flat;
+}
+function validateGroup(key, definition) {
+    if (key === "" || key.includes("#") || /\p{Cc}/u.test(key)) {
+        throw new EnvDefinitionError(`'${key}' is not a usable group name: a group name is one line and has no '#'.`);
+    }
+    if (Object.keys(definition.definitions).length === 0) {
+        throw new EnvDefinitionError(`'${key}' declares no variables. A group contains the variables an app takes together, so it has at least one.`);
+    }
+    const problem = descriptionProblem(definition.description);
+    if (problem) {
+        throw new EnvDefinitionError(`'${key}' has an unusable description: ${problem}`);
+    }
+    const unsatisfiable = unsharedScopes(definition.definitions);
+    if (unsatisfiable) {
+        throw new EnvDefinitionError(`'${key}' is read as one, and no folder satisfies every member: ${unsatisfiable}.`);
+    }
+}
+function unsharedScopes(definitions) {
+    let shared;
+    const scoped = [];
+    for (const [key, definition] of Object.entries(definitions)) {
+        const folders = definition.folders;
+        if (!folders || folders.length === 0)
+            continue;
+        scoped.push(`${key} (${folders.join(", ")})`);
+        shared = shared === undefined ? folders : shared.filter((folder) => folders.includes(folder));
+    }
+    if (shared === undefined || shared.length > 0)
+        return undefined;
+    return scoped.join(", ");
+}
+function descriptionProblem(description) {
+    if (description === undefined)
+        return "";
+    if (new TextEncoder().encode(description).length > 120) {
+        return "a description is at most 120 bytes.";
+    }
+    if (/\p{Cc}/u.test(description)) {
+        return "a description is one line and has no control characters.";
+    }
+    return "";
+}
+function validateDefinition(key, definition, source) {
+    if (!KEY_PATTERN.test(key)) {
+        throw new EnvDefinitionError(`'${key}' is not a usable variable name: use upper-case letters, digits and underscores, starting with a letter or underscore.`);
+    }
+    const writtenFor = RESERVED_KEYS.get(key);
+    if (writtenFor !== undefined) {
+        throw new EnvDefinitionError(`'${key}' is written by Ocel for ${writtenFor}, from the hostname the deploy serves it on, so a declared one would be overwritten before anything read it. Read it as \`deployment.url\` from 'ocel/env'.`);
+    }
+    const claimed = owner.get(key);
+    if (claimed !== undefined && claimed !== source) {
+        throw new EnvDefinitionError(`'${key}' is already declared in ${claimed}. A key may be defined by exactly one definitions file.`);
+    }
+    const variableClass = definition.class;
+    if (definition.client && variableClass !== "plain") {
+        throw new EnvDefinitionError(`'${key}' is client-accessible and class '${variableClass}'. A value the browser can read cannot be an encrypted class.`);
+    }
+    if (BARE_KEY_CLASSES.has(variableClass) &&
+        RESERVED_PREFIXES.some((prefix) => key.startsWith(prefix))) {
+        throw new EnvDefinitionError(`'${key}' starts with a reserved prefix (${RESERVED_PREFIXES.join(", ")}). A '${variableClass}' variable is delivered under its own name, so Ocel would overwrite it.`);
+    }
+    if (definition.client && !isRequired(definition)) {
+        throw new EnvDefinitionError(`'${key}' is client-accessible and its schema accepts a missing value. A client value is inlined into the browser bundle at build time, so a default or an optional could not be told apart from a value the bundler never inlined.`);
+    }
+    if (definition.folders) {
+        const problem = scopeProblem(definition.folders);
+        if (problem) {
+            throw new EnvDefinitionError(`'${key}' has an unusable folder scope: ${problem}`);
+        }
+    }
+    const described = descriptionProblem(definition.description);
+    if (described) {
+        throw new EnvDefinitionError(`'${key}' has an unusable description: ${described}`);
+    }
+    if (LIVE_CLASSES.has(definition.class) && !isRequired(definition)) {
+        throw new EnvDefinitionError(`'${key}' is class '${definition.class}' and its schema supplies a default. A live value must fail loudly when it is missing rather than fall back.`);
+    }
+}
+export function isRequired(definition) {
+    if (!definition.schema)
+        return true;
+    return parse(definition.schema, undefined).ok === false;
+}
+export function complaint(definition, message) {
+    if (definition.class === "plain")
+        return message;
+    return `withheld, because a '${definition.class}' value's schema message can quote the value itself`;
+}

package/dist/env/deployment.d.ts

@@ -0,0 +1,23 @@
+/** What this deployment knows about itself. Ocel writes it; nothing declares it. */
+export interface Deployment {
+    /**
+     * The absolute url this app is served on, scheme and all —
+     * `https://web-j-1.ocel.site` deployed, `http://localhost:3000` under
+     * `ocel dev`. It is the first production hostname the app declares, and
+     * the project's own hostnames where the app is the first one `apps`
+     * names — the deploy serves those on that app alone. On a preview it is
+     * the derived preview hostname.
+     *
+     * Present under `ocel dev` always, and on a deploy that gives this app a
+     * hostname. An app past the first that declares none of its own is served
+     * on no hostname, and is handed no url: reading it then throws
+     * {@link EnvValueError}. Declare `domains.production` on the app.
+     *
+     * A client bundle reads the value inlined at build time, so adding a
+     * hostname with `ocel domain add` and not deploying again leaves the browser
+     * reading the hostname the last build was given. Deploy to move it.
+     */
+    readonly url: string;
+}
+/** This deployment, as the running app sees it. */
+export declare const deployment: Deployment;

package/dist/env/deployment.js

@@ -0,0 +1,13 @@
+import { URL_KEY } from "./definition.js";
+import { EnvValueError } from "./errors.js";
+import { readDelivered } from "./value.js";
+/** This deployment, as the running app sees it. */
+export const deployment = {
+    get url() {
+        const url = readDelivered(URL_KEY);
+        if (url === undefined) {
+            throw new EnvValueError(`'${URL_KEY}' was not delivered to this app. Ocel writes it from the hostname the deploy serves the app on, and this app is served on none: add one under \`domains.production\` on the app, or on the project if this is the first app it names, and deploy again.`);
+        }
+        return url;
+    },
+};

package/dist/env/edge.d.ts

@@ -0,0 +1,10 @@
+import { type Env } from "./access.js";
+import { type EnvDefinitions } from "./definition.js";
+export type { Env } from "./access.js";
+export { EnvClientError } from "./client.js";
+export type { Definitions, EnvDefinitions, GroupDefinition, GroupOptions, VariableClass, VariableDefinition, } from "./definition.js";
+export { group } from "./definition.js";
+export { type Deployment, deployment } from "./deployment.js";
+export { EnvDefinitionError, EnvEdgeError, EnvValueError } from "./errors.js";
+export { EnvScopeError } from "./scope.js";
+export declare function defineEnv<const TDefinitions extends EnvDefinitions>(definitions: TDefinitions): Env<TDefinitions>;

package/dist/env/edge.js

@@ -0,0 +1,30 @@
+import { callSiteFile } from "../declaration/callsite.js";
+import { envAccessor, FIXED } from "./access.js";
+import { isLive, validateDefinitions, } from "./definition.js";
+import { EnvEdgeError } from "./errors.js";
+import { assertInScope } from "./scope.js";
+import { coerce, readDelivered } from "./value.js";
+export { EnvClientError } from "./client.js";
+export { group } from "./definition.js";
+export { deployment } from "./deployment.js";
+export { EnvDefinitionError, EnvEdgeError, EnvValueError } from "./errors.js";
+export { EnvScopeError } from "./scope.js";
+const ENTRY_GLOBAL = "__OCEL_EDGE_ENTRY";
+export function defineEnv(definitions) {
+    validateDefinitions(definitions, callSiteFile());
+    return envAccessor(definitions, { resolve, delivered, generationOf: () => FIXED });
+}
+function delivered(key) {
+    return readDelivered(key) !== undefined;
+}
+function resolve(key, definition) {
+    assertInScope(key, definition.folders ?? []);
+    if (isLive(definition))
+        throw notLive(key, definition);
+    return coerce(key, definition, readDelivered(key));
+}
+function notLive(key, definition) {
+    const entry = globalThis[ENTRY_GLOBAL];
+    const where = typeof entry === "string" && entry !== "" ? `edge entry '${entry}'` : "an edge entry";
+    return new EnvEdgeError(`'${key}' is class '${definition.class}' and cannot be read from ${where}: a '${definition.class}' value is read live on every request, and the edge tier has no live channel to read it over. Move this entry to the nodejs runtime, or declare '${key}' as 'sensitive'.`);
+}

package/dist/env/errors.d.ts

@@ -0,0 +1,9 @@
+export declare class EnvDefinitionError extends Error {
+    name: string;
+}
+export declare class EnvValueError extends Error {
+    name: string;
+}
+export declare class EnvEdgeError extends Error {
+    name: string;
+}

package/dist/env/errors.js

@@ -0,0 +1,9 @@
+export class EnvDefinitionError extends Error {
+    name = "EnvDefinitionError";
+}
+export class EnvValueError extends Error {
+    name = "EnvValueError";
+}
+export class EnvEdgeError extends Error {
+    name = "EnvEdgeError";
+}

package/dist/env/file.d.ts

@@ -0,0 +1 @@
+export declare function readLiveFile(key: string): string | undefined;

package/dist/env/file.js

@@ -0,0 +1,27 @@
+const LIVE_DIR = "OCEL_LIVE_DIR";
+function host() {
+    return globalThis.process;
+}
+function fileSystem(on) {
+    const loaded = on.getBuiltinModule?.("node:fs");
+    if (loaded)
+        return loaded;
+    if (!on.versions?.node)
+        return undefined;
+    throw new Error(`${LIVE_DIR} is set, and reading the bindings it projects needs node 22.3 or newer. This app runs on node ${on.versions.node}.`);
+}
+export function readLiveFile(key) {
+    const on = host();
+    const dir = on?.env?.[LIVE_DIR];
+    if (!on || !dir)
+        return undefined;
+    const fs = fileSystem(on);
+    if (!fs)
+        return undefined;
+    try {
+        return fs.readFileSync(`${dir}/${key}`, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/env/index.d.ts

@@ -0,0 +1,10 @@
+import { type Env } from "./access.js";
+import { type EnvDefinitions } from "./definition.js";
+export type { Env } from "./access.js";
+export { EnvClientError } from "./client.js";
+export type { Definitions, EnvDefinitions, GroupDefinition, GroupOptions, VariableClass, VariableDefinition, } from "./definition.js";
+export { group } from "./definition.js";
+export { type Deployment, deployment } from "./deployment.js";
+export { EnvDefinitionError, EnvEdgeError, EnvValueError } from "./errors.js";
+export { EnvScopeError } from "./scope.js";
+export declare function defineEnv<const TDefinitions extends EnvDefinitions>(definitions: TDefinitions): Env<TDefinitions>;

package/dist/env/index.js

@@ -0,0 +1,63 @@
+import { callSiteFile } from "../declaration/callsite.js";
+import { defer } from "../declaration/defer.js";
+import { envAccessor, FIXED, UNCACHED } from "./access.js";
+import { declareEnv } from "./declare.js";
+import { isLive, validateDefinitions, } from "./definition.js";
+import { EnvValueError } from "./errors.js";
+import { readLiveFile } from "./file.js";
+import { liveGeneration, NO_GENERATION, readLive } from "./live.js";
+import { sourceOf } from "./schema.js";
+import { assertInScope, inScope } from "./scope.js";
+import { coerce, readDelivered } from "./value.js";
+export { EnvClientError } from "./client.js";
+export { group } from "./definition.js";
+export { deployment } from "./deployment.js";
+export { EnvDefinitionError, EnvEdgeError, EnvValueError } from "./errors.js";
+export { EnvScopeError } from "./scope.js";
+export function defineEnv(definitions) {
+    const source = callSiteFile();
+    const flat = validateDefinitions(definitions, source);
+    if (process.env.OCEL_PHASE === "discovery") {
+        defer(declareEnv(flat, source, sourceOf(definitions)));
+    }
+    const env = envAccessor(definitions, { resolve, delivered, generationOf });
+    validateLiveValues(flat, env);
+    return env;
+}
+function delivered(key, definition) {
+    return read(key, definition) !== undefined;
+}
+function generationOf(definition) {
+    if (!isLive(definition))
+        return FIXED;
+    const generation = liveGeneration();
+    return generation === NO_GENERATION ? UNCACHED : generation;
+}
+function validateLiveValues(definitions, env) {
+    if (liveGeneration() === NO_GENERATION)
+        return;
+    if (process.env.OCEL_PHASE === "discovery")
+        return;
+    for (const [key, definition] of Object.entries(definitions)) {
+        if (!isLive(definition))
+            continue;
+        if (!inScope(definition.folders ?? []))
+            continue;
+        void env[definition.group ?? key];
+    }
+}
+function resolve(key, definition) {
+    if (process.env.OCEL_PHASE === "discovery") {
+        throw new EnvValueError(`'${key}' cannot be read during discovery: values are resolved after the requirements are declared.`);
+    }
+    assertInScope(key, definition.folders ?? []);
+    return coerce(key, definition, read(key, definition));
+}
+function read(key, definition) {
+    if (isLive(definition)) {
+        const pushed = readLive(key);
+        if (pushed !== undefined)
+            return pushed;
+    }
+    return readDelivered(key) ?? readLiveFile(key);
+}

package/dist/env/live.d.ts

@@ -0,0 +1,3 @@
+export declare const NO_GENERATION = 0;
+export declare function liveGeneration(): number;
+export declare function readLive(key: string): string | undefined;

package/dist/env/live.js

@@ -0,0 +1,12 @@
+const LIVE_VALUES = Symbol.for("ocel.env.liveValues");
+export const NO_GENERATION = 0;
+function published() {
+    return globalThis[LIVE_VALUES];
+}
+export function liveGeneration() {
+    return published()?.generation ?? NO_GENERATION;
+}
+export function readLive(key) {
+    const value = published()?.values?.[key];
+    return typeof value === "string" ? value : undefined;
+}

package/dist/env/schema.d.ts

@@ -0,0 +1,27 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { Definitions, EnvDefinitions } from "./definition.js";
+declare const SOURCE: unique symbol;
+/** Definitions handed back by {@link envSchema}, marked with the module they were declared in. */
+export type EnvSchema<TDefinitions extends Definitions> = TDefinitions & {
+    readonly [SOURCE]: string;
+};
+/**
+ * Declares variables without reading, declaring or resolving anything, so a
+ * browser bundle can import the module for its schemas. Hand the result to
+ * `defineEnv` on the server.
+ */
+export declare function envSchema<const TDefinitions extends Definitions>(definitions: TDefinitions): EnvSchema<TDefinitions>;
+/** The module a set of definitions was declared in through {@link envSchema}, or `""`. */
+export declare function sourceOf(definitions: EnvDefinitions): string;
+/** The {@link envSchema} export of a module, whatever it is named. */
+export type Declared<TModule> = Extract<TModule[keyof TModule], {
+    readonly [SOURCE]: string;
+}>;
+type ExportingSchema<TModule> = [Declared<TModule>] extends [never] ? "this module exports nothing made by envSchema()" : unknown;
+/** Picks the {@link envSchema} export out of a module; a module without one fails at typecheck and at runtime. */
+export declare function declared<TModule extends object>(module: TModule & ExportingSchema<TModule>): Declared<TModule>;
+/** What the client accessor hands back for a key: the schema's output where one was declared, otherwise `string`. */
+export type ClientValue<TSchema extends Definitions, TKey extends string> = TKey extends keyof TSchema ? TSchema[TKey]["schema"] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<TSchema[TKey]["schema"]> : string : string;
+/** Parses a value the bundler inlined through the key's schema; a missing or failing value throws {@link EnvClientError}. */
+export declare function inlined<TSchema extends Definitions, TKey extends string>(schema: TSchema, key: TKey, value: string | undefined): ClientValue<TSchema, TKey>;
+export {};

package/dist/env/schema.js

@@ -0,0 +1,43 @@
+import { callSiteFile } from "../declaration/callsite.js";
+import { EnvClientError } from "./client.js";
+import { parse } from "./standard.js";
+const SOURCE = Symbol.for("ocel.env.schema");
+/**
+ * Declares variables without reading, declaring or resolving anything, so a
+ * browser bundle can import the module for its schemas. Hand the result to
+ * `defineEnv` on the server.
+ */
+export function envSchema(definitions) {
+    return Object.defineProperty(definitions, SOURCE, {
+        value: callSiteFile(),
+        enumerable: false,
+    });
+}
+/** The module a set of definitions was declared in through {@link envSchema}, or `""`. */
+export function sourceOf(definitions) {
+    const source = definitions[SOURCE];
+    return typeof source === "string" ? source : "";
+}
+/** Picks the {@link envSchema} export out of a module; a module without one fails at typecheck and at runtime. */
+export function declared(module) {
+    for (const exported of Object.values(module)) {
+        if (exported !== null && typeof exported === "object" && SOURCE in exported) {
+            return exported;
+        }
+    }
+    throw new EnvClientError("The module the client accessor imports its schemas from exports nothing made by envSchema(). Declare the variables with envSchema from 'ocel/env/schema' in a module that does not call defineEnv, and hand that to defineEnv.");
+}
+/** Parses a value the bundler inlined through the key's schema; a missing or failing value throws {@link EnvClientError}. */
+export function inlined(schema, key, value) {
+    if (value === undefined) {
+        throw new EnvClientError(`'${key}' is client-accessible, but no value was inlined into this bundle. A bundler inlines only the names matching its own public convention (NEXT_PUBLIC_* under Next, VITE_* under Vite); rename the variable to one of those, or read it on the server instead.`);
+    }
+    const definition = schema[key];
+    if (!definition?.schema)
+        return value;
+    const result = parse(definition.schema, value);
+    if (!result.ok) {
+        throw new EnvClientError(`'${key}' is set but does not satisfy its schema: ${result.message}. Fix it with \`ocel env set ${key}=<VALUE>\`.`);
+    }
+    return result.value;
+}

package/dist/env/scope.d.ts

@@ -0,0 +1,7 @@
+export declare class EnvScopeError extends Error {
+    name: string;
+}
+export declare const APP_FOLDER_ENV_VAR = "OCEL_APP_FOLDER";
+export declare function scopeProblem(folders: readonly string[]): string | undefined;
+export declare function inScope(folders: readonly string[]): boolean;
+export declare function assertInScope(key: string, folders: readonly string[]): void;

package/dist/env/scope.js

@@ -0,0 +1,45 @@
+export class EnvScopeError extends Error {
+    name = "EnvScopeError";
+}
+export const APP_FOLDER_ENV_VAR = "OCEL_APP_FOLDER";
+const KEY_DELIMITER = "#";
+export function scopeProblem(folders) {
+    if (folders.length === 0) {
+        return "an empty folder scope says nothing. Leave 'folders' off to keep the variable at the project root.";
+    }
+    const seen = new Set();
+    for (const folder of folders) {
+        if (seen.has(folder)) {
+            return `folder '${folder}' is named twice. A scoped variable has one value per folder it names.`;
+        }
+        seen.add(folder);
+        const problem = folderProblem(folder);
+        if (problem)
+            return `folder '${folder}': ${problem}`;
+    }
+    return undefined;
+}
+function folderProblem(folder) {
+    if (!folder.startsWith("/"))
+        return "a folder path must start with '/'.";
+    if (folder === "/")
+        return "'/' is the project root, which is what an unscoped variable already uses. Leave 'folders' off instead.";
+    if (folder.endsWith("/"))
+        return "a folder path must not end with '/'.";
+    if (folder.includes("//"))
+        return "a folder path has no empty segments.";
+    if (folder.includes(KEY_DELIMITER))
+        return `a folder path may not contain '${KEY_DELIMITER}'.`;
+    return undefined;
+}
+export function inScope(folders) {
+    if (folders.length === 0)
+        return true;
+    return folders.includes(process.env[APP_FOLDER_ENV_VAR] ?? "");
+}
+export function assertInScope(key, folders) {
+    if (inScope(folders))
+        return;
+    const binding = process.env[APP_FOLDER_ENV_VAR] ?? "";
+    throw new EnvScopeError(`'${key}' is scoped to ${folders.join(", ")}, but this app is bound to ${binding === "" ? "the project root" : binding}. Bind this app to one of those folders in ocel.json, or widen the variable's scope.`);
+}

package/dist/env/standard.d.ts

@@ -0,0 +1,10 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+export type ParseResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function parse(schema: StandardSchemaV1, value: unknown): ParseResult;
+export declare function describeIssues(issues: ReadonlyArray<StandardSchemaV1.Issue>): string;

package/dist/env/standard.js

@@ -0,0 +1,21 @@
+import { EnvDefinitionError } from "./errors.js";
+export function parse(schema, value) {
+    const result = schema["~standard"].validate(value);
+    if (result instanceof Promise) {
+        throw new EnvDefinitionError("A variable's schema must validate synchronously: variables are read as plain properties.");
+    }
+    if (result.issues) {
+        return { ok: false, message: describeIssues(result.issues) };
+    }
+    return { ok: true, value: result.value };
+}
+export function describeIssues(issues) {
+    return issues
+        .map((issue) => {
+        const path = (issue.path ?? [])
+            .map((segment) => (typeof segment === "object" ? String(segment.key) : String(segment)))
+            .join(".");
+        return path ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join("; ");
+}

package/dist/env/value.d.ts

@@ -0,0 +1,5 @@
+import { type VariableDefinition } from "./definition.js";
+import { EnvValueError } from "./errors.js";
+export declare function readDelivered(key: string): string | undefined;
+export declare function coerce(key: string, definition: VariableDefinition, raw: string | undefined): unknown;
+export declare function undeclared(key: string): EnvValueError;

package/dist/env/value.js

@@ -0,0 +1,26 @@
+import { complaint } from "./definition.js";
+import { EnvValueError } from "./errors.js";
+import { parse } from "./standard.js";
+const BAKED_PREFIX = "OCEL_VAR_";
+export function readDelivered(key) {
+    return process.env[BAKED_PREFIX + key] ?? process.env[key];
+}
+export function coerce(key, definition, raw) {
+    if (!definition.schema) {
+        if (raw === undefined)
+            throw unset(key);
+        return raw;
+    }
+    const result = parse(definition.schema, raw);
+    if (result.ok)
+        return result.value;
+    if (raw === undefined)
+        throw unset(key);
+    throw new EnvValueError(`'${key}' is set but does not satisfy its schema: ${complaint(definition, result.message)}. Fix it with \`ocel env set ${key}=<VALUE>\`.`);
+}
+function unset(key) {
+    return new EnvValueError(`'${key}' has no value. Set one with \`ocel env set ${key}=<VALUE>\`.`);
+}
+export function undeclared(key) {
+    return new EnvValueError(`'${key}' is not a declared variable. Add it to a defineEnv call.`);
+}

package/dist/env-source.d.ts

@@ -0,0 +1,17 @@
+import type { ExecOptions, InfisicalOptions } from "./config.js";
+/**
+ * Declares Infisical as where a tier's values are read from. Production and
+ * preview sign in as the machine identity `auth` names; `ocel dev` signs in as
+ * you, from `INFISICAL_TOKEN` or else the `infisical` CLI you are logged in to.
+ */
+export declare function infisical(options: InfisicalOptions): {
+    infisical: InfisicalOptions;
+};
+/**
+ * Declares a command whose output is a tier's values. It runs on the machine
+ * running ocel, once per variables folder with `{folder}` replaced, at each
+ * deploy and each `ocel dev`, and never on a schedule.
+ */
+export declare function exec(options: ExecOptions): {
+    exec: ExecOptions;
+};

package/dist/env-source.js

@@ -0,0 +1,16 @@
+/**
+ * Declares Infisical as where a tier's values are read from. Production and
+ * preview sign in as the machine identity `auth` names; `ocel dev` signs in as
+ * you, from `INFISICAL_TOKEN` or else the `infisical` CLI you are logged in to.
+ */
+export function infisical(options) {
+    return { infisical: options };
+}
+/**
+ * Declares a command whose output is a tier's values. It runs on the machine
+ * running ocel, once per variables folder with `{folder}` replaced, at each
+ * deploy and each `ocel dev`, and never on a schedule.
+ */
+export function exec(options) {
+    return { exec: options };
+}