pipework 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,6 +1,32 @@
 # Changelog
 
-## 0.15.0
+## 0.17.0
+
+- **Feature: `observability.onStatement` — a caller-supplied observer that fires once per statement written to the wire, on every connection the manifold owns.** The callback receives `{ connectionId, query, parameters }` and is pure observation: the return value is discarded, the statement is never mutated, and nothing is installed when the option is unset. It exists for exact wire-level statement accounting, which no application-level hook can do — the driver issues its own `BEGIN`/`SAVEPOINT`/`COMMIT`/`ROLLBACK`, and those are observed too.
+  - **Honored on both connection arms.** Pooled connections (`createManagedConnection`) *and* the test harness's own connections — both the per-test rolled-back connection and the setup connection behind `useSetupDb()`. The test harness builds its postgres.js clients directly rather than through the pool, so a config-only hook would have been silently dead under `pipework test`; that arm is wired explicitly and covered by its own tests.
+  - **Composes with `logAllQueries`.** Either alone installs the driver hook; with both configured both fire. Query logging keeps its 500-character truncation; the observer receives the query untruncated, because a counter must not see mangled SQL.
+  - **`connectionId` is the driver's process-local connection ordinal, not the PostgreSQL backend pid.** Unique and stable per connection for that connection's lifetime within the process, meaningless across processes. Correct for per-connection accounting — every statement of one transaction carries the same id, which is asserted by a test — and wrong for correlating with `pg_stat_activity`.
+  - **Counts wire truth, not application intent.** Two things a total will include that callers should expect: driver-issued transaction control, and one `pg_catalog.pg_type` lookup per connection the first time that connection is used.
+  - Admitted through zod with `z.custom`, deliberately not `z.function()` — in zod 4 the latter returns a validating wrapper, so the parsed value is not the function the caller passed (identity is lost) and every call pays argument validation, on a hook that fires once per statement.
+
+- **Observation adds no leak surface: a driver error boundary keeps the observer from widening what query errors serialize.** postgres.js defines `stack`/`query`/`parameters`/`args`/`types` on every query error and marks them **enumerable** exactly when its `debug` option is truthy — and installing an observer requires turning `debug` on. Without a boundary, merely observing statements would start leaking bind parameters into every log drain that serializes errors. Errors from observed connections are now put back to their unobserved shape: observed and unobserved errors have identical own-key sets, and the values stay reachable by property access so debugging is unaffected. `instanceof`, `message`, `code` and every server field survive. Applies to every statement path pipework mediates — `pipe()`, every `pipe.*` write, `connection.drizzle`, transactions and savepoints. `logAllQueries: true` is untouched and behaves exactly as before; that mode already opted into verbose errors.
+  - **The one gap, deliberate and announced: `ManagedConnection.client`.** The raw driver door stays raw — that is what it is for — so queries issued through it are outside the boundary and their errors do serialize bind parameters. Reading `.client` on an observed connection now logs a warning saying so, once per database, and the contract is stated on `StatementObserver` and on `ManagedConnection.client`.
+  - **Wrapping the `Sql` client to close that gap was considered and rejected.** It would mean proxying a callable tagged-template whose `begin`/`savepoint` hand out fresh client instances needing recursive re-wrapping, on the hottest path in the system — more risk than the narrow, documented gap it closes. Recorded here so it is not re-proposed as cleanup.
+
+- **Fix: the migration safety tests no longer depend on a virgin database.** `migrateOne` integration tests assert on hazards in *pending* migrations, but their migration tags are fixed while the tracker outlives the run — so from the second run onward those tags read as already-applied, dropped out of the pending set, and `hasDestructive` flipped to false. The tracker is now dropped before each of those tests. (Surfaced by 0.16.0's move to tag membership; under the old timestamp high-water mark the stale rows were inert.)
+
+- **Fix: `docker-compose.test.yml`'s published port is parameterized (`PIPEWORK_TEST_PORT`, default 5432).** Where 5432 is already held, compose silently failed to publish and the suite ran against whatever else answered there — which matters because the harness creates and drops databases and provisions BYPASSRLS fixture roles, so it must talk to a disposable cluster where its own role is the superuser. Stock machines are unaffected.
+
+## 0.16.0
+
+- **Fix: a queue registered by a module reached only through the schema glob now makes it into `pipework generate`'s output.** The CLI used to snapshot internal definitions (including registered queues) *before* the schema files were imported, so a `createQueue()` living in a glob-matched module — with no side-effect import in the config — was silently dropped from the migration, and consumers worked around it by importing the queue module from `pipework.config.ts`. Internal definitions are now collected after the schema-file imports. Breaking for API consumers: `generateForDatabase`'s `internalDefinitions` parameter is now a thunk (`() => Promise<Record<string, unknown>>`).
+- **Feature: a registered queue whose table is missing from the database is now a loud, actionable failure at startup and at test bootstrap — not a crash at first insert.** Startup validation (`pipework serve`/`dev`, `manifold.start()`) and the test harness's template provisioning both verify every `createQueue()`-registered table exists in the default database (`to_regclass` probe), and refuse with a message naming the table, the schema-glob rule, and the fix (`pipework generate`, then `pipework migrate`).
+- **Behavior change: a database whose `testUrl` resolves to the same connection string as its `url` is refused at config resolution in the test environment.** Identical values mean "tests" run against the real database: the test harness creates/drops databases and rolls back transactions on what it assumes is a dedicated instance, and RLS-inertness goes unnoticed — with zero signal from the framework. The refusal names both env vars and the fix (point the test var at a separate database); `testUrl` naming the *same env var* as `url` is reported as its own case. Applies to both the url/testUrl and appUrl/appTestUrl pairs.
+- **Fix: `pipework generate` surfaces the real config-load error instead of misreporting every failure as "No pipework.config.ts found".**
+- **Behavior change: a database with `rls` configured whose runtime role is SUPERUSER or BYPASSRLS now fails startup validation and test bootstrap.** RLS policies never apply to such a role, so the entire tenant-isolation policy set is silently inert — the framework now says so, naming the database, the role, the flag, and the fix (provision a non-bypassing application role; point the runtime connection at it). At startup the probed connection is `appUrl ?? url`; at test bootstrap it is the connection tests actually execute on — transaction isolation collapses every role onto the resolved `url`, database/container isolation resolves roles normally. Consumers whose test role is the compose superuser are refused until they provision a non-bypassing test role — deliberate: that is exactly the world where an RLS test suite proves nothing.
+- **Feature: `.env.local` and `.env.test.local` are loaded alongside `.env`/`.env.test`, with the `.local` (machine-local, never-committed) variant taking precedence** — the standard dotenv convention.
+- **Docs: the `env` config field is now a first-class section in REFERENCE.md** — every declaration shape (`string`/`number`/`boolean`/`string[]`), `required`/`default`/per-environment `defaults`/`sensitive`, typed `manifold.env` access, and a complete `createManifold` example. Previously it appeared only inside a type signature, leaving the feature undiscoverable while consumers accumulated ad-hoc `process.env` reads. The reference generator now renders multi-line JSDoc and `@example` blocks as fenced code instead of flattening them to one line.
+- **Behavior change: relative `migrations`/`schema` paths now resolve against the directory of `pipework.config.ts`, never against the process working directory.** Previously every consumer of these fields (`pipework generate`, `pipework migrate`'s safety gate, test template provisioning) resolved them against cwd — so `pnpm --filter <module> test` (which cd's into the module) failed at `beforeAll` with "No migration journal found", and the only workaround was hand-absolutizing the paths with `import.meta.url`. `ResolvedDatabase.migrations` is now absolute (resolved once, at config load), `ResolvedDatabase` carries the new `baseDir` field (the config file's directory), and schema globs are matched against `baseDir`. Already-absolute consumer paths are unchanged (`resolve(base, abs) === abs`). Breaking for API consumers: `generateForDatabase` loses its `cwd` parameter — the resolved config is the single source of path truth.
 
 - **Fix: the migration tracker now records WHICH migrations have been applied (tag membership), replacing the `max(created_at)` timestamp high-water mark that silently skipped any unapplied migration dated earlier than the newest applied one.** Two real production hits of the old model: (1) two manifolds sharing one physical database under the same tracker table name (both declared database key `app`) — the second manifold's entire journal predated the first's newest entry, so its migrations were silently skipped and its schema never materialized; (2) a migration merged from a branch with an earlier date than migrations already applied was silently skipped ("relation does not exist" at runtime, in CI). The tracker table gains a `tag` column (unique) and `applyMigrations` decides "already applied" by membership: tag recorded → skip (after verifying the recorded content hash still matches — see below), tag absent → apply, in journal order. Existing deployed tracker tables are upgraded in place on the next `migrate`: the `tag` column is added and each legacy row's identity is recovered by matching its recorded content hash against the journal's files; rows matching no current journal entry keep a NULL tag and never participate in membership.
 - **Fix: editing an already-applied migration file is now a loud error instead of silently ignored.** Membership verifies the recorded sha256 against the file: a tag recorded with a different hash aborts with an error naming the migration, the two hashes, and the fix (put schema changes in a NEW migration; if two manifolds share a database and collide on a tag, that is a schema-level collision no tracker can reconcile — separate databases or distinct `migrationTable` names).

package/REFERENCE.md

@@ -1,11 +1,12 @@
 # Pipework API Reference
 
 > Auto-generated from source JSDoc. Do not edit manually.
-> Generated: 2026-06-29
+> Generated: 2026-07-19
 
 ## Contents
 
 - [Core](#core)
+- [env — Environment Variables](#env-environment-variables)
 - [jobs — Background Jobs](#jobs-background-jobs)
 - [pipeline — Multi-Step Pipelines](#pipeline-multi-step-pipelines)
 - [state — State Machines](#state-state-machines)
@@ -33,6 +34,7 @@
 - [http — Server](#http-server)
 - [openapi — API Documentation](#openapi-api-documentation)
 - [test](#test)
+- [data](#data)
 - [trace](#trace)
 
 ## Core
@@ -41,7 +43,29 @@ Application instance and foundational types.
 
 ### `createManifold`
 
-Creates the Pipework application instance. This is the entry point for every Pipework app. Define in `pipework.config.ts` and export as default. /
+Creates the Pipework application instance. This is the entry point for every Pipework app.
+Define in `pipework.config.ts` and export as default.
+
+The `env` field declares the app's environment variables — the canonical
+home for runtime config (ports, service tokens, bucket names, flags) in
+place of scattered `process.env` reads. Each variable is read once at config
+load, validated and coerced to its declared type (loud error on a bad or
+missing-required value), and exposed typed on `manifold.env`.
+
+
+```typescript
+const manifold = createManifold({
+  databases: { app: { url: 'DATABASE_URL', testUrl: 'DATABASE_URL_TEST' } },
+  env: {
+    PORT: { type: 'number', defaults: { development: '3000', test: '0' } },
+    S3_BUCKET: { type: 'string', required: true },
+    API_TOKEN: { type: 'string', required: true, sensitive: true },
+  },
+})
+manifold.env.PORT       // number — from process.env.PORT, or the per-environment default
+manifold.env.S3_BUCKET  // string — startup fails loudly if unset
+export default manifold
+```
 
 ```typescript
 function createManifold<const TEnv extends EnvDefs = EnvDefs>( raw: Omit<BlueprintInput, 'env'> &
@@ -79,6 +103,114 @@ interface IsolationState
 interface ConnectionTracker
 ```
 
+## env — Environment Variables
+
+Declared environment variables — the canonical home for runtime config (ports, service tokens, bucket names, feature flags). Declare them under the `env` blueprint field; each is read once at config load, validated and coerced to its declared type (loud error on a bad or missing-required value), and exposed typed on `manifold.env` — in place of scattered ad-hoc `process.env` reads.
+
+### Types
+
+**`StringEnvVar`**
+
+A string environment variable — resolved verbatim.
+
+
+```typescript
+S3_BUCKET: { type: 'string', required: true }
+```
+
+```typescript
+interface StringEnvVar extends EnvVarBase
+```
+
+**`NumberEnvVar`**
+
+A number environment variable — parsed with a loud error on a non-numeric value.
+
+
+```typescript
+PORT: { type: 'number', default: 3000 }
+```
+
+```typescript
+interface NumberEnvVar extends EnvVarBase
+```
+
+**`BooleanEnvVar`**
+
+A boolean environment variable — accepts true/false/1/0, loud error otherwise.
+
+
+```typescript
+FEATURE_GRAPH: { type: 'boolean', default: false }
+```
+
+```typescript
+interface BooleanEnvVar extends EnvVarBase
+```
+
+**`StringArrayEnvVar`**
+
+A string-array environment variable — the raw value split on `separator`
+(default `,`), each element trimmed.
+
+
+```typescript
+CORS_ORIGINS: { type: 'string[]', separator: ',', default: [] }
+```
+
+```typescript
+interface StringArrayEnvVar extends EnvVarBase
+```
+
+**`EnvVarDef`**
+
+One declared environment variable: its type, whether it is required, its
+fallbacks, and whether the value is sensitive. Declared under the `env`
+blueprint field; resolved once at config load and exposed typed on
+`manifold.env` — the canonical replacement for ad-hoc `process.env` reads.
+
+```typescript
+type EnvVarDef = StringEnvVar | NumberEnvVar | BooleanEnvVar | StringArrayEnvVar
+```
+
+**`EnvDefs`**
+
+The `env` blueprint field: environment-variable declarations keyed by
+variable name. Passing this map to `createManifold` is what types
+`manifold.env`.
+
+
+```typescript
+export default createManifold({
+  databases: { app: { url: 'DATABASE_URL', testUrl: 'DATABASE_URL_TEST' } },
+  env: {
+    PORT: { type: 'number', defaults: { development: '3000', test: '0' } },
+    S3_BUCKET: { type: 'string', required: true },
+    API_TOKEN: { type: 'string', required: true, sensitive: true },
+    CORS_ORIGINS: { type: 'string[]', default: [] },
+  },
+})
+// manifold.env.PORT         → number
+// manifold.env.S3_BUCKET    → string
+// manifold.env.CORS_ORIGINS → string[]
+```
+
+```typescript
+type EnvDefs = Record<string, EnvVarDef>
+```
+
+**`ResolvedEnvType`** — The resolved runtime type of one declaration: 'string' → string, 'number' → number, 'boolean' → boolean, 'string[]' → string[].
+
+```typescript
+type ResolvedEnvType<T extends EnvVarDef> =
+```
+
+**`ResolveEnvDefs`** — Maps a declaration map to the shape of `manifold.env` — each key typed by its declared `type`.
+
+```typescript
+type ResolveEnvDefs<T extends EnvDefs> =
+```
+
 ## jobs — Background Jobs
 
 Background job queue namespace — Postgres-backed with SKIP LOCKED, LISTEN/NOTIFY, cron scheduling.
@@ -367,6 +499,38 @@ The zod schema for Blueprint validation — useful for custom config tooling.
 
 Thrown for configuration problems — includes a suggestion for how to fix.
 
+### Types
+
+**`StatementEvent`**
+
+One statement as it is handed to the driver for writing to the wire —
+including the transaction-control statements the driver issues on its own
+(`BEGIN`, `SAVEPOINT`, `COMMIT`, `ROLLBACK`), which no application-level hook
+can see.
+
+```typescript
+interface StatementEvent
+```
+
+**`StatementObserver`**
+
+Caller-supplied per-statement observer. Fires once per statement written to
+the wire, on every connection the manifold owns — pooled connections and the
+test harness's own connections alike.
+
+Pure observation: the return value is discarded and the statement is never
+mutated. It runs synchronously on the driver's write path, so it must be
+cheap and must not throw.
+
+Counts wire truth, not application intent. Two consequences worth knowing
+before you assert on a total: the driver issues its own transaction control
+(`BEGIN`/`SAVEPOINT`/`COMMIT`/`ROLLBACK`), and it issues one `pg_catalog.pg_type`
+lookup per connection the first time that connection is used.
+
+```typescript
+type StatementObserver = (event: StatementEvent) => void
+```
+
 ## errors — Error Classes
 
 Standard error classes — all extend PipeworkError with structured error codes and actionable messages.
@@ -564,6 +728,18 @@ interface ValueColumnDef
 interface SerializableOptions
 ```
 
+**`ManagedConnection`** — A standalone pooled connection: the raw postgres.js client, its drizzle handle, and a `close()` that ends the pool.
+
+```typescript
+interface ManagedConnection
+```
+
+**`ConnectOptions`** — Options for `tap()` — pool size (default 1) and idle timeout in seconds.
+
+```typescript
+interface ConnectOptions
+```
+
 ## jsonb — JSONB Column Helpers
 
 JSONB query operators — typed helpers for PostgreSQL JSONB containment, key checks, and field extraction.
@@ -1022,6 +1198,19 @@ Generates an OpenAPI 3.1 document from route registrations — schemas derived f
 
 ## test
 
+## data
+
+### `tap`
+
+Opens a standalone managed connection outside the manifold's pools — the
+sanctioned door for contexts where `pipe()` structurally cannot resolve:
+`worker_threads`, detached monitors, one-off scripts. Callers own the
+lifecycle: always `await conn.close()`.
+
+```typescript
+function tap(url: string, options?: ConnectOptions): ManagedConnection
+```
+
 ## trace
 
 ### `__flowStep`

package/dist/cli/commands/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/generate.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAA;IACtB,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACxB,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,wBAAsB,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsD7E"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/generate.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAA;IACtB,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACxB,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,wBAAsB,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0D7E"}

package/dist/cli/commands/generate.js

@@ -1,26 +1,28 @@
 import { info, success, warn, error as logError } from '../output.js';
 export async function generate(options) {
-    const { discoverInstance } = await import('../../core/config/discover.js');
+    const { discoverInstance, findConfig } = await import('../../core/config/discover.js');
     const { generateForDatabase } = await import('../../data/migrate/generate.js');
     const { loadInternalDefinitions } = await import('../../data/migrate/internal-definitions.js');
-    let instance;
-    try {
-        instance = await discoverInstance(options.cwd);
-    }
-    catch {
+    if (findConfig(options.cwd) === null) {
         logError('No pipework.config.ts found.\n\n' +
             '  Run `pipework init` to create one.\n');
         process.exit(1);
     }
+    // A config that exists but fails to load (missing env var, refused
+    // url/testUrl identity, …) must surface its real error, not be misreported
+    // as a missing config.
+    const instance = await discoverInstance(options.cwd);
     const defaultDbName = instance.config.defaultDatabaseName();
     try {
         if (options.db !== undefined) {
             const dbConfig = instance.config.database(options.db);
             info(`Generating migration for database: ${options.db}`);
-            const internal = await loadInternalDefinitions(instance.config.raw, {
+            // Passed as a thunk so queue registrations made by glob-imported schema
+            // modules (inside generateForDatabase) are visible when it runs.
+            const internal = () => loadInternalDefinitions(instance.config.raw, {
                 isDefaultDatabase: options.db === defaultDbName,
             });
-            const result = await generateForDatabase(dbConfig, options.cwd, options.name, internal);
+            const result = await generateForDatabase(dbConfig, options.name, internal);
             if (result.migrationFile === null) {
                 warn(`${options.db}: no schema changes detected`);
             }
@@ -34,10 +36,10 @@ export async function generate(options) {
             for (const [, dbConfig] of instance.config.databases()) {
                 if (dbConfig.schema === undefined)
                     continue;
-                const internal = await loadInternalDefinitions(instance.config.raw, {
+                const internal = () => loadInternalDefinitions(instance.config.raw, {
                     isDefaultDatabase: dbConfig.name === defaultDbName,
                 });
-                const result = await generateForDatabase(dbConfig, options.cwd, options.name, internal);
+                const result = await generateForDatabase(dbConfig, options.name, internal);
                 if (result.migrationFile === null) {
                     warn(`${dbConfig.name}: no schema changes detected`);
                 }

package/dist/cli/commands/generate.js.map

@@ -1 +1 @@
-{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../../src/cli/commands/generate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../../src/cli/commands/generate.ts"],"names":[],"mappings":"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"}

package/dist/core/config/base-dir.d.ts

@@ -0,0 +1,6 @@
+export declare function setConfigBaseDir(dir: string): void;
+/** Read-and-clear. Undefined when no config import is in flight — directly-constructed configs resolve against process.cwd(). */
+export declare function consumeConfigBaseDir(): string | undefined;
+/** Cleared in the importer's finally: an ESM cache hit skips loadConfig, and the stale slot must not leak into a later directly-constructed loadConfig. */
+export declare function clearConfigBaseDir(): void;
+//# sourceMappingURL=base-dir.d.ts.map

package/dist/core/config/base-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-dir.d.ts","sourceRoot":"","sources":["../../../src/core/config/base-dir.ts"],"names":[],"mappings":"AASA,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAElD;AAED,iIAAiI;AACjI,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,SAAS,CAIzD;AAED,2JAA2J;AAC3J,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/core/config/base-dir.js

@@ -0,0 +1,21 @@
+// The directory relative `migrations`/`schema` paths resolve against (D1,
+// subseam audit 2026-07-16). Set from the config file's directory immediately
+// before the config module is imported; consumed exactly once by loadConfig.
+// A module-level slot rather than a parameter because the config file itself
+// calls createManifold() during its own import — there is no call chain to
+// thread the value through.
+let configBaseDir;
+export function setConfigBaseDir(dir) {
+    configBaseDir = dir;
+}
+/** Read-and-clear. Undefined when no config import is in flight — directly-constructed configs resolve against process.cwd(). */
+export function consumeConfigBaseDir() {
+    const dir = configBaseDir;
+    configBaseDir = undefined;
+    return dir;
+}
+/** Cleared in the importer's finally: an ESM cache hit skips loadConfig, and the stale slot must not leak into a later directly-constructed loadConfig. */
+export function clearConfigBaseDir() {
+    configBaseDir = undefined;
+}
+//# sourceMappingURL=base-dir.js.map

package/dist/core/config/base-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-dir.js","sourceRoot":"","sources":["../../../src/core/config/base-dir.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,8EAA8E;AAC9E,6EAA6E;AAC7E,6EAA6E;AAC7E,2EAA2E;AAC3E,4BAA4B;AAE5B,IAAI,aAAiC,CAAA;AAErC,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,aAAa,GAAG,GAAG,CAAA;AACrB,CAAC;AAED,iIAAiI;AACjI,MAAM,UAAU,oBAAoB;IAClC,MAAM,GAAG,GAAG,aAAa,CAAA;IACzB,aAAa,GAAG,SAAS,CAAA;IACzB,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,2JAA2J;AAC3J,MAAM,UAAU,kBAAkB;IAChC,aAAa,GAAG,SAAS,CAAA;AAC3B,CAAC"}

package/dist/core/config/discover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../src/core/config/discover.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAK9C,wBAAgB,sBAAsB,IAAI,IAAI,CAsD7C;AAED,wBAAsB,gBAAgB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CA6BtE;AAMD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYtD"}
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../src/core/config/discover.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAM9C,wBAAgB,sBAAsB,IAAI,IAAI,CAsD7C;AAED,wBAAsB,gBAAgB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CActE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYtD"}

package/dist/core/config/discover.js

@@ -1,8 +1,8 @@
 import { resolve, dirname } from 'node:path';
 import { existsSync } from 'node:fs';
-import { pathToFileURL } from 'node:url';
 import { register } from 'node:module';
 import { ConfigError } from './errors.js';
+import { importConfig } from './import-config.js';
 const CONFIG_FILENAME = 'pipework.config.ts';
 export function registerTsResolveHooks() {
     {
@@ -66,20 +66,7 @@ export async function discoverInstance(cwd) {
         throw new ConfigError(`No ${CONFIG_FILENAME} found in ${start} or any parent directory.`, `Create one with \`pipework init\`, or see the getting-started guide.`);
     }
     registerTsResolveHooks();
-    const configUrl = pathToFileURL(configPath).href;
-    const mod = await import(configUrl);
-    const exported = mod['default'] ?? mod;
-    if (!isManifold(exported)) {
-        throw new ConfigError(`${CONFIG_FILENAME} must export a Pipework instance as its default export.`, `Your config should look like:\n\n` +
-            `  import { createManifold } from 'pipework'\n\n` +
-            `  export default createManifold({\n` +
-            `    databases: { app: { url: 'DATABASE_URL' } },\n` +
-            `  })\n`);
-    }
-    return exported;
-}
-function isManifold(v) {
-    return typeof v === 'object' && v !== null && 'pool' in v && 'config' in v;
+    return importConfig(configPath);
 }
 export function findConfig(from) {
     let dir = resolve(from);

package/dist/core/config/discover.js.map

@@ -1 +1 @@
-{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../../src/core/config/discover.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEzC,MAAM,eAAe,GAAG,oBAAoB,CAAA;AAE5C,MAAM,UAAU,sBAAsB;IACpC,CAAC;QACC,+EAA+E;QAC/E,qEAAqE;QACrE,8EAA8E;QAC9E,+EAA+E;QAC/E,+DAA+D;QAC/D,gFAAgF;QAChF,qEAAqE;QACrE,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA0CZ,CAAA;QACD,QAAQ,CAAC,wBAAwB,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC9D,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,GAAY;IACjD,MAAM,KAAK,GAAG,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAA;IAClC,MAAM,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,CAAA;IAEpC,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,MAAM,IAAI,WAAW,CACnB,MAAM,eAAe,aAAa,KAAK,2BAA2B,EAClE,sEAAsE,CACvE,CAAA;IACH,CAAC;IAED,sBAAsB,EAAE,CAAA;IAExB,MAAM,SAAS,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC,IAAI,CAAA;IAChD,MAAM,GAAG,GAA4B,MAAM,MAAM,CAAC,SAAS,CAAC,CAAA;IAC5D,MAAM,QAAQ,GAAY,GAAG,CAAC,SAAS,CAAC,IAAI,GAAG,CAAA;IAE/C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,WAAW,CACnB,GAAG,eAAe,yDAAyD,EAC3E,mCAAmC;YACnC,iDAAiD;YACjD,qCAAqC;YACrC,oDAAoD;YACpD,QAAQ,CACT,CAAA;IACH,CAAC;IAED,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,SAAS,UAAU,CAAC,CAAU;IAC5B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,MAAM,IAAI,CAAC,IAAI,QAAQ,IAAI,CAAC,CAAA;AAC5E,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,IAAI,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvB,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IACzB,OAAO,GAAG,KAAK,MAAM,EAAE,CAAC;QACtB,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,CAAA;QAC/C,IAAI,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAA;QAC3C,GAAG,GAAG,MAAM,CAAA;QACZ,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IACvB,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,CAAA;IAC1C,IAAI,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IACjC,OAAO,IAAI,CAAA;AACb,CAAC"}
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../../src/core/config/discover.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD,MAAM,eAAe,GAAG,oBAAoB,CAAA;AAE5C,MAAM,UAAU,sBAAsB;IACpC,CAAC;QACC,+EAA+E;QAC/E,qEAAqE;QACrE,8EAA8E;QAC9E,+EAA+E;QAC/E,+DAA+D;QAC/D,gFAAgF;QAChF,qEAAqE;QACrE,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA0CZ,CAAA;QACD,QAAQ,CAAC,wBAAwB,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC9D,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,GAAY;IACjD,MAAM,KAAK,GAAG,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAA;IAClC,MAAM,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,CAAA;IAEpC,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,MAAM,IAAI,WAAW,CACnB,MAAM,eAAe,aAAa,KAAK,2BAA2B,EAClE,sEAAsE,CACvE,CAAA;IACH,CAAC;IAED,sBAAsB,EAAE,CAAA;IAExB,OAAO,YAAY,CAAC,UAAU,CAAC,CAAA;AACjC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,IAAI,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvB,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IACzB,OAAO,GAAG,KAAK,MAAM,EAAE,CAAC;QACtB,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,CAAA;QAC/C,IAAI,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAA;QAC3C,GAAG,GAAG,MAAM,CAAA;QACZ,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IACvB,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,CAAA;IAC1C,IAAI,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IACjC,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/core/config/env-types.d.ts

@@ -1,31 +1,100 @@
 import type { Environment } from './schema.js';
 interface EnvVarBase {
+    /** Redact the resolved value from logs and error messages (tokens, secrets). */
     readonly sensitive?: boolean | undefined;
+    /**
+     * Per-environment fallback values, keyed by environment name. Always given
+     * as strings (they take the same parse path as a real environment variable);
+     * a variable that is set in the environment wins over any default here.
+     *
+     * @example
+     * PORT: { type: 'number', defaults: { development: '3000', test: '0' } }
+     */
     readonly defaults?: Partial<Record<Environment, string>> | undefined;
 }
+/**
+ * A string environment variable — resolved verbatim.
+ *
+ * @example
+ * S3_BUCKET: { type: 'string', required: true }
+ */
 export interface StringEnvVar extends EnvVarBase {
     readonly type: 'string';
+    /** Fail startup when unset and no default applies. */
     readonly required?: boolean | undefined;
+    /** Environment-independent fallback; `defaults` (per-environment) wins over this. */
     readonly default?: string | undefined;
 }
+/**
+ * A number environment variable — parsed with a loud error on a non-numeric value.
+ *
+ * @example
+ * PORT: { type: 'number', default: 3000 }
+ */
 export interface NumberEnvVar extends EnvVarBase {
     readonly type: 'number';
+    /** Fail startup when unset and no default applies. */
     readonly required?: boolean | undefined;
+    /** Environment-independent fallback; `defaults` (per-environment) wins over this. */
     readonly default?: number | undefined;
 }
+/**
+ * A boolean environment variable — accepts true/false/1/0, loud error otherwise.
+ *
+ * @example
+ * FEATURE_GRAPH: { type: 'boolean', default: false }
+ */
 export interface BooleanEnvVar extends EnvVarBase {
     readonly type: 'boolean';
+    /** Fail startup when unset and no default applies. */
     readonly required?: boolean | undefined;
+    /** Environment-independent fallback; `defaults` (per-environment) wins over this. */
     readonly default?: boolean | undefined;
 }
+/**
+ * A string-array environment variable — the raw value split on `separator`
+ * (default `,`), each element trimmed.
+ *
+ * @example
+ * CORS_ORIGINS: { type: 'string[]', separator: ',', default: [] }
+ */
 export interface StringArrayEnvVar extends EnvVarBase {
     readonly type: 'string[]';
+    /** Split character for the raw value (default ','). */
     readonly separator?: string | undefined;
+    /** Fail startup when unset and no default applies. */
     readonly required?: boolean | undefined;
+    /** Environment-independent fallback; `defaults` (per-environment) wins over this. */
     readonly default?: readonly string[] | undefined;
 }
+/**
+ * One declared environment variable: its type, whether it is required, its
+ * fallbacks, and whether the value is sensitive. Declared under the `env`
+ * blueprint field; resolved once at config load and exposed typed on
+ * `manifold.env` — the canonical replacement for ad-hoc `process.env` reads.
+ */
 export type EnvVarDef = StringEnvVar | NumberEnvVar | BooleanEnvVar | StringArrayEnvVar;
+/**
+ * The `env` blueprint field: environment-variable declarations keyed by
+ * variable name. Passing this map to `createManifold` is what types
+ * `manifold.env`.
+ *
+ * @example
+ * export default createManifold({
+ *   databases: { app: { url: 'DATABASE_URL', testUrl: 'DATABASE_URL_TEST' } },
+ *   env: {
+ *     PORT: { type: 'number', defaults: { development: '3000', test: '0' } },
+ *     S3_BUCKET: { type: 'string', required: true },
+ *     API_TOKEN: { type: 'string', required: true, sensitive: true },
+ *     CORS_ORIGINS: { type: 'string[]', default: [] },
+ *   },
+ * })
+ * // manifold.env.PORT         → number
+ * // manifold.env.S3_BUCKET    → string
+ * // manifold.env.CORS_ORIGINS → string[]
+ */
 export type EnvDefs = Record<string, EnvVarDef>;
+/** The resolved runtime type of one declaration: 'string' → string, 'number' → number, 'boolean' → boolean, 'string[]' → string[]. */
 export type ResolvedEnvType<T extends EnvVarDef> = T extends {
     readonly type: 'string';
 } ? string : T extends {
@@ -35,6 +104,7 @@ export type ResolvedEnvType<T extends EnvVarDef> = T extends {
 } ? boolean : T extends {
     readonly type: 'string[]';
 } ? string[] : never;
+/** Maps a declaration map to the shape of `manifold.env` — each key typed by its declared `type`. */
 export type ResolveEnvDefs<T extends EnvDefs> = {
     readonly [K in keyof T]: ResolvedEnvType<T[K]>;
 };

package/dist/core/config/env-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env-types.d.ts","sourceRoot":"","sources":["../../../src/core/config/env-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C,UAAU,UAAU;IAClB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAA;CACrE;AAED,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACtC;AAED,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACtC;AAED,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CACvC;AAED,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACnD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;CACjD;AAED,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,YAAY,GAAG,aAAa,GAAG,iBAAiB,CAAA;AAEvF,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;AAE/C,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,SAAS,IAC7C,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,MAAM,GAC9C,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,MAAM,GAC9C,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG,OAAO,GAChD,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG,MAAM,EAAE,GAClD,KAAK,CAAA;AAEP,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,OAAO,IAAI;IAC9C,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/C,CAAA"}
+{"version":3,"file":"env-types.d.ts","sourceRoot":"","sources":["../../../src/core/config/env-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C,UAAU,UAAU;IAClB,gFAAgF;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACxC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAA;CACrE;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACvC,qFAAqF;IACrF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACtC;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACvC,qFAAqF;IACrF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACtC;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACvC,qFAAqF;IACrF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CACvC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACnD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,uDAAuD;IACvD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACvC,qFAAqF;IACrF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;CACjD;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,YAAY,GAAG,aAAa,GAAG,iBAAiB,CAAA;AAEvF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;AAE/C,sIAAsI;AACtI,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,SAAS,IAC7C,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,MAAM,GAC9C,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,MAAM,GAC9C,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG,OAAO,GAChD,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG,MAAM,EAAE,GAClD,KAAK,CAAA;AAEP,qGAAqG;AACrG,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,OAAO,IAAI;IAC9C,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/C,CAAA"}

package/dist/core/config/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../src/core/config/env.ts"],"names":[],"mappings":"AAGA,wBAAgB,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAM/C"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../src/core/config/env.ts"],"names":[],"mappings":"AAKA,wBAAgB,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAU/C"}

package/dist/core/config/env.js

@@ -1,24 +1,28 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
+const ENV_FILES = ['.env.test.local', '.env.test', '.env.local', '.env'];
 export function loadEnvFiles(cwd) {
     const start = cwd ?? process.cwd();
     const envDir = findEnvDir(start) ?? start;
-    loadFile(resolve(envDir, '.env.test'));
-    loadFile(resolve(envDir, '.env'));
+    // First-set wins (loadFile never overwrites), so the machine-local,
+    // never-committed `.local` variant of each tier takes precedence over the
+    // committed file — the standard dotenv convention.
+    for (const file of ENV_FILES) {
+        loadFile(resolve(envDir, file));
+    }
 }
 function findEnvDir(from) {
+    const hasEnvFile = (dir) => ENV_FILES.some(f => existsSync(resolve(dir, f)));
     let dir = resolve(from);
     let parent = dirname(dir);
     while (dir !== parent) {
-        if (existsSync(resolve(dir, '.env')) || existsSync(resolve(dir, '.env.test'))) {
+        if (hasEnvFile(dir))
             return dir;
-        }
         dir = parent;
         parent = dirname(dir);
     }
-    if (existsSync(resolve(dir, '.env')) || existsSync(resolve(dir, '.env.test'))) {
+    if (hasEnvFile(dir))
         return dir;
-    }
     return null;
 }
 function loadFile(path) {

package/dist/core/config/env.js.map

@@ -1 +1 @@
-{"version":3,"file":"env.js","sourceRoot":"","sources":["../../../src/core/config/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAE5C,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,MAAM,KAAK,GAAG,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAA;IAClC,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAA;IAEzC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAA;IACtC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AACnC,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,IAAI,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvB,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IACzB,OAAO,GAAG,KAAK,MAAM,EAAE,CAAC;QACtB,IAAI,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,IAAI,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC;YAC9E,OAAO,GAAG,CAAA;QACZ,CAAC;QACD,GAAG,GAAG,MAAM,CAAA;QACZ,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IACvB,CAAC;IACD,IAAI,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,IAAI,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC;QAC9E,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAM;IAE7B,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IAC3C,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QAC3B,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAQ;QAEvD,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAClC,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,SAAQ;QAE1B,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,CAAA;QAC1C,IAAI,GAAG,KAAK,EAAE;YAAE,SAAQ;QAExB,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,SAAQ;QAE5C,IAAI,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAC3C,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC9C,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACnD,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;QAC5B,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;IAC1B,CAAC;AACH,CAAC"}
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../../src/core/config/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAE5C,MAAM,SAAS,GAAG,CAAC,iBAAiB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,CAAC,CAAA;AAExE,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,MAAM,KAAK,GAAG,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAA;IAClC,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAA;IAEzC,oEAAoE;IACpE,0EAA0E;IAC1E,mDAAmD;IACnD,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAA;IACjC,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,UAAU,GAAG,CAAC,GAAW,EAAW,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;IAC7F,IAAI,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvB,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IACzB,OAAO,GAAG,KAAK,MAAM,EAAE,CAAC;QACtB,IAAI,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,GAAG,CAAA;QAC/B,GAAG,GAAG,MAAM,CAAA;QACZ,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IACvB,CAAC;IACD,IAAI,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAA;IAC/B,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAM;IAE7B,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IAC3C,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QAC3B,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAQ;QAEvD,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAClC,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,SAAQ;QAE1B,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,CAAA;QAC1C,IAAI,GAAG,KAAK,EAAE;YAAE,SAAQ;QAExB,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,SAAQ;QAE5C,IAAI,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAC3C,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC9C,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACnD,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;QAC5B,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;IAC1B,CAAC;AACH,CAAC"}

package/dist/core/config/import-config.d.ts

@@ -0,0 +1,3 @@
+import type { Manifold } from '../pipework.js';
+export declare function importConfig(configPath: string): Promise<Manifold>;
+//# sourceMappingURL=import-config.d.ts.map

package/dist/core/config/import-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-config.d.ts","sourceRoot":"","sources":["../../../src/core/config/import-config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAS9C,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAwBxE"}