@dokebi/cli 0.4.2 → 0.4.27

package/dist/dev-watch.js

@@ -0,0 +1,192 @@
+// What `dokebi dev` restarts for. A file event alone is not proof of a change: on macOS, FSEvents
+// also delivers events that were still queued in fseventsd when the watch started, and a busy
+// fseventsd can deliver them tens of seconds late. After `dokebi init`, `dokebi add`, `npm install`
+// or a `git checkout` right before `dokebi dev`, those events restarted the app again and again,
+// and every restart closes its port for a moment. libuv also names an event on the watched
+// folder itself by the folder's own name (a `src/src` that does not exist).
+//
+// So dev records the state of every watched path before the first app start (the app reads its
+// files after that) and restarts only when a reported path's state differs from the recorded one:
+// a new, deleted, replaced or rewritten file or folder. An event on a folder whose own state did
+// not change means "something below may have changed" (FSEvents coalesces events onto folders),
+// so the folder is compared entry by entry. The state of a file is its device, inode, size and
+// modification time, of a folder its device and inode; access and attribute-only changes do not
+// restart.
+import { readdirSync, statSync } from 'node:fs';
+import { basename, join, sep } from 'node:path';
+import { debug, isMissing, reportError } from './diagnostics.js';
+/** Entries recorded at most; past it, unknown paths count as changed. */
+const DEFAULT_LIMIT = 100_000;
+/** A folder is its identity (what is in it is compared entry by entry); a file also its content. */
+function stateOf(stats) {
+    return stats.isDirectory()
+        ? `d:${stats.dev}:${stats.ino}`
+        : `f:${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeMs}`;
+}
+/**
+ * The recorded state of the watched paths. `changed(path)` answers whether a reported path really
+ * changed since it was recorded (or since its last change) and records its new state.
+ */
+export class WatchedState {
+    #states = new Map();
+    #limit;
+    #skip;
+    #complete = true;
+    #ignored = 0;
+    /**
+     * @param skip paths that are neither recorded nor compared (files whose events the caller drops,
+     * such as views served by Vite).
+     */
+    constructor(options = {}) {
+        this.#limit = options.limit ?? DEFAULT_LIMIT;
+        this.#skip = options.skip ?? (() => false);
+    }
+    /** Whether every path under the recorded folders is known (false past the limit). */
+    get complete() {
+        return this.#complete;
+    }
+    /** Events answered "no change" so far. */
+    get ignored() {
+        return this.#ignored;
+    }
+    /** Records a file or folder (not its contents); a missing one is recorded as absent. */
+    record(path) {
+        this.#update(path, this.#read(path));
+    }
+    /** Records a folder and everything under it (symbolic links are not followed into). */
+    recordTree(folder) {
+        const started = performance.now();
+        this.record(folder);
+        this.#walk(folder);
+        debug('dev watch: recorded the watched files', {
+            folder,
+            entries: this.#states.size,
+            complete: this.#complete,
+            ms: Math.round(performance.now() - started),
+        });
+    }
+    /**
+     * Whether the path an fs.watch event on `folder` names changed (see `changed`). The folder's own
+     * name that is not an entry of it means the folder itself (libuv).
+     */
+    changedIn(folder, name) {
+        const path = join(folder, name);
+        if (name === basename(folder) && this.#read(path) === undefined && !this.#states.has(path))
+            return this.changed(folder);
+        return this.changed(path);
+    }
+    /**
+     * Whether `path` differs from its recorded state; the new state is recorded. A path that is
+     * absent now and was absent (or unknown with a complete record) did not change; an unchanged
+     * folder changed when an entry below it did.
+     */
+    changed(path) {
+        const state = this.#read(path);
+        // Unreadable (reported): restart, as a watcher without this check would.
+        if (state === null)
+            return true;
+        const before = this.#states.get(path);
+        const same = state === undefined ? before === undefined && this.#complete : state === before;
+        if (!same) {
+            this.#update(path, state);
+            // A new or replaced folder: record what is in it, so later events for it compare.
+            if (state?.startsWith('d:'))
+                this.#walk(path);
+            debug('dev watch: path changed', { path, state: state === undefined ? 'absent' : 'present' });
+            return true;
+        }
+        if (state?.startsWith('d:') && this.#walk(path)) {
+            debug('dev watch: an entry of the folder changed', { path });
+            return true;
+        }
+        this.#ignored++;
+        if (this.#ignored === 1 || this.#ignored % 100 === 0)
+            debug('dev watch: event for a path that did not change ignored', {
+                path,
+                ignored: this.#ignored,
+            });
+        return false;
+    }
+    /**
+     * Compares and records everything below `folder`; true when an entry is new, deleted or
+     * different. Stops early only past the limit (unknown then counts as changed).
+     */
+    #walk(folder) {
+        let changed = false;
+        const seen = new Set();
+        const pending = [folder];
+        while (pending.length) {
+            const current = pending.pop();
+            let entries;
+            try {
+                entries = readdirSync(current, { withFileTypes: true });
+            }
+            catch (error) {
+                // A folder removed while it is read is simply absent; anything else leaves it unknown.
+                if (!isMissing(error)) {
+                    this.#complete = false;
+                    reportError('DEV_WATCH_SCAN_FAILED', `Unable to read ${current} for dokebi dev`, error);
+                }
+                changed = true;
+                continue;
+            }
+            for (const entry of entries) {
+                const path = join(current, entry.name);
+                if (this.#skip(path))
+                    continue;
+                seen.add(path);
+                const state = this.#read(path);
+                if (state !== this.#states.get(path)) {
+                    changed = true;
+                    this.#update(path, state);
+                }
+                if (entry.isDirectory())
+                    pending.push(path);
+            }
+        }
+        // Recorded entries that are gone.
+        const prefix = folder.endsWith(sep) ? folder : `${folder}${sep}`;
+        for (const path of this.#states.keys())
+            if (path.startsWith(prefix) && !seen.has(path)) {
+                this.#states.delete(path);
+                changed = true;
+            }
+        return changed || !this.#complete;
+    }
+    #update(path, state) {
+        if (state === null)
+            return;
+        if (state === undefined) {
+            // A deleted folder takes what was recorded below it.
+            if (this.#states.get(path)?.startsWith('d:')) {
+                const prefix = `${path}${sep}`;
+                for (const key of this.#states.keys())
+                    if (key.startsWith(prefix))
+                        this.#states.delete(key);
+            }
+            this.#states.delete(path);
+            return;
+        }
+        if (!this.#states.has(path) && this.#states.size >= this.#limit) {
+            if (this.#complete)
+                debug('dev watch: too many files to record; unknown paths count as changed', {
+                    limit: this.#limit,
+                });
+            this.#complete = false;
+            return;
+        }
+        this.#states.set(path, state);
+    }
+    /** The state, undefined when absent, null when it cannot be read (reported). */
+    #read(path) {
+        try {
+            return stateOf(statSync(path));
+        }
+        catch (error) {
+            if (isMissing(error))
+                return undefined;
+            reportError('DEV_WATCH_STAT_FAILED', `Unable to read ${path} for dokebi dev`, error, 10_000);
+            return null;
+        }
+    }
+}

package/dist/diagnostics.d.ts

@@ -1,14 +1,17 @@
-/**
- * CLI diagnostics on stderr (D-0047). The CLI has no logger: errors it recovers from are printed
- * as one line on stderr, and `DOKEBI_LOG_LEVEL=debug` adds debug lines. stdout stays reserved
- * for command results (and the --json envelope).
- */
 /**
  * The full text of a caught value for a log field (D-0047): name, whole message and stack, then
- * each `cause` the same way. Only credentials in URLs (`//user:password@`) are removed; a text
- * over 16 KB is cut and marked. A hostile accessor still yields the value's type.
+ * each `cause` the same way. Only credentials are removed, by core's rule (`maskCredentials`:
+ * `//user:password@` of a URL, also with a raw `/` in the password, and `Password=` of a
+ * connection string); a text over 16 KB is cut and marked. A hostile accessor still yields the
+ * value's type.
  */
 export declare function describeError(error: unknown): string;
+/**
+ * Every string in a value with credentials masked by core's rule (`maskCredentials`): for what a
+ * child process of the project sends back (describe, the user-store probe), whose own masking is
+ * a first line of defence only. Other values are kept; arrays and plain objects are copied.
+ */
+export declare function maskTexts<T>(value: T, depth?: number): T;
 /** Errors that mean "the file or folder is not there", which callers treat as absence. */
 export declare function isMissing(error: unknown): boolean;
 export declare function debugEnabled(): boolean;

package/dist/diagnostics.js

@@ -3,12 +3,15 @@
  * as one line on stderr, and `DOKEBI_LOG_LEVEL=debug` adds debug lines. stdout stays reserved
  * for command results (and the --json envelope).
  */
+import { redaction } from '@dokebi/core/libraries';
 const reported = new Map();
 const suppressed = new Map();
 /**
  * The full text of a caught value for a log field (D-0047): name, whole message and stack, then
- * each `cause` the same way. Only credentials in URLs (`//user:password@`) are removed; a text
- * over 16 KB is cut and marked. A hostile accessor still yields the value's type.
+ * each `cause` the same way. Only credentials are removed, by core's rule (`maskCredentials`:
+ * `//user:password@` of a URL, also with a raw `/` in the password, and `Password=` of a
+ * connection string); a text over 16 KB is cut and marked. A hostile accessor still yields the
+ * value's type.
  */
 export function describeError(error) {
     const parts = [];
@@ -34,11 +37,25 @@ export function describeError(error) {
             current = undefined;
         }
     }
-    const text = parts.join('\n').replace(/\/\/[^\s/@]*@/g, '//***@');
+    const text = redaction.maskCredentials(parts.join('\n'));
     return text.length > 16_384
         ? `${text.slice(0, 16_384)}… [truncated ${text.length - 16_384} characters]`
         : text;
 }
+/**
+ * Every string in a value with credentials masked by core's rule (`maskCredentials`): for what a
+ * child process of the project sends back (describe, the user-store probe), whose own masking is
+ * a first line of defence only. Other values are kept; arrays and plain objects are copied.
+ */
+export function maskTexts(value, depth = 0) {
+    if (typeof value === 'string')
+        return redaction.maskCredentials(value);
+    if (depth > 32 || value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => maskTexts(item, depth + 1));
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, maskTexts(item, depth + 1)]));
+}
 /** Errors that mean "the file or folder is not there", which callers treat as absence. */
 export function isMissing(error) {
     const code = error?.code;
@@ -46,10 +63,11 @@ export function isMissing(error) {
 }
 function write(record) {
     try {
+        // dokebi-check: allow console-output the CLI's own diagnostics: it has no app logger (JSON lines on stderr)
         process.stderr.write(`${JSON.stringify({ time: new Date().toISOString(), ...record })}\n`);
     }
     catch {
-        // stderr itself is unavailable: there is no further channel to report on.
+        // dokebi-check: allow empty-catch stderr itself is unavailable: there is no channel left to report on
     }
 }
 export function debugEnabled() {

package/dist/drift.d.ts

@@ -0,0 +1,50 @@
+import type { DescribeOptions } from './describe.js';
+/** What one entry says differs. */
+export type DriftKind = 'connection' | 'table' | 'collection' | 'column' | 'column_comment';
+export interface DriftEntry {
+    readonly kind: DriftKind;
+    /** The dokebi-db connection. */
+    readonly connection: string;
+    /** `<connection>`, `<table>` (`<schema>.<table>` outside the first schema), `<table>.<column>`. */
+    readonly target: string;
+    /** What the file says; null: the file has it not (only in the code). */
+    readonly expected_value: string | null;
+    /** What the database has; null: the database has it not (a missing column, no comment). */
+    readonly code_value: string | null;
+}
+export interface DriftResult {
+    /** No drift and every connection named in the file could be read. */
+    readonly ok: boolean;
+    readonly drift: DriftEntry[];
+    /** Connections named in the file that could not be read (nothing compared for them). */
+    readonly unavailable: {
+        readonly connection: string;
+        readonly reason: string;
+    }[];
+    readonly compared: {
+        readonly connections: number;
+        readonly tables: number;
+        readonly columns: number;
+        readonly comments: number;
+    };
+    readonly ms: number;
+}
+type Row = Record<string, unknown>;
+/** Whitespace runs are one space and the ends are trimmed before two comments are compared. */
+export declare const normalComment: (text: string) => string;
+/** The connections of an expected file (a describe result, or its `--json` envelope). */
+export declare function expectedConnections(file: string, document: unknown): Row[];
+/**
+ * The drift between expected and actual `db.connections` (pure: no reading, no connecting).
+ * Entries come in the order of the expected file, then what only the database has.
+ */
+export declare function compareDatabases(expected: readonly Row[], actual: readonly Row[]): Omit<DriftResult, 'ok' | 'ms'>;
+export interface DriftOptions extends Pick<DescribeOptions, 'timeoutMs'> {
+    /** The expected file, relative to `root` or absolute. */
+    readonly expected: string;
+}
+/** `dokebi drift`: reads the expected file, describes the project with its databases, compares. */
+export declare function drift(root: string, options: DriftOptions): Promise<DriftResult>;
+/** The human output: one line per entry, then a summary line. */
+export declare function driftText(result: DriftResult): string;
+export {};

package/dist/drift.js

@@ -0,0 +1,218 @@
+// `dokebi drift --expected <file> [--json]` (D-0120, the shape proposed in D-0090 §3 N): what the
+// project's databases have against what a file says they should have. The file has the shape of
+// `dokebi describe --json` (only `db.connections` is read; the whole describe envelope works
+// too), written by hand or by a design tool. The actual side is `describe --with-db`: the
+// project's own `dokebi-migrate schema` per connection (it connects). Only what the file names
+// is compared: a connection, its tables (or collections) when it lists them, a table's columns
+// when it lists them, and a column's comment when it gives one. A database comment is what the
+// migrations wrote (PostgreSQL `COMMENT ON COLUMN … IS '…'`, MySQL and MariaDB `COMMENT '…'` in
+// the column definition); MongoDB has no comments.
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { debug } from './diagnostics.js';
+import { CliError } from './errors.js';
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+/** Whitespace runs are one space and the ends are trimmed before two comments are compared. */
+export const normalComment = (text) => text.replace(/\s+/g, ' ').trim();
+function invalid(file, path, message) {
+    return new CliError('DRIFT_EXPECTED_INVALID', `${file}: ${path} ${message}`, {
+        phase: 'arguments',
+        details: {
+            file,
+            path,
+            fix: 'write the describe shape: { "db": { "connections": [{ "name": "main", "tables": [{ "name": "posts", "columns": [{ "name": "title", "comment": "Post title" }] }] }] } }',
+        },
+    });
+}
+/** A list of named objects at `path`, or undefined when the field is absent. */
+function named(file, path, value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw invalid(file, path, 'must be a list');
+    return value.map((item, index) => {
+        const row = record(item);
+        if (!row || typeof row.name !== 'string' || !row.name)
+            throw invalid(file, `${path}[${index}]`, 'must be an object with a name');
+        return row;
+    });
+}
+/** The connections of an expected file (a describe result, or its `--json` envelope). */
+export function expectedConnections(file, document) {
+    const top = record(document);
+    if (!top)
+        throw invalid(file, '$', 'must be a JSON object');
+    const result = record(top.result) ?? top;
+    const db = record(result.db);
+    if (!db)
+        throw invalid(file, 'db', 'is missing: the file names no database to compare');
+    const connections = named(file, 'db.connections', db.connections);
+    if (!connections)
+        throw invalid(file, 'db.connections', 'is missing');
+    connections.forEach((connection, index) => {
+        const at = `db.connections[${index}]`;
+        const tables = named(file, `${at}.tables`, connection.tables) ?? [];
+        named(file, `${at}.collections`, connection.collections);
+        tables.forEach((table, position) => {
+            const columns = named(file, `${at}.tables[${position}].columns`, table.columns) ?? [];
+            columns.forEach((column, place) => {
+                const comment = column.comment;
+                if (comment !== undefined && comment !== null && typeof comment !== 'string')
+                    throw invalid(file, `${at}.tables[${position}].columns[${place}].comment`, 'must be a string or null');
+            });
+        });
+    });
+    return connections;
+}
+/**
+ * The drift between expected and actual `db.connections` (pure: no reading, no connecting).
+ * Entries come in the order of the expected file, then what only the database has.
+ */
+export function compareDatabases(expected, actual) {
+    const drift = [];
+    const unavailable = [];
+    const compared = { connections: 0, tables: 0, columns: 0, comments: 0 };
+    const entry = (kind, connection, target, expectedValue, codeValue) => drift.push({
+        kind,
+        connection,
+        target,
+        expected_value: expectedValue,
+        code_value: codeValue,
+    });
+    for (const want of expected) {
+        const name = want.name;
+        const have = actual.find((item) => item.name === name);
+        if (!have) {
+            entry('connection', name, name, name, null);
+            continue;
+        }
+        if (typeof have.unavailable === 'string') {
+            unavailable.push({ connection: name, reason: have.unavailable });
+            continue;
+        }
+        compared.connections++;
+        // A table outside the first schema of the search path is named `<schema>.<table>`.
+        const first = Array.isArray(have.schemas) ? have.schemas[0] : undefined;
+        const key = (table) => typeof table.schema === 'string' && table.schema !== first
+            ? `${table.schema}.${String(table.name)}`
+            : String(table.name);
+        for (const [kind, field] of [
+            ['table', 'tables'],
+            ['collection', 'collections'],
+        ]) {
+            if (!Array.isArray(want[field]))
+                continue;
+            // The migration history is never compared, on either side: a describe answer used as the
+            // expected file lists it too (`isMigrationHistory`).
+            const all = Array.isArray(have[field]) ? have[field] : [];
+            const history = new Set(all.filter((item) => item.isMigrationHistory === true).map((item) => key(item)));
+            const wanted = want[field].filter((item) => item.isMigrationHistory !== true && !history.has(key(item)));
+            const held = all.filter((item) => item.isMigrationHistory !== true);
+            const heldBy = new Map(held.map((item) => [key(item), item]));
+            const wantedKeys = new Set();
+            for (const table of wanted) {
+                const target = key(table);
+                wantedKeys.add(target);
+                const found = heldBy.get(target);
+                if (!found) {
+                    entry(kind, name, target, target, null);
+                    continue;
+                }
+                compared.tables++;
+                if (kind !== 'table' || !Array.isArray(table.columns))
+                    continue;
+                const columns = Array.isArray(found.columns) ? found.columns : [];
+                const columnBy = new Map(columns.map((column) => [String(column.name), column]));
+                const wantedColumns = new Set();
+                for (const column of table.columns) {
+                    const columnName = String(column.name);
+                    wantedColumns.add(columnName);
+                    const at = `${target}.${columnName}`;
+                    const real = columnBy.get(columnName);
+                    if (!real) {
+                        entry('column', name, at, at, null);
+                        continue;
+                    }
+                    compared.columns++;
+                    // An empty or absent comment in the file means "not decided": not compared.
+                    const comment = typeof column.comment === 'string' ? column.comment : '';
+                    if (!normalComment(comment))
+                        continue;
+                    compared.comments++;
+                    const stored = typeof real.comment === 'string' && real.comment ? real.comment : null;
+                    if (normalComment(comment) !== normalComment(stored ?? ''))
+                        entry('column_comment', name, at, comment, stored);
+                }
+                for (const column of columns)
+                    if (!wantedColumns.has(String(column.name))) {
+                        const at = `${target}.${String(column.name)}`;
+                        entry('column', name, at, null, at);
+                    }
+            }
+            for (const [target] of heldBy)
+                if (!wantedKeys.has(target))
+                    entry(kind, name, target, null, target);
+        }
+    }
+    return { drift, unavailable, compared };
+}
+/** `dokebi drift`: reads the expected file, describes the project with its databases, compares. */
+export async function drift(root, options) {
+    const started = Date.now();
+    const file = resolve(root, options.expected);
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        throw new CliError('DRIFT_EXPECTED_INVALID', `Cannot read the expected file ${file}`, {
+            cause: error,
+            phase: 'arguments',
+            details: { file, fix: 'pass --expected <file> with a JSON file of the describe shape' },
+        });
+    }
+    let document;
+    try {
+        document = JSON.parse(text);
+    }
+    catch (error) {
+        throw new CliError('DRIFT_EXPECTED_INVALID', `${file} is not JSON`, {
+            cause: error,
+            phase: 'arguments',
+            details: { file, fix: 'write the expected file as JSON (the shape of describe --json)' },
+        });
+    }
+    const expected = expectedConnections(file, document);
+    const { describeProject } = await import('./describe.js');
+    const described = await describeProject(root, {
+        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+        withDb: true,
+    });
+    const actual = Array.isArray(described.db.connections) ? described.db.connections : [];
+    const result = compareDatabases(expected, actual);
+    debug('drift: compared', {
+        drift: result.drift.length,
+        unavailable: result.unavailable.length,
+        ...result.compared,
+    });
+    return {
+        ok: result.drift.length === 0 && result.unavailable.length === 0,
+        ...result,
+        ms: Date.now() - started,
+    };
+}
+/** The human output: one line per entry, then a summary line. */
+export function driftText(result) {
+    const value = (text) => (text === null ? 'none' : JSON.stringify(text));
+    const lines = result.drift.map((item) => item.kind === 'column_comment'
+        ? `${item.connection} ${item.target}  column_comment  expected ${value(item.expected_value)}, database ${value(item.code_value)}`
+        : `${item.connection} ${item.target}  ${item.kind}  ${item.code_value === null ? 'only in the expected file' : 'only in the database'}`);
+    for (const item of result.unavailable)
+        lines.push(`${item.connection}  unavailable  ${item.reason}`);
+    const { connections, tables, columns, comments } = result.compared;
+    const counts = `${connections} connections, ${tables} tables, ${columns} columns, ${comments} comments compared (${result.ms} ms)`;
+    lines.push(result.ok
+        ? `drift none: ${counts}`
+        : `drift FOUND: ${result.drift.length} difference${result.drift.length === 1 ? '' : 's'}${result.unavailable.length ? `, ${result.unavailable.length} unavailable` : ''}; ${counts}`);
+    return `${lines.join('\n')}\n`;
+}

package/dist/env-file.d.ts

@@ -6,15 +6,39 @@ export declare const ENV_FILE = ".env";
  * names the line only, never its content.
  */
 export declare function checkEnvText(text: string): void;
+/**
+ * The variables of a .env text, checked line by line first (ENV_FILE_INVALID). R4CA-11: a byte
+ * order mark (editors on Windows write one) is no part of the first name; util.parseEnv kept it
+ * there (`\uFEFFDATABASE_URL`), so the app missed that variable and an install that looked for
+ * it appended a second line that won over the user's value.
+ */
+export declare function parseEnvText(text: string): Record<string, string>;
 /**
  * The variables of `<root>/.env` (empty when there is none). Throws ENV_FILE_INVALID when the
  * file cannot be read or a line is not `KEY=value`.
  */
 export declare function readEnvFile(root: string): Record<string, string>;
+/**
+ * Variables .env never passes to the app (R4CA-3, user decision 2026-10-26): DOKEBI_CONFIG chooses
+ * the settings file, and every CLI command and `npm start` read it from the environment only;
+ * from .env it would make only the app the CLI runs read another file than all of them.
+ */
+export declare const ENVIRONMENT_ONLY: readonly string[];
+/** A line of .env the CLI does not pass on (ENV_DOKEBI_CONFIG_IGNORED); never its value. */
+export interface EnvFileWarning {
+    readonly code: 'ENV_DOKEBI_CONFIG_IGNORED';
+    /** `.env:<line>` */
+    readonly path: string;
+    readonly variable: string;
+    readonly hint: string;
+}
+/** What `.env` sets that the app does not get (ENVIRONMENT_ONLY), by line; [] without .env. */
+export declare function envFileWarnings(root: string): EnvFileWarning[];
 /**
  * The environment of an app the CLI runs: the project's .env, then the CLI's own environment on
  * top (it wins), then NODE_ENV (`mode` unless one of them set it) and `extra` (the CLI's own
- * variables such as DOKEBI_DEV or the verify and instance tokens).
+ * variables such as DOKEBI_DEV or the verify and instance tokens). ENVIRONMENT_ONLY variables are
+ * never taken from .env (envFileWarnings names their lines).
  */
 export declare function appEnvironment(root: string, mode: string, extra?: Readonly<Record<string, string>>, fileValues?: Readonly<Record<string, string>>): NodeJS.ProcessEnv;
 /** Whether a variable is set in the environment or in the project's .env (values not returned). */