pipework 0.251.0 → 0.252.1

package/src/test/system-channel.ts

@@ -0,0 +1,50 @@
+import type postgres from 'postgres'
+import { drizzle, type PostgresJsDatabase } from '../data/query/postgres-js/index.js'
+
+/** The setting the test-only policy `pipework_test_system` reads. */
+export const TEST_SYSTEM_SETTING = 'pipework.test_system'
+
+/** The setting a door's generated policy reads. */
+export const DOOR_SETTING = 'pipework.door'
+
+const ON = `SELECT set_config('${TEST_SYSTEM_SETTING}', 'on', true)`
+const OFF = `SELECT set_config('${TEST_SYSTEM_SETTING}', 'off', true)`
+const quoted = (value: string): string => `'${value.replace(/'/g, "''")}'`
+const noop = (): void => {}
+
+/**
+ * A handle over the test's own connection whose every statement runs with the
+ * test-only escape policy open: the statement is sent between two
+ * `set_config` queries enqueued in the same tick, so on this single
+ * connection no other query can land between them. The escape is never left
+ * on for a span of time. A statement that fails leaves the transaction
+ * aborted; the closing query then fails too, and its failure is swallowed.
+ */
+export function createSystemHandle(client: postgres.Sql, door?: string): PostgresJsDatabase {
+  // A door's statement also names the door, so the door policy is open too
+  // wherever the connection's role is the platform role.
+  const on = door === undefined ? ON : `${ON}, set_config('${DOOR_SETTING}', ${quoted(door)}, true)`
+  const off = door === undefined ? OFF : `${OFF}, set_config('${DOOR_SETTING}', '', true)`
+  const bracketed = new Proxy(client, {
+    get(target, prop, receiver) {
+      if (prop !== 'unsafe') return Reflect.get(target, prop, receiver)
+      // Read at call time: the connection's `unsafe` is patched after this handle is built.
+      const send = (target as { unsafe: (...args: unknown[]) => unknown }).unsafe.bind(target)
+      return (query: string, params?: unknown[], ...rest: unknown[]): unknown => {
+        const middle = send(query, params, ...rest) as { handle(): Promise<void>; executed: boolean }
+        const start = middle.handle
+        middle.handle = function (this: typeof middle): Promise<void> {
+          if (this.executed) return Promise.resolve()
+          const open = send(on) as { execute(): { catch(f: () => void): unknown } }
+          open.execute().catch(noop)
+          const result = start.call(this)
+          const close = send(off) as { execute(): { catch(f: () => void): unknown } }
+          close.execute().catch(noop)
+          return result
+        }
+        return middle
+      }
+    },
+  })
+  return drizzle(bracketed)
+}

package/src/test/vitest-plugin.ts

