pipework 0.252.0 → 0.253.0

package/src/core/config/base-dir.ts

@@ -0,0 +1,24 @@
+// 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: string | undefined
+
+export function setConfigBaseDir(dir: string): void {
+  configBaseDir = dir
+}
+
+/** Read-and-clear. Undefined when no config import is in flight — directly-constructed configs resolve against process.cwd(). */
+export function consumeConfigBaseDir(): string | undefined {
+  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(): void {
+  configBaseDir = undefined
+}

package/src/core/config/discover.ts

@@ -0,0 +1,64 @@
+import { resolve, dirname } from 'node:path'
+import { existsSync } from 'node:fs'
+import type { Manifold } from '../pipework.js'
+import { ConfigError } from './errors.js'
+import { importConfig } from './import-config.js'
+import { registerTsResolveHooks } from './ts-inline-hooks.js'
+
+export { registerTsResolveHooks }
+
+const CONFIG_FILENAME = 'pipework.config.ts'
+
+/**
+ * Loads the Manifold for `cwd` (default `process.cwd()`).
+ *
+ * Normally the config is found by walking up from `cwd` for
+ * `pipework.config.ts`. Setting `PIPEWORK_CONFIG` names the config file to
+ * load instead — resolved against `process.cwd()` when relative, and a
+ * ConfigError when it names a file that does not exist. Nothing in pipework
+ * sets or defaults it; only a deliberate caller (a test runner pointing a
+ * fork at a slim test-only manifold) gets the override. Discovery itself
+ * leaves the variable alone; the test fork's `discoverForTestFork` consumes
+ * it after loading, so it never travels to processes a test spawns.
+ */
+export async function discoverInstance(cwd?: string): Promise<Manifold> {
+  const start = cwd ?? process.cwd()
+  const override = process.env['PIPEWORK_CONFIG']
+  const configPath = override === undefined ? findConfig(start) : resolveOverride(override)
+
+  if (configPath === null) {
+    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()
+
+  return importConfig(configPath)
+}
+
+function resolveOverride(value: string): string {
+  const path = resolve(process.cwd(), value)
+  if (!existsSync(path)) {
+    throw new ConfigError(
+      `PIPEWORK_CONFIG names a config file that does not exist: ${path}`,
+      `Unset PIPEWORK_CONFIG to discover ${CONFIG_FILENAME} normally, or point it at a file that exists.`,
+    )
+  }
+  return path
+}
+
+export function findConfig(from: string): string | null {
+  let dir = resolve(from)
+  let parent = dirname(dir)
+  while (dir !== parent) {
+    const candidate = resolve(dir, CONFIG_FILENAME)
+    if (existsSync(candidate)) return candidate
+    dir = parent
+    parent = dirname(dir)
+  }
+  const root = resolve(dir, CONFIG_FILENAME)
+  if (existsSync(root)) return root
+  return null
+}

package/src/core/config/env-resolve.ts

@@ -0,0 +1,87 @@
+import type { EnvDefs, EnvVarDef } from './env-types.js'
+import type { Environment } from './schema.js'
+import { ConfigError } from './errors.js'
+
+const TRUTHY = new Set(['true', '1', 'yes'])
+const FALSY = new Set(['false', '0', 'no'])
+
+export function resolveEnvVars(
+  defs: EnvDefs | Record<string, EnvVarDef>,
+  environment: Environment,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  const errors: string[] = []
+
+  for (const [name, def] of Object.entries(defs)) {
+    const raw = readRaw(name, def, environment)
+
+    if (raw === null) {
+      if (def.default !== undefined) {
+        result[name] = def.type === 'string[]' ? [...def.default] : def.default
+        continue
+      }
+      if (def.required === true) {
+        errors.push(def.sensitive === true
+          ? `  ${name}: Required but not set. (value redacted — marked sensitive)`
+          : `  ${name}: Required but not set.`)
+        continue
+      }
+      errors.push(`  ${name}: No value set and no default provided.`)
+      continue
+    }
+
+    try {
+      result[name] = coerce(raw, def)
+    } catch (err) {
+      errors.push(`  ${name}: ${(err as Error).message}`)
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new ConfigError(
+      `Environment validation failed (${errors.length} error${errors.length > 1 ? 's' : ''}):\n\n${errors.join('\n')}`,
+      'Set these in your .env file or environment.',
+    )
+  }
+
+  return result
+}
+
+function readRaw(name: string, def: EnvVarDef, environment: Environment): string | null {
+  const envValue = process.env[name]
+  if (envValue !== undefined && envValue !== '') return envValue
+
+  const envSpecific = def.defaults?.[environment]
+  if (envSpecific !== undefined && envSpecific !== '') return envSpecific
+
+  return null
+}
+
+function coerce(raw: string, def: EnvVarDef): unknown {
+  switch (def.type) {
+    case 'string':
+      return raw
+
+    case 'number': {
+      const n = Number(raw)
+      if (Number.isNaN(n)) {
+        const display = def.sensitive === true ? '(redacted)' : `"${raw}"`
+        throw new Error(`Expected a number, got ${display}.`)
+      }
+      return n
+    }
+
+    case 'boolean': {
+      const lower = raw.toLowerCase()
+      if (TRUTHY.has(lower)) return true
+      if (FALSY.has(lower)) return false
+      const display = def.sensitive === true ? '(redacted)' : `"${raw}"`
+      throw new Error(`Expected a boolean (true/false/1/0/yes/no), got ${display}.`)
+    }
+
+    case 'string[]': {
+      const sep = def.separator ?? ','
+      return raw.split(sep).map(s => s.trim()).filter(s => s !== '')
+    }
+  }
+}

package/src/core/config/env-types.ts

@@ -0,0 +1,116 @@
+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 { readonly type: 'number' } ? number :
+  T extends { readonly type: 'boolean' } ? 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/src/core/config/env.ts

@@ -0,0 +1,55 @@
+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?: string): void {
+  const start = cwd ?? process.cwd()
+  const envDir = findEnvDir(start) ?? start
+
+  // 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: string): string | null {
+  const hasEnvFile = (dir: string): boolean => ENV_FILES.some(f => existsSync(resolve(dir, f)))
+  let dir = resolve(from)
+  let parent = dirname(dir)
+  while (dir !== parent) {
+    if (hasEnvFile(dir)) return dir
+    dir = parent
+    parent = dirname(dir)
+  }
+  if (hasEnvFile(dir)) return dir
+  return null
+}
+
+function loadFile(path: string): void {
+  if (!existsSync(path)) return
+
+  const content = readFileSync(path, 'utf-8')
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed === '' || trimmed.startsWith('#')) continue
+
+    const eqIdx = trimmed.indexOf('=')
+    if (eqIdx === -1) continue
+
+    const key = trimmed.slice(0, eqIdx).trim()
+    if (key === '') continue
+
+    if (process.env[key] !== undefined) continue
+
+    let value = trimmed.slice(eqIdx + 1).trim()
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1)
+    }
+
+    process.env[key] = value
+  }
+}

