@dbx-tools/core 0.6.89 → 0.6.90

package/README.md

@@ -90,18 +90,39 @@ const timeoutMs = config.positiveInt(undefined, "TIMEOUT_MS", 30_000, {
 });
 ```
 
-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
+Resolution is lazy and follows constant `data`, process env, `.env`, Databricks
+bundle configuration, then `app.yaml` / `app.yml` env values. 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`.
 
+Pass one config map or an array of maps through `data`; the first matching value
+wins before environment lookup by default. When a custom `sources` order omits
+`config`, passed data is still read and is appended last. This lets a caller put
+env first without accidentally discarding its fallback config:
+
+```ts
+const endpoint = config.resolveValue("lakebaseEndpoint", {
+  data: { LAKEBASE_ENDPOINT: flags.endpoint },
+  sources: ["env", "dotenv", "bundle", "app"],
+});
+```
+
+`resolveValue()` tries the exact, uppercase, and tokenized-uppercase forms from
+`environmentKeys()` before applying normal scope and prefix expansion.
+
 Bundle lookup runs `databricks bundle validate --output json` only after earlier
 sources miss. It reads literal values from the single App's `config.env`, 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. Root bundle `variables` are NOT a
+usable partial JSON from a failed validation, and honors the active Databricks
+profile. Parsed dotenv records are cached by file path; parsed bundle output is
+cached by bundle path plus profile. App YAML lookup runs only if the bundle did
+not resolve the key and reads `env[].value` entries. Bundle `value_from` and App
+YAML `valueFrom` references resolve supported fields from their named
+`sql_warehouse`, `genie_space`, or `postgres` resource. Config-file discovery and parsed results
+are single-attempt per source key: found paths, missing files, empty records,
+invalid records, and `undefined` results all cache. Root bundle `variables` are NOT a
 config source: they are authoring inputs interpolated into the bundle's own
 targets, resources, and paths, so reading one as a process setting resolves names
 the deployed App never sees. Reference a variable from `config.env` to make it
@@ -113,13 +134,14 @@ contains a bundle, and bundle reads are enabled, validation runs. This keeps
 pre-boot callers such as `@dbx-tools/appkit` auto-configuration on the same
 deterministic path as CLIs and ordinary Node consumers.
 
-Deployed Apps skip dotenv and bundle lookup after `isDatabricksAppEnv()`
+Deployed Apps skip dotenv, bundle, and app YAML 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
+`DBX_TOOLS_CONFIG_DOTENV`, `DBX_TOOLS_CONFIG_BUNDLE`, and
+`DBX_TOOLS_CONFIG_APP` 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
@@ -130,6 +152,8 @@ Use `config.string()`, `boolean()`, `positiveNumber()`, `positiveInt()`,
 `port()`, and `list()` to normalize typed options and text-based configuration
 through one rule. `config.port()` accepts only TCP ports from 1 through 65535;
 `config.ENV_ONLY` disables file fallbacks for exact environment reads.
+`config.flattenBundleEnv()`, `flattenAppEnv()`, and `getBundlePath()` expose the
+same parsing logic for callers that already have parsed configuration data.
 
 ## Run Commands
 
@@ -254,19 +278,25 @@ import { project } from "@dbx-tools/core";
 const root = project.root();
 const name = project.name();
 const origins = [...project.resolveProjectRoots(process.cwd())];
+const cwd = project.resolveWorkingDirectory("");
 ```
 
 `project.root()` checks npm/pnpm workspace roots, git top-level, and cwd.
 `project.name()` prefers package metadata, then git remote name, then directory
-basename. `project.stat()` returns `undefined` instead of throwing.
+basename. `project.resolveWorkingDirectory()` normalizes blank, null, omitted,
+relative, and absolute cwd values for cache decisions. Project subprocess probes
+share a command/argument result cache only when that resolved path is the live
+process cwd; another directory executes directly. Empty command results are
+cached too.
 
 ## Modules
 
 - `exec` - async/sync process spawning, stdio handling, abort wiring, and shlex.
 - `bin` - executable download, optional archive extraction, selection, and
   atomic installation.
-- `project` - root discovery, project naming, git-remote parsing, and safe
-  filesystem stat.
+- `project` - cwd normalization, root discovery, project naming, and git-remote
+  parsing.
+- `file` - best-effort stat and parsed-record caching by caller-defined source key.
 - `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.

