@sqldoc/cli 0.0.1

package/src/commands/schema.ts

@@ -0,0 +1,329 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import type { AtlasResult } from '@sqldoc/atlas'
+import { createRunner } from '@sqldoc/atlas'
+import type { ResolvedConfig } from '@sqldoc/core'
+import { loadConfig, resolveProject } from '@sqldoc/core'
+import pc from 'picocolors'
+import { CliError } from '../errors.ts'
+import { runCompilePipeline } from '../utils/pipeline.ts'
+import { printChanges } from '../utils/pretty-changes.ts'
+
+type Format = 'sql' | 'json' | 'pretty'
+
+// ── Source resolution ────────────────────────────────────────────────
+
+interface ResolvedSource {
+  type: 'file' | 'directory' | 'database'
+  /** For database: connection URL. For file/directory: merged compiled SQL */
+  value: string
+  /** Atlas realm from the pipeline (reuse instead of re-inspecting) */
+  atlasRealm?: unknown
+}
+
+async function resolveSource(source: string, config: ResolvedConfig, configRoot: string): Promise<ResolvedSource> {
+  if (
+    source.startsWith('postgres://') ||
+    source.startsWith('postgresql://') ||
+    source.startsWith('mysql://') ||
+    source.startsWith('sqlite://')
+  ) {
+    return { type: 'database', value: source }
+  }
+
+  const resolved = path.resolve(source)
+  const result = await runCompilePipeline(resolved, config, configRoot)
+  if (result.totalErrors > 0) {
+    throw new Error(`${result.totalErrors} compilation error(s)`)
+  }
+
+  return {
+    type: fs.statSync(resolved).isDirectory() ? 'directory' : 'file',
+    value: result.mergedSql,
+    atlasRealm: result.atlasRealm,
+  }
+}
+
+// ── schema inspect ───────────────────────────────────────────────────
+
+export async function schemaInspectCommand(
+  source: string | undefined,
+  options: { config?: string; format?: string; devUrl?: string; project?: string },
+): Promise<void> {
+  const configRoot = options.config
+    ? path.dirname(path.resolve(options.config))
+    : process.env.SQLDOC_PROJECT_ROOT || process.cwd()
+  const { config: rawConfig } = await loadConfig(configRoot, options.config)
+  const config = resolveProject(rawConfig, options.project)
+  if (options.devUrl) config.devUrl = options.devUrl
+
+  // Resolve source: explicit arg > config.schema > error
+  const resolvedSource = source ?? config.schema
+  if (!resolvedSource) {
+    throw new CliError('No source provided. Specify a path argument or set "schema" in sqldoc.config.ts')
+  }
+  const dialect = (config.dialect ?? 'postgres') as 'postgres' | 'mysql' | 'sqlite'
+  const format = (options.format ?? 'sql') as Format
+
+  try {
+    const resolved = await resolveSource(resolvedSource, config, configRoot)
+
+    if (resolved.type === 'database') {
+      // Live database — inspect directly, no compilation needed
+      const runner = await createRunner({ dialect, devUrl: resolved.value })
+      try {
+        const result = await runner.inspect([], {
+          schema: dialect === 'postgres' ? 'public' : undefined,
+          dialect,
+        })
+        if (result.error) {
+          throw new CliError(`Inspect error: ${result.error}`)
+        }
+        outputInspect(result, format)
+      } finally {
+        await runner.close()
+      }
+    } else if (resolved.atlasRealm) {
+      // Pipeline already inspected — reuse the realm
+      outputInspect({ schema: resolved.atlasRealm } as AtlasResult, format)
+    } else {
+      throw new CliError('No schema available')
+    }
+  } catch (err: any) {
+    if (err instanceof CliError) throw err
+    throw new CliError(friendlyError(err, config))
+  }
+}
+
+function outputInspect(result: AtlasResult, format: Format): void {
+  if (format === 'json') {
+    console.log(JSON.stringify(result.schema, null, 2))
+  } else {
+    if (result.statements?.length) {
+      console.log(`${result.statements.join(';\n')};`)
+    } else if (result.schema) {
+      console.log(JSON.stringify(result.schema, null, 2))
+    }
+  }
+}
+
+// ── schema diff ──────────────────────────────────────────────────────
+
+export async function schemaDiffCommand(options: {
+  config?: string
+  from?: string
+  to?: string
+  format?: string
+  devUrl?: string
+  check?: boolean
+  project?: string
+}): Promise<void> {
+  const configRoot = options.config
+    ? path.dirname(path.resolve(options.config))
+    : process.env.SQLDOC_PROJECT_ROOT || process.cwd()
+  const { config: rawConfig } = await loadConfig(configRoot, options.config)
+  const config = resolveProject(rawConfig, options.project)
+  if (options.devUrl) config.devUrl = options.devUrl
+  const dialect = (config.dialect ?? 'postgres') as 'postgres' | 'mysql' | 'sqlite'
+  const format = (options.format ?? 'sql') as Format
+
+  // Default --to to config.schema, --from to config.migrations.dir when both omitted
+  let toSource = options.to
+  let fromSource = options.from
+
+  if (!toSource && !fromSource && config.schema && config.migrations?.dir) {
+    // Smart default: diff migrations -> schema
+    fromSource = path.resolve(configRoot, config.migrations.dir)
+    toSource = config.schema
+  } else {
+    toSource = toSource ?? config.schema
+  }
+
+  if (!toSource) {
+    throw new CliError('--to is required. Usage: sqldoc schema diff --to <source> [--from <source>]')
+  }
+
+  try {
+    const toResolved = await resolveSource(toSource, config, configRoot)
+    const fromResolved = fromSource
+      ? await resolveSource(fromSource, config, configRoot)
+      : { type: 'file' as const, value: '' } // empty = no existing schema
+
+    const fromSql: string[] = fromResolved.type === 'database' ? [] : [fromResolved.value]
+    const toSql: string[] = toResolved.type === 'database' ? [] : [toResolved.value]
+
+    if (fromResolved.type === 'database' || toResolved.type === 'database') {
+      await diffWithLiveDb(fromResolved, toResolved, config, dialect, format, options.check ?? false)
+      return
+    }
+
+    // Pass both from + to SQL so extensions are detected and loaded
+    const allSql = [...fromSql, ...toSql].filter(Boolean)
+    const runner = await createRunner({ dialect, devUrl: config.devUrl, sqlFiles: allSql })
+    try {
+      const result = await runner.diff(fromSql, toSql, {
+        schema: dialect === 'postgres' ? 'public' : undefined,
+        dialect,
+      })
+      outputDiff(result, format, options.check ?? false)
+    } finally {
+      await runner.close()
+    }
+  } catch (err: any) {
+    if (err instanceof CliError) throw err
+    throw new CliError(friendlyError(err, config))
+  }
+}
+
+async function diffWithLiveDb(
+  from: ResolvedSource,
+  to: ResolvedSource,
+  config: ResolvedConfig,
+  dialect: 'postgres' | 'mysql' | 'sqlite',
+  format: Format,
+  check: boolean,
+): Promise<void> {
+  const schemaOpt = dialect === 'postgres' ? 'public' : undefined
+
+  const liveSource = from.type === 'database' ? from : to
+  const sqlSource = from.type === 'database' ? to : from
+
+  const liveRunner = await createRunner({ dialect, devUrl: liveSource.value })
+  let liveRealm
+  try {
+    const liveResult = await liveRunner.inspect([], { schema: schemaOpt, dialect })
+    if (liveResult.error) throw new Error(`Live DB inspect: ${liveResult.error}`)
+    liveRealm = liveResult.schema
+  } finally {
+    await liveRunner.close()
+  }
+
+  const devRunner = await createRunner({ dialect, devUrl: config.devUrl, sqlFiles: [sqlSource.value] })
+  let sqlRealm
+  try {
+    const sqlResult = await devRunner.inspect([sqlSource.value], { schema: schemaOpt, dialect })
+    if (sqlResult.error) throw new Error(`SQL inspect: ${sqlResult.error}`)
+    sqlRealm = sqlResult.schema
+  } finally {
+    await devRunner.close()
+  }
+
+  const diffRunner = await createRunner({
+    dialect,
+    devUrl: config.devUrl,
+    sqlFiles: [...(from.type !== 'database' ? [from.value] : []), ...(to.type !== 'database' ? [to.value] : [])],
+  })
+  try {
+    const fromSql = from.type === 'database' ? [] : [from.value]
+    const toSql = to.type === 'database' ? [] : [to.value]
+
+    if (from.type === 'database' && to.type !== 'database') {
+      if (format === 'json') {
+        console.log(JSON.stringify({ from: liveRealm, to: sqlRealm }, null, 2))
+        return
+      } else if (format === 'pretty') {
+        prettyCompareRealms(liveRealm, sqlRealm, check)
+        return
+      }
+    }
+    const result = await diffRunner.diff(fromSql, toSql, { schema: schemaOpt, dialect })
+    outputDiff(result, format, check)
+  } finally {
+    await diffRunner.close()
+  }
+}
+
+function outputDiff(result: AtlasResult, format: Format, check: boolean): void {
+  if (result.error) {
+    throw new CliError(`Diff error: ${result.error}`)
+  }
+
+  const stmts = result.statements ?? []
+
+  if (stmts.length === 0) {
+    if (format === 'pretty' || check) {
+      console.error(pc.green('Schemas are identical. No changes detected.'))
+    }
+    return
+  }
+
+  switch (format) {
+    case 'sql':
+      for (const stmt of stmts) {
+        console.log(`${stmt};`)
+      }
+      break
+    case 'json':
+      console.log(JSON.stringify({ statements: stmts }, null, 2))
+      break
+    case 'pretty':
+      if (result.changes && result.changes.length > 0) {
+        const header = check ? pc.red(pc.bold('Schema drift detected!')) : pc.yellow(pc.bold('Schema differences:'))
+        printChanges(result.changes, header)
+        console.error(`  ${stmts.length} statement(s)`)
+      } else {
+        prettyDiff(stmts, check)
+      }
+      break
+  }
+
+  if (check) {
+    throw new CliError('Schema drift detected')
+  }
+}
+
+function prettyDiff(statements: string[], check: boolean): void {
+  const header = check ? pc.red(pc.bold('Schema drift detected!')) : pc.yellow(pc.bold('Schema differences:'))
+  console.error(header)
+  console.error('')
+
+  for (const stmt of statements) {
+    const upper = stmt.trimStart().toUpperCase()
+    if (upper.startsWith('CREATE')) {
+      console.error(pc.green(`  + ${stmt}`))
+    } else if (upper.startsWith('DROP')) {
+      console.error(pc.red(`  - ${stmt}`))
+    } else if (upper.startsWith('ALTER')) {
+      if (upper.includes('ADD')) {
+        console.error(pc.green(`  ~ ${stmt}`))
+      } else if (upper.includes('DROP')) {
+        console.error(pc.red(`  ~ ${stmt}`))
+      } else {
+        console.error(pc.yellow(`  ~ ${stmt}`))
+      }
+    } else {
+      console.error(`  ${stmt}`)
+    }
+  }
+
+  console.error('')
+  console.error(`  ${statements.length} statement(s)`)
+}
+
+function prettyCompareRealms(from: any, to: any, check: boolean): void {
+  const fromTables = new Set((from?.schemas?.[0]?.tables ?? []).map((t: any) => t.name))
+  const toTables = new Set((to?.schemas?.[0]?.tables ?? []).map((t: any) => t.name))
+
+  const stmts: string[] = []
+  for (const name of toTables) {
+    if (!fromTables.has(name)) stmts.push(`CREATE TABLE ${name} (new)`)
+  }
+  for (const name of fromTables) {
+    if (!toTables.has(name)) stmts.push(`DROP TABLE ${name}`)
+  }
+
+  if (stmts.length === 0) {
+    console.error(pc.green('Schemas are identical. No changes detected.'))
+    return
+  }
+
+  prettyDiff(stmts, check)
+  if (check) throw new CliError('Schema drift detected')
+}
+
+function friendlyError(err: any, config: ResolvedConfig): string {
+  if (err?.code === 'ECONNREFUSED') {
+    return `Cannot connect to database${config.devUrl ? ` at ${config.devUrl}` : ''}. Is it running?`
+  }
+  return err?.message ?? String(err)
+}

