@sqldoc/sqldoc 0.0.1

package/src/commands/add.ts

@@ -0,0 +1,48 @@
+import { spawnSync } from 'node:child_process'
+import { dirname } from 'node:path'
+import pc from 'picocolors'
+import { detectPM } from '../detect-pm.ts'
+import { generateConfigTypes } from '../generate-config-types.ts'
+
+function isCompiledBinary(): boolean {
+  return typeof process.versions?.bun === 'string' && !process.execPath.match(/\/(bun|node)(\.exe)?$/)
+}
+
+/**
+ * Install packages into .sqldoc/node_modules.
+ */
+export function addCommand(sqldocDir: string, packages: string[]): void {
+  if (packages.length === 0) {
+    console.error(pc.red('Error: No packages specified'))
+    console.error(`Usage: ${pc.cyan('sqldoc add <package> [package...]')}`)
+    process.exit(1)
+  }
+
+  const installArgs = isCompiledBinary()
+    ? [process.execPath, 'install', ...packages]
+    : (() => {
+        const projectRoot = dirname(sqldocDir)
+        const pm = detectPM(projectRoot)
+        console.log(pc.dim(`Installing ${packages.join(', ')} with ${pm}...`))
+        return pm === 'yarn' ? ['yarn', 'add', ...packages] : [pm, 'install', ...packages]
+      })()
+
+  const env = isCompiledBinary() ? { ...process.env, BUN_BE_BUN: '1' } : process.env
+
+  if (isCompiledBinary()) {
+    console.log(pc.dim(`Installing ${packages.join(', ')} with built-in package manager...`))
+  }
+
+  const result = spawnSync(installArgs[0], installArgs.slice(1), {
+    cwd: sqldocDir,
+    stdio: 'inherit',
+    env,
+  })
+
+  if (result.status === 0) {
+    generateConfigTypes(sqldocDir)
+    console.log(pc.dim('Updated .sqldoc/config.d.ts'))
+  }
+
+  process.exit(result.status ?? 1)
+}

package/src/commands/init.ts