package/index.ts

@@ -13,7 +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, ENV_ONLY, valueSchema, bundleResourceSchema, bundleEnvEntrySchema, bundleAppSchema } from "./src/config.ts";
+export { MAX_TCP_PORT, ENV_ONLY, valueSchema, bundleResourceSchema, bundleEnvEntrySchema, bundleAppSchema, appEnvEntrySchema, appSchema } from "./src/config.ts";
+export type { ConfigMapValue, ConfigData, 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

@@ -9,7 +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, ENV_ONLY, valueSchema, bundleResourceSchema, bundleEnvEntrySchema, bundleAppSchema } from "./src/config.ts";
+export { MAX_TCP_PORT, ENV_ONLY, valueSchema, bundleResourceSchema, bundleEnvEntrySchema, bundleAppSchema, appEnvEntrySchema, appSchema } from "./src/config.ts";
+export type { ConfigMapValue, ConfigData, 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

@@ -10,6 +10,6 @@ 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, ENV_ONLY, valueSchema, bundleResourceSchema, bundleEnvEntrySchema, bundleAppSchema } from "./src/config.js";
+export { MAX_TCP_PORT, ENV_ONLY, valueSchema, bundleResourceSchema, bundleEnvEntrySchema, bundleAppSchema, appEnvEntrySchema, appSchema } from "./src/config.js";
 export { COMMAND_NOT_FOUND_EXIT_CODE } from "./src/exec.js";
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssR0FBRyxNQUFNLGNBQWMsQ0FBQztBQUNwQyxPQUFPLEtBQUssS0FBSyxNQUFNLGdCQUFnQixDQUFDO0FBQ3hDLE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLElBQUksTUFBTSxlQUFlLENBQUM7QUFDdEMsT0FBTyxLQUFLLElBQUksTUFBTSxlQUFlLENBQUM7QUFDdEMsT0FBTyxLQUFLLFFBQVEsTUFBTSxvQkFBb0IsQ0FBQztBQUMvQyxPQUFPLEtBQUssV0FBVyxNQUFNLHVCQUF1QixDQUFDO0FBQ3JELE9BQU8sS0FBSyxPQUFPLE1BQU0sa0JBQWtCLENBQUM7QUFFNUMsT0FBTyxFQUFFLGtCQUFrQixFQUFFLG1CQUFtQixFQUFFLGlCQUFpQixFQUFFLHNCQUFzQixFQUFFLGtCQUFrQixFQUFFLE1BQU0sZ0JBQWdCLENBQUM7QUFFeEksT0FBTyxFQUFFLFlBQVksRUFBRSxRQUFRLEVBQUUsV0FBVyxFQUFFLG9CQUFvQixFQUFFLG9CQUFvQixFQUFFLGVBQWUsRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBQ25JLE9BQU8sRUFBRSwyQkFBMkIsRUFBRSxNQUFNLGVBQWUsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEdFTkVSQVRFRCBieSBwcm9qZW4gd2F0Y2ggLSBETyBOT1QgRURJVC5cbi8vIFJlZ2VuZXJhdGVkIGZyb20gdGhlIGV4cG9ydGluZyBtb2R1bGVzIGluIC4vc3JjLlxuLy8gSGFuZCBlZGl0cyBhcmUgb3ZlcndyaXR0ZW4gb24gdGhlIG5leHQgd2F0Y2g7IHRoaXMgZmlsZSBpcyByZWFkLW9ubHkuXG5cbmV4cG9ydCAqIGFzIGJpbiBmcm9tIFwiLi9zcmMvYmluLnRzXCI7XG5leHBvcnQgKiBhcyBicmFuZCBmcm9tIFwiLi9zcmMvYnJhbmQudHNcIjtcbmV4cG9ydCAqIGFzIGNvbmZpZyBmcm9tIFwiLi9zcmMvY29uZmlnLnRzXCI7XG5leHBvcnQgKiBhcyBleGVjIGZyb20gXCIuL3NyYy9leGVjLnRzXCI7XG5leHBvcnQgKiBhcyBmaWxlIGZyb20gXCIuL3NyYy9maWxlLnRzXCI7XG5leHBvcnQgKiBhcyBmaWxlTG9jayBmcm9tIFwiLi9zcmMvZmlsZS1sb2NrLnRzXCI7XG5leHBvcnQgKiBhcyBwcm9jZXNzTG9jayBmcm9tIFwiLi9zcmMvcHJvY2Vzcy1sb2NrLnRzXCI7XG5leHBvcnQgKiBhcyBwcm9qZWN0IGZyb20gXCIuL3NyYy9wcm9qZWN0LnRzXCI7XG5leHBvcnQgdHlwZSB7IEJpbkNvbnRleHQsIEJpblNlbGVjdGlvbkNvbnRleHQsIEJpblNlbGVjdG9yLCBCaW5WZXJzaW9uT3V0cHV0LCBCaW5WZXJzaW9uUGFyc2VyLCBCaW5PcHRpb25zLCBCaW5VcmwgfSBmcm9tIFwiLi9zcmMvYmluLnRzXCI7XG5leHBvcnQgeyBCcmFuZENvbnRleHRTY2hlbWEsIGRlZmF1bHRCcmFuZENvbnRleHQsIHBhcnNlQnJhbmRDb250ZXh0LCBicmFuZENvbnRleHRKc29uU2NoZW1hLCBicmFuZENvbnRleHRQcm9tcHQgfSBmcm9tIFwiLi9zcmMvYnJhbmQudHNcIjtcbmV4cG9ydCB0eXBlIHsgQnJhbmRDb250ZXh0LCBCcmFuZENvbnRleHRJbnB1dCB9IGZyb20gXCIuL3NyYy9icmFuZC50c1wiO1xuZXhwb3J0IHsgTUFYX1RDUF9QT1JULCBFTlZfT05MWSwgdmFsdWVTY2hlbWEsIGJ1bmRsZVJlc291cmNlU2NoZW1hLCBidW5kbGVFbnZFbnRyeVNjaGVtYSwgYnVuZGxlQXBwU2NoZW1hIH0gZnJvbSBcIi4vc3JjL2NvbmZpZy50c1wiO1xuZXhwb3J0IHsgQ09NTUFORF9OT1RfRk9VTkRfRVhJVF9DT0RFIH0gZnJvbSBcIi4vc3JjL2V4ZWMudHNcIjtcbmV4cG9ydCB0eXBlIHsgRXhlY1N0ZGlvLCBMaW5lSGFuZGxlciwgU3RkaW9PcHRpb24sIEV4ZWNSZXN1bHQsIENoaWxkUHJvY2Vzc1Jlc3VsdCwgRXhlY09wdGlvbnMsIFN5bmNFeGVjU3RkaW8sIFN5bmNFeGVjT3B0aW9ucywgU3Bhd25BcmdzIH0gZnJvbSBcIi4vc3JjL2V4ZWMudHNcIjtcbmV4cG9ydCB0eXBlIHsgRmlsZUxvY2tCYWNrZW5kLCBGaWxlTG9ja0FjcXVpc2l0aW9uLCBGaWxlTG9ja09wdGlvbnMgfSBmcm9tIFwiLi9zcmMvZmlsZS1sb2NrLnRzXCI7XG5leHBvcnQgdHlwZSB7IFByb2plY3RDb250ZXh0IH0gZnJvbSBcIi4vc3JjL3Byb2plY3QudHNcIjtcbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssR0FBRyxNQUFNLGNBQWMsQ0FBQztBQUNwQyxPQUFPLEtBQUssS0FBSyxNQUFNLGdCQUFnQixDQUFDO0FBQ3hDLE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLElBQUksTUFBTSxlQUFlLENBQUM7QUFDdEMsT0FBTyxLQUFLLElBQUksTUFBTSxlQUFlLENBQUM7QUFDdEMsT0FBTyxLQUFLLFFBQVEsTUFBTSxvQkFBb0IsQ0FBQztBQUMvQyxPQUFPLEtBQUssV0FBVyxNQUFNLHVCQUF1QixDQUFDO0FBQ3JELE9BQU8sS0FBSyxPQUFPLE1BQU0sa0JBQWtCLENBQUM7QUFFNUMsT0FBTyxFQUFFLGtCQUFrQixFQUFFLG1CQUFtQixFQUFFLGlCQUFpQixFQUFFLHNCQUFzQixFQUFFLGtCQUFrQixFQUFFLE1BQU0sZ0JBQWdCLENBQUM7QUFFeEksT0FBTyxFQUFFLFlBQVksRUFBRSxRQUFRLEVBQUUsV0FBVyxFQUFFLG9CQUFvQixFQUFFLG9CQUFvQixFQUFFLGVBQWUsRUFBRSxpQkFBaUIsRUFBRSxTQUFTLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUVqSyxPQUFPLEVBQUUsMkJBQTJCLEVBQUUsTUFBTSxlQUFlLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBHRU5FUkFURUQgYnkgcHJvamVuIHdhdGNoIC0gRE8gTk9UIEVESVQuXG4vLyBSZWdlbmVyYXRlZCBmcm9tIHRoZSBleHBvcnRpbmcgbW9kdWxlcyBpbiAuL3NyYy5cbi8vIEhhbmQgZWRpdHMgYXJlIG92ZXJ3cml0dGVuIG9uIHRoZSBuZXh0IHdhdGNoOyB0aGlzIGZpbGUgaXMgcmVhZC1vbmx5LlxuXG5leHBvcnQgKiBhcyBiaW4gZnJvbSBcIi4vc3JjL2Jpbi50c1wiO1xuZXhwb3J0ICogYXMgYnJhbmQgZnJvbSBcIi4vc3JjL2JyYW5kLnRzXCI7XG5leHBvcnQgKiBhcyBjb25maWcgZnJvbSBcIi4vc3JjL2NvbmZpZy50c1wiO1xuZXhwb3J0ICogYXMgZXhlYyBmcm9tIFwiLi9zcmMvZXhlYy50c1wiO1xuZXhwb3J0ICogYXMgZmlsZSBmcm9tIFwiLi9zcmMvZmlsZS50c1wiO1xuZXhwb3J0ICogYXMgZmlsZUxvY2sgZnJvbSBcIi4vc3JjL2ZpbGUtbG9jay50c1wiO1xuZXhwb3J0ICogYXMgcHJvY2Vzc0xvY2sgZnJvbSBcIi4vc3JjL3Byb2Nlc3MtbG9jay50c1wiO1xuZXhwb3J0ICogYXMgcHJvamVjdCBmcm9tIFwiLi9zcmMvcHJvamVjdC50c1wiO1xuZXhwb3J0IHR5cGUgeyBCaW5Db250ZXh0LCBCaW5TZWxlY3Rpb25Db250ZXh0LCBCaW5TZWxlY3RvciwgQmluVmVyc2lvbk91dHB1dCwgQmluVmVyc2lvblBhcnNlciwgQmluT3B0aW9ucywgQmluVXJsIH0gZnJvbSBcIi4vc3JjL2Jpbi50c1wiO1xuZXhwb3J0IHsgQnJhbmRDb250ZXh0U2NoZW1hLCBkZWZhdWx0QnJhbmRDb250ZXh0LCBwYXJzZUJyYW5kQ29udGV4dCwgYnJhbmRDb250ZXh0SnNvblNjaGVtYSwgYnJhbmRDb250ZXh0UHJvbXB0IH0gZnJvbSBcIi4vc3JjL2JyYW5kLnRzXCI7XG5leHBvcnQgdHlwZSB7IEJyYW5kQ29udGV4dCwgQnJhbmRDb250ZXh0SW5wdXQgfSBmcm9tIFwiLi9zcmMvYnJhbmQudHNcIjtcbmV4cG9ydCB7IE1BWF9UQ1BfUE9SVCwgRU5WX09OTFksIHZhbHVlU2NoZW1hLCBidW5kbGVSZXNvdXJjZVNjaGVtYSwgYnVuZGxlRW52RW50cnlTY2hlbWEsIGJ1bmRsZUFwcFNjaGVtYSwgYXBwRW52RW50cnlTY2hlbWEsIGFwcFNjaGVtYSB9IGZyb20gXCIuL3NyYy9jb25maWcudHNcIjtcbmV4cG9ydCB0eXBlIHsgQ29uZmlnTWFwVmFsdWUsIENvbmZpZ0RhdGEsIENvbmZpZ1NvdXJjZSwgQ29uZmlnT3B0aW9ucywgQ29uZmlnRmlsZSB9IGZyb20gXCIuL3NyYy9jb25maWcudHNcIjtcbmV4cG9ydCB7IENPTU1BTkRfTk9UX0ZPVU5EX0VYSVRfQ09ERSB9IGZyb20gXCIuL3NyYy9leGVjLnRzXCI7XG5leHBvcnQgdHlwZSB7IEV4ZWNTdGRpbywgTGluZUhhbmRsZXIsIFN0ZGlvT3B0aW9uLCBFeGVjUmVzdWx0LCBDaGlsZFByb2Nlc3NSZXN1bHQsIEV4ZWNPcHRpb25zLCBTeW5jRXhlY1N0ZGlvLCBTeW5jRXhlY09wdGlvbnMsIFNwYXduQXJncyB9IGZyb20gXCIuL3NyYy9leGVjLnRzXCI7XG5leHBvcnQgdHlwZSB7IEZpbGVMb2NrQmFja2VuZCwgRmlsZUxvY2tBY3F1aXNpdGlvbiwgRmlsZUxvY2tPcHRpb25zIH0gZnJvbSBcIi4vc3JjL2ZpbGUtbG9jay50c1wiO1xuZXhwb3J0IHR5cGUgeyBQcm9qZWN0Q29udGV4dCB9IGZyb20gXCIuL3NyYy9wcm9qZWN0LnRzXCI7XG4iXX0=