package/src/commands/validate.ts

@@ -0,0 +1,100 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import type { Diagnostic, ResolvedConfig, SqlStatement } from '@sqldoc/core'
+import { loadConfig, loadImports, parse, resolveProject, SqlparserTsAdapter, validate } from '@sqldoc/core'
+import pc from 'picocolors'
+import { CliError } from '../errors.ts'
+import { promptAndInstallMissing } from '../utils/auto-install.ts'
+import { discoverSqlFiles } from '../utils/discover.ts'
+import { formatDiagnostic, formatSummary } from '../utils/format.ts'
+
+/**
+ * validate command: checks tags in SQL files and reports diagnostics
+ * with file:line:col format. Exits non-zero when errors are found.
+ */
+export async function validateCommand(
+  inputPath: string | undefined,
+  options: { config?: string; project?: string },
+): Promise<void> {
+  // Load project config
+  const configRoot = options.config
+    ? path.dirname(path.resolve(options.config))
+    : process.env.SQLDOC_PROJECT_ROOT || process.cwd()
+  const { config: rawConfig } = await loadConfig(configRoot, options.config)
+  const config: ResolvedConfig = resolveProject(rawConfig, options.project)
+
+  // Resolve input path: explicit arg > config.schema > error
+  const resolvedInput = inputPath ?? config.schema
+  if (!resolvedInput) {
+    throw new CliError('No input path provided. Specify a path argument or set "schema" in sqldoc.config.ts')
+  }
+
+  // Discover SQL files
+  const sqlFiles = await discoverSqlFiles(resolvedInput, config.include)
+  if (sqlFiles.length === 0) {
+    console.log(pc.yellow('No SQL files found'))
+    return
+  }
+
+  let totalErrors = 0
+  let totalWarnings = 0
+
+  for (const filePath of sqlFiles) {
+    const source = fs.readFileSync(filePath, 'utf-8')
+
+    // Parse tags and imports
+    const { imports, tags } = parse(source)
+
+    // Load namespace definitions (with auto-install for missing packages)
+    let { namespaces, errors: loadErrors } = await loadImports(
+      imports.map((i) => i.path),
+      filePath,
+    )
+
+    if (loadErrors.length > 0) {
+      const retryResult = await promptAndInstallMissing(
+        loadErrors,
+        imports.map((i) => i.path),
+        filePath,
+      )
+      if (retryResult) {
+        namespaces = retryResult.namespaces
+        loadErrors = retryResult.errors
+      }
+
+      if (loadErrors.length > 0) {
+        for (const err of loadErrors) {
+          console.log(pc.red(`Error loading ${err.importPath}: ${err.message}`))
+        }
+        totalErrors += loadErrors.length
+      }
+    }
+
+    // Parse SQL AST for enriched validation
+    let statements: SqlStatement[] = []
+    try {
+      const adapter = new SqlparserTsAdapter()
+      await adapter.init()
+      statements = adapter.parseStatements(source)
+    } catch {
+      // AST parse failure is non-fatal
+    }
+
+    // Validate: signature is validate(tags, namespaces, docText, stmts?)
+    const diagnostics: Diagnostic[] = validate(tags, namespaces, source, statements)
+
+    // Format and print diagnostics
+    for (const d of diagnostics) {
+      console.log(formatDiagnostic(filePath, d))
+      if (d.severity === 'error') totalErrors++
+      else totalWarnings++
+    }
+  }
+
+  // Print summary
+  console.log(formatSummary(totalErrors, totalWarnings))
+
+  if (totalErrors > 0) {
+    throw new CliError(`${totalErrors} validation error(s)`)
+  }
+}

