pipework 0.252.0 → 0.252.1

package/src/cli/commands/shared/pnpm-install.ts

@@ -0,0 +1,95 @@
+import { execSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Runs `pnpm install` and then reads back what actually landed in node_modules.
+ * pnpm asks for confirmation before purging a modules directory; with no TTY it
+ * takes the abort branch and still exits 0, so exit status alone cannot tell a
+ * real install from a no-op. The version read after the step is the verdict.
+ */
+
+const PURGE_PROMPT_ENV = { npm_config_confirm_modules_purge: 'false' } as const
+
+export function readInstalledPipeworkVersion(cwd: string): string | undefined {
+  try {
+    const raw = readFileSync(join(cwd, 'node_modules', 'pipework', 'package.json'), 'utf-8')
+    const pkg = JSON.parse(raw) as { version?: unknown }
+    return typeof pkg.version === 'string' ? pkg.version : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * True when `installed` is at least `required`. A version either side that is
+ * not a plain `x.y.z` (a workspace link, a tag) is not something this can
+ * judge, so it passes — the point is catching an install that did not run.
+ */
+export function isAtLeastVersion(installed: string, required: string): boolean {
+  const a = parseVersion(installed)
+  const b = parseVersion(required)
+  if (a === undefined || b === undefined) return true
+  if (a.major !== b.major) return a.major > b.major
+  if (a.minor !== b.minor) return a.minor > b.minor
+  return a.patch >= b.patch
+}
+
+interface Version {
+  readonly major: number
+  readonly minor: number
+  readonly patch: number
+}
+
+function parseVersion(value: string): Version | undefined {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value.trim())
+  if (match === null) return undefined
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) }
+}
+
+export function installMismatchMessage(
+  required: string,
+  installed: string | undefined,
+  cwd: string,
+): string {
+  const found = installed === undefined
+    ? 'node_modules/pipework is not there at all'
+    : `node_modules/pipework is at ${installed}`
+  return (
+    `pnpm install exited 0 but did not install pipework@^${required}.\n\n` +
+    `  ${found}.\n\n` +
+    `  With no TTY, pnpm aborts on its modules-purge confirmation prompt and\n` +
+    `  still exits 0. Pipework sets npm_config_confirm_modules_purge=false to\n` +
+    `  answer it; something else stopped the install. Run pnpm install directly\n` +
+    `  in ${cwd} to see what it asks.\n`
+  )
+}
+
+export interface PnpmInstallOptions {
+  readonly cwd: string
+  /** The pipework version the generated package.json asks for, as plain `x.y.z`. */
+  readonly requiredPipeworkVersion: string
+}
+
+export type PnpmInstallOutcome =
+  | { readonly ok: true; readonly installedPipeworkVersion: string }
+  | { readonly ok: false; readonly message: string }
+
+export function runPnpmInstall(options: PnpmInstallOptions): PnpmInstallOutcome {
+  try {
+    execSync('pnpm install', {
+      cwd: options.cwd,
+      stdio: 'inherit',
+      env: { ...process.env, PIPEWORK_SKIP_GUARD: '1', ...PURGE_PROMPT_ENV },
+    })
+  } catch {
+    return { ok: false, message: 'pnpm install failed. Check the output above for details.' }
+  }
+
+  const installed = readInstalledPipeworkVersion(options.cwd)
+  if (installed === undefined || !isAtLeastVersion(installed, options.requiredPipeworkVersion)) {
+    return { ok: false, message: installMismatchMessage(options.requiredPipeworkVersion, installed, options.cwd) }
+  }
+
+  return { ok: true, installedPipeworkVersion: installed }
+}

package/src/cli/commands/shared/report-removed.ts

@@ -0,0 +1,8 @@
+import type { SyncResult } from '../../../workspace/sync.js'
+import { warn } from '../../output.js'
+
+export function reportRemoved(result: Pick<SyncResult, 'removed'>): void {
+  for (const gone of result.removed) {
+    warn(`Removed ${gone.field} entry "${gone.name}" from ${gone.file}.`)
+  }
+}

package/src/cli/commands/sync.ts

@@ -0,0 +1,32 @@
+import { resolve } from 'node:path'
+import { sync as syncWorkspace } from '../../workspace/sync.js'
+import { loadConfig } from './shared/load-config.js'
+import { reportRemoved } from './shared/report-removed.js'
+import { info, success, warn } from '../output.js'
+
+export async function syncCommand(cwd: string): Promise<void> {
+  const { config, appName } = await loadConfig(resolve(cwd))
+
+  const result = syncWorkspace({
+    config,
+    cwd: resolve(cwd),
+    appName,
+  })
+
+  if (result.written === 0) {
+    info('Workspace already up to date.')
+  } else {
+    for (const file of result.files) {
+      if (result.written > 0) {
+        info(`  ${file.relativePath}`)
+      }
+    }
+    success(`Synced ${String(result.written)} file(s), ${String(result.skipped)} unchanged.`)
+  }
+
+  reportRemoved(result)
+
+  if (result.files.length === 0) {
+    warn('No files generated. Check your config for dependencies and modules.')
+  }
+}

package/src/cli/commands/test.ts

@@ -0,0 +1,307 @@
+import { spawnSync } from 'node:child_process'
+import { dirname } from 'node:path'
+import { bold, error, info, success, warn } from '../output.js'
+import type { ScopeMode } from '../../workspace/affected.js'
+import { resolveAffected } from '../../workspace/affected.js'
+import { findConfig } from '../../core/config/discover.js'
+import { resolveModules, type ResolvedModule } from '../../workspace/discover.js'
+import { shardArg, type Shard } from './shard.js'
+
+export interface TestOptions {
+  cwd: string
+  db?: string | undefined
+  vitestArgs: string[]
+  scope?: ScopeMode | undefined
+  suite?: string | undefined
+  /** `--fast` — run only the fast test tiers (issue #325). */
+  fast?: boolean | undefined
+  reap?: boolean | undefined
+  /** `--shard i/n`: run part i of n disjoint parts of the selected files. */
+  shard?: Shard | undefined
+}
+
+export async function test(options: TestOptions): Promise<void> {
+  const { discoverInstance } = await import('../../core/config/discover.js')
+  const { setupTestDatabases, teardownTestDatabases } = await import('../../test/setup.js')
+
+  process.env['PIPEWORK_ENV'] = 'test'
+  const instance = await discoverInstance(options.cwd)
+
+  if (options.reap === true) {
+    const { reapConfiguredTestDatabases } = await import('../../test/reap.js')
+    info('Reaping orphan test databases...')
+    try {
+      const result = await reapConfiguredTestDatabases(instance)
+      success(`Reaped ${String(result.droppedDatabases.length)} orphan test database(s).`)
+      // #391: a name in the prefix that pipework did not write is left alone. Saying
+      // which ones is the difference between a deliberate skip and a silent one.
+      if (result.skippedDatabases.length > 0) {
+        warn(`Left alone — not created by pipework (${String(result.skippedDatabases.length)}):`)
+        for (const datname of result.skippedDatabases) {
+          warn(`  ${datname}`)
+        }
+      }
+    } finally {
+      await instance.pool.closeAll()
+    }
+    return
+  }
+
+  let emptyBasis = ''
+  const projectArgs = buildProjectArgs(options, instance, (basis) => { emptyBasis = basis })
+  if (projectArgs === null) {
+    const filters = targetedFilters(options.vitestArgs)
+    if (filters.length > 0) {
+      // A named path that did not run must not look like a pass (#337).
+      error(`Nothing ran: no affected module in scope (${emptyBasis}), so ${filters.join(' ')} did not run. Run with --all to test it regardless.`)
+      process.exitCode = 1
+    } else {
+      success('No affected modules — nothing to test')
+    }
+    await instance.pool.closeAll()
+    return
+  }
+
+  // A selection whose every project opts out of the database (`database:
+  // false` on the profile/module/workspace chain) runs without provisioning
+  // one — and without demanding DB env, which config resolution defers to
+  // first URL access for exactly this path.
+  let needsDatabase = projectArgs.needsDatabase
+  if (needsDatabase && options.shard !== undefined && projectArgs.databaseByProject !== undefined) {
+    const specs = await shardSpecifications(options.cwd, options.shard, projectArgs.args, targetedFilters(options.vitestArgs))
+    if (specs !== null) {
+      needsDatabase = shardNeedsDatabase(specs, projectArgs.databaseByProject)
+      const owned = [...new Set(specs.map(spec => spec.project))].sort()
+      info(`Shard ${shardArg(options.shard)} runs ${String(specs.length)} file(s) in ${String(owned.length)} project(s): ${owned.join(', ') || '(none)'}`)
+    }
+  }
+  if (needsDatabase) {
+    info('Setting up test databases...')
+    await setupTestDatabases(instance)
+  } else {
+    info('Selected projects declare no database use — skipping database setup')
+  }
+
+  // Tear down on signals too, not just clean exit: a default SIGINT/SIGTERM
+  // would kill this process before `finally` runs, leaking the per-run
+  // databases. `teardownTestDatabases` is idempotent and the shared promise
+  // makes the signal handler wait for an in-flight teardown before exiting.
+  let cleanup: Promise<void> | null = null
+  const teardownOnce = (): Promise<void> => {
+    cleanup ??= needsDatabase ? teardownTestDatabases().catch(() => {}) : Promise.resolve()
+    return cleanup
+  }
+  process.once('SIGINT', () => { void teardownOnce().finally(() => process.exit(130)) })
+  process.once('SIGTERM', () => { void teardownOnce().finally(() => process.exit(143)) })
+
+  try {
+    const shardArgs = options.shard === undefined ? [] : [`--shard=${shardArg(options.shard)}`]
+    const args = ['vitest', 'run', ...projectArgs.args, ...shardArgs, ...options.vitestArgs]
+    info(`Running: ${bold(args.join(' '))}`)
+
+    const result = spawnSync('npx', args, {
+      cwd: options.cwd,
+      stdio: 'inherit',
+      env: { ...process.env, PIPEWORK_ENV: 'test' },
+    })
+
+    if (result.error !== undefined) {
+      throw new Error(
+        `Failed to spawn vitest: ${result.error.message}\n\n` +
+        `  Ensure vitest is installed as a devDependency.\n` +
+        `  Example: ${bold('pnpm add -D vitest')}\n`,
+      )
+    }
+
+    if (result.status !== 0) {
+      process.exitCode = result.status ?? 1
+    } else {
+      success('Tests completed.')
+    }
+  } finally {
+    if (needsDatabase) {
+      info('Tearing down test databases...')
+    }
+    await teardownOnce()
+    await instance.pool.closeAll()
+  }
+}
+
+/** Path/name filters in vitestArgs: args not starting with `-` and not the value of a preceding `--flag value`. */
+export function targetedFilters(vitestArgs: readonly string[]): string[] {
+  return vitestArgs.filter((arg, i) => {
+    if (arg.startsWith('-')) return false
+    const prev = vitestArgs[i - 1]
+    return !(prev !== undefined && prev.startsWith('-') && !prev.includes('='))
+  })
+}
+
+export interface ProjectSelection {
+  /** `--project` filter args for vitest (empty = run unfiltered). */
+  readonly args: string[]
+  /**
+   * Whether any selected project uses a database, per the `database` flag
+   * chain (profile ?? module ?? workspace ?? true). False lets `test` skip
+   * database setup — and, with URL resolution deferred to first access, skip
+   * demanding DB env entirely.
+   */
+  readonly needsDatabase: boolean
+  /** Per selected project: does it use a database. Absent for unfiltered runs. */
+  readonly databaseByProject?: ReadonlyMap<string, boolean>
+}
+
+export interface ShardSpec {
+  readonly file: string
+  readonly project: string
+}
+
+/**
+ * The (file, project) pairs this shard runs, found with vitest's own file glob
+ * and shard sequencer so the answer is the split the run will make. Null when it
+ * cannot be computed; the caller then assumes every selected project runs.
+ */
+export async function shardSpecifications(
+  cwd: string,
+  shard: Shard,
+  projectArgs: readonly string[],
+  filters: readonly string[],
+): Promise<ShardSpec[] | null> {
+  try {
+    const { createVitest } = await import('vitest/node')
+    const project = projectArgs.filter(arg => arg !== '--project')
+    const ctx = await createVitest('test', { root: cwd, watch: false, project, shard: shardArg(shard) })
+    try {
+      const specs = await ctx.globTestSpecifications([...filters])
+      const Sequencer = ctx.config.sequence.sequencer
+      const mine = await new Sequencer(ctx).shard(specs)
+      return mine.map(spec => ({ file: spec.moduleId, project: spec.project.name }))
+    } finally {
+      await ctx.close()
+    }
+  } catch {
+    return null
+  }
+}
+
+/** Whether any project that has files in the shard uses a database. */
+export function shardNeedsDatabase(
+  specs: readonly ShardSpec[],
+  databaseByProject: ReadonlyMap<string, boolean>,
+): boolean {
+  return specs.some(spec => databaseByProject.get(spec.project) ?? true)
+}
+
+export function buildProjectArgs(
+  options: TestOptions,
+  instance: import('../../core/pipework.js').Manifold,
+  onEmpty?: (basis: string) => void,
+): ProjectSelection | null {
+  const blueprint = instance.config.raw
+  // Unfiltered runs: nothing is known about what executes, so assume it connects.
+  if (blueprint.vitest === undefined) return { args: [], needsDatabase: true }
+
+  const configPath = findConfig(options.cwd)
+  if (configPath === null) return { args: [], needsDatabase: true }
+
+  const configDir = dirname(configPath)
+  const resolved = resolveModules(blueprint.modules, configDir)
+  // No declared modules: single-package repo whose one implicit module is the
+  // repo root, addressed as '.'. Synthesize it so --suite/--scope/profile
+  // selection works — `resolveVitestModules` projects the same '.' module, so
+  // the `--project` names line up.
+  const effectiveModules: ResolvedModule[] = resolved.length === 0
+    ? [{ key: '.', relativePath: '.', config: {} }]
+    : resolved
+
+  const scope = options.scope ?? { kind: 'all' } as ScopeMode
+  const scopeResult = resolveAffected(configDir, effectiveModules, blueprint.name ?? '', scope, blueprint.fastPath?.baseBranches)
+
+  // Population line: what this run's module scope was computed from. Printed
+  // unconditionally so scope-of-invocation is visible next to every verdict.
+  info(`Scope: ${scopeResult.basis}`)
+
+  // No affected modules — nothing to test. Signal the caller to exit 0
+  // gracefully rather than emitting a bogus --project filter that vitest
+  // rejects as a startup error. Mirrors `pipework check`, which degrades the
+  // same way on an empty diff (e.g. a pre-push hook with an empty git index).
+  if (scopeResult.modules.size === 0) {
+    onEmpty?.(scopeResult.basis)
+    return null
+  }
+
+  if (scopeResult.failedOpen === true) {
+    warn('Affected set could not be computed — running all modules (fast path failed open). Issue #325.')
+  }
+
+  const manualProfiles = collectManualProfiles(blueprint.vitest)
+  // --fast: include only the fast test tiers; property/stress are deferred to
+  // the full run. The base (profile-less) project is always kept. Issue #325.
+  const fastTiers = options.fast === true
+    ? new Set(blueprint.fastPath?.test?.tiers ?? ['unit', 'contract', 'isolation'])
+    : null
+  const projectNames: string[] = []
+  const databaseByProject = new Map<string, boolean>()
+  let needsDatabase = false
+
+  // The same flag chain `resolveVitestModules` projects into each vitest
+  // project: profile ?? module ?? workspace ?? true.
+  const workspaceDatabase = blueprint.vitest.database ?? true
+  const usesDatabase = (modulePath: string, profileName?: string): boolean => {
+    const moduleConfig = blueprint.vitest?.modules?.[modulePath]
+    const moduleDatabase = moduleConfig?.database ?? workspaceDatabase
+    if (profileName === undefined) return moduleDatabase
+    return moduleConfig?.profiles?.[profileName]?.database ?? moduleDatabase
+  }
+
+  for (const modulePath of [...scopeResult.modules].sort()) {
+    if (options.suite !== undefined) {
+      projectNames.push(`${modulePath}:${options.suite}`)
+      databaseByProject.set(`${modulePath}:${options.suite}`, usesDatabase(modulePath, options.suite))
+      needsDatabase ||= usesDatabase(modulePath, options.suite)
+    } else {
+      projectNames.push(modulePath)
+      databaseByProject.set(modulePath, usesDatabase(modulePath))
+      needsDatabase ||= usesDatabase(modulePath)
+      const moduleVitestConfig = blueprint.vitest.modules?.[modulePath]
+      if (moduleVitestConfig?.profiles !== undefined) {
+        for (const profileName of Object.keys(moduleVitestConfig.profiles).sort()) {
+          if (fastTiers !== null && !fastTiers.has(profileName)) continue
+          const fullName = `${modulePath}:${profileName}`
+          if (!manualProfiles.has(fullName)) {
+            projectNames.push(fullName)
+            databaseByProject.set(fullName, usesDatabase(modulePath, profileName))
+            needsDatabase ||= usesDatabase(modulePath, profileName)
+          }
+        }
+      }
+    }
+  }
+
+  if (!scopeResult.all) {
+    info(`Scoped to ${String(scopeResult.modules.size)} of ${String(effectiveModules.length)} module(s): ${[...scopeResult.modules].sort().join(', ')}`)
+  }
+
+  const args: string[] = []
+  for (const name of projectNames) {
+    args.push('--project', name)
+  }
+  return { args, needsDatabase, databaseByProject }
+}
+
+function collectManualProfiles(
+  vitestConfig: NonNullable<import('../../core/config/schema.js').Blueprint['vitest']>,
+): Set<string> {
+  const manual = new Set<string>()
+  if (vitestConfig.modules === undefined) return manual
+
+  for (const [modulePath, moduleConfig] of Object.entries(vitestConfig.modules)) {
+    if (moduleConfig.profiles === undefined) continue
+    for (const [profileName, profileConfig] of Object.entries(moduleConfig.profiles)) {
+      if (profileConfig.manual === true) {
+        manual.add(`${modulePath}:${profileName}`)
+      }
+    }
+  }
+
+  return manual
+}

package/src/cli/commands/upgrade.ts

@@ -0,0 +1,48 @@
+import { execSync } from 'node:child_process'
+import { resolve } from 'node:path'
+import { info, success, warn, error, bold } from '../output.js'
+import { install } from './install.js'
+import { findConfigFile } from './shared/find-config.js'
+import { rewriteConfigFileVersion } from './shared/config-pipework-version.js'
+import { detectPipeworkInstall } from '../../workspace/detect-pipework-copies.js'
+
+export async function upgrade(cwd: string, targetVersion: string | undefined): Promise<void> {
+  const version = targetVersion ?? resolveLatestVersion()
+  const root = resolve(cwd)
+
+  info(`Upgrading to pipework@${bold(version)}`)
+
+  // The config's own pipework pin outranks the installed CLI's version: left at the old
+  // version, the next `pipework install` would regenerate package.json there.
+  const configFile = findConfigFile(root)
+  const rewrite = rewriteConfigFileVersion(configFile, version)
+  if (rewrite.kind === 'rewritten') {
+    info(`Set the pipework version in ${configFile} to ${version}`)
+  } else if (rewrite.kind === 'ambiguous') {
+    warn(
+      `${configFile} has ${String(rewrite.count)} pipework version literals; change the one in ` +
+      `dependencies/devDependencies to ${version} yourself, or the next \`pipework install\` regenerates package.json at the old version.`,
+    )
+  }
+
+  await install(root, version)
+
+  const { orphans } = detectPipeworkInstall(root)
+  for (const o of orphans) {
+    warn(`Orphaned pipework ${o.version} at ${o.path}: a stale copy pnpm left in its virtual store; \`pnpm prune\` removes it.`)
+  }
+
+  success(`Upgraded to pipework@${version}`)
+}
+
+function resolveLatestVersion(): string {
+  try {
+    return execSync('npm view pipework version', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim()
+  } catch {
+    error(
+      `Could not resolve latest pipework version from npm.\n\n` +
+      `  Specify a version explicitly: ${bold('pipework upgrade 0.7.5')}\n`,
+    )
+    process.exit(1)
+  }
+}

package/src/cli/dev-bootstrap.ts

@@ -0,0 +1,24 @@
+import { loadEnvFiles } from '../core/config/env.js'
+import { discoverInstance } from '../core/config/discover.js'
+import { parsePort } from './port.js'
+import { parseSurfaceKinds, SURFACE_KINDS_ENV } from './surface-kinds.js'
+
+const cwd = process.env['PIPEWORK_CWD'] ?? process.cwd()
+
+loadEnvFiles(cwd)
+
+const port = parsePort(process.env['PORT'])
+
+const kinds = parseSurfaceKinds(process.env[SURFACE_KINDS_ENV])
+
+const manifold = await discoverInstance(cwd)
+const names = manifold.surfaceNames()
+
+if (names.length > 0) {
+  process.stderr.write(`\n  Starting ${names.length} surface${names.length > 1 ? 's' : ''}...\n\n`)
+}
+
+await manifold.start({
+  ...(port === undefined ? {} : { port }),
+  ...(kinds === undefined ? {} : { kinds }),
+})

package/src/cli/errors.ts

@@ -0,0 +1,10 @@
+import { error } from './output.js'
+
+export function handleError(err: unknown): never {
+  if (err instanceof Error) {
+    error(err.message)
+  } else {
+    error(String(err))
+  }
+  process.exit(1)
+}