package/lib/src/config.d.ts

@@ -1,29 +1,25 @@
 /**
- * Layered configuration lookup: environment, `.env`, Databricks bundle.
+ * Layered configuration lookup: environment, `.env`, bundle, and `app.yaml`.
  *
  * 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 one App's `resources.apps.<app>.config.env` in
- * `databricks.yml`.
+ * locations: `.env` files, one App's `resources.apps.<app>.config.env` in
+ * `databricks.yml`, and literal env values in `app.yaml` / `app.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; app YAML is only
+ * read after the bundle source also missed.
  *
- *   - {@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
+ * Inside a deployed Databricks App all three 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.
  *
- * Only the single app's `config.env` is consulted. Root bundle `variables` are
- * not: they are authoring inputs for the bundle itself (interpolated into
- * targets, resources, and paths), so treating one as a process setting resolves
- * names the deployed app never sees.
+ * Only the single bundle app's `config.env` and literal app YAML `env[].value`
+ * entries are consulted. Root bundle `variables` are not: they are authoring
+ * inputs for the bundle itself (interpolated into targets, resources, and paths),
+ * so treating one as a process setting resolves names the deployed app never sees.
  *
  * Node-only (`child_process`, `fs`, `process`).
  *
@@ -31,22 +27,30 @@
  */
 import { z } from "zod";
 type ConfigKey = string | readonly string[];