package/src/errors.ts

@@ -0,0 +1,24 @@
+/**
+ * CLI error with an exit code and user-friendly message.
+ * Thrown by command functions, caught at the entry point.
+ */
+export class CliError extends Error {
+  exitCode: number
+  constructor(message: string, exitCode: number = 1) {
+    super(message)
+    this.name = 'CliError'
+    this.exitCode = exitCode
+  }
+}
+
+/**
+ * Format a pipeline error into a user-friendly CliError.
+ * Handles ECONNREFUSED (database not reachable) and falls back to the raw message.
+ */
+export function formatPipelineError(err: any, config: { devUrl?: string }): CliError {
+  const msg =
+    err?.code === 'ECONNREFUSED'
+      ? `Cannot connect to database${config.devUrl ? ` at ${config.devUrl}` : ''}. Is it running?`
+      : (err?.message ?? String(err))
+  return new CliError(msg)
+}

package/src/index.ts

@@ -0,0 +1,103 @@
+// Suppress Node experimental warnings (WASI)
+process.removeAllListeners('warning')
+
+import { createRequire } from 'node:module'
+import { Command } from 'commander'
+import pc from 'picocolors'
+import { codegenCommand } from './commands/codegen.ts'
+import { doctorCommand } from './commands/doctor.ts'
+import { lintCommand } from './commands/lint.ts'
+import { migrateCommand } from './commands/migrate.ts'
+import { schemaDiffCommand, schemaInspectCommand } from './commands/schema.ts'
+import { validateCommand } from './commands/validate.ts'
+import { CliError } from './errors.ts'
+
+const req = createRequire(import.meta.url)
+const version: string = req('../package.json').version
+
+const program = new Command()
+
+program.name('sqldoc').description('SQL documentation and code generation tool').version(version)
+
+program
+  .command('codegen')
+  .description('Run code generation plugins (templates, docs, etc.)')
+  .argument('[path]', 'Path to SQL files or directory (defaults to config schema)')
+  .option('-c, --config <path>', 'Path to sqldoc.config.ts')
+  .option('-p, --plugins <names>', 'Comma-separated project-level plugin names to run (default: all)')
+  .option('--project <name>', 'Select a named project from multi-project config')
+  .action(codegenCommand)
+
+program
+  .command('validate')
+  .description('Validate tags in SQL files')
+  .argument('[path]', 'Path to SQL files or directory (defaults to config schema)')
+  .option('-c, --config <path>', 'Path to sqldoc.config.ts')
+  .option('--project <name>', 'Select a named project from multi-project config')
+  .action(validateCommand)
+
+program
+  .command('lint')
+  .description('Run lint rules from namespace plugins against SQL files')
+  .argument('[path]', 'Path to SQL files or directory (defaults to config schema)')
+  .option('-c, --config <path>', 'Path to sqldoc.config.ts')
+  .option('-v, --verbose', 'Show ignored rules')
+  .option('--project <name>', 'Select a named project from multi-project config')
+  .action(lintCommand)
+
+const schema = program.command('schema').description('Schema inspection and comparison')
+
+schema
+  .command('inspect')
+  .description('Inspect schema from SQL files, directory, or database')
+  .argument('[source]', 'SQL file, directory, or database URL (defaults to config schema)')
+  .option('-c, --config <path>', 'Path to sqldoc.config.ts')
+  .option('-f, --format <format>', 'Output format: sql, json', 'sql')
+  .option('--dev-url <url>', 'Dev database URL (pglite, docker://<image>, dockerfile://<path>, postgres://...)')
+  .option('--project <name>', 'Select a named project from multi-project config')
+  .action(schemaInspectCommand)
+
+schema
+  .command('diff')
+  .description('Compare two schema states')
+  .option('--from <source>', 'Source state: SQL file, directory, or database URL (default: empty)')
+  .option('--to <source>', 'Target state: SQL file, directory, or database URL')
+  .option('-c, --config <path>', 'Path to sqldoc.config.ts')
+  .option('-f, --format <format>', 'Output format: sql, json, pretty', 'sql')
+  .option('--dev-url <url>', 'Dev database URL (pglite, docker://<image>, dockerfile://<path>, postgres://...)')
+  .option('--check', 'Exit non-zero if schemas differ (CI mode)')
+  .option('--project <name>', 'Select a named project from multi-project config')
+  .action(schemaDiffCommand)
+
+program
+  .command('migrate')
+  .description('Generate migration files or check for schema drift')
+  .option('-c, --config <path>', 'Path to sqldoc.config.ts')
+  .option('--project <name>', 'Select a named project from multi-project config')
+  .option('--check', 'Exit non-zero if schema differs from migrations (CI mode)')
+  .option('--name <name>', 'Custom migration name')
+  .option('--force', 'Allow destructive changes (DROP TABLE, DROP COLUMN, etc.)')
+  .action(migrateCommand)
+
+program.command('doctor').description('Check project setup and report status').action(doctorCommand)
+
+// Global handler — force exit on both success and error
+// (pglite/WASI worker threads keep the process alive otherwise)
+program
+  .parseAsync()
+  .then(() => {
+    process.exit(0)
+  })
+  .catch((err) => {
+    if (err instanceof CliError) {
+      console.error(pc.red(err.message))
+      process.exit(err.exitCode)
+    }
+    if (err?.code === 'ECONNREFUSED') {
+      console.error(pc.red('Cannot connect to database. Is it running?'))
+      process.exit(1)
+    }
+    console.error(pc.red(err?.message ?? String(err)))
+    if (err?.stack) console.error(pc.dim(err.stack))
+    process.exit(1)
+  })