@@ -0,0 +1,142 @@
+import { existsSync } from 'node:fs'
+import { isAbsolute, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Plugin } from 'vitest/config'
+
+import { applyFlowStepTransform } from '../trace/transformer/apply.js'
+
+export interface PipeworkVitestOptions {
+  globals?: boolean
+  isolate?: boolean
+  /** Set to `false` to skip auto-setup (manifold discovery, DB provisioning, per-test isolation). Use this for pure unit test configs that never call `pipe()` or `withFlow()`. */
+  database?: boolean
+  /**
+   * Absolute path to the project (package) root. When set, any module that
+   * Vite would resolve to `<root>/dist/*.js` is rewritten to its `<root>/src/*.ts`
+   * (or `.tsx`) source so `vi.mock` matches the file handlers actually import
+   * — without this, a built workspace package gets split into two module
+   * identities (dist + src), and mock interception silently fails. Issue #274.
+   */
+  packageRoot?: string
+  /**
+   * Map of bare cross-package workspace specifier → absolute source file.
+   * vitest does not honour tsconfig `paths`, so an import of `@scope/pkg` (or
+   * one of its export subpaths) resolves through the package's `exports` field
+   * to `dist/`, which is not built during `pipework test`. This routes those
+   * specifiers to `src/` instead. Issue #301.
+   *
+   * A wildcard export subpath contributes a single `*` entry — key and value
+   * both contain one `*` (e.g. `@scope/pkg/events/*` → `<abs>/pkg/src/events/*.ts`).
+   * The resolver substitutes the matched segment into the value. Issue #311.
+   */
+  workspacePackages?: Record<string, string>
+}
+
+/**
+ * A wildcard workspace entry split at its single `*`: a specifier matches when
+ * it starts with `prefix` and ends with `suffix`, and the segment between them
+ * is substituted into the value at `valuePrefix`/`valueSuffix`. Issue #311.
+ */
+interface WildcardPackage {
+  prefix: string
+  suffix: string
+  valuePrefix: string
+  valueSuffix: string
+}
+
+function splitWorkspacePackages(workspacePackages: Record<string, string>): {
+  exact: Record<string, string>
+  wildcard: WildcardPackage[]
+} {
+  const exact: Record<string, string> = {}
+  const wildcard: WildcardPackage[] = []
+  for (const [specifier, value] of Object.entries(workspacePackages)) {
+    const star = specifier.indexOf('*')
+    const valueStar = value.indexOf('*')
+    // A wildcard specifier must map to a wildcard value — otherwise every
+    // matched subpath would collapse onto one file. Treat a mismatched entry
+    // as exact so a malformed map degrades to a miss rather than misresolving.
+    if (star === -1 || valueStar === -1) {
+      exact[specifier] = value
+      continue
+    }
+    wildcard.push({
+      prefix: specifier.slice(0, star),
+      suffix: specifier.slice(star + 1),
+      valuePrefix: value.slice(0, valueStar),
+      valueSuffix: value.slice(valueStar + 1),
+    })
+  }
+  return { exact, wildcard }
+}
+
+// Wraps `@flow_step` functions in consumer source so they run as trace steps
+// under test. Runs before Vite strips types; the printer reflows the file, so
+// stack-trace lines inside an annotated file can shift.
+const flowStepTransform: NonNullable<Plugin['transform']> = function (code, id) {
+  const file = id.split('?')[0] ?? id
+  if (!/\.tsx?$/.test(file) || file.includes('/node_modules/') || !isAbsolute(file)) return null
+  const applied = applyFlowStepTransform(code, file)
+  return applied === null ? null : { code: applied.code, map: null }
+}
+
+// Forked workers are SIGTERMed right after vitest's `stop` handshake, so their
+// last queued clone drops never run. This module's teardown runs in the parent
+// once every worker is gone and drops what they left (#810).
+const REAP_AFTER_RUN = fileURLToPath(new URL(`./reap-after-run${import.meta.url.slice(import.meta.url.lastIndexOf('.'))}`, import.meta.url))
+
+export function pipework(options?: PipeworkVitestOptions): Plugin {
+  const reapConfig: Pick<Plugin, 'config'> =
+    options?.database === false ? {} : { config: () => ({ test: { globalSetup: [REAP_AFTER_RUN] } }) }
+  const packageRoot = options?.packageRoot
+  const workspacePackages = options?.workspacePackages
+  if (packageRoot === undefined && workspacePackages === undefined) {
+    return { name: 'pipework', enforce: 'pre', transform: flowStepTransform, ...reapConfig }
+  }
+  const distPrefix = packageRoot !== undefined ? packageRoot + sep + 'dist' + sep : undefined
+  const srcPrefix = packageRoot !== undefined ? packageRoot + sep + 'src' + sep : undefined
+  const { exact, wildcard } =
+    workspacePackages !== undefined
+      ? splitWorkspacePackages(workspacePackages)
+      : { exact: {}, wildcard: [] }
+
+  return {
+    name: 'pipework',
+    enforce: 'pre',
+    transform: flowStepTransform,
+    ...reapConfig,
+    async resolveId(source, importer) {
+      // Cross-package (#301): a bare workspace specifier resolves straight to src/.
+      if (workspacePackages !== undefined) {
+        const mapped = exact[source]
+        if (mapped !== undefined) return mapped
+        // Wildcard export subpath (#311): match `prefix*suffix`, substitute the
+        // captured segment, and resolve only when the source file exists — a
+        // miss falls through so Vite reports its own error.
+        for (const w of wildcard) {
+          if (
+            source.length > w.prefix.length + w.suffix.length &&
+            source.startsWith(w.prefix) &&
+            source.endsWith(w.suffix)
+          ) {
+            const matched = source.slice(w.prefix.length, source.length - w.suffix.length)
+            const candidate = w.valuePrefix + matched + w.valueSuffix
+            if (existsSync(candidate)) return candidate
+          }
+        }
+      }
+      // Intra-package (#274): a built dist/*.js is rewritten to its src/*.ts.
+      if (distPrefix === undefined || srcPrefix === undefined) return null
+      const resolved = await this.resolve(source, importer, { skipSelf: true })
+      if (resolved === null) return null
+      const id = resolved.id
+      if (!id.startsWith(distPrefix) || !id.endsWith('.js')) return null
+      const relative = id.slice(distPrefix.length, -3)
+      for (const ext of ['.ts', '.tsx']) {
+        const candidate = srcPrefix + relative + ext
+        if (existsSync(candidate)) return candidate
+      }
+      return null
+    },
+  }
+}

package/src/test/vitest-workspace.ts

@@ -0,0 +1,507 @@
+import { resolve, dirname } from 'node:path'
+import { configDefaults } from 'vitest/config'
+import type { ViteUserConfig, UserWorkspaceConfig } from 'vitest/config'
+import type { VitestConfig, VitestModuleConfig, VitestProfileConfig, CoverageConfig } from '../core/config/schema.js'
+import type { ResolvedModule } from '../workspace/discover.js'
+import type { Manifold } from '../core/pipework.js'
+import { findConfig, registerTsResolveHooks } from '../core/config/discover.js'
+import { importConfig } from '../core/config/import-config.js'
+import { loadEnvFiles } from '../core/config/env.js'
+import { resolveModules } from '../workspace/discover.js'
+import { workspaceSourcePaths } from '../workspace/source-paths.js'
+import { pipework as pipeworkPlugin } from './vitest-plugin.js'
+
+const DEFAULT_TEST_TIMEOUT = 30_000
+export const DEFAULT_HOOK_TIMEOUT = 60_000
+
+// Pipework's own defaults, overridable per workspace, module and profile via
+// `vitest.pool` / `vitest.isolate`. `forks` because a test that sets a process-wide
+// Postgres session must not share a worker; `isolate: false` because pipework's
+// per-test database isolation already separates test state and re-isolating the
+// worker costs a process spawn per file.
+const DEFAULT_POOL = 'forks'
+const DEFAULT_ISOLATE = false
+
+type PoolName = NonNullable<VitestConfig['pool']>
+
+/**
+ * Consumer excludes on TOP of vitest's defaults, not in place of them.
+ *
+ * Vitest replaces `exclude` outright, so a config that adds one glob silently stops
+ * excluding `node_modules` and `.git` — the suite then tries to run every test in every
+ * installed package. Merging is the behaviour a consumer means (#394).
+ */
+function mergeExclude(configured: string[] | undefined): string[] {
+  if (configured === undefined) return [...configDefaults.exclude]
+  return [...new Set([...configDefaults.exclude, ...configured])]
+}
+
+/**
+ * Build the full vitest UserConfig from pipework.config.ts.
+ *
+ * The generated `vitest.config.ts` is a single line: `defineConfig(await resolveVitestConfig())`.
+ * Everything that would normally live in `vitest.config.ts` — projects, reporters, sequencer,
+ * outer-level Vite options — flows through `pipework.config.ts` so pipework remains the single
+ * source of truth and the generated file stays byte-stable for `pipework check`.
+ *
+ * Shape:
+ *   - `vitest.extra.test.*` → spread into `test` (reporters, sequence, cache, bail, ...)
+ *   - `vitest.extra.*` (anything outside `test`) → spread at the top level (resolve, plugins, ...)
+ *   - `test.projects` is owned by pipework — defining it in `extra` throws.
+ */
+export async function resolveVitestConfig(cwd?: string): Promise<ViteUserConfig> {
+  const start = cwd ?? process.cwd()
+  const configPath = findConfig(start)
+
+  if (configPath === null) {
+    throw new Error(
+      `[pipework] No pipework.config.ts found in ${start} or any parent directory.\n\n` +
+      '  The vitest config resolver needs pipework.config.ts to discover modules.\n' +
+      '  Create one with `pipework init`.\n',
+    )
+  }
+
+  const configDir = dirname(configPath)
+  loadEnvFiles(configDir)
+  registerTsResolveHooks()
+
+  let manifold: Manifold
+  try {
+    manifold = await importConfig(configPath)
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err)
+    throw new Error(
+      `[pipework] Failed to load pipework.config.ts for vitest config resolution.\n\n` +
+      `  ${message}\n\n` +
+      '  This usually means database environment variables are missing.\n' +
+      '  Ensure your .env file exists and contains DATABASE_URL (or equivalent).\n\n' +
+      '  The vitest config resolver imports your config to read module definitions.\n' +
+      '  It does not connect to any database.\n',
+    )
+  }
+
+  const blueprint = manifold.config.raw
+  if (blueprint.vitest === undefined) {
+    return { test: { projects: [] } }
+  }
+
+  const resolvedModules = resolveModules(blueprint.modules, configDir)
+  const workspacePackages: Record<string, string> = {}
+  for (const [specifier, relPath] of workspaceSourcePaths(resolvedModules, blueprint.name ?? 'app')) {
+    workspacePackages[specifier] = resolve(configDir, relPath)
+  }
+  const projects = resolveVitestModules(blueprint.vitest, resolvedModules, configDir, workspacePackages)
+  return mergeExtraWithProjects(blueprint.vitest.extra, projects, blueprint.vitest.coverage)
+}
+
+/**
+ * Merge consumer-supplied top-level vitest config (from `vitest.extra`) with the
+ * pipework-controlled `test.projects`. Splits `extra` into outer-level keys (Vite-level:
+ * `resolve`, `plugins`, ...) and `test`-level keys (`reporters`, `sequence`, ...),
+ * spreading each at the right depth. Throws if the consumer tries to override `projects`.
+ */
+function mergeExtraWithProjects(
+  extra: Record<string, unknown> | undefined,
+  projects: UserWorkspaceConfig[],
+  coverage: CoverageConfig | undefined,
+): ViteUserConfig {
+  // Vitest reads coverage at the root only. It used to be written into each project,
+  // where it did nothing — including `coverage.enabled`, which had no schema entry at
+  // all, so an env-gated preset was unreachable except through `extra.test` (#394).
+  const root = coverage !== undefined ? { coverage: rootCoverage(coverage) } : {}
+
+  if (extra === undefined) {
+    return { test: { ...root, projects } }
+  }
+
+  const { test: extraTest, ...extraOuter } = extra
+
+  if (extraTest !== undefined && (typeof extraTest !== 'object' || extraTest === null || Array.isArray(extraTest))) {
+    throw new Error(
+      `[pipework] vitest.extra.test must be an object — got ${describe(extraTest)}.\n\n` +
+      '  vitest.extra mirrors the shape of `defineConfig({...})`:\n' +
+      '    - test-level keys (reporters, sequence, ...) go under `extra.test`\n' +
+      '    - outer Vite keys (resolve, plugins, ...) go at the top of `extra`\n',
+    )
+  }
+
+  const testRecord = (extraTest ?? {}) as Record<string, unknown>
+
+  if ('projects' in testRecord) {
+    throw new Error(
+      `[pipework] vitest.extra.test.projects is owned by pipework — \n` +
+      '  define modules in `vitest.modules` (in pipework.config.ts) instead.\n' +
+      '  The generated vitest.config.ts wires `projects` through `resolveVitestConfig()`.\n',
+    )
+  }
+
+  return {
+    ...extraOuter,
+    test: {
+      ...root,
+      ...testRecord,
+      projects,
+    },
+  }
+}
+
+// `exactOptionalPropertyTypes` makes an explicit `undefined` a different thing from an
+// absent key, and vitest's InlineConfig accepts only the latter. Drop the unset ones.
+function rootCoverage(coverage: CoverageConfig): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(coverage)) {
+    if (value !== undefined) out[key] = value
+  }
+  return out
+}
+
+function describe(v: unknown): string {
+  if (v === null) return 'null'
+  if (Array.isArray(v)) return 'array'
+  return typeof v
+}
+
+/**
+ * Refuse a `coverage` key on a module or profile.
+ *
+ * Vitest treats coverage as a root-level option, so one written into a project is
+ * discarded without a word — the exact silent-no-op #394 was filed for. Naming the
+ * module beats accepting a setting that cannot take effect.
+ */
+function refuseProjectCoverage(where: string, config: { coverage?: unknown }): void {
+  if (config.coverage === undefined) return
+  throw new Error(
+    `[pipework] vitest coverage is a root-level option — remove it from \`${where}\`.\n\n` +
+    '  Vitest reads `coverage` at the config root; inside a project it is ignored.\n' +
+    '  Move the settings to the top-level `vitest.coverage` in pipework.config.ts.\n' +
+    '  Gate collection with `vitest.coverage.enabled` (compute the boolean there to\n' +
+    '  key it off an environment variable).\n',
+  )
+}
+
+export function resolveVitestModules(
+  vitestConfig: VitestConfig,
+  resolvedModules: ResolvedModule[],
+  configDir: string,
+  workspacePackages: Record<string, string>,
+): UserWorkspaceConfig[] {
+  // A repo with no declared modules is a single-package project: the repo root
+  // is the one implicit module, addressed as '.'. The centralized vitest model
+  // must be able to express this layout — otherwise single-package projects
+  // have no in-config home for their test setup.
+  const effectiveModules: ResolvedModule[] = resolvedModules.length === 0
+    ? [{ key: '.', relativePath: '.', config: {} }]
+    : resolvedModules
+  const moduleMap = new Map(effectiveModules.map(m => [m.relativePath, m]))
+  const included = resolveIncludedModules(vitestConfig, moduleMap)
+
+  const projects: UserWorkspaceConfig[] = []
+
+  for (const [modulePath, moduleConfig] of [...included.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    refuseProjectCoverage(`vitest.modules["${modulePath}"].coverage`, moduleConfig)
+    const project = buildProjectConfig(modulePath, moduleConfig, vitestConfig, configDir, workspacePackages)
+    projects.push(project)
+
+    if (moduleConfig.profiles !== undefined) {
+      for (const [profileName, profileConfig] of Object.entries(moduleConfig.profiles).sort(([a], [b]) => a.localeCompare(b))) {
+        refuseProjectCoverage(`vitest.modules["${modulePath}"].profiles["${profileName}"].coverage`, profileConfig)
+        const profileProject = buildProfileConfig(modulePath, profileName, moduleConfig, profileConfig, vitestConfig, configDir, workspacePackages)
+        projects.push(profileProject)
+      }
+    }
+  }
+
+  return projects
+}
+
+function resolveIncludedModules(
+  vitestConfig: VitestConfig,
+  moduleMap: Map<string, ResolvedModule>,
+): Map<string, VitestModuleConfig> {
+  if (vitestConfig.modules === undefined) {
+    const result = new Map<string, VitestModuleConfig>()
+    for (const key of moduleMap.keys()) {
+      result.set(key, {})
+    }
+    return result
+  }
+
+  const globs: Array<{ pattern: string; config: VitestModuleConfig }> = []
+  const explicit: Array<{ key: string; config: VitestModuleConfig }> = []
+
+  for (const [key, config] of Object.entries(vitestConfig.modules)) {
+    if (key.includes('*')) {
+      globs.push({ pattern: key, config })
+    } else {
+      explicit.push({ key, config })
+    }
+  }
+
+  const result = new Map<string, VitestModuleConfig>()
+
+  for (const { pattern, config } of globs) {
+    for (const modulePath of matchGlob(pattern, moduleMap)) {
+      result.set(modulePath, config)
+    }
+  }
+
+  for (const { key, config } of explicit) {
+    if (!moduleMap.has(key)) {
+      const known = [...moduleMap.keys()]
+      const suggestion = closestMatch(key, known)
+      const knownList = known.join(', ')
+      const hint = suggestion !== null
+        ? `Did you mean "${suggestion}"? Known modules: ${knownList}`
+        : `Known modules: ${knownList}`
+      throw new Error(
+        `[pipework] Unknown module "${key}" in vitest.modules.\n\n  ${hint}\n`,
+      )
+    }
+
+    const existing = result.get(key)
+    if (existing !== undefined) {
+      result.set(key, mergeModuleConfigs(existing, config))
+    } else {
+      result.set(key, config)
+    }
+  }
+
+  return result
+}
+
+function matchGlob(pattern: string, moduleMap: Map<string, ResolvedModule>): string[] {
+  const parts = pattern.split('/')
+  const starIndex = parts.indexOf('*')
+  if (starIndex === -1) return []
+
+  const prefix = parts.slice(0, starIndex).join('/')
+  const suffix = parts.slice(starIndex + 1).join('/')
+
+  const matches: string[] = []
+  for (const key of moduleMap.keys()) {
+    const keyParts = key.split('/')
+    if (keyParts.length !== parts.length) continue
+
+    const keyPrefix = keyParts.slice(0, starIndex).join('/')
+    const keySuffix = keyParts.slice(starIndex + 1).join('/')
+
+    if (keyPrefix === prefix && keySuffix === suffix) {
+      matches.push(key)
+    }
+  }
+  return matches.sort()
+}
+
+function mergeModuleConfigs(base: VitestModuleConfig, override: VitestModuleConfig): VitestModuleConfig {
+  return {
+    ...override,
+    coverage: override.coverage !== undefined || base.coverage !== undefined
+      ? { ...base.coverage, ...override.coverage }
+      : undefined,
+    env: override.env !== undefined || base.env !== undefined
+      ? { ...base.env, ...override.env }
+      : undefined,
+    extra: override.extra !== undefined || base.extra !== undefined
+      ? { ...base.extra, ...override.extra }
+      : undefined,
+    profiles: override.profiles !== undefined || base.profiles !== undefined
+      ? { ...base.profiles, ...override.profiles }
+      : undefined,
+  }
+}
+
+function buildProjectConfig(
+  modulePath: string,
+  moduleConfig: VitestModuleConfig,
+  workspace: VitestConfig,
+  configDir: string,
+  workspacePackages: Record<string, string>,
+): UserWorkspaceConfig {
+  const database = moduleConfig.database ?? workspace.database ?? true
+  const testTimeout = moduleConfig.testTimeout ?? workspace.testTimeout ?? DEFAULT_TEST_TIMEOUT
+  const hookTimeout = moduleConfig.hookTimeout ?? workspace.hookTimeout ?? DEFAULT_HOOK_TIMEOUT
+  const include = moduleConfig.include ?? workspace.include
+  const exclude = moduleConfig.exclude ?? workspace.exclude
+
+  const setupFiles = buildSetupFiles(database, moduleConfig.setupFiles)
+  const inlineDeps = buildInlineDeps(workspace.inlineDeps)
+
+  const extra = moduleConfig.extra ?? {}
+
+  return buildProject({
+    name: modulePath,
+    root: resolve(configDir, modulePath),
+    database,
+    testTimeout,
+    hookTimeout,
+    include,
+    exclude,
+    setupFiles,
+    inlineDeps,
+    pool: moduleConfig.pool ?? workspace.pool,
+    isolate: moduleConfig.isolate ?? workspace.isolate,
+    env: moduleConfig.env,
+    extra,
+    workspacePackages,
+  })
+}
+
+function buildProfileConfig(
+  modulePath: string,
+  profileName: string,
+  moduleConfig: VitestModuleConfig,
+  profileConfig: VitestProfileConfig,
+  workspace: VitestConfig,
+  configDir: string,
+  workspacePackages: Record<string, string>,
+): UserWorkspaceConfig {
+  const database = profileConfig.database ?? moduleConfig.database ?? workspace.database ?? true
+  const testTimeout = profileConfig.testTimeout ?? moduleConfig.testTimeout ?? workspace.testTimeout ?? DEFAULT_TEST_TIMEOUT
+  const hookTimeout = profileConfig.hookTimeout ?? moduleConfig.hookTimeout ?? workspace.hookTimeout ?? DEFAULT_HOOK_TIMEOUT
+  const include = profileConfig.include ?? moduleConfig.include ?? workspace.include
+  const exclude = profileConfig.exclude ?? moduleConfig.exclude ?? workspace.exclude
+
+  const profileSetupFiles = profileConfig.setupFiles ?? moduleConfig.setupFiles
+  const setupFiles = buildSetupFiles(database, profileSetupFiles)
+  const inlineDeps = buildInlineDeps(workspace.inlineDeps)
+
+  const moduleExtra = moduleConfig.extra ?? {}
+  const extra = profileConfig.extra !== undefined
+    ? { ...moduleExtra, ...profileConfig.extra }
+    : moduleExtra
+
+  const env = profileConfig.env !== undefined || moduleConfig.env !== undefined
+    ? { ...moduleConfig.env, ...profileConfig.env }
+    : undefined
+
+  return buildProject({
+    name: `${modulePath}:${profileName}`,
+    root: resolve(configDir, modulePath),
+    database,
+    testTimeout,
+    hookTimeout,
+    include,
+    exclude,
+    setupFiles,
+    inlineDeps,
+    pool: profileConfig.pool ?? moduleConfig.pool ?? workspace.pool,
+    isolate: profileConfig.isolate ?? moduleConfig.isolate ?? workspace.isolate,
+    env,
+    extra,
+    workspacePackages,
+  })
+}
+
+interface ProjectBuildInput {
+  name: string
+  root: string
+  database: boolean
+  testTimeout: number
+  hookTimeout: number
+  include: string[] | undefined
+  exclude: string[] | undefined
+  setupFiles: string[]
+  inlineDeps: string[]
+  pool: PoolName | undefined
+  isolate: boolean | undefined
+  env: Record<string, string> | undefined
+  extra: Record<string, unknown>
+  workspacePackages: Record<string, string>
+}
+
+function buildProject(input: ProjectBuildInput): UserWorkspaceConfig {
+  return {
+    ...input.extra,
+    plugins: [
+      pipeworkPlugin({ database: input.database, packageRoot: input.root, workspacePackages: input.workspacePackages }),
+    ],
+    test: {
+      // Pipework defaults — overridable via `extra.test` below (#260).
+      pool: DEFAULT_POOL,
+      isolate: DEFAULT_ISOLATE,
+      ...('test' in input.extra ? input.extra['test'] as Record<string, unknown> : {}),
+      // Dedicated config fields and project identity — these win over
+      // `extra.test`. `name`/`root` are the project's identity (changing them
+      // breaks `--project` matching and module rooting); `setupFiles` and the
+      // inline-deps `server` config are load-bearing for test isolation.
+      name: input.name,
+      root: input.root,
+      testTimeout: input.testTimeout,
+      hookTimeout: input.hookTimeout,
+      server: {
+        deps: {
+          inline: input.inlineDeps,
+        },
+      },
+      setupFiles: input.setupFiles,
+      // `vitest.pool` / `vitest.isolate` are dedicated fields, so an explicitly
+      // configured one wins over `extra.test`; unset, the default above stands and
+      // `extra.test` still overrides it as it always did.
+      ...(input.pool !== undefined ? { pool: input.pool } : {}),
+      ...(input.isolate !== undefined ? { isolate: input.isolate } : {}),
+      ...(input.include !== undefined ? { include: input.include } : {}),
+      exclude: mergeExclude(input.exclude),
+      ...(input.env !== undefined ? { env: input.env } : {}),
+    },
+  }
+}
+
+function buildSetupFiles(database: boolean, userSetupFiles: string[] | undefined): string[] {
+  const files: string[] = []
+  if (database) {
+    files.push('pipework/test/setup')
+  }
+  if (userSetupFiles !== undefined) {
+    files.push(...userSetupFiles)
+  }
+  return files
+}
+
+function buildInlineDeps(workspaceInlineDeps: string[] | undefined): string[] {
+  const deps = new Set<string>(['pipework'])
+  if (workspaceInlineDeps !== undefined) {
+    for (const dep of workspaceInlineDeps) {
+      deps.add(dep)
+    }
+  }
+  return [...deps]
+}
+
+function closestMatch(input: string, candidates: string[]): string | null {
+  if (candidates.length === 0) return null
+
+  let best: string | null = null
+  let bestDistance = Infinity
+
+  for (const candidate of candidates) {
+    const d = levenshtein(input.toLowerCase(), candidate.toLowerCase())
+    if (d < bestDistance && d <= Math.max(input.length, candidate.length) * 0.6) {
+      bestDistance = d
+      best = candidate
+    }
+  }
+
+  return best
+}
+
+function levenshtein(a: string, b: string): number {
+  const m = a.length
+  const n = b.length
+  const dp: number[][] = Array.from({ length: m + 1 }, () => Array.from({ length: n + 1 }, () => 0))
+
+  for (let i = 0; i <= m; i++) dp[i]![0] = i
+  for (let j = 0; j <= n; j++) dp[0]![j] = j
+
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      dp[i]![j] = Math.min(
+        dp[i - 1]![j]! + 1,
+        dp[i]![j - 1]! + 1,
+        dp[i - 1]![j - 1]! + cost,
+      )
+    }
+  }
+
+  return dp[m]![n]!
+}