@dbx-tools/core 0.6.82 → 0.6.86

package/README.md

@@ -1,7 +1,7 @@
 # @dbx-tools/core
 
-Node-only core helpers for binary installation, process execution, and project
-discovery.
+Node-only core helpers for layered configuration, binary installation, process
+execution, locking, and project discovery.
 
 Import this package when code needs `node:child_process`, `node:fs`, or
 `node:path`. Browser-safe utilities live in
@@ -16,8 +16,12 @@ Key features:
 - Workspace/project root discovery from package-manager files, git metadata, and
   the current working directory.
 - Safe filesystem stat and project naming helpers for CLIs and projen synth.
+- Layered config from process env, environment-specific `.env` files, and
+  Databricks bundle App config or variables.
 - YAML/JSON brand-context discovery and loading with shared Zod validation.
 - Idempotent executable downloads with zip/tar extraction and atomic installs.
+- Cross-process file locks with a Bun `flock(2)` fast path and a portable,
+  stale-reclaiming lock-directory fallback.
 - Keyed mutual exclusion across the main thread and its worker threads.
 
 ## Install A Binary
@@ -73,6 +77,48 @@ files. Missing files return the complete dbx tools default context; malformed
 files fail validation. Use `loadBrandContextFile(path)` for an explicit file and
 `resolveBrandAssetPath(path, asset)` for relative asset references.
 
+## Resolve Configuration
+
+```ts
+import { config } from "@dbx-tools/core";
+
+const publicDomain = config.string(undefined, "PUBLIC_DOMAIN", {
+  prefix: "TUNNEL",
+});
+const timeoutMs = config.positiveInt(undefined, "TIMEOUT_MS", 30_000, {
+  prefix: "SEARCH",
+});
+```
+
+Resolution is lazy and follows process env, `.env`, then Databricks bundle
+configuration. The default `DBX_TOOLS` scope and an optional capability prefix
+produce names such as `DBX_TOOLS_TUNNEL_PUBLIC_DOMAIN`, then
+`TUNNEL_PUBLIC_DOMAIN`, then `PUBLIC_DOMAIN`. `.env.production` and `.env.prod`
+are checked before `.env` when `NODE_ENV=production`; development uses
+`.env.development` and `.env.dev`.
+
+Bundle lookup runs `databricks bundle validate --output json` only after earlier
+sources miss. It reads literal values from the single App's `config.env` first,
+then root bundle variables, accepts usable partial JSON from a failed validation,
+and caches each dotenv file or validated bundle once per resolved working-
+directory context. Bundle cache entries also include the Databricks profile.
+Deployed Apps skip dotenv and bundle lookup after `isDatabricksAppEnv()`
+recognizes the required App name, HTTP(S) host, and valid port. Set
+`DBX_TOOLS_DATABRICKS_APP_ENV=true` or `false` to force that result; unrecognized
+values leave automatic detection in place.
+
+`DBX_TOOLS_CONFIG_DOTENV` and `DBX_TOOLS_CONFIG_BUNDLE` independently force
+those file sources on or off. A recognized boolean takes precedence over App
+runtime detection, so `true` can enable a local source inside an App and `false`
+can suppress it during local development. Absent or unrecognized values keep
+the default: read files outside an App and skip them inside one. Bundle reads
+also default off when `NODE_ENV=production`; set
+`DBX_TOOLS_CONFIG_BUNDLE=true` to opt into bundle validation there.
+
+Use `config.string()`, `boolean()`, `positiveNumber()`, `positiveInt()`, and
+`list()` to normalize typed options and text-based configuration through one
+rule. `config.ENV_ONLY` disables file fallbacks for exact environment reads.
+
 ## Run Commands
 
 ```ts
@@ -166,6 +212,28 @@ deployment, use
 [`@dbx-tools/postgres`](../postgres)'s `withAdvisoryLock`, which puts the arbiter
 in PostgreSQL where every replica can see it.
 
+## Serialize Work Across Processes
+
+```ts
+import { fileLock } from "@dbx-tools/core";
+
+await fileLock.withFileLock(["cache", name], async () => {
+  if (!(await exists(name))) await build(name);
+});
+```
+
+`withFileLock()` serializes processes on the same machine or shared filesystem.
+Under Bun on Unix it prefers a kernel `flock(2)` lock, which the OS releases if
+the process dies. Plain Node, Windows, and systems without the FFI path use
+atomic lock-directory creation with a heartbeat and stale-lock reclamation.
+Callers can select the lock directory, restrict the backend cascade, observe the
+chosen backend, or set a wait timeout. Lock keys use the same stable structured
+identity as process and Postgres advisory locks.
+
+Use `processLock.withProcessLock()` when only threads in one process compete,
+`fileLock.withFileLock()` when local processes compete, and Postgres advisory
+locks when multiple app replicas need one arbiter.
+
 ## Discover Project Roots
 
 ```ts
