@fuzdev/fuz_app 0.1.0

package/dist/dev/setup.js

@@ -0,0 +1,265 @@
+/**
+ * Dev workflow helpers for setup, reset, and database management.
+ *
+ * Composable functions that consumer projects (tx, visiones, etc.) use in their
+ * `scripts/dev_setup.ts`, `scripts/dev_reset.ts`, etc. All functions accept narrow
+ * `*Deps` interfaces from `runtime/deps.ts` — pass a `RuntimeDeps` instance
+ * created by `create_deno_runtime()`.
+ *
+ * @module
+ */
+/** Default logger using bracket format. */
+export const default_setup_logger = {
+    ok: (msg) => console.log(`  [ok] ${msg}`),
+    skip: (msg) => console.log(`  [skip] ${msg}`),
+    error: (msg) => console.error(`  [error] ${msg}`),
+};
+// === Pure utilities ===
+/**
+ * Extract the database name from a PostgreSQL URL.
+ *
+ * @returns the database name, or `null` if the URL is invalid or has no path
+ */
+export const parse_db_name = (url) => {
+    try {
+        const u = new URL(url);
+        const name = u.pathname.slice(1); // remove leading /
+        return name || null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Generate a random base64 key using openssl.
+ *
+ * @param deps - command execution capability
+ * @returns a random 32-byte base64-encoded key
+ */
+export const generate_random_key = async (deps) => {
+    const result = await deps.run_command('openssl', ['rand', '-base64', '32']);
+    if (!result.success)
+        throw new Error('Failed to generate key with openssl');
+    return result.stdout.trim();
+};
+// === File helpers ===
+/**
+ * Read a single env var from a dotenv-style file.
+ *
+ * @param deps - file read capability
+ * @param env_path - path to the .env file
+ * @param name - the variable name to read
+ * @returns the value, or `undefined` if the file or variable doesn't exist
+ */
+export const read_env_var = async (deps, env_path, name) => {
+    const stat = await deps.stat(env_path);
+    if (!stat?.is_file)
+        return undefined;
+    try {
+        const content = await deps.read_file(env_path);
+        const match = new RegExp(`^${name}=(.+)$`, 'm').exec(content);
+        return match?.[1]?.trim();
+    }
+    catch {
+        return undefined;
+    }
+};
+// === Setup helpers ===
+/**
+ * Create an env file from its example template, auto-generating `SECRET_COOKIE_KEYS`.
+ *
+ * If the file already exists, backfills any empty values that have generators.
+ * Idempotent — safe to re-run.
+ *
+ * @param deps - file read, write, and command capabilities
+ * @param env_path - path for the env file (e.g. `.env.development`)
+ * @param example_path - path to the example template
+ * @param options - extra replacements, permissions, logger
+ * @returns result indicating whether the file was created or updated
+ */
+export const setup_env_file = async (deps, env_path, example_path, options) => {
+    const log = options?.log ?? default_setup_logger;
+    const set_permissions = options?.set_permissions;
+    // build the full replacement map (SECRET_COOKIE_KEYS + extras)
+    const replacements = {
+        SECRET_COOKIE_KEYS: () => generate_random_key(deps),
+        ...options?.replacements,
+    };
+    const stat = await deps.stat(env_path);
+    if (stat?.is_file) {
+        // file exists — backfill any empty values
+        let content = await deps.read_file(env_path);
+        let changed = false;
+        for (const [key, generate] of Object.entries(replacements)) {
+            const pattern = new RegExp(`^${key}=$`, 'm');
+            if (pattern.test(content)) {
+                const value = await generate(); // eslint-disable-line no-await-in-loop
+                content = content.replace(pattern, `${key}=${value}`);
+                changed = true;
+                log.ok(`Generated ${key} in existing ${env_path}`);
+            }
+        }
+        if (changed) {
+            await deps.write_file(env_path, content);
+            if (set_permissions)
+                await set_permissions(env_path, 0o600);
+        }
+        else {
+            log.skip(`${env_path} already configured`);
+        }
+        return { created: false, updated: changed, path: env_path };
+    }
+    // create from example
+    let content = await deps.read_file(example_path);
+    for (const [key, generate] of Object.entries(replacements)) {
+        const pattern = new RegExp(`^${key}=$`, 'm');
+        if (pattern.test(content)) {
+            const value = await generate(); // eslint-disable-line no-await-in-loop
+            content = content.replace(pattern, `${key}=${value}`);
+        }
+    }
+    await deps.write_file(env_path, content);
+    if (set_permissions)
+        await set_permissions(env_path, 0o600);
+    log.ok(`Created ${env_path} with generated secrets`);
+    return { created: true, updated: true, path: env_path };
+};
+/**
+ * Create a bootstrap token file if it doesn't exist.
+ *
+ * The token is a one-shot secret used to create the first admin account.
+ * Stored at `~/.{app_name}/secret_bootstrap_token` by default.
+ *
+ * @param deps - file, command, and env capabilities
+ * @param app_name - application name (used for default state directory)
+ * @param options - state_dir override, permissions, logger
+ * @returns result indicating whether a token was created
+ */
+export const setup_bootstrap_token = async (deps, app_name, options) => {
+    const log = options?.log ?? default_setup_logger;
+    const set_permissions = options?.set_permissions;
+    const home = deps.env_get('HOME');
+    if (!home) {
+        log.skip('$HOME not set, skipping bootstrap token');
+        return { created: false, token_path: '' };
+    }
+    const state_dir = options?.state_dir ?? `${home}/.${app_name}`;
+    const token_path = `${state_dir}/secret_bootstrap_token`;
+    const stat = await deps.stat(token_path);
+    if (stat?.is_file) {
+        log.skip(`~/.${app_name}/secret_bootstrap_token already exists`);
+        return { created: false, token_path };
+    }
+    await deps.mkdir(state_dir, { recursive: true });
+    if (set_permissions)
+        await set_permissions(state_dir, 0o700);
+    const key = await generate_random_key(deps);
+    await deps.write_file(token_path, key + '\n');
+    if (set_permissions)
+        await set_permissions(token_path, 0o600);
+    log.ok(`Created ~/.${app_name}/secret_bootstrap_token (one-shot, deleted after first use)`);
+    return { created: true, token_path };
+};
+/**
+ * Remove an existing bootstrap token and create a new one.
+ *
+ * @param deps - file, command, env, and remove capabilities
+ * @param app_name - application name
+ * @param options - state_dir override, permissions, logger
+ * @returns result from creating the new token
+ */
+export const reset_bootstrap_token = async (deps, app_name, options) => {
+    const log = options?.log ?? default_setup_logger;
+    const set_permissions = options?.set_permissions;
+    const home = deps.env_get('HOME');
+    if (!home) {
+        log.skip('$HOME not set');
+        return { created: false, token_path: '' };
+    }
+    const state_dir = options?.state_dir ?? `${home}/.${app_name}`;
+    const token_path = `${state_dir}/secret_bootstrap_token`;
+    const stat = await deps.stat(token_path);
+    if (stat?.is_file) {
+        await deps.remove(token_path);
+        log.ok('Removed existing bootstrap token');
+    }
+    return setup_bootstrap_token(deps, app_name, { state_dir, set_permissions, log });
+};
+// === Database helpers ===
+/**
+ * Create a PostgreSQL database if `createdb` is available.
+ *
+ * @param deps - command execution capability
+ * @param db_name - database name to create
+ * @param options - logger
+ * @returns the command result
+ */
+export const create_database = async (deps, db_name, options) => {
+    const log = options?.log ?? default_setup_logger;
+    const check = await deps.run_command('which', ['createdb']);
+    if (!check.success) {
+        log.skip('createdb not found — install PostgreSQL or use pglite');
+        return check;
+    }
+    const result = await deps.run_command('createdb', [db_name]);
+    if (result.success) {
+        log.ok(`Created ${db_name} database`);
+    }
+    else {
+        log.skip(`${db_name} database already exists`);
+    }
+    return result;
+};
+/**
+ * Reset a database to a clean slate.
+ *
+ * For PostgreSQL: drops and recreates the database.
+ * For pglite: removes the data directory if `pglite_data_dir` is provided.
+ * For empty/missing URLs: skips.
+ *
+ * @param deps - command and file capabilities
+ * @param database_url - the DATABASE_URL value
+ * @param options - pglite_data_dir, logger
+ * @returns result describing what happened
+ */
+export const reset_database = async (deps, database_url, options) => {
+    const log = options?.log ?? default_setup_logger;
+    // empty or missing
+    if (!database_url) {
+        log.skip('No DATABASE_URL, skipping database reset');
+        return { reset: false, skipped: true, db_type: 'none' };
+    }
+    // pglite
+    if (database_url === 'pglite' || database_url.startsWith('pglite:')) {
+        const pglite_dir = options?.pglite_data_dir;
+        if (pglite_dir) {
+            const stat = await deps.stat(pglite_dir);
+            if (stat?.is_directory) {
+                await deps.remove(pglite_dir, { recursive: true });
+                log.ok(`Removed pglite directory: ${pglite_dir}`);
+                return { reset: true, skipped: false, db_type: 'pglite' };
+            }
+        }
+        log.skip('No pglite directory to remove');
+        return { reset: false, skipped: true, db_type: 'pglite' };
+    }
+    // PostgreSQL
+    const db_name = parse_db_name(database_url);
+    if (!db_name) {
+        log.error('Could not parse database name from DATABASE_URL');
+        return { reset: false, skipped: true, db_type: 'postgres' };
+    }
+    const drop = await deps.run_command('dropdb', ['--if-exists', db_name]);
+    if (!drop.success) {
+        log.error(`Failed to drop database: ${drop.stderr}`);
+        return { reset: false, skipped: false, db_type: 'postgres' };
+    }
+    log.ok(`Dropped database: ${db_name}`);
+    const create = await deps.run_command('createdb', [db_name]);
+    if (!create.success) {
+        log.error(`Failed to create database: ${create.stderr}`);
+        return { reset: false, skipped: false, db_type: 'postgres' };
+    }
+    log.ok(`Created database: ${db_name}`);
+    return { reset: true, skipped: false, db_type: 'postgres' };
+};

package/dist/env/dotenv.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Dotenv file parsing and loading.
+ *
+ * Provides `parse_dotenv` for parsing dotenv-format strings
+ * and `load_env_file` for reading and parsing env files from disk.
+ *
+ * @module
+ */
+import type { FsReadDeps } from '../runtime/deps.js';
+/**
+ * Parse a dotenv-format string into a record.
+ *
+ * @param content - dotenv file content
+ * @returns parsed key-value pairs
+ */
+export declare const parse_dotenv: (content: string) => Record<string, string>;
+/**
+ * Load and parse an env file.
+ *
+ * @param runtime - runtime with `read_file` capability
+ * @param path - path to env file
+ * @returns parsed env record, or null if file doesn't exist
+ */
+export declare const load_env_file: (runtime: Pick<FsReadDeps, "read_file">, path: string) => Promise<Record<string, string> | null>;
+//# sourceMappingURL=dotenv.d.ts.map

package/dist/env/dotenv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dotenv.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/env/dotenv.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAqBnE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GACzB,SAAS,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,EACtC,MAAM,MAAM,KACV,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAOvC,CAAC"}

package/dist/env/dotenv.js

@@ -0,0 +1,52 @@
+/**
+ * Dotenv file parsing and loading.
+ *
+ * Provides `parse_dotenv` for parsing dotenv-format strings
+ * and `load_env_file` for reading and parsing env files from disk.
+ *
+ * @module
+ */
+/**
+ * Parse a dotenv-format string into a record.
+ *
+ * @param content - dotenv file content
+ * @returns parsed key-value pairs
+ */
+export const parse_dotenv = (content) => {
+    const result = {};
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        // skip empty lines and comments
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eq_index = trimmed.indexOf('=');
+        if (eq_index === -1)
+            continue;
+        const key = trimmed.slice(0, eq_index).trim();
+        let value = trimmed.slice(eq_index + 1).trim();
+        // remove surrounding quotes if present (need at least 2 chars for open+close)
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        result[key] = value;
+    }
+    return result;
+};
+/**
+ * Load and parse an env file.
+ *
+ * @param runtime - runtime with `read_file` capability
+ * @param path - path to env file
+ * @returns parsed env record, or null if file doesn't exist
+ */
+export const load_env_file = async (runtime, path) => {
+    try {
+        const content = await runtime.read_file(path);
+        return parse_dotenv(content);
+    }
+    catch {
+        return null;
+    }
+};

package/dist/env/load.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Generic environment loading from Zod schemas.
+ *
+ * Provides `load_env` which iterates Zod schema keys, gets env values, and validates.
+ * Apps handle error messages themselves (they're always app-specific).
+ *
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * Error thrown when environment validation fails.
+ *
+ * Contains structured information for apps to format their own error messages.
+ */
+export declare class EnvValidationError extends Error {
+    /** The raw env values that were read. */
+    readonly raw: Record<string, string | undefined>;
+    /** The Zod validation error. */
+    readonly zod_error: z.core.$ZodError;
+    /** True if every env var was undefined (nothing loaded). */
+    readonly all_undefined: boolean;
+    constructor(raw: Record<string, string | undefined>, zod_error: z.core.$ZodError);
+    /**
+     * Format Zod validation issues as human-readable strings.
+     *
+     * @returns array of formatted issue strings like `"PORT: Expected number"`
+     */
+    format_issues(): Array<string>;
+}
+/**
+ * Log formatted env validation issues to stderr.
+ *
+ * Handles the common case: labels each Zod issue with an optional prefix.
+ * Callers who want app-specific "getting started" instructions should check
+ * `error.all_undefined` before calling this.
+ *
+ * @param error - the env validation error
+ * @param label - optional prefix for log lines (e.g., 'tx daemon', 'env')
+ */
+export declare const log_env_validation_error: (error: EnvValidationError, label?: string) => void;
+/**
+ * Load and validate env vars against a Zod schema.
+ *
+ * Reads each key from the schema using `get_env`, then validates.
+ * Throws `EnvValidationError` on failure.
+ *
+ * @param schema - Zod object schema defining expected env vars
+ * @param get_env - function to read an env var by key
+ * @returns validated env object
+ */
+export declare const load_env: <T extends z.ZodObject>(schema: T, get_env: (key: string) => string | undefined) => z.infer<T>;
+//# sourceMappingURL=load.d.ts.map

package/dist/env/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/env/load.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC5C,yCAAyC;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACjD,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;gBAEpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS;IAOhF;;;;OAIG;IACH,aAAa,IAAI,KAAK,CAAC,MAAM,CAAC;CAG9B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GAAI,OAAO,kBAAkB,EAAE,QAAQ,MAAM,KAAG,IAUpF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,CAAC,CAAC,SAAS,EAC7C,QAAQ,CAAC,EACT,SAAS,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,KAC1C,CAAC,CAAC,KAAK,CAAC,CAAC,CAaX,CAAC"}

package/dist/env/load.js

@@ -0,0 +1,79 @@
+/**
+ * Generic environment loading from Zod schemas.
+ *
+ * Provides `load_env` which iterates Zod schema keys, gets env values, and validates.
+ * Apps handle error messages themselves (they're always app-specific).
+ *
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * Error thrown when environment validation fails.
+ *
+ * Contains structured information for apps to format their own error messages.
+ */
+export class EnvValidationError extends Error {
+    /** The raw env values that were read. */
+    raw;
+    /** The Zod validation error. */
+    zod_error;
+    /** True if every env var was undefined (nothing loaded). */
+    all_undefined;
+    constructor(raw, zod_error) {
+        super('Environment validation failed');
+        this.raw = raw;
+        this.zod_error = zod_error;
+        this.all_undefined = Object.values(raw).every((v) => v === undefined);
+    }
+    /**
+     * Format Zod validation issues as human-readable strings.
+     *
+     * @returns array of formatted issue strings like `"PORT: Expected number"`
+     */
+    format_issues() {
+        return this.zod_error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`);
+    }
+}
+/**
+ * Log formatted env validation issues to stderr.
+ *
+ * Handles the common case: labels each Zod issue with an optional prefix.
+ * Callers who want app-specific "getting started" instructions should check
+ * `error.all_undefined` before calling this.
+ *
+ * @param error - the env validation error
+ * @param label - optional prefix for log lines (e.g., 'tx daemon', 'env')
+ */
+export const log_env_validation_error = (error, label) => {
+    const prefix = label ? `[${label}] ` : '';
+    if (error.all_undefined) {
+        console.error(`${prefix}No environment configured.`);
+    }
+    else {
+        console.error(`${prefix}Invalid environment configuration:`);
+        for (const line of error.format_issues()) {
+            console.error(`${prefix}  ${line}`);
+        }
+    }
+};
+/**
+ * Load and validate env vars against a Zod schema.
+ *
+ * Reads each key from the schema using `get_env`, then validates.
+ * Throws `EnvValidationError` on failure.
+ *
+ * @param schema - Zod object schema defining expected env vars
+ * @param get_env - function to read an env var by key
+ * @returns validated env object
+ */
+export const load_env = (schema, get_env) => {
+    const raw = {};
+    for (const key of Object.keys(schema.shape)) {
+        raw[key] = get_env(key);
+    }
+    const result = schema.safeParse(raw);
+    if (!result.success) {
+        throw new EnvValidationError(raw, result.error);
+    }
+    return result.data;
+};

package/dist/env/mask.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Environment value display formatting with secret masking.
+ *
+ * Provides utilities for safely displaying env values in logs
+ * and startup summaries, masking secrets with a placeholder.
+ *
+ * @module
+ */
+/** Placeholder displayed in place of secret values. */
+export declare const MASKED_VALUE = "***";
+/**
+ * Format an env value for display, masking secrets.
+ *
+ * @param value - the env value to format
+ * @param secret - whether the value is secret and should be masked
+ * @returns display string — masked placeholder for secrets, string values as-is, non-strings JSON-stringified
+ */
+export declare const format_env_display_value: (value: unknown, secret: boolean) => string;
+//# sourceMappingURL=mask.d.ts.map

package/dist/env/mask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/env/mask.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,uDAAuD;AACvD,eAAO,MAAM,YAAY,QAAQ,CAAC;AAElC;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAI,OAAO,OAAO,EAAE,QAAQ,OAAO,KAAG,MAK1E,CAAC"}

package/dist/env/mask.js

@@ -0,0 +1,26 @@
+/**
+ * Environment value display formatting with secret masking.
+ *
+ * Provides utilities for safely displaying env values in logs
+ * and startup summaries, masking secrets with a placeholder.
+ *
+ * @module
+ */
+/** Placeholder displayed in place of secret values. */
+export const MASKED_VALUE = '***';
+/**
+ * Format an env value for display, masking secrets.
+ *
+ * @param value - the env value to format
+ * @param secret - whether the value is secret and should be masked
+ * @returns display string — masked placeholder for secrets, string values as-is, non-strings JSON-stringified
+ */
+export const format_env_display_value = (value, secret) => {
+    if (secret)
+        return MASKED_VALUE;
+    if (typeof value === 'string')
+        return value;
+    if (value === undefined)
+        return 'undefined';
+    return JSON.stringify(value);
+};

package/dist/env/resolve.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Environment variable `$$VAR$$` resolution suite.
+ *
+ * Resolves `$$VAR$$` references in strings and object trees,
+ * scans configs for references, and validates/formats missing vars.
+ *
+ * The double-dollar bookending syntax is:
+ * - Visually distinct from shell `$VAR` syntax
+ * - Unambiguous about variable boundaries
+ * - Easy to grep: `grep '\$\$'`
+ * - Fails loud if accidentally shell-processed (`$$`=PID in shell)
+ *
+ * @module
+ */
+import type { EnvDeps } from '../runtime/deps.js';
+/**
+ * Resolve environment variable references in a string.
+ *
+ * Uses `$$VAR$$` syntax (bookended double-dollar signs).
+ * Only resolves variables that are actually set in the environment.
+ * Unset variables are left as-is for clear error messages.
+ *
+ * @param runtime - runtime with `env_get` capability
+ * @param value - string that may contain `$$VAR$$` references
+ * @returns string with env vars resolved
+ */
+export declare const resolve_env_vars: (runtime: Pick<EnvDeps, "env_get">, value: string) => string;
+/**
+ * Check if a string contains unresolved env var references.
+ *
+ * @param value - string to check
+ * @returns `true` if string contains `$$VAR$$` patterns
+ */
+export declare const has_env_vars: (value: string) => boolean;
+/**
+ * Get list of env var names referenced in a string.
+ *
+ * @param value - string to scan
+ * @returns array of variable names (without `$$` delimiters)
+ */
+export declare const get_env_var_names: (value: string) => Array<string>;
+/**
+ * Resolve env vars in an object's string values (shallow).
+ *
+ * @param runtime - runtime with `env_get` capability
+ * @param obj - object with string values
+ * @returns new object with env vars resolved
+ */
+export declare const resolve_env_vars_in_object: <T extends Record<string, unknown>>(runtime: Pick<EnvDeps, "env_get">, obj: T) => T;
+/**
+ * Resolve env vars and throw if any are missing/empty.
+ *
+ * Use this for values that must be present.
+ *
+ * @param runtime - runtime with `env_get` capability
+ * @param value - string with `$$VAR$$` references
+ * @param context - description for error message (e.g., `"target.host"`)
+ * @returns resolved string
+ * @throws error if any referenced env var is missing or empty
+ */
+export declare const resolve_env_vars_required: (runtime: Pick<EnvDeps, "env_get">, value: string, context: string) => string;
+/**
+ * An env var reference found in a config.
+ */
+export interface EnvVarRef {
+    /** Variable name (without `$$` delimiters). */
+    name: string;
+    /** Path where the reference was found (e.g., `"target.host"`, `"resources[3].path"`). */
+    path: string;
+}
+/**
+ * Recursively scan an object for `$$VAR$$` env var references.
+ *
+ * Walks all string values in the object tree and extracts env var names
+ * with their path context for error reporting.
+ *
+ * @param obj - object to scan (typically a config)
+ * @returns array of env var references with paths
+ */
+export declare const scan_env_vars: (obj: unknown) => Array<EnvVarRef>;
+/**
+ * Result of env var validation.
+ *
+ * Uses discriminated union for better type narrowing:
+ * - `ok: true, missing: null` — all vars present
+ * - `ok: false, missing: EnvVarRef[]` — some vars missing
+ */
+export type EnvValidationResult = {
+    ok: true;
+    missing: null;
+} | {
+    ok: false;
+    missing: Array<EnvVarRef>;
+};
+/**
+ * Validate that all referenced env vars exist in the environment.
+ *
+ * Returns all missing refs (including duplicates by name). Grouping
+ * and deduplication is handled by `format_missing_env_vars` at display time.
+ *
+ * @param runtime - runtime with `env_get` capability
+ * @param refs - env var references from `scan_env_vars`
+ * @returns validation result with any missing vars
+ */
+export declare const validate_env_vars: (runtime: Pick<EnvDeps, "env_get">, refs: Array<EnvVarRef>) => EnvValidationResult;
+/**
+ * Options for `format_missing_env_vars`.
+ */
+export interface FormatMissingEnvVarsOptions {
+    /** Path to env file if one was loaded. */
+    env_file?: string;
+    /** Hint text for how to set up the environment. */
+    setup_hint?: string;
+}
+/**
+ * Format missing env vars error message.
+ *
+ * Groups refs by variable name so each missing var is shown once
+ * with all paths where it's referenced.
+ *
+ * @param missing - missing env var references (may contain duplicate names)
+ * @param options - formatting options
+ * @returns formatted error message for display
+ */
+export declare const format_missing_env_vars: (missing: Array<EnvVarRef>, options?: FormatMissingEnvVarsOptions) => string;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/env/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/env/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAOhD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,OAAO,MAAM,KAAG,MAMnF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,OAG5C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,KAAK,CAAC,MAAM,CAS7D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3E,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,KAAK,CAAC,KACJ,CAQF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,GACrC,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,OAAO,MAAM,EACb,SAAS,MAAM,KACb,MAmBF,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,OAAO,KAAG,KAAK,CAAC,SAAS,CAI3D,CAAC;AAwBF;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAC5B;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,IAAI,CAAA;CAAC,GACzB;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;CAAC,CAAC;AAE1C;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,MAAM,KAAK,CAAC,SAAS,CAAC,KACpB,mBAWF,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC3C,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GACnC,SAAS,KAAK,CAAC,SAAS,CAAC,EACzB,UAAU,2BAA2B,KACnC,MA+BF,CAAC"}