+export type ConfigMapValue = string | readonly string[] | null | undefined;
+export type ConfigData = Readonly<Record<string, ConfigMapValue>>;
 /** Where a value may come from, consulted in the order given. */
-type ConfigSource = "env" | "dotenv" | "bundle";
-interface ConfigOptions {
+export type ConfigSource = "config" | "env" | "dotenv" | "bundle" | "app";
+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[];
-    /** Sources in precedence order. Default: `env`, `dotenv`, `bundle`. */
+    /** Constant config maps read by the `config` source. */
+    data?: ConfigData | readonly ConfigData[];
+    /** Parsed bundle data used instead of loading `databricks.yml`. */
+    bundleData?: ConfigFile | Record<string, unknown>;
+    /** Parsed app YAML data used instead of loading `app.yaml`. */
+    appData?: ConfigFile | Record<string, unknown>;
+    /** Sources in precedence order. Default: `config`, `env`, `dotenv`, `bundle`, `app`. */
     sources?: ConfigSource | readonly ConfigSource[];
     /** Directory to resolve `.env` and the bundle from. Default: `process.cwd()`. */
     cwd?: string;
 }
 /** A config file found on disk, with its parsed contents. */
-interface ConfigFile {
+export interface ConfigFile {
     path: string;
     data: Record<string, unknown>;
 }
@@ -58,13 +62,7 @@ export declare const ENV_ONLY: {
     sources: "env";
 };
 export declare const valueSchema: z.ZodString;
-/**
- * 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.
- */
+/** A named bundle or App resource; concrete resource fields pass through. */
 export declare const bundleResourceSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
@@ -86,6 +84,27 @@ export declare const bundleAppSchema: z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>>;
 }, z.core.$strip>;