package/src/core/config/errors.ts

@@ -0,0 +1,9 @@
+export class ConfigError extends Error {
+  public readonly hint: string
+
+  constructor(message: string, hint: string) {
+    super(`[pipework] ${message}\n\n  Hint: ${hint}\n`)
+    this.name = 'BlueprintError'
+    this.hint = hint
+  }
+}

package/src/core/config/import-config.ts

@@ -0,0 +1,40 @@
+import { dirname } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { Manifold } from '../pipework.js'
+import { ConfigError } from './errors.js'
+import { setConfigBaseDir, clearConfigBaseDir } from './base-dir.js'
+
+// The single import-and-validate chokepoint for pipework.config.ts. Every
+// importer (discoverInstance, the vitest config resolver, the eslint config
+// resolver) goes through here so relative `migrations`/`schema` paths always
+// resolve against the config file's directory, whichever entry path loads the
+// config first in a process.
+export async function importConfig(configPath: string): Promise<Manifold> {
+  setConfigBaseDir(dirname(configPath))
+  try {
+    const mod: Record<string, unknown> = await import(pathToFileURL(configPath).href)
+    const exported: unknown = mod['default'] ?? mod
+
+    if (!isManifold(exported)) {
+      throw new ConfigError(
+        `pipework.config.ts 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
+  } finally {
+    // An ESM cache hit re-enters here without re-running loadConfig (the
+    // consume). Clear unconditionally so the slot cannot leak into a later
+    // directly-constructed loadConfig.
+    clearConfigBaseDir()
+  }
+}
+
+function isManifold(v: unknown): v is Manifold {
+  return typeof v === 'object' && v !== null && 'pool' in v && 'config' in v
+}

package/src/core/config/index.ts

@@ -0,0 +1,8 @@
+export { trunkConfigSchema, type Blueprint, type DatabaseConfig, type TestConfig, type Environment, type IsolationStrategy, type ObservabilityConfig, type ModuleConfig, type VitestConfig, type VitestModuleConfig, type VitestProfileConfig, type CoverageConfig } from './schema.js'
+export { loadConfig, type ResolvedConfig, type ResolvedDatabase, type ResolvedObservability } from './load.js'
+export { resolveEnvironment } from './resolve.js'
+export { ConfigError } from './errors.js'
+export { discoverInstance, findConfig } from './discover.js'
+export { loadEnvFiles } from './env.js'
+export { resolveEnvVars } from './env-resolve.js'
+export type { EnvVarDef, EnvDefs, ResolveEnvDefs, StringEnvVar, NumberEnvVar, BooleanEnvVar, StringArrayEnvVar } from './env-types.js'