pipework 0.252.0 → 0.253.0

package/src/cli/commands/codemod.ts

@@ -0,0 +1,78 @@
+// The `pipework codemod` command. Today it runs one codemod: filling missing
+// `@downstream <kind>` cardinalities (Phase 4a). It uses the same module
+// discovery as `pipework check`, so the codemod's scope matches the corpus
+// the flow / cardinality checks would validate.
+
+import { findSourceFiles } from '../../lint/doctrine.js'
+import { runFlowCardinalityCodemod, type FileResult } from '../../trace/codemod/run.js'
+import { info, success, warn } from '../output.js'
+import { resolveModulePaths } from './check.js'
+
+export interface CodemodOptions {
+  readonly cwd: string
+  readonly dryRun: boolean
+}
+
+export async function codemod(options: CodemodOptions): Promise<void> {
+  const { paths: modulePaths } = await resolveModulePaths(options.cwd, { kind: 'all' })
+  if (modulePaths.length === 0) {
+    success('No source modules — nothing to codemod')
+    return
+  }
+
+  const files = findSourceFiles(options.cwd, modulePaths)
+  if (files.length === 0) {
+    success('No TypeScript sources — nothing to codemod')
+    return
+  }
+
+  info(options.dryRun ? 'Cardinality codemod (dry run)' : 'Cardinality codemod')
+
+  const result = runFlowCardinalityCodemod({
+    cwd: options.cwd,
+    files,
+    dryRun: options.dryRun,
+  })
+
+  reportFills(result.files)
+  reportUnresolved(result.files)
+
+  const verb = options.dryRun ? 'would update' : 'updated'
+  if (result.totalFills > 0) {
+    success(
+      `Cardinality codemod (${verb} ${String(result.filesChanged)} `
+      + `file${result.filesChanged === 1 ? '' : 's'}, `
+      + `${String(result.totalFills)} edge${result.totalFills === 1 ? '' : 's'} filled)`,
+    )
+  } else {
+    success('Cardinality codemod (no fillable edges)')
+  }
+
+  if (result.totalUnresolved > 0) {
+    warn(
+      `Cardinality codemod: ${String(result.totalUnresolved)} edge`
+      + `${result.totalUnresolved === 1 ? '' : 's'} need human attention `
+      + `(see "unresolved" output above)`,
+    )
+  }
+}
+
+function reportFills(files: readonly FileResult[]): void {
+  for (const fr of files) {
+    if (fr.fills.length === 0) continue
+    info(`  ${fr.file} (${String(fr.fills.length)} filled)`)
+    for (const fill of fr.fills) {
+      info(`    ${String(fill.line)}: @downstream ${fill.target} ${fill.kind}`)
+    }
+  }
+}
+
+function reportUnresolved(files: readonly FileResult[]): void {
+  for (const fr of files) {
+    if (fr.unresolved.length === 0) continue
+    warn(`  ${fr.file} (${String(fr.unresolved.length)} unresolved)`)
+    for (const u of fr.unresolved) {
+      warn(`    ${String(u.line)}: @downstream ${u.target} — ${u.reason}`)
+    }
+  }
+}

package/src/cli/commands/db.ts