+export declare const appEnvEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    value: z.ZodOptional<z.ZodString>;
+    valueFrom: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const appSchema: z.ZodObject<{
+    env: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodOptional<z.ZodString>;
+        valueFrom: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    resources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+}, z.core.$strip>;
+/** Flatten the single bundle App's `config.env`, resolving resource references. */
+export declare function flattenBundleEnv(data: unknown): Record<string, string>;
+/** Flatten `app.yaml` env entries, resolving `valueFrom` resource references. */
+export declare function flattenAppEnv(data: unknown): Record<string, string>;
+/** Walk a dot-separated path through parsed bundle data. */
+export declare function getBundlePath(data: Record<string, unknown>, path: string): string | undefined;
 /**
  * Detect a Databricks App runtime from its required name, host, and port.
  *
@@ -95,6 +114,8 @@ export declare const bundleAppSchema: z.ZodObject<{
  * absent or unrecognized override falls back to structural detection.
  */
 export declare function isDatabricksAppEnv(source?: Record<string, string | undefined>): boolean;
+/** Exact, uppercase, and tokenized-uppercase names for a human-friendly key. */
+export declare function environmentKeys(name: string): readonly string[];
 /**
  * The first value that resolves for `input`, or `undefined`.
  *
@@ -102,6 +123,8 @@ export declare function isDatabricksAppEnv(source?: Record<string, string | unde
  * const domain = config.text(["TUNNEL_PUBLIC_DOMAIN", "PUBLIC_DOMAIN"]);
  */
 export declare function text(input: ConfigKey, options?: ConfigOptions): string | undefined;
+/** Resolve a human-friendly name through {@link environmentKeys} and {@link text}. */
+export declare function resolveValue(name: string, 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
@@ -156,10 +179,10 @@ export declare function list(configured: string | readonly string[] | undefined
  * or a deployed App without an explicit override, 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.
+ * Parsed validation output is cached by bundle path and Databricks profile.
+ *
  */
 export declare function bundleFile(cwd?: string | null): ConfigFile | undefined;
+/** The parsed `app.yaml` / `app.yml` for `cwd`, when local App config reads are enabled. */
+export declare function appFile(cwd?: string | null): ConfigFile | undefined;
 export {};