@@ -0,0 +1,210 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, readdirSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import pc from 'picocolors'
+import { detectPM } from '../detect-pm.ts'
+import { generateConfigTypes } from '../generate-config-types.ts'
+
+function isCompiledBinary(): boolean {
+  return typeof process.versions?.bun === 'string' && !process.execPath.match(/\/(bun|node)(\.exe)?$/)
+}
+
+function findLocalPackages(repoPath: string): Array<{ name: string; path: string }> {
+  const packagesDir = join(repoPath, 'packages')
+  if (!existsSync(packagesDir)) return []
+
+  const packages: Array<{ name: string; path: string }> = []
+  for (const dir of readdirSync(packagesDir, { withFileTypes: true })) {
+    if (!dir.isDirectory()) continue
+    const pkgPath = join(packagesDir, dir.name, 'package.json')
+    if (!existsSync(pkgPath)) continue
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+      if (pkg.name?.startsWith('@sqldoc/')) {
+        packages.push({ name: pkg.name, path: join(packagesDir, dir.name) })
+      }
+    } catch {}
+  }
+  return packages
+}
+
+function installPackages(sqldocDir: string, targetDir: string, packages: string[]): boolean {
+  const installArgs = isCompiledBinary()
+    ? [process.execPath, 'install', ...packages]
+    : (() => {
+        const pm = detectPM(targetDir)
+        console.log(pc.dim(`Using ${pm} to install ${packages.join(', ')}...`))
+        return pm === 'yarn' ? ['yarn', 'add', ...packages] : [pm, 'install', ...packages]
+      })()
+
+  const env = isCompiledBinary() ? { ...process.env, BUN_BE_BUN: '1' } : process.env
+
+  if (isCompiledBinary()) {
+    console.log(pc.dim('Using built-in package manager...'))
+  }
+
+  const result = spawnSync(installArgs[0], installArgs.slice(1), {
+    cwd: sqldocDir,
+    stdio: 'inherit',
+    env,
+  })
+
+  return result.status === 0
+}
+
+const DEFAULT_CONFIG = `import type { Config } from './.sqldoc/config'
+
+export default {
+  dialect: 'postgres',
+  schema: 'schema/',
+  migrations: {
+    dir: 'migrations/',
+    format: 'plain',
+  },
+  namespaces: {
+    docs: {
+      format: 'html',
+      output: 'docs/schema.html',
+    },
+  },
+} satisfies Config
+`
+
+const EXAMPLE_SCHEMA = `-- @import '@sqldoc/ns-docs'
+
+-- @docs.description('Application users')
+CREATE TABLE users (
+    id BIGSERIAL PRIMARY KEY,
+
+    -- @docs.description('Login email address')
+    email TEXT NOT NULL UNIQUE,
+
+    -- @docs.description('Display name')
+    name TEXT,
+
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- @docs.description('User-created posts')
+CREATE TABLE posts (
+    id BIGSERIAL PRIMARY KEY,
+
+    -- @docs.description('Author of the post')
+    user_id BIGINT NOT NULL REFERENCES users(id),
+
+    title TEXT NOT NULL,
+    body TEXT,
+    published BOOLEAN NOT NULL DEFAULT false,
+
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+`
+
+/**
+ * Initialize a .sqldoc/ project directory.
+ *
+ * --dev <path>: link all @sqldoc/* packages from a local monorepo.
+ * Otherwise: installs @sqldoc/cli and @sqldoc/ns-docs from npm.
+ */
+export async function initCommand(targetDir: string = process.cwd(), devPath?: string): Promise<void> {
+  const sqldocDir = join(targetDir, '.sqldoc')
+
+  if (existsSync(sqldocDir)) {
+    console.error(pc.red('Error: .sqldoc/ already exists in this directory'))
+    process.exit(1)
+  }
+
+  console.log(pc.cyan('Initializing .sqldoc/ project...'))
+  console.log('')
+
+  mkdirSync(sqldocDir, { recursive: true })
+  writeFileSync(join(sqldocDir, '.gitignore'), 'node_modules/\n')
+
+  if (devPath) {
+    // Dev mode — link all @sqldoc/* packages from local repo
+    const repoPath = resolve(devPath)
+    if (!existsSync(repoPath)) {
+      console.error(pc.red(`Error: ${repoPath} does not exist`))
+      process.exit(1)
+    }
+
+    const localPackages = findLocalPackages(repoPath)
+    if (localPackages.length === 0) {
+      console.error(pc.red(`No @sqldoc/* packages found in ${repoPath}/packages/`))
+      process.exit(1)
+    }
+
+    const deps: Record<string, string> = {}
+    for (const pkg of localPackages) {
+      const relPath = relative(sqldocDir, pkg.path)
+      deps[pkg.name] = `file:${relPath}`
+    }
+
+    writeFileSync(
+      join(sqldocDir, 'package.json'),
+      `${JSON.stringify({ name: 'sqldoc-local', private: true, workspaces: [], dependencies: deps }, null, 2)}\n`,
+    )
+
+    const nmDir = join(sqldocDir, 'node_modules', '@sqldoc')
+    mkdirSync(nmDir, { recursive: true })
+    for (const pkg of localPackages) {
+      const linkName = pkg.name.replace('@sqldoc/', '')
+      const linkPath = join(nmDir, linkName)
+      try {
+        symlinkSync(pkg.path, linkPath)
+      } catch (e: any) {
+        if (e.code !== 'EEXIST') throw e
+      }
+    }
+
+    console.log(pc.dim(`Linked ${localPackages.length} packages from ${repoPath}`))
+  } else {
+    // Production mode — install @sqldoc/cli and ns-docs
+    writeFileSync(
+      join(sqldocDir, 'package.json'),
+      `${JSON.stringify({ name: 'sqldoc-local', private: true, workspaces: [] }, null, 2)}\n`,
+    )
+
+    if (!installPackages(sqldocDir, targetDir, ['@sqldoc/cli', '@sqldoc/ns-docs'])) {
+      console.error(pc.red('Failed to install packages'))
+      process.exit(1)
+    }
+  }
+
+  // Generate config types
+  generateConfigTypes(sqldocDir)
+
+  // Scaffold sqldoc.config.ts
+  const configPath = join(targetDir, 'sqldoc.config.ts')
+  if (!existsSync(configPath)) {
+    writeFileSync(configPath, DEFAULT_CONFIG)
+    console.log(`  ${pc.green('+')} ${pc.bold('sqldoc.config.ts')}`)
+  }
+
+  // Scaffold example schema if schema/ doesn't exist
+  const schemaDir = join(targetDir, 'schema')
+  if (!existsSync(schemaDir)) {
+    mkdirSync(schemaDir, { recursive: true })
+    writeFileSync(join(schemaDir, 'schema.sql'), EXAMPLE_SCHEMA)
+    console.log(`  ${pc.green('+')} ${pc.bold('schema/schema.sql')} ${pc.dim('(example schema with two tables)')}`)
+  }
+
+  console.log('')
+  console.log(pc.green('Project initialized!'))
+  console.log('')
+  console.log(`Edit ${pc.bold('sqldoc.config.ts')} to configure your project.`)
+  console.log(`We've created an example schema in ${pc.bold('schema/')} to get you started.`)
+  console.log('')
+  console.log('Try these commands:')
+  console.log(`  ${pc.cyan('sqldoc codegen')}                 Generate HTML docs from your schema`)
+  console.log(`  ${pc.cyan('sqldoc schema inspect')}          View the parsed schema`)
+  console.log(`  ${pc.cyan('sqldoc migrate')}                 Generate a migration file`)
+  console.log('')
+  console.log('Install more plugins:')
+  console.log(`  ${pc.cyan('sqldoc add @sqldoc/ns-audit')}    Audit trail triggers`)
+  console.log(`  ${pc.cyan('sqldoc add @sqldoc/ns-validate')} CHECK constraints from tags`)
+  console.log(`  ${pc.cyan('sqldoc add @sqldoc/ns-rls')}      Row-level security policies`)
+  console.log(`  ${pc.cyan('sqldoc add @sqldoc/templates')}   Code generation (TypeScript, Go, etc.)`)
+}