package/src/runtime.ts

@@ -0,0 +1,17 @@
+/**
+ * Runtime detection helpers for the sqldoc CLI.
+ * Used by binary-entry.ts to determine execution context.
+ *
+ * In Node.js (dev mode), both return false.
+ * In a Bun-compiled binary, both return true.
+ */
+
+/** Whether we're running inside a Bun runtime (compiled or not) */
+export function isBunRuntime(): boolean {
+  return typeof (globalThis as any).Bun !== 'undefined'
+}
+
+/** Whether we're running as a Bun-compiled binary (not just bun CLI) */
+export function isCompiledBinary(): boolean {
+  return isBunRuntime() && process.execPath.includes('sqldoc')
+}

package/src/utils/auto-install.ts

@@ -0,0 +1,116 @@
+import { spawnSync } from 'node:child_process'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import * as readline from 'node:readline'
+import type { ImportError } from '@sqldoc/core'
+import { findSqldocDir, loadImports } from '@sqldoc/core'
+import pc from 'picocolors'
+
+/**
+ * Detect missing npm packages from loadImport errors.
+ * Returns an array of package names that look like "Cannot find module/package"
+ * for npm scoped/unscoped packages (not relative paths).
+ */
+export function extractMissingPackages(errors: ImportError[]): string[] {
+  const missing: string[] = []
+  for (const err of errors) {
+    if (
+      /cannot find (module|package)/i.test(err.message) &&
+      !err.importPath.startsWith('.') &&
+      !err.importPath.startsWith('/')
+    ) {
+      missing.push(err.importPath)
+    }
+  }
+  return [...new Set(missing)]
+}
+
+/**
+ * Prompt the user via stdin whether to install missing packages.
+ * Returns true if user agrees (Enter or 'y'/'Y').
+ */
+export async function promptInstall(packages: string[]): Promise<boolean> {
+  // Non-interactive (piped stdin) — skip prompt
+  if (!process.stdin.isTTY) return false
+
+  const names = packages.map((p) => pc.cyan(p)).join(', ')
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr })
+  const answer = await new Promise<string>((resolve) =>
+    rl.question(`Package ${names} is not installed. Install it? (Y/n) `, resolve),
+  )
+  rl.close()
+  return answer === '' || answer.toLowerCase() === 'y'
+}
+
+/**
+ * Find the .sqldoc/ directory, checking SQLDOC_PROJECT_ROOT first, then walking up from cwd.
+ */
+function findSqldocDirWithEnv(): string | null {
+  const envRoot = process.env.SQLDOC_PROJECT_ROOT
+  if (envRoot) {
+    const candidate = path.join(envRoot, '.sqldoc')
+    if (fs.existsSync(candidate)) return candidate
+  }
+  return findSqldocDir()
+}
+
+/**
+ * Install packages into .sqldoc/node_modules using the same mechanism as `sqldoc add`.
+ * Returns true if install succeeded.
+ */
+export function installPackages(sqldocDir: string, packages: string[]): boolean {
+  // Detect if running as compiled Bun binary
+  const isBunBinary = typeof (globalThis as any).Bun !== 'undefined' && !process.execPath.match(/\/(bun|node)(\.exe)?$/)
+
+  let installArgs: string[]
+  const env: Record<string, string> = { ...process.env } as Record<string, string>
+
+  if (isBunBinary) {
+    installArgs = [process.execPath, 'install', ...packages]
+    env.BUN_BE_BUN = '1'
+  } else {
+    // Detect package manager from lockfiles
+    const projectRoot = path.dirname(sqldocDir)
+    let pm = 'npm'
+    if (fs.existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) pm = 'pnpm'
+    else if (fs.existsSync(path.join(projectRoot, 'yarn.lock'))) pm = 'yarn'
+    else if (fs.existsSync(path.join(projectRoot, 'bun.lockb')) || fs.existsSync(path.join(projectRoot, 'bun.lock')))
+      pm = 'bun'
+
+    installArgs = pm === 'yarn' ? ['yarn', 'add', ...packages] : [pm, 'install', ...packages]
+  }
+
+  console.error(pc.dim(`Installing ${packages.join(', ')}...`))
+  const result = spawnSync(installArgs[0], installArgs.slice(1), {
+    cwd: sqldocDir,
+    stdio: 'inherit',
+    env,
+  })
+
+  return result.status === 0
+}
+
+/**
+ * Check for missing package errors, prompt the user to install, and retry loadImports.
+ * Returns updated namespaces and remaining errors.
+ */
+export async function promptAndInstallMissing(
+  loadErrors: ImportError[],
+  importPaths: string[],
+  filePath: string,
+): Promise<{ namespaces: Map<string, any>; errors: ImportError[] } | null> {
+  const missingPackages = extractMissingPackages(loadErrors)
+  if (missingPackages.length === 0) return null
+
+  const sqldocDir = findSqldocDirWithEnv()
+  if (!sqldocDir) return null
+
+  if (await promptInstall(missingPackages)) {
+    if (installPackages(sqldocDir, missingPackages)) {
+      // Retry loading after install
+      return await loadImports(importPaths, filePath)
+    }
+  }
+
+  return null
+}