@dbx-tools/core 0.6.88 → 0.6.90

package/README.md

@@ -90,51 +90,70 @@ 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
 one.
 
-Because validation is a process spawn, it is gated on this being an AppKit
-project at all, in three steps. `@databricks/appkit` must be RESOLVABLE - it is
-an optional peer, the probe resolves the path without evaluating the module, and
-a consumer that never installed it never spawns the CLI. The bundle must then
-describe exactly ONE app carrying `config.env`, since nothing in this package
-says which of several apps a process is. Finally AppKit's execution context
-confirms the process really is that app; that context does not exist until AppKit
-boots, so only the affirmative is remembered and a lookup during boot still
-resolves from the bundle instead of being permanently denied. Setting
-`DBX_TOOLS_CONFIG_BUNDLE=true` skips this gate for a tool that wants the bundle
-without being the App.
-
-Deployed Apps skip dotenv and bundle lookup after `isDatabricksAppEnv()`
+Bundle lookup is not coupled to AppKit installation or execution context. If
+earlier sources miss during local development, the configured working directory
+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, 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
 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.
+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
 
@@ -259,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,8 +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 { 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,8 +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 { 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, DATABRICKS_APP_ENV_KEY, CONFIG_DOTENV_KEY, CONFIG_BUNDLE_KEY, ENV_ONLY, bundleValue, 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,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssR0FBRyxNQUFNLGNBQWMsQ0FBQztBQUNwQyxPQUFPLEtBQUssS0FBSyxNQUFNLGdCQUFnQixDQUFDO0FBQ3hDLE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLElBQUksTUFBTSxlQUFlLENBQUM7QUFDdEMsT0FBTyxLQUFLLElBQUksTUFBTSxlQUFlLENBQUM7QUFDdEMsT0FBTyxLQUFLLFFBQVEsTUFBTSxvQkFBb0IsQ0FBQztBQUMvQyxPQUFPLEtBQUssV0FBVyxNQUFNLHVCQUF1QixDQUFDO0FBQ3JELE9BQU8sS0FBSyxPQUFPLE1BQU0sa0JBQWtCLENBQUM7QUFFNUMsT0FBTyxFQUFFLGtCQUFrQixFQUFFLG1CQUFtQixFQUFFLGlCQUFpQixFQUFFLHNCQUFzQixFQUFFLGtCQUFrQixFQUFFLE1BQU0sZ0JBQWdCLENBQUM7QUFFeEksT0FBTyxFQUFFLFlBQVksRUFBRSxzQkFBc0IsRUFBRSxpQkFBaUIsRUFBRSxpQkFBaUIsRUFBRSxRQUFRLEVBQUUsV0FBVyxFQUFFLG9CQUFvQixFQUFFLG9CQUFvQixFQUFFLGVBQWUsRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBRWpNLE9BQU8sRUFBRSwyQkFBMkIsRUFBRSxNQUFNLGVBQWUsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEdFTkVSQVRFRCBieSBwcm9qZW4gd2F0Y2ggLSBETyBOT1QgRURJVC5cbi8vIFJlZ2VuZXJhdGVkIGZyb20gdGhlIGV4cG9ydGluZyBtb2R1bGVzIGluIC4vc3JjLlxuLy8gSGFuZCBlZGl0cyBhcmUgb3ZlcndyaXR0ZW4gb24gdGhlIG5leHQgd2F0Y2g7IHRoaXMgZmlsZSBpcyByZWFkLW9ubHkuXG5cbmV4cG9ydCAqIGFzIGJpbiBmcm9tIFwiLi9zcmMvYmluLnRzXCI7XG5leHBvcnQgKiBhcyBicmFuZCBmcm9tIFwiLi9zcmMvYnJhbmQudHNcIjtcbmV4cG9ydCAqIGFzIGNvbmZpZyBmcm9tIFwiLi9zcmMvY29uZmlnLnRzXCI7XG5leHBvcnQgKiBhcyBleGVjIGZyb20gXCIuL3NyYy9leGVjLnRzXCI7XG5leHBvcnQgKiBhcyBmaWxlIGZyb20gXCIuL3NyYy9maWxlLnRzXCI7XG5leHBvcnQgKiBhcyBmaWxlTG9jayBmcm9tIFwiLi9zcmMvZmlsZS1sb2NrLnRzXCI7XG5leHBvcnQgKiBhcyBwcm9jZXNzTG9jayBmcm9tIFwiLi9zcmMvcHJvY2Vzcy1sb2NrLnRzXCI7XG5leHBvcnQgKiBhcyBwcm9qZWN0IGZyb20gXCIuL3NyYy9wcm9qZWN0LnRzXCI7XG5leHBvcnQgdHlwZSB7IEJpbkNvbnRleHQsIEJpblNlbGVjdGlvbkNvbnRleHQsIEJpblNlbGVjdG9yLCBCaW5WZXJzaW9uT3V0cHV0LCBCaW5WZXJzaW9uUGFyc2VyLCBCaW5PcHRpb25zLCBCaW5VcmwgfSBmcm9tIFwiLi9zcmMvYmluLnRzXCI7XG5leHBvcnQgeyBCcmFuZENvbnRleHRTY2hlbWEsIGRlZmF1bHRCcmFuZENvbnRleHQsIHBhcnNlQnJhbmRDb250ZXh0LCBicmFuZENvbnRleHRKc29uU2NoZW1hLCBicmFuZENvbnRleHRQcm9tcHQgfSBmcm9tIFwiLi9zcmMvYnJhbmQudHNcIjtcbmV4cG9ydCB0eXBlIHsgQnJhbmRDb250ZXh0LCBCcmFuZENvbnRleHRJbnB1dCB9IGZyb20gXCIuL3NyYy9icmFuZC50c1wiO1xuZXhwb3J0IHsgTUFYX1RDUF9QT1JULCBEQVRBQlJJQ0tTX0FQUF9FTlZfS0VZLCBDT05GSUdfRE9URU5WX0tFWSwgQ09ORklHX0JVTkRMRV9LRVksIEVOVl9PTkxZLCBidW5kbGVWYWx1ZSwgYnVuZGxlUmVzb3VyY2VTY2hlbWEsIGJ1bmRsZUVudkVudHJ5U2NoZW1hLCBidW5kbGVBcHBTY2hlbWEgfSBmcm9tIFwiLi9zcmMvY29uZmlnLnRzXCI7XG5leHBvcnQgdHlwZSB7IENvbmZpZ0tleSwgQ29uZmlnU291cmNlLCBDb25maWdPcHRpb25zLCBDb25maWdGaWxlIH0gZnJvbSBcIi4vc3JjL2NvbmZpZy50c1wiO1xuZXhwb3J0IHsgQ09NTUFORF9OT1RfRk9VTkRfRVhJVF9DT0RFIH0gZnJvbSBcIi4vc3JjL2V4ZWMudHNcIjtcbmV4cG9ydCB0eXBlIHsgRXhlY1N0ZGlvLCBMaW5lSGFuZGxlciwgU3RkaW9PcHRpb24sIEV4ZWNSZXN1bHQsIENoaWxkUHJvY2Vzc1Jlc3VsdCwgRXhlY09wdGlvbnMsIFN5bmNFeGVjU3RkaW8sIFN5bmNFeGVjT3B0aW9ucywgU3Bhd25BcmdzIH0gZnJvbSBcIi4vc3JjL2V4ZWMudHNcIjtcbmV4cG9ydCB0eXBlIHsgRmlsZUxvY2tCYWNrZW5kLCBGaWxlTG9ja0FjcXVpc2l0aW9uLCBGaWxlTG9ja09wdGlvbnMgfSBmcm9tIFwiLi9zcmMvZmlsZS1sb2NrLnRzXCI7XG5leHBvcnQgdHlwZSB7IFByb2plY3RDb250ZXh0IH0gZnJvbSBcIi4vc3JjL3Byb2plY3QudHNcIjtcbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssR0FBRyxNQUFNLGNBQWMsQ0FBQztBQUNwQyxPQUFPLEtBQUssS0FBSyxNQUFNLGdCQUFnQixDQUFDO0FBQ3hDLE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLElBQUksTUFBTSxlQUFlLENBQUM7QUFDdEMsT0FBTyxLQUFLLElBQUksTUFBTSxlQUFlLENBQUM7QUFDdEMsT0FBTyxLQUFLLFFBQVEsTUFBTSxvQkFBb0IsQ0FBQztBQUMvQyxPQUFPLEtBQUssV0FBVyxNQUFNLHVCQUF1QixDQUFDO0FBQ3JELE9BQU8sS0FBSyxPQUFPLE1BQU0sa0JBQWtCLENBQUM7QUFFNUMsT0FBTyxFQUFFLGtCQUFrQixFQUFFLG1CQUFtQixFQUFFLGlCQUFpQixFQUFFLHNCQUFzQixFQUFFLGtCQUFrQixFQUFFLE1BQU0sZ0JBQWdCLENBQUM7QUFFeEksT0FBTyxFQUFFLFlBQVksRUFBRSxRQUFRLEVBQUUsV0FBVyxFQUFFLG9CQUFvQixFQUFFLG9CQUFvQixFQUFFLGVBQWUsRUFBRSxpQkFBaUIsRUFBRSxTQUFTLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUVqSyxPQUFPLEVBQUUsMkJBQTJCLEVBQUUsTUFBTSxlQUFlLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBHRU5FUkFURUQgYnkgcHJvamVuIHdhdGNoIC0gRE8gTk9UIEVESVQuXG4vLyBSZWdlbmVyYXRlZCBmcm9tIHRoZSBleHBvcnRpbmcgbW9kdWxlcyBpbiAuL3NyYy5cbi8vIEhhbmQgZWRpdHMgYXJlIG92ZXJ3cml0dGVuIG9uIHRoZSBuZXh0IHdhdGNoOyB0aGlzIGZpbGUgaXMgcmVhZC1vbmx5LlxuXG5leHBvcnQgKiBhcyBiaW4gZnJvbSBcIi4vc3JjL2Jpbi50c1wiO1xuZXhwb3J0ICogYXMgYnJhbmQgZnJvbSBcIi4vc3JjL2JyYW5kLnRzXCI7XG5leHBvcnQgKiBhcyBjb25maWcgZnJvbSBcIi4vc3JjL2NvbmZpZy50c1wiO1xuZXhwb3J0ICogYXMgZXhlYyBmcm9tIFwiLi9zcmMvZXhlYy50c1wiO1xuZXhwb3J0ICogYXMgZmlsZSBmcm9tIFwiLi9zcmMvZmlsZS50c1wiO1xuZXhwb3J0ICogYXMgZmlsZUxvY2sgZnJvbSBcIi4vc3JjL2ZpbGUtbG9jay50c1wiO1xuZXhwb3J0ICogYXMgcHJvY2Vzc0xvY2sgZnJvbSBcIi4vc3JjL3Byb2Nlc3MtbG9jay50c1wiO1xuZXhwb3J0ICogYXMgcHJvamVjdCBmcm9tIFwiLi9zcmMvcHJvamVjdC50c1wiO1xuZXhwb3J0IHR5cGUgeyBCaW5Db250ZXh0LCBCaW5TZWxlY3Rpb25Db250ZXh0LCBCaW5TZWxlY3RvciwgQmluVmVyc2lvbk91dHB1dCwgQmluVmVyc2lvblBhcnNlciwgQmluT3B0aW9ucywgQmluVXJsIH0gZnJvbSBcIi4vc3JjL2Jpbi50c1wiO1xuZXhwb3J0IHsgQnJhbmRDb250ZXh0U2NoZW1hLCBkZWZhdWx0QnJhbmRDb250ZXh0LCBwYXJzZUJyYW5kQ29udGV4dCwgYnJhbmRDb250ZXh0SnNvblNjaGVtYSwgYnJhbmRDb250ZXh0UHJvbXB0IH0gZnJvbSBcIi4vc3JjL2JyYW5kLnRzXCI7XG5leHBvcnQgdHlwZSB7IEJyYW5kQ29udGV4dCwgQnJhbmRDb250ZXh0SW5wdXQgfSBmcm9tIFwiLi9zcmMvYnJhbmQudHNcIjtcbmV4cG9ydCB7IE1BWF9UQ1BfUE9SVCwgRU5WX09OTFksIHZhbHVlU2NoZW1hLCBidW5kbGVSZXNvdXJjZVNjaGVtYSwgYnVuZGxlRW52RW50cnlTY2hlbWEsIGJ1bmRsZUFwcFNjaGVtYSwgYXBwRW52RW50cnlTY2hlbWEsIGFwcFNjaGVtYSB9IGZyb20gXCIuL3NyYy9jb25maWcudHNcIjtcbmV4cG9ydCB0eXBlIHsgQ29uZmlnTWFwVmFsdWUsIENvbmZpZ0RhdGEsIENvbmZpZ1NvdXJjZSwgQ29uZmlnT3B0aW9ucywgQ29uZmlnRmlsZSB9IGZyb20gXCIuL3NyYy9jb25maWcudHNcIjtcbmV4cG9ydCB7IENPTU1BTkRfTk9UX0ZPVU5EX0VYSVRfQ09ERSB9IGZyb20gXCIuL3NyYy9leGVjLnRzXCI7XG5leHBvcnQgdHlwZSB7IEV4ZWNTdGRpbywgTGluZUhhbmRsZXIsIFN0ZGlvT3B0aW9uLCBFeGVjUmVzdWx0LCBDaGlsZFByb2Nlc3NSZXN1bHQsIEV4ZWNPcHRpb25zLCBTeW5jRXhlY1N0ZGlvLCBTeW5jRXhlY09wdGlvbnMsIFNwYXduQXJncyB9IGZyb20gXCIuL3NyYy9leGVjLnRzXCI7XG5leHBvcnQgdHlwZSB7IEZpbGVMb2NrQmFja2VuZCwgRmlsZUxvY2tBY3F1aXNpdGlvbiwgRmlsZUxvY2tPcHRpb25zIH0gZnJvbSBcIi4vc3JjL2ZpbGUtbG9jay50c1wiO1xuZXhwb3J0IHR5cGUgeyBQcm9qZWN0Q29udGV4dCB9IGZyb20gXCIuL3NyYy9wcm9qZWN0LnRzXCI7XG4iXX0=

package/lib/src/config.d.ts

@@ -1,56 +1,36 @@
 /**
- * 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 `resources.apps.<app>.config.env` or root
- * `variables` 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.
  *
- * The bundle is gated on this being an AppKit project at all. `databricks bundle
- * validate` is a process spawn measured in seconds, and a plain library or CLI
- * consumer has no bundle to find, so the gate runs in three steps before the
- * spawn is allowed - see {@link bundleFile}:
- *
- *   1. `@databricks/appkit` is resolved WITHOUT evaluating it. It is an optional
- *      peer, so a consumer that never installed it is not an AppKit project and
- *      the bundle is never loaded. The probe is cached, so this costs one
- *      resolution for the life of the process.
- *   2. The bundle is read (once per context) and must describe EXACTLY ONE app
- *      with `config.env`. Nothing here says which of several apps this process
- *      is, so an ambiguous bundle contributes nothing rather than a guess.
- *   3. AppKit's execution context confirms this process really is that app. The
- *      context does not exist until AppKit boots and `getExecutionContext()`
- *      THROWS until then, so the probe is caught and only the affirmative is
- *      remembered - a lookup before boot still resolves, and re-confirms later
- *      once the context is available.
- *
- * 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`).
  *
  * @module
  */
 import { z } from "zod";
-export type ConfigKey = string | readonly string[];
+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. */
-export type ConfigSource = "env" | "dotenv" | "bundle";
+export type ConfigSource = "config" | "env" | "dotenv" | "bundle" | "app";
 export interface ConfigOptions {
     /**
      * Outermost namespaces tried before each key. Defaults to `DBX_TOOLS`.
@@ -58,10 +38,16 @@ export interface ConfigOptions {
     scope?: string | readonly string[];
     /** Capability namespaces inserted after the scope and before each key. */
     prefix?: string | readonly string[];
+    /** 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;
-    /** 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 {
@@ -70,47 +56,55 @@ export interface ConfigFile {
 }
 /** 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 valueSchema: z.ZodString;
+/** A named bundle or App resource; concrete resource fields pass through. */
 export declare const bundleResourceSchema: z.ZodObject<{
-    name: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    name: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 export declare const bundleEnvEntrySchema: z.ZodObject<{
-    name: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    name: z.ZodOptional<z.ZodString>;
     value: z.ZodOptional<z.ZodString>;
-    value_from: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    value_from: z.ZodOptional<z.ZodString>;
 }, 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>;
+    name: 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>>>;
+            name: z.ZodOptional<z.ZodString>;
             value: z.ZodOptional<z.ZodString>;
-            value_from: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+            value_from: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
     resources: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        name: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        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.
  *
@@ -120,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`.
  *
@@ -127,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
@@ -162,6 +160,12 @@ export declare function positiveNumber(configured: unknown, input: ConfigKey, fa
  * 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 TCP port between 1 and {@link MAX_TCP_PORT}. Invalid configured or
+ * sourced values fall back to the caller's default, which may be a sentinel
+ * such as `0` when the caller uses one.
+ */
+export declare function port(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.
@@ -171,20 +175,14 @@ export declare function list(configured: string | readonly string[] | undefined
  * 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 App
- * config. `undefined` when bundle reads are disabled, this is not an AppKit
- * project, the bundle does not describe exactly one app with `config.env`, there
- * is no bundle, or the CLI produces no JSON.
+ * config. `undefined` when bundle reads are disabled, the process is production
+ * or a deployed App without an explicit override, there is no bundle, or the
+ * CLI produces no JSON.
  *
- * The spawn is guarded because it is expensive and usually pointless. In order:
- * `@databricks/appkit` must be RESOLVABLE (no AppKit, no bundle - and the probe
- * never evaluates the module); the bundle must describe exactly ONE app carrying
- * `config.env`; and AppKit's execution context must confirm this process is that
- * app. Only the confirmation is remembered, so a lookup during boot - before any
- * context exists - still resolves from the bundle and re-confirms later.
+ * Parsed validation output is cached by bundle path and Databricks profile.
  *
- * 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;
+/** 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 {};