package/src/commands/upgrade.ts

@@ -0,0 +1,45 @@
+import { spawnSync } from 'node:child_process'
+import { dirname } from 'node:path'
+import pc from 'picocolors'
+import { detectPM } from '../detect-pm.ts'
+
+function isCompiledBinary(): boolean {
+  return typeof process.versions?.bun === 'string' && !process.execPath.match(/\/(bun|node)(\.exe)?$/)
+}
+
+/**
+ * Upgrade all packages in .sqldoc/node_modules.
+ */
+export function upgradeCommand(sqldocDir: string): void {
+  const upgradeArgs = isCompiledBinary()
+    ? [process.execPath, 'update']
+    : (() => {
+        const projectRoot = dirname(sqldocDir)
+        const pm = detectPM(projectRoot)
+        console.log(pc.dim(`Upgrading packages with ${pm}...`))
+        switch (pm) {
+          case 'pnpm':
+            return ['pnpm', 'update']
+          case 'yarn':
+            return ['yarn', 'upgrade']
+          case 'bun':
+            return ['bun', 'update']
+          default:
+            return ['npm', 'update']
+        }
+      })()
+
+  const env = isCompiledBinary() ? { ...process.env, BUN_BE_BUN: '1' } : process.env
+
+  if (isCompiledBinary()) {
+    console.log(pc.dim('Upgrading packages with built-in package manager...'))
+  }
+
+  const result = spawnSync(upgradeArgs[0], upgradeArgs.slice(1), {
+    cwd: sqldocDir,
+    stdio: 'inherit',
+    env,
+  })
+
+  process.exit(result.status ?? 1)
+}

package/src/delegate.ts

@@ -0,0 +1,44 @@
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import pc from 'picocolors'
+
+/**
+ * Delegate command execution to the project-local @sqldoc/cli.
+ * Spawns the local CLI with inherited stdio and SQLDOC_PROJECT_ROOT env var.
+ */
+export function delegate(sqldocDir: string, args: string[]): void {
+  // Try src/index.ts first (Bun runtime can execute .ts directly)
+  let localCli = join(sqldocDir, 'node_modules', '@sqldoc', 'cli', 'src', 'index.ts')
+  if (!existsSync(localCli)) {
+    // Fallback to dist/index.js (for pre-built npm packages)
+    localCli = join(sqldocDir, 'node_modules', '@sqldoc', 'cli', 'dist', 'index.js')
+  }
+
+  if (!existsSync(localCli)) {
+    console.error(pc.red('Error: @sqldoc/cli not found in .sqldoc/node_modules'))
+    console.error(`Run: ${pc.cyan('sqldoc init')}`)
+    process.exit(1)
+  }
+
+  const projectRoot = dirname(sqldocDir)
+  const child = spawn(process.execPath, [localCli, ...args], {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+    env: {
+      ...process.env,
+      SQLDOC_PROJECT_ROOT: projectRoot,
+      BUN_BE_BUN: '1',
+      NODE_PATH: join(sqldocDir, 'node_modules'),
+    },
+  })
+
+  child.on('exit', (code) => {
+    process.exit(code ?? 1)
+  })
+
+  child.on('error', (err) => {
+    console.error(pc.red(`Failed to start @sqldoc/cli: ${err.message}`))
+    process.exit(1)
+  })
+}

package/src/detect-pm.ts

@@ -0,0 +1,17 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun'
+
+/**
+ * Detect the package manager used in a project by checking lockfiles.
+ * Priority: pnpm > yarn > bun > npm (fallback).
+ */
+export function detectPM(projectRoot: string): PackageManager {
+  if (existsSync(join(projectRoot, 'pnpm-lock.yaml'))) return 'pnpm'
+  if (existsSync(join(projectRoot, 'yarn.lock'))) return 'yarn'
+  if (existsSync(join(projectRoot, 'bun.lockb'))) return 'bun'
+  if (existsSync(join(projectRoot, 'bun.lock'))) return 'bun'
+  if (existsSync(join(projectRoot, 'package-lock.json'))) return 'npm'
+  return 'npm'
+}

package/src/find-sqldoc.ts

@@ -0,0 +1,22 @@
+import { existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+/**
+ * Walk up from startDir looking for .sqldoc/ directory.
+ * Returns the absolute path to .sqldoc/ or null.
+ */
+export function findSqldocDir(startDir: string = process.cwd()): string | null {
+  let current = resolve(startDir)
+  while (true) {
+    const candidate = join(current, '.sqldoc')
+    if (existsSync(candidate)) {
+      return candidate
+    }
+    const parent = dirname(current)
+    if (parent === current) {
+      // Reached filesystem root
+      return null
+    }
+    current = parent
+  }
+}

package/src/generate-config-types.ts

@@ -0,0 +1,77 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+/**
+ * Scan .sqldoc/node_modules for installed @sqldoc namespace plugins,
+ * and generate .sqldoc/config.d.ts with a typed SqldocConfig interface.
+ *
+ * Base config fields (devUrl, dialect, extensions, etc.) are imported from
+ * @sqldoc/core so they stay in sync. Only the namespaces block is generated.
+ */
+export function generateConfigTypes(sqldocDir: string): void {
+  const nodeModules = path.join(sqldocDir, 'node_modules', '@sqldoc')
+  if (!fs.existsSync(nodeModules)) return
+
+  const imports: string[] = ["import type { ProjectConfig as BaseProjectConfig } from '@sqldoc/core'"]
+  const namespaceFields: string[] = []
+
+  const dirs = fs.readdirSync(nodeModules).sort()
+  for (const dir of dirs) {
+    if (!dir.startsWith('ns-')) continue
+
+    const pkgPath = path.join(nodeModules, dir)
+    const pkgJsonPath = path.join(pkgPath, 'package.json')
+    if (!fs.existsSync(pkgJsonPath)) continue
+
+    const nsName = dir.replace('ns-', '')
+    const pkgName = `@sqldoc/${dir}`
+
+    const configTypeName = findConfigTypeName(pkgPath, nsName)
+
+    if (configTypeName) {
+      imports.push(`import type { ${configTypeName} } from '${pkgName}'`)
+      namespaceFields.push(`    ${nsName}?: Partial<${configTypeName}>`)
+    } else {
+      namespaceFields.push(`    ${nsName}?: Record<string, unknown>`)
+    }
+  }
+
+  const namespacesBlock =
+    namespaceFields.length > 0
+      ? `  namespaces?: {
+${namespaceFields.join('\n')}
+  }`
+      : `  namespaces?: Record<string, Record<string, unknown>>`
+
+  const content = `// Auto-generated by sqldoc -- DO NOT EDIT
+// Regenerated on: sqldoc init, sqldoc add, sqldoc codegen
+${imports.join('\n')}
+
+interface ProjectConfig extends BaseProjectConfig {
+${namespacesBlock}
+}
+
+export type SqldocConfig = ProjectConfig | ProjectConfig[]
+export type Config = SqldocConfig
+`
+
+  fs.writeFileSync(path.join(sqldocDir, 'config.d.ts'), content)
+}
+
+/**
+ * Look for an exported Config type in a namespace package.
+ * Checks for PascalCase(nsName)Config (e.g. DocsConfig, CodegenConfig).
+ */
+function findConfigTypeName(pkgPath: string, _nsName: string): string | null {
+  const candidates = ['src/index.ts', 'index.ts', 'src/index.js', 'index.js']
+  for (const candidate of candidates) {
+    const filePath = path.join(pkgPath, candidate)
+    if (!fs.existsSync(filePath)) continue
+
+    const content = fs.readFileSync(filePath, 'utf-8')
+    const match = content.match(/export\s+(?:type\s+)?{\s*[^}]*\b(\w+Config)\b/)
+    if (match) return match[1]
+  }
+
+  return null
+}

package/src/index.ts

@@ -0,0 +1,127 @@
+import { execSync } from 'node:child_process'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import pc from 'picocolors'
+import { addCommand } from './commands/add.ts'
+import { initCommand } from './commands/init.ts'
+import { upgradeCommand } from './commands/upgrade.ts'
+import { delegate } from './delegate.ts'
+import { findSqldocDir } from './find-sqldoc.ts'
+import { getPackageManagerCommand } from './runtime.ts'
+
+// Version is set at build time — the compiled binary can't read package.json
+const VERSION = '0.0.1'
+
+const HELP = `
+${pc.bold('sqldoc')} - SQL documentation and code generation
+
+${pc.dim('Usage:')}
+  sqldoc <command> [options]
+
+${pc.dim('Built-in commands:')}
+  init                 Initialize .sqldoc/ in the current directory
+  add <packages...>    Install packages into .sqldoc/node_modules
+  upgrade              Update all packages in .sqldoc/
+
+${pc.dim('Options:')}
+  --version, -V        Show version
+  --help, -h           Show this help
+
+All other commands are delegated to the project-local @sqldoc/cli
+installed in .sqldoc/node_modules/@sqldoc/cli.
+`.trim()
+
+/** Run install in .sqldoc/ to ensure node_modules is up to date */
+function ensureDeps(sqldocDir: string): void {
+  const nodeModules = path.join(sqldocDir, 'node_modules')
+  const pkgJson = path.join(sqldocDir, 'package.json')
+
+  // Skip if no package.json
+  if (!fs.existsSync(pkgJson)) return
+
+  // Dev mode uses symlinks — no install needed
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgJson, 'utf-8'))
+    if (pkg.description?.includes('dev mode')) return
+  } catch {}
+
+  // Quick check: if node_modules exists and is newer than package.json, skip
+  if (fs.existsSync(nodeModules)) {
+    const pkgMtime = fs.statSync(pkgJson).mtimeMs
+    const nmMtime = fs.statSync(nodeModules).mtimeMs
+    if (nmMtime > pkgMtime) return
+  }
+
+  const pm = getPackageManagerCommand(sqldocDir)
+  try {
+    execSync(`${pm.cmd} install`, {
+      cwd: sqldocDir,
+      stdio: 'inherit',
+      env: { ...process.env, ...pm.env },
+    })
+  } catch {
+    console.error(pc.yellow('Warning: failed to sync .sqldoc/ dependencies'))
+  }
+}
+
+function requireSqldocDir(): string {
+  const sqldocDir = findSqldocDir()
+  if (!sqldocDir) {
+    console.error(pc.red('Error: No .sqldoc/ directory found'))
+    console.error(`Run ${pc.cyan('sqldoc init')} to create one.`)
+    process.exit(1)
+  }
+  return sqldocDir
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2)
+  const command = args[0]
+
+  // Handle flags
+  if (command === '--version' || command === '-V') {
+    console.log(VERSION)
+    return
+  }
+
+  if (command === '--help' || command === '-h') {
+    console.log(HELP)
+    return
+  }
+
+  // Handle built-in commands
+  if (command === 'init') {
+    const devIdx = args.indexOf('--dev')
+    const devPath = devIdx !== -1 ? args[devIdx + 1] : undefined
+    await initCommand(process.cwd(), devPath)
+    return
+  }
+
+  if (command === 'add') {
+    const sqldocDir = requireSqldocDir()
+    addCommand(sqldocDir, args.slice(1))
+    return
+  }
+
+  if (command === 'upgrade') {
+    const sqldocDir = requireSqldocDir()
+    upgradeCommand(sqldocDir)
+    return
+  }
+
+  // No command given → show help
+  if (!command) {
+    console.log(HELP)
+    return
+  }
+
+  // Default: ensure dependencies are installed, then delegate
+  const sqldocDir = requireSqldocDir()
+  ensureDeps(sqldocDir)
+  delegate(sqldocDir, args)
+}
+
+main().catch((err) => {
+  console.error(pc.red(err.message))
+  process.exit(1)
+})

package/src/prompt.ts

@@ -0,0 +1,92 @@
+import * as readline from 'node:readline'
+import pc from 'picocolors'
+
+/**
+ * Low-level: ask a question, return the raw answer.
+ */
+function ask(rl: readline.Interface, question: string): Promise<string> {
+  return new Promise((resolve) => rl.question(question, resolve))
+}
+
+/**
+ * Create a readline interface on stdin/stdout.
+ */
+export function createRL(): readline.Interface {
+  return readline.createInterface({ input: process.stdin, output: process.stdout })
+}
+
+/**
+ * Prompt the user to select one option from a list.
+ * Shows numbered options; user types a number or presses Enter for default.
+ */
+export async function promptSelect<T extends string>(
+  rl: readline.Interface,
+  message: string,
+  options: Array<{ value: T; label: string }>,
+  defaultValue: T,
+): Promise<T> {
+  console.log('')
+  console.log(pc.bold(message))
+  for (let i = 0; i < options.length; i++) {
+    const isDefault = options[i].value === defaultValue
+    const marker = isDefault ? pc.cyan('*') : ' '
+    console.log(`  ${marker} ${i + 1}) ${options[i].label}`)
+  }
+
+  const defaultIdx = options.findIndex((o) => o.value === defaultValue)
+  const answer = await ask(rl, `${pc.dim(`[${defaultIdx + 1}]`)} > `)
+
+  if (answer.trim() === '') return defaultValue
+  const idx = parseInt(answer.trim(), 10) - 1
+  if (idx >= 0 && idx < options.length) return options[idx].value
+  return defaultValue
+}
+
+/**
+ * Prompt the user to select multiple options from a list.
+ * Shows numbered options; user types comma-separated numbers.
+ * Enter with no input selects the defaults.
+ */
+export async function promptCheckbox<T extends string>(
+  rl: readline.Interface,
+  message: string,
+  options: Array<{ value: T; label: string; checked?: boolean }>,
+): Promise<T[]> {
+  console.log('')
+  console.log(pc.bold(message))
+  console.log(pc.dim('  (enter comma-separated numbers, or press Enter for defaults)'))
+  for (let i = 0; i < options.length; i++) {
+    const marker = options[i].checked ? pc.green('[x]') : pc.dim('[ ]')
+    console.log(`  ${marker} ${i + 1}) ${options[i].label}`)
+  }
+
+  const defaults = options.filter((o) => o.checked).map((o) => o.value)
+  const answer = await ask(
+    rl,
+    `${pc.dim(
+      `[${options
+        .map((o, i) => (o.checked ? i + 1 : ''))
+        .filter(Boolean)
+        .join(',')}]`,
+    )} > `,
+  )
+
+  if (answer.trim() === '') return defaults
+
+  const indices = answer.split(',').map((s) => parseInt(s.trim(), 10) - 1)
+  const selected: T[] = []
+  for (const idx of indices) {
+    if (idx >= 0 && idx < options.length) {
+      selected.push(options[idx].value)
+    }
+  }
+  return selected.length > 0 ? selected : defaults
+}
+
+/**
+ * Simple yes/no confirmation prompt. Enter = yes.
+ */
+export async function promptConfirm(rl: readline.Interface, message: string): Promise<boolean> {
+  const answer = await ask(rl, `${message} ${pc.dim('(Y/n)')} `)
+  return answer.trim() === '' || answer.trim().toLowerCase() === 'y'
+}