@@ -188,6 +256,11 @@ basename. `project.stat()` returns `undefined` instead of throwing.
 - `project` - root discovery, project naming, git-remote parsing, and safe
   filesystem stat.
 - `brand` - YAML/JSON discovery, parsing, validation, and asset path resolution.
+- `config` - scoped environment, dotenv, and validated Databricks bundle lookup,
+  including runtime detection and typed coercion helpers.
+- `file` - best-effort filesystem stat.
+- `fileLock` - cascading cross-process locks using `flock` or portable lock
+  directories.
 - `processLock` - keyed mutual exclusion across the main thread and its workers,
   with worker wiring (`processLockWorkerOptions`, `attachProcessLock`,
   `processLockAttached`).

package/index.ts

@@ -4,6 +4,7 @@
 
 export * as bin from "./src/bin.ts";
 export * as brand from "./src/brand.ts";
+export * as config from "./src/config.ts";
 export * as exec from "./src/exec.ts";
 export * as file from "./src/file.ts";
 export * as fileLock from "./src/file-lock.ts";
@@ -12,6 +13,8 @@ export * as project from "./src/project.ts";
 export type { BinContext, BinSelectionContext, BinSelector, BinVersionOutput, BinVersionParser, BinOptions, BinUrl } from "./src/bin.ts";
 export { BrandContextSchema, defaultBrandContext, parseBrandContext, brandContextJsonSchema, brandContextPrompt } from "./src/brand.ts";
 export type { BrandContext, BrandContextInput } from "./src/brand.ts";
+export { MAX_TCP_PORT, DATABRICKS_APP_ENV_KEY, CONFIG_DOTENV_KEY, CONFIG_BUNDLE_KEY, ENV_ONLY, bundleValue, bundleResourceSchema, bundleEnvEntrySchema, bundleAppSchema } from "./src/config.ts";
+export type { ConfigKey, ConfigSource, ConfigOptions, ConfigFile } from "./src/config.ts";
 export { COMMAND_NOT_FOUND_EXIT_CODE } from "./src/exec.ts";
 export type { ExecStdio, LineHandler, StdioOption, ExecResult, ChildProcessResult, ExecOptions, SyncExecStdio, SyncExecOptions, SpawnArgs } from "./src/exec.ts";
 export type { FileLockBackend, FileLockAcquisition, FileLockOptions } from "./src/file-lock.ts";

package/lib/index.d.ts

@@ -1,5 +1,6 @@
 export * as bin from "./src/bin.ts";
 export * as brand from "./src/brand.ts";
+export * as config from "./src/config.ts";
 export * as exec from "./src/exec.ts";
 export * as file from "./src/file.ts";
 export * as fileLock from "./src/file-lock.ts";
@@ -8,6 +9,8 @@ export * as project from "./src/project.ts";
 export type { BinContext, BinSelectionContext, BinSelector, BinVersionOutput, BinVersionParser, BinOptions, BinUrl } from "./src/bin.ts";
 export { BrandContextSchema, defaultBrandContext, parseBrandContext, brandContextJsonSchema, brandContextPrompt } from "./src/brand.ts";
 export type { BrandContext, BrandContextInput } from "./src/brand.ts";
+export { MAX_TCP_PORT, DATABRICKS_APP_ENV_KEY, CONFIG_DOTENV_KEY, CONFIG_BUNDLE_KEY, ENV_ONLY, bundleValue, bundleResourceSchema, bundleEnvEntrySchema, bundleAppSchema } from "./src/config.ts";
+export type { ConfigKey, ConfigSource, ConfigOptions, ConfigFile } from "./src/config.ts";
 export { COMMAND_NOT_FOUND_EXIT_CODE } from "./src/exec.ts";
 export type { ExecStdio, LineHandler, StdioOption, ExecResult, ChildProcessResult, ExecOptions, SyncExecStdio, SyncExecOptions, SpawnArgs } from "./src/exec.ts";
 export type { FileLockBackend, FileLockAcquisition, FileLockOptions } from "./src/file-lock.ts";

package/lib/index.js

@@ -3,11 +3,13 @@
 // Hand edits are overwritten on the next watch; this file is read-only.
 export * as bin from "./src/bin.js";
 export * as brand from "./src/brand.js";
+export * as config from "./src/config.js";
 export * as exec from "./src/exec.js";
 export * as file from "./src/file.js";
 export * as fileLock from "./src/file-lock.js";
 export * as processLock from "./src/process-lock.js";
 export * as project from "./src/project.js";
 export { BrandContextSchema, defaultBrandContext, parseBrandContext, brandContextJsonSchema, brandContextPrompt } from "./src/brand.js";
+export { MAX_TCP_PORT, DATABRICKS_APP_ENV_KEY, CONFIG_DOTENV_KEY, CONFIG_BUNDLE_KEY, ENV_ONLY, bundleValue, bundleResourceSchema, bundleEnvEntrySchema, bundleAppSchema } from "./src/config.js";
 export { COMMAND_NOT_FOUND_EXIT_CODE } from "./src/exec.js";
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssR0FBRyxNQUFNLGNBQWMsQ0FBQztBQUNwQyxPQUFPLEtBQUssS0FBSyxNQUFNLGdCQUFnQixDQUFDO0FBQ3hDLE9BQU8sS0FBSyxJQUFJLE1BQU0sZUFBZSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxJQUFJLE1BQU0sZUFBZSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxRQUFRLE1BQU0sb0JBQW9CLENBQUM7QUFDL0MsT0FBTyxLQUFLLFdBQVcsTUFBTSx1QkFBdUIsQ0FBQztBQUNyRCxPQUFPLEtBQUssT0FBTyxNQUFNLGtCQUFrQixDQUFDO0FBRTVDLE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxtQkFBbUIsRUFBRSxpQkFBaUIsRUFBRSxzQkFBc0IsRUFBRSxrQkFBa0IsRUFBRSxNQUFNLGdCQUFnQixDQUFDO0FBRXhJLE9BQU8sRUFBRSwyQkFBMkIsRUFBRSxNQUFNLGVBQWUsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEdFTkVSQVRFRCBieSBwcm9qZW4gd2F0Y2ggLSBETyBOT1QgRURJVC5cbi8vIFJlZ2VuZXJhdGVkIGZyb20gdGhlIGV4cG9ydGluZyBtb2R1bGVzIGluIC4vc3JjLlxuLy8gSGFuZCBlZGl0cyBhcmUgb3ZlcndyaXR0ZW4gb24gdGhlIG5leHQgd2F0Y2g7IHRoaXMgZmlsZSBpcyByZWFkLW9ubHkuXG5cbmV4cG9ydCAqIGFzIGJpbiBmcm9tIFwiLi9zcmMvYmluLnRzXCI7XG5leHBvcnQgKiBhcyBicmFuZCBmcm9tIFwiLi9zcmMvYnJhbmQudHNcIjtcbmV4cG9ydCAqIGFzIGV4ZWMgZnJvbSBcIi4vc3JjL2V4ZWMudHNcIjtcbmV4cG9ydCAqIGFzIGZpbGUgZnJvbSBcIi4vc3JjL2ZpbGUudHNcIjtcbmV4cG9ydCAqIGFzIGZpbGVMb2NrIGZyb20gXCIuL3NyYy9maWxlLWxvY2sudHNcIjtcbmV4cG9ydCAqIGFzIHByb2Nlc3NMb2NrIGZyb20gXCIuL3NyYy9wcm9jZXNzLWxvY2sudHNcIjtcbmV4cG9ydCAqIGFzIHByb2plY3QgZnJvbSBcIi4vc3JjL3Byb2plY3QudHNcIjtcbmV4cG9ydCB0eXBlIHsgQmluQ29udGV4dCwgQmluU2VsZWN0aW9uQ29udGV4dCwgQmluU2VsZWN0b3IsIEJpblZlcnNpb25PdXRwdXQsIEJpblZlcnNpb25QYXJzZXIsIEJpbk9wdGlvbnMsIEJpblVybCB9IGZyb20gXCIuL3NyYy9iaW4udHNcIjtcbmV4cG9ydCB7IEJyYW5kQ29udGV4dFNjaGVtYSwgZGVmYXVsdEJyYW5kQ29udGV4dCwgcGFyc2VCcmFuZENvbnRleHQsIGJyYW5kQ29udGV4dEpzb25TY2hlbWEsIGJyYW5kQ29udGV4dFByb21wdCB9IGZyb20gXCIuL3NyYy9icmFuZC50c1wiO1xuZXhwb3J0IHR5cGUgeyBCcmFuZENvbnRleHQsIEJyYW5kQ29udGV4dElucHV0IH0gZnJvbSBcIi4vc3JjL2JyYW5kLnRzXCI7XG5leHBvcnQgeyBDT01NQU5EX05PVF9GT1VORF9FWElUX0NPREUgfSBmcm9tIFwiLi9zcmMvZXhlYy50c1wiO1xuZXhwb3J0IHR5cGUgeyBFeGVjU3RkaW8sIExpbmVIYW5kbGVyLCBTdGRpb09wdGlvbiwgRXhlY1Jlc3VsdCwgQ2hpbGRQcm9jZXNzUmVzdWx0LCBFeGVjT3B0aW9ucywgU3luY0V4ZWNTdGRpbywgU3luY0V4ZWNPcHRpb25zLCBTcGF3bkFyZ3MgfSBmcm9tIFwiLi9zcmMvZXhlYy50c1wiO1xuZXhwb3J0IHR5cGUgeyBGaWxlTG9ja0JhY2tlbmQsIEZpbGVMb2NrQWNxdWlzaXRpb24sIEZpbGVMb2NrT3B0aW9ucyB9IGZyb20gXCIuL3NyYy9maWxlLWxvY2sudHNcIjtcbmV4cG9ydCB0eXBlIHsgUHJvamVjdENvbnRleHQgfSBmcm9tIFwiLi9zcmMvcHJvamVjdC50c1wiO1xuIl19
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssR0FBRyxNQUFNLGNBQWMsQ0FBQztBQUNwQyxPQUFPLEtBQUssS0FBSyxNQUFNLGdCQUFnQixDQUFDO0FBQ3hDLE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLElBQUksTUFBTSxlQUFlLENBQUM7QUFDdEMsT0FBTyxLQUFLLElBQUksTUFBTSxlQUFlLENBQUM7QUFDdEMsT0FBTyxLQUFLLFFBQVEsTUFBTSxvQkFBb0IsQ0FBQztBQUMvQyxPQUFPLEtBQUssV0FBVyxNQUFNLHVCQUF1QixDQUFDO0FBQ3JELE9BQU8sS0FBSyxPQUFPLE1BQU0sa0JBQWtCLENBQUM7QUFFNUMsT0FBTyxFQUFFLGtCQUFrQixFQUFFLG1CQUFtQixFQUFFLGlCQUFpQixFQUFFLHNCQUFzQixFQUFFLGtCQUFrQixFQUFFLE1BQU0sZ0JBQWdCLENBQUM7QUFFeEksT0FBTyxFQUFFLFlBQVksRUFBRSxzQkFBc0IsRUFBRSxpQkFBaUIsRUFBRSxpQkFBaUIsRUFBRSxRQUFRLEVBQUUsV0FBVyxFQUFFLG9CQUFvQixFQUFFLG9CQUFvQixFQUFFLGVBQWUsRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBRWpNLE9BQU8sRUFBRSwyQkFBMkIsRUFBRSxNQUFNLGVBQWUsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEdFTkVSQVRFRCBieSBwcm9qZW4gd2F0Y2ggLSBETyBOT1QgRURJVC5cbi8vIFJlZ2VuZXJhdGVkIGZyb20gdGhlIGV4cG9ydGluZyBtb2R1bGVzIGluIC4vc3JjLlxuLy8gSGFuZCBlZGl0cyBhcmUgb3ZlcndyaXR0ZW4gb24gdGhlIG5leHQgd2F0Y2g7IHRoaXMgZmlsZSBpcyByZWFkLW9ubHkuXG5cbmV4cG9ydCAqIGFzIGJpbiBmcm9tIFwiLi9zcmMvYmluLnRzXCI7XG5leHBvcnQgKiBhcyBicmFuZCBmcm9tIFwiLi9zcmMvYnJhbmQudHNcIjtcbmV4cG9ydCAqIGFzIGNvbmZpZyBmcm9tIFwiLi9zcmMvY29uZmlnLnRzXCI7XG5leHBvcnQgKiBhcyBleGVjIGZyb20gXCIuL3NyYy9leGVjLnRzXCI7XG5leHBvcnQgKiBhcyBmaWxlIGZyb20gXCIuL3NyYy9maWxlLnRzXCI7XG5leHBvcnQgKiBhcyBmaWxlTG9jayBmcm9tIFwiLi9zcmMvZmlsZS1sb2NrLnRzXCI7XG5leHBvcnQgKiBhcyBwcm9jZXNzTG9jayBmcm9tIFwiLi9zcmMvcHJvY2Vzcy1sb2NrLnRzXCI7XG5leHBvcnQgKiBhcyBwcm9qZWN0IGZyb20gXCIuL3NyYy9wcm9qZWN0LnRzXCI7XG5leHBvcnQgdHlwZSB7IEJpbkNvbnRleHQsIEJpblNlbGVjdGlvbkNvbnRleHQsIEJpblNlbGVjdG9yLCBCaW5WZXJzaW9uT3V0cHV0LCBCaW5WZXJzaW9uUGFyc2VyLCBCaW5PcHRpb25zLCBCaW5VcmwgfSBmcm9tIFwiLi9zcmMvYmluLnRzXCI7XG5leHBvcnQgeyBCcmFuZENvbnRleHRTY2hlbWEsIGRlZmF1bHRCcmFuZENvbnRleHQsIHBhcnNlQnJhbmRDb250ZXh0LCBicmFuZENvbnRleHRKc29uU2NoZW1hLCBicmFuZENvbnRleHRQcm9tcHQgfSBmcm9tIFwiLi9zcmMvYnJhbmQudHNcIjtcbmV4cG9ydCB0eXBlIHsgQnJhbmRDb250ZXh0LCBCcmFuZENvbnRleHRJbnB1dCB9IGZyb20gXCIuL3NyYy9icmFuZC50c1wiO1xuZXhwb3J0IHsgTUFYX1RDUF9QT1JULCBEQVRBQlJJQ0tTX0FQUF9FTlZfS0VZLCBDT05GSUdfRE9URU5WX0tFWSwgQ09ORklHX0JVTkRMRV9LRVksIEVOVl9PTkxZLCBidW5kbGVWYWx1ZSwgYnVuZGxlUmVzb3VyY2VTY2hlbWEsIGJ1bmRsZUVudkVudHJ5U2NoZW1hLCBidW5kbGVBcHBTY2hlbWEgfSBmcm9tIFwiLi9zcmMvY29uZmlnLnRzXCI7XG5leHBvcnQgdHlwZSB7IENvbmZpZ0tleSwgQ29uZmlnU291cmNlLCBDb25maWdPcHRpb25zLCBDb25maWdGaWxlIH0gZnJvbSBcIi4vc3JjL2NvbmZpZy50c1wiO1xuZXhwb3J0IHsgQ09NTUFORF9OT1RfRk9VTkRfRVhJVF9DT0RFIH0gZnJvbSBcIi4vc3JjL2V4ZWMudHNcIjtcbmV4cG9ydCB0eXBlIHsgRXhlY1N0ZGlvLCBMaW5lSGFuZGxlciwgU3RkaW9PcHRpb24sIEV4ZWNSZXN1bHQsIENoaWxkUHJvY2Vzc1Jlc3VsdCwgRXhlY09wdGlvbnMsIFN5bmNFeGVjU3RkaW8sIFN5bmNFeGVjT3B0aW9ucywgU3Bhd25BcmdzIH0gZnJvbSBcIi4vc3JjL2V4ZWMudHNcIjtcbmV4cG9ydCB0eXBlIHsgRmlsZUxvY2tCYWNrZW5kLCBGaWxlTG9ja0FjcXVpc2l0aW9uLCBGaWxlTG9ja09wdGlvbnMgfSBmcm9tIFwiLi9zcmMvZmlsZS1sb2NrLnRzXCI7XG5leHBvcnQgdHlwZSB7IFByb2plY3RDb250ZXh0IH0gZnJvbSBcIi4vc3JjL3Byb2plY3QudHNcIjtcbiJdfQ==

package/lib/src/config.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Layered configuration lookup: environment, `.env`, Databricks bundle.
+ *
+ * Every package resolves settings the same way: take the caller's value, else
+ * an environment variable, else a default. Local development adds two fallback
+ * locations: `.env` files and `resources.apps.<app>.config.env` or root
+ * `variables` in `databricks.yml`.
+ *
+ * Two things make it cheap to call from a hot path:
+ *
+ *   - {@link values} is LAZY (an `object.Sequence`), so `databricks bundle
+ *     validate` is only spawned when the environment and `.env` both missed.
+ *   - the parsed `.env` and bundle are cached through {@link context.cached}, so
+ *     the spawn happens once per working directory and a `cwd` change misses
+ *     rather than returning another project's config.
+ *
+ * Inside a deployed Databricks App both file sources are skipped by default
+ * ({@link isDatabricksAppEnv}): the platform has already turned them into real
+ * environment variables, there is no bundle to validate, and the `databricks`
+ * CLI is not on the image. Boolean environment overrides can force either file
+ * source on or off when a tool needs different behavior.
+ *
+ * Node-only (`child_process`, `fs`, `process`).
+ *
+ * @module
+ */
+import { z } from "zod";
+export type ConfigKey = string | readonly string[];
+/** Where a value may come from, consulted in the order given. */
+export type ConfigSource = "env" | "dotenv" | "bundle";
+export interface ConfigOptions {
+    /**
+     * Outermost namespaces tried before each key. Defaults to `DBX_TOOLS`.
+     */
+    scope?: string | readonly string[];
+    /** Capability namespaces inserted after the scope and before each key. */
+    prefix?: string | readonly string[];
+    /** Directory to resolve `.env` and the bundle from. Default: `process.cwd()`. */
+    cwd?: string;
+    /** Sources in precedence order. Default: `env`, `dotenv`, `bundle`. */
+    sources?: ConfigSource | readonly ConfigSource[];
+}
+/** A config file found on disk, with its parsed contents. */
+export interface ConfigFile {
+    path: string;
+    data: Record<string, unknown>;
+}
+/** Highest valid TCP port number. */
+export declare const MAX_TCP_PORT = 65535;
+/** Boolean environment override for {@link isDatabricksAppEnv}. */
+export declare const DATABRICKS_APP_ENV_KEY = "DBX_TOOLS_DATABRICKS_APP_ENV";
+/** Boolean environment override for project `.env` reads. */
+export declare const CONFIG_DOTENV_KEY = "DBX_TOOLS_CONFIG_DOTENV";
+/** Boolean environment override for Databricks bundle reads. */
+export declare const CONFIG_BUNDLE_KEY = "DBX_TOOLS_CONFIG_BUNDLE";
+/** Exact process-environment lookup for callers that do not read local config files. */
+export declare const ENV_ONLY: {
+    scope: readonly [];
+    sources: "env";
+};
+export declare const bundleValue: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+/**
+ * The GENERIC shape of a bundle resource: a name, and whatever else the resource
+ * type carries. Deliberately unopinionated and `passthrough()` - the concrete
+ * resource kinds (`sql_warehouse`, `genie_space`, `postgres`, ...) are
+ * Databricks-App concepts that belong to the package that resolves them, so
+ * node-appkit `.extend()`s this rather than this module knowing about them.
+ */
+export declare const bundleResourceSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+}, z.core.$loose>;
+export declare const bundleEnvEntrySchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    value: z.ZodOptional<z.ZodString>;
+    value_from: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+}, z.core.$strip>;
+export declare const bundleAppSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    source_code_path: z.ZodOptional<z.ZodString>;
+    config: z.ZodOptional<z.ZodObject<{
+        env: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+            value: z.ZodOptional<z.ZodString>;
+            value_from: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    resources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    }, z.core.$loose>>>;
+}, z.core.$strip>;
+/**
+ * Detect a Databricks App runtime from its required name, host, and port.
+ *
+ * `DBX_TOOLS_DATABRICKS_APP_ENV` takes precedence when it contains a recognized
+ * boolean value. This lets local tools emulate the deployed runtime (`true`) or
+ * lets unusual deployed processes retain local config lookup (`false`). An
+ * absent or unrecognized override falls back to structural detection.
+ */
+export declare function isDatabricksAppEnv(source?: Record<string, string | undefined>): boolean;
+/**
+ * The first value that resolves for `input`, or `undefined`.
+ *
+ * @example
+ * const domain = config.text(["TUNNEL_PUBLIC_DOMAIN", "PUBLIC_DOMAIN"]);
+ */
+export declare function text(input: ConfigKey, options?: ConfigOptions): string | undefined;
+/**
+ * The PRIMARY (fully-scoped) name for `input` - what to print in a log line or an
+ * error, so the message names the variable a reader should set. Do not index
+ * `keys(...)[0]` for this if `input` may be a bare string.
+ *
+ * @example
+ * logger.warn(`${config.name(JWT_SECRET_ENV)} is not set`);
+ */
+export declare function name(input: ConfigKey, options?: Pick<ConfigOptions, "scope" | "prefix">): string;
+/**
+ * Resolve a string: `configured` when non-empty, else {@link text}, else `undefined`.
+ *
+ * The coercion rules are deliberately loose (`on` / `yes` / `1` are all
+ * `true`) because values may come from a file a human typed.
+ *
+ * @example
+ * config.string(options.host, "SMTP_HOST");
+ */
+export declare function string(configured: unknown, input: ConfigKey, options?: ConfigOptions): string | undefined;
+/**
+ * Resolve a boolean through `object.toBoolean`. `undefined` when neither source
+ * is interpretable, so the caller picks a default with `??`.
+ */
+export declare function boolean(configured: unknown, input: ConfigKey, options?: ConfigOptions): boolean | undefined;
+/**
+ * Resolve a positive number that may be fractional (a score threshold, a ratio).
+ * Use {@link positiveInt} for a count, port, or timeout.
+ */
+export declare function positiveNumber(configured: unknown, input: ConfigKey, fallback: number, options?: ConfigOptions): number;
+/**
+ * Resolve a positive integer (a port, a timeout, a page size), floored. A
+ * non-numeric or non-positive value is treated as ABSENT rather than fatal -
+ * these are ceilings where a sane default beats a boot failure.
+ */
+export declare function positiveInt(configured: unknown, input: ConfigKey, fallback: number, options?: ConfigOptions): number;
+/**
+ * Resolve a list through `string.parseList`, so an array from typed config and a
+ * `"a, b c"` string normalize identically. `[]` when neither source has entries.
+ */
+export declare function list(configured: string | readonly string[] | undefined | null, input: ConfigKey, transform?: (entry: string) => string, options?: ConfigOptions): string[];
+/**
+ * The Databricks bundle output for `cwd` - `databricks bundle validate --output
+ * json` run from the directory holding `databricks.yml`, with the config file's
+ * path. A non-zero validation may still return partial JSON with usable
+ * variables. `undefined` when bundle reads are disabled, there is no bundle, or
+ * the CLI produces no JSON.
+ *
+ * Cached once per resolved working-directory context and
+ * `DATABRICKS_CONFIG_PROFILE` through {@link context.cached}, so repeated
+ * lookups do not rerun validation and changing either cannot return another
+ * context's bundle.
+ */
+export declare function bundleFile(cwd?: string | null): ConfigFile | undefined;