@@ -0,0 +1,356 @@
+import { randomBytes } from 'node:crypto'
+import { resolve, join } from 'node:path'
+import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { bold, info, success, error as logError, warn } from '../output.js'
+import { loadConfig } from './shared/load-config.js'
+import type { Blueprint, DatabaseConfig } from '../../core/config/schema.js'
+
+export interface DbOptions {
+  readonly cwd: string
+  readonly subcommand: string | undefined
+  readonly db?: string | undefined
+  readonly test?: boolean | undefined
+  readonly confirm?: boolean | undefined
+  readonly adminUrl?: string | undefined
+}
+
+export async function db(opts: DbOptions): Promise<void> {
+  switch (opts.subcommand) {
+    case 'setup':
+      await setup(opts)
+      break
+    case 'teardown':
+      await teardown(opts)
+      break
+    case 'reset':
+      await teardown(opts)
+      await setup(opts)
+      break
+    default: {
+      const sub = opts.subcommand ?? '(none)'
+      logError('Unknown db subcommand: ' + sub)
+      process.stderr.write('\n  Usage: ' + bold('pipework db <setup|teardown|reset>') + '\n\n')
+      process.stderr.write('  setup              Create databases, roles, extensions, run migrations\n')
+      process.stderr.write('  setup --test       Create test database with isolated credentials\n')
+      process.stderr.write('  teardown           Drop databases and roles\n')
+      process.stderr.write('  reset              Teardown + setup\n\n')
+      process.exit(1)
+    }
+  }
+}
+
+async function setup(opts: DbOptions): Promise<void> {
+  {
+    const { config } = await loadConfig(resolve(opts.cwd))
+    const databases = filterDatabases(config, opts.db)
+
+    for (const [name, dbConfig] of databases) {
+      info('Setting up database: ' + name)
+
+      const adminUrl = resolveAdminUrl(opts, dbConfig)
+      if (adminUrl === null) {
+        const envName = dbConfig.adminUrl ?? 'ADMIN_DATABASE_URL'
+        logError('No admin URL for database "' + name + '". Set ' + envName + ' or pass --admin-url.')
+        process.exit(1)
+      }
+
+      const isTest = opts.test === true
+      const dbName = isTest ? name + '_test' : name
+      const ownerRole = name + '_owner'
+      const runtimeRole = name + '_app'
+      const ownerPassword = randomBytes(16).toString('hex')
+      const runtimePassword = randomBytes(16).toString('hex')
+      const ownerUrl = buildConnectionUrl(adminUrl, dbName, ownerRole, ownerPassword)
+      const runtimeUrl = buildConnectionUrl(adminUrl, dbName, runtimeRole, runtimePassword)
+      const ownerEnvVar = isTest ? dbConfig.testUrl : dbConfig.url
+      const runtimeEnvVar = isTest ? dbConfig.appTestUrl : dbConfig.appUrl
+      // Platform mode: the platform role is named in config (generated policies
+      // name it), created here like the runtime role, and written to systemUrl.
+      const platformRole = dbConfig.rls?.platformRole
+      const platformPassword = randomBytes(16).toString('hex')
+      const platformUrl = platformRole !== undefined ? buildConnectionUrl(adminUrl, dbName, platformRole, platformPassword) : undefined
+      const platformEnvVar = isTest ? dbConfig.systemTestUrl : dbConfig.systemUrl
+
+      let adminClient: AdminClient | null = null
+      try {
+        adminClient = await connectAdmin(adminUrl)
+
+        await ensureRole(adminClient, ownerRole, ownerPassword, { bypassRls: true })
+        await ensureRole(adminClient, runtimeRole, runtimePassword, { bypassRls: false })
+        if (platformRole !== undefined) await ensureRole(adminClient, platformRole, platformPassword, { bypassRls: false })
+        await ensureDatabase(adminClient, dbName, ownerRole)
+        await grantConnect(adminClient, dbName, runtimeRole)
+        if (platformRole !== undefined) await grantConnect(adminClient, dbName, platformRole)
+
+        // Extensions and the runtime grants run as the owner so the database
+        // objects (and the owner-scoped default privileges) belong to the owner.
+        const ownerClient = await connectAdmin(ownerUrl)
+        try {
+          if (dbConfig.extensions !== undefined) {
+            for (const ext of dbConfig.extensions) {
+              await ensureExtension(ownerClient, ext)
+            }
+          }
+          for (const stmt of buildRuntimeGrants('public', ownerRole, runtimeRole)) {
+            await ownerClient.query(stmt)
+          }
+          // The platform role gets the runtime role's privileges; which rows it
+          // sees is the policies' business (a door, or none).
+          if (platformRole !== undefined) {
+            for (const stmt of buildRuntimeGrants('public', ownerRole, platformRole)) {
+              await ownerClient.query(stmt)
+            }
+          }
+        } finally {
+          await ownerClient.close()
+        }
+        info('Granted runtime DML to role: ' + runtimeRole)
+        if (platformRole !== undefined) info('Granted runtime DML to platform role: ' + platformRole)
+
+        success('Database "' + dbName + '" ready (owner: ' + ownerRole + ', runtime: ' + runtimeRole + ')')
+
+        if (ownerEnvVar !== undefined) {
+          writeEnvVar(opts.cwd, ownerEnvVar, ownerUrl)
+          success('Wrote ' + ownerEnvVar + ' to .env')
+        }
+        if (runtimeEnvVar !== undefined) {
+          writeEnvVar(opts.cwd, runtimeEnvVar, runtimeUrl)
+          success('Wrote ' + runtimeEnvVar + ' to .env')
+        }
+        if (platformUrl !== undefined && platformEnvVar !== undefined) {
+          writeEnvVar(opts.cwd, platformEnvVar, platformUrl)
+          success('Wrote ' + platformEnvVar + ' to .env')
+        }
+        if (runtimeEnvVar === undefined) {
+          warn('No appUrl configured for "' + name + '" — runtime would fall back to the owner connection and RLS would be inert. Set appUrl/appTestUrl in the database config to enable role separation.')
+        }
+      } catch (err) {
+        logError('Failed to setup "' + name + '": ' + (err instanceof Error ? err.message : String(err)))
+        process.exit(1)
+      } finally {
+        if (adminClient !== null) {
+          await adminClient.close()
+        }
+      }
+    }
+
+    success('Database setup complete')
+  }
+}
+
+async function teardown(opts: DbOptions): Promise<void> {
+  {
+    const { config } = await loadConfig(resolve(opts.cwd))
+    const databases = filterDatabases(config, opts.db)
+
+    if (config.environment === 'production' && opts.confirm !== true) {
+      logError('Teardown in production requires --confirm flag.')
+      process.exit(1)
+    }
+
+    for (const [name, dbConfig] of databases) {
+      const adminUrl = resolveAdminUrl(opts, dbConfig)
+      if (adminUrl === null) {
+        warn('No admin URL for database "' + name + '" — skipping teardown')
+        continue
+      }
+
+      let adminClient: AdminClient | null = null
+      try {
+        adminClient = await connectAdmin(adminUrl)
+
+        const dbName = name
+        const testDbName = name + '_test'
+        const ownerRole = name + '_owner'
+        const runtimeRole = name + '_app'
+
+        // Databases first: dropping them removes the in-database grants and
+        // owner-scoped default privileges, so the roles drop cleanly afterwards.
+        await dropDatabaseIfExists(adminClient, testDbName)
+        await dropDatabaseIfExists(adminClient, dbName)
+        await dropRoleIfExists(adminClient, runtimeRole)
+        if (dbConfig.rls?.platformRole !== undefined) await dropRoleIfExists(adminClient, dbConfig.rls.platformRole)
+        await dropRoleIfExists(adminClient, ownerRole)
+
+        success('Torn down: ' + name)
+      } catch (err) {
+        logError('Failed to teardown "' + name + '": ' + (err instanceof Error ? err.message : String(err)))
+      } finally {
+        if (adminClient !== null) {
+          await adminClient.close()
+        }
+      }
+    }
+
+    success('Database teardown complete')
+  }
+}
+
+function filterDatabases(config: Blueprint, dbFilter?: string): Array<[string, DatabaseConfig]> {
+  const entries = Object.entries(config.databases)
+  if (dbFilter !== undefined) {
+    const filtered = entries.filter(([name]) => name === dbFilter)
+    if (filtered.length === 0) {
+      logError('Database "' + dbFilter + '" not found in config. Available: ' + entries.map(([n]) => n).join(', '))
+      process.exit(1)
+    }
+    return filtered
+  }
+  return entries
+}
+
+function resolveAdminUrl(opts: DbOptions, dbConfig: DatabaseConfig): string | null {
+  if (opts.adminUrl !== undefined) return opts.adminUrl
+  if (dbConfig.adminUrl !== undefined) {
+    const fromEnv = process.env[dbConfig.adminUrl]
+    if (fromEnv !== undefined && fromEnv !== '') return fromEnv
+  }
+  const fallback = process.env['ADMIN_DATABASE_URL']
+  if (fallback !== undefined && fallback !== '') return fallback
+  return null
+}
+
+function buildConnectionUrl(adminUrl: string, dbName: string, role: string, password: string): string {
+  try {
+    const url = new URL(adminUrl)
+    url.username = role
+    url.password = password
+    url.pathname = '/' + dbName
+    return url.toString()
+  } catch {
+    const match = adminUrl.match(/^postgresql:\/\/([^@]+@)?([^/]+)/)
+    if (match !== null) {
+      return 'postgresql://' + role + ':' + password + '@' + String(match[2]) + '/' + dbName
+    }
+    return 'postgresql://' + role + ':' + password + '@localhost:5432/' + dbName
+  }
+}
+
+interface AdminClient {
+  query(sql: string, params?: unknown[]): Promise<unknown[]>
+  close(): Promise<void>
+}
+
+async function connectAdmin(url: string): Promise<AdminClient> {
+  const { default: postgres } = await import('postgres')
+  const client = postgres(url, { max: 1, onnotice: () => {} })
+  return {
+    async query(sqlStr: string, params?: unknown[]) {
+      if (params !== undefined && params.length > 0) {
+        return client.unsafe(sqlStr, params as never[])
+      }
+      return client.unsafe(sqlStr)
+    },
+    async close() {
+      await client.end()
+    },
+  }
+}
+
+interface RoleAttributes {
+  /** Owner roles carry BYPASSRLS so migrations/bootstrap span tenants regardless of FORCE; runtime roles must not, or RLS is inert. */
+  readonly bypassRls: boolean
+}
+
+// Both roles are LOGIN, non-superuser, and cannot create databases or roles.
+// The single discriminator is BYPASSRLS: the owner has it (DDL/bootstrap reads
+// and writes across every tenant), the non-owner runtime role explicitly does
+// not, so generated RLS policies actually bind to it.
+function roleAttributeClause(attrs: RoleAttributes): string {
+  return 'NOSUPERUSER NOCREATEDB NOCREATEROLE ' + (attrs.bypassRls ? 'BYPASSRLS' : 'NOBYPASSRLS')
+}
+
+async function ensureRole(client: AdminClient, name: string, password: string, attrs: RoleAttributes): Promise<void> {
+  const clause = roleAttributeClause(attrs)
+  const rows = await client.query('SELECT 1 FROM pg_roles WHERE rolname = $1', [name]) as unknown[]
+  if (rows.length === 0) {
+    await client.query('CREATE ROLE ' + quoteIdent(name) + ' WITH LOGIN PASSWORD \'' + escapePassword(password) + '\' ' + clause)
+    info('Created role: ' + name)
+  } else {
+    await client.query('ALTER ROLE ' + quoteIdent(name) + ' WITH LOGIN PASSWORD \'' + escapePassword(password) + '\' ' + clause)
+    info('Updated role: ' + name)
+  }
+}
+
+async function grantConnect(client: AdminClient, dbName: string, role: string): Promise<void> {
+  await client.query('GRANT CONNECT ON DATABASE ' + quoteIdent(dbName) + ' TO ' + quoteIdent(role))
+}
+
+/**
+ * The DML grants for the non-owner runtime role, applied at provision time on a
+ * connection authenticated as the owner. The two ALTER DEFAULT PRIVILEGES lines
+ * are the drift guard: every future table the owner creates via migrations is
+ * granted to the runtime role automatically, so an RLS-enabled table can never
+ * be left ungranted — which would blank the rows the app is entitled to.
+ */
+export function buildRuntimeGrants(schema: string, ownerRole: string, runtimeRole: string): string[] {
+  const s = quoteIdent(schema)
+  const owner = quoteIdent(ownerRole)
+  const runtime = quoteIdent(runtimeRole)
+  return [
+    'GRANT USAGE ON SCHEMA ' + s + ' TO ' + runtime,
+    'GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA ' + s + ' TO ' + runtime,
+    'GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA ' + s + ' TO ' + runtime,
+    'ALTER DEFAULT PRIVILEGES FOR ROLE ' + owner + ' IN SCHEMA ' + s + ' GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ' + runtime,
+    'ALTER DEFAULT PRIVILEGES FOR ROLE ' + owner + ' IN SCHEMA ' + s + ' GRANT USAGE, SELECT ON SEQUENCES TO ' + runtime,
+  ]
+}
+
+
+async function ensureDatabase(client: AdminClient, dbName: string, owner: string): Promise<void> {
+  const rows = await client.query('SELECT 1 FROM pg_database WHERE datname = $1', [dbName]) as unknown[]
+  if (rows.length === 0) {
+    await client.query('CREATE DATABASE ' + quoteIdent(dbName) + ' OWNER ' + quoteIdent(owner))
+    info('Created database: ' + dbName)
+  } else {
+    info('Database "' + dbName + '" already exists')
+  }
+}
+
+async function ensureExtension(client: AdminClient, ext: string): Promise<void> {
+  await client.query('CREATE EXTENSION IF NOT EXISTS ' + quoteIdent(ext))
+  info('Extension: ' + ext)
+}
+
+async function dropDatabaseIfExists(client: AdminClient, dbName: string): Promise<void> {
+  const rows = await client.query('SELECT 1 FROM pg_database WHERE datname = $1', [dbName]) as unknown[]
+  if (rows.length > 0) {
+    await client.query('DROP DATABASE ' + quoteIdent(dbName))
+    info('Dropped database: ' + dbName)
+  }
+}
+
+async function dropRoleIfExists(client: AdminClient, name: string): Promise<void> {
+  const rows = await client.query('SELECT 1 FROM pg_roles WHERE rolname = $1', [name]) as unknown[]
+  if (rows.length > 0) {
+    await client.query('DROP ROLE ' + quoteIdent(name))
+    info('Dropped role: ' + name)
+  }
+}
+
+function quoteIdent(name: string): string {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+    throw new Error('[pipework] Invalid identifier: "' + name + '"')
+  }
+  return '"' + name + '"'
+}
+
+function escapePassword(password: string): string {
+  return password.replace(/'/g, "''")
+}
+
+function writeEnvVar(cwd: string, key: string, value: string): void {
+  const envPath = join(cwd, '.env')
+  let content = ''
+  if (existsSync(envPath)) {
+    content = readFileSync(envPath, 'utf-8')
+    const pattern = new RegExp('^' + key + '=.*$', 'm')
+    if (pattern.test(content)) {
+      content = content.replace(pattern, key + '=' + value)
+      writeFileSync(envPath, content, 'utf-8')
+      return
+    }
+  }
+  const newLine = content.length > 0 && !content.endsWith('\n') ? '\n' : ''
+  writeFileSync(envPath, content + newLine + key + '=' + value + '\n', 'utf-8')
+}

package/src/cli/commands/dev.ts

@@ -0,0 +1,101 @@
+import { spawn } from 'node:child_process'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { info, bold, cyan, yellow } from '../output.js'
+
+export interface DevOptions {
+  port: string | undefined
+  cwd: string
+  entry: string | undefined
+}
+
+export function dev(options: DevOptions): void {
+  if (options.entry !== undefined) {
+    startLegacy(options)
+    return
+  }
+
+  startSurfaceAware(options)
+}
+
+// dev.js compiles to dist/cli/commands/dev.js. The TS loader and the dev
+// bootstrap are sibling build outputs, NOT source files — once pipework is
+// installed they live under node_modules. Both must be resolved as the
+// compiled `.js`: the loader source is src/core/config/ts-register.ts →
+// dist/core/config/ts-register.js (two levels up to dist, then core/config),
+// and the bootstrap is src/cli/dev-bootstrap.ts → dist/cli/dev-bootstrap.js
+// (one level up to dist/cli). Referencing the bootstrap as `.ts` only works in
+// pipework's own repo (source not under node_modules) and is doubly broken
+// once installed: the `.ts` isn't shipped, and Node refuses to strip types for
+// any file under node_modules.
+export function resolveRegisterPath(cliDir: string): string {
+  return resolve(cliDir, '..', '..', 'core', 'config', 'ts-register.js')
+}
+
+export function resolveBootstrapPath(cliDir: string): string {
+  return resolve(cliDir, '..', 'dev-bootstrap.js')
+}
+
+
+function startSurfaceAware(options: DevOptions): void {
+  {
+    const cliDir = dirname(fileURLToPath(import.meta.url))
+    const bootstrapPath = resolveBootstrapPath(cliDir)
+    const registerPath = resolveRegisterPath(cliDir)
+
+    const env: Record<string, string | undefined> = { ...process.env, 'PIPEWORK_CWD': options.cwd }
+    if (options.port !== undefined) {
+      env['PORT'] = options.port
+    }
+
+    printBanner()
+
+    const args = ['--watch', '--import', registerPath, bootstrapPath]
+
+    const child = spawn('node', args, {
+      cwd: options.cwd,
+      stdio: 'inherit',
+      env,
+    })
+
+    child.on('exit', (code, signal) => {
+      if (signal === 'SIGTERM' || signal === 'SIGINT') {
+        process.exit(0)
+      }
+      process.exit(code ?? 0)
+    })
+
+    process.on('SIGTERM', () => child.kill('SIGTERM'))
+    process.on('SIGINT', () => child.kill('SIGINT'))
+  }
+}
+
+function startLegacy(options: DevOptions): void {
+  {
+    const cliDir = dirname(fileURLToPath(import.meta.url))
+    const registerPath = resolveRegisterPath(cliDir)
+    const entry = options.entry ?? 'src/server.ts'
+    const args = ['--watch', '--import', registerPath, entry]
+
+    if (options.port !== undefined) {
+      process.env['PORT'] = options.port
+    }
+
+    info(`Starting dev server: node ${args.join(' ')}`)
+
+    const child = spawn('node', args, {
+      cwd: options.cwd,
+      stdio: 'inherit',
+      env: process.env,
+    })
+
+    child.on('exit', (code) => {
+      process.exit(code ?? 0)
+    })
+  }
+}
+
+function printBanner(): void {
+  process.stderr.write(`\n  ${bold(cyan('pipework dev'))}\n`)
+  process.stderr.write(`  ${yellow('watching for changes...')}\n\n`)
+}

package/src/cli/commands/generate.ts

@@ -0,0 +1,75 @@
+import type { ResolvedConfig, ResolvedDoor } from '../../core/config/load.js'
+import { queueFrameworkDoors } from '../../async/jobs/queue-door.js'
+import { info, success, warn, error as logError } from '../output.js'
+
+export interface GenerateCommandOptions {
+  db: string | undefined
+  name: string | undefined
+  cwd: string
+}
+
+/** Evaluated after the schema files load: queue tables register when a worker surface or graph is constructed. */
+function doorsOf(config: ResolvedConfig, database: string): () => ResolvedDoor[] {
+  return () => [...Object.values(config.doors), ...Object.values(config.frameworkDoors), ...Object.values(queueFrameworkDoors(config))]
+    .filter(door => door.database === database)
+}
+
+export async function generate(options: GenerateCommandOptions): Promise<void> {
+  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')
+
+  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}`)
+      // 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.name, internal, doorsOf(instance.config, dbConfig.name))
+      if (result.migrationFile === null) {
+        warn(`${options.db}: no schema changes detected`)
+      } else {
+        success(`${options.db}: generated ${result.migrationFile}`)
+      }
+    } else {
+      info('Generating migrations for all databases...')
+      let generated = 0
+      for (const [, dbConfig] of instance.config.databases()) {
+        if (dbConfig.schema === undefined) continue
+        const internal = () => loadInternalDefinitions(instance.config.raw, {
+          isDefaultDatabase: dbConfig.name === defaultDbName,
+        })
+        const result = await generateForDatabase(dbConfig, options.name, internal, doorsOf(instance.config, dbConfig.name))
+        if (result.migrationFile === null) {
+          warn(`${dbConfig.name}: no schema changes detected`)
+        } else {
+          success(`${dbConfig.name}: generated ${result.migrationFile}`)
+          generated++
+        }
+      }
+      if (generated === 0) {
+        warn('No schema changes detected in any database.')
+      }
+    }
+  } finally {
+    await instance.pool.closeAll()
+  }
+}

package/src/cli/commands/init.ts

@@ -0,0 +1,36 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { success, warn } from '../output.js'
+
+const CONFIG_TEMPLATE = `import { createManifold } from 'pipework'
+
+export default createManifold({
+  databases: {
+    app: {
+      url: 'DATABASE_URL',
+      testUrl: 'DATABASE_URL_TEST',
+      schema: './src/db/schema.ts',
+      migrations: './migrations/app',
+    },
+  },
+})
+`
+
+export function init(cwd: string): void {
+  const configPath = join(cwd, 'pipework.config.ts')
+  const migrationsPath = join(cwd, 'migrations', 'app')
+
+  if (existsSync(configPath)) {
+    warn('pipework.config.ts already exists — skipping')
+  } else {
+    writeFileSync(configPath, CONFIG_TEMPLATE, 'utf-8')
+    success('Created pipework.config.ts')
+  }
+
+  if (!existsSync(migrationsPath)) {
+    mkdirSync(migrationsPath, { recursive: true })
+    success(`Created ${migrationsPath}`)
+  } else {
+    warn(`${migrationsPath} already exists — skipping`)
+  }
+}

package/src/cli/commands/install.ts

@@ -0,0 +1,28 @@
+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 { runPnpmInstall } from './shared/pnpm-install.js'
+import { info, success, error } from '../output.js'
+
+export async function install(cwd: string, pipeworkVersion?: string): Promise<void> {
+  const resolved = resolve(cwd)
+  const { config, appName } = await loadConfig(resolved)
+
+  info('Syncing workspace...')
+  const syncInput = { config, cwd: resolved, appName }
+  const result = syncWorkspace(
+    pipeworkVersion !== undefined ? { ...syncInput, pipeworkVersion } : syncInput,
+  )
+
+  success(`Generated ${String(result.files.length)} file(s).`)
+  reportRemoved(result)
+
+  info('Running pnpm install...')
+  const outcome = runPnpmInstall({ cwd: resolved, requiredPipeworkVersion: result.pipeworkVersion })
+  if (!outcome.ok) {
+    error(outcome.message)
+    process.exit(1)
+  }
+  success(`Install complete — pipework@${outcome.installedPipeworkVersion} in node_modules.`)
+}