@sqldoc/atlas 0.0.1

package/src/index.ts

@@ -0,0 +1,97 @@
+// @sqldoc/atlas -- Atlas WASI integration for sqldoc
+// Schema types, database adapters, and WASI runner
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createDockerAdapter } from './db/docker.ts'
+import { createPgliteAdapter } from './db/pglite.ts'
+import { createPostgresAdapter } from './db/postgres.ts'
+import { extractExtensions, validatePgliteExtensions, validatePostgresExtensions } from './extensions.ts'
+import { createAtlasRunner } from './runner.ts'
+
+export { createDockerAdapter } from './db/docker.ts'
+export { createPgliteAdapter } from './db/pglite.ts'
+export { createPostgresAdapter } from './db/postgres.ts'
+export type { DatabaseAdapter, ExecResult, QueryResult } from './db/types.ts'
+export { extractExtensions, validatePgliteExtensions, validatePostgresExtensions } from './extensions.ts'
+export type { AtlasRunner, AtlasRunnerOptions } from './runner.ts'
+export { createAtlasRunner } from './runner.ts'
+export * from './types.ts'
+
+export interface CreateRunnerConfig {
+  /** SQL dialect. Default: 'postgres' */
+  dialect?: 'postgres' | 'mysql' | 'sqlite'
+  /** Database connection URL. If omitted, uses pglite (in-memory postgres). */
+  devUrl?: string
+  /** SQL file contents to scan for CREATE EXTENSION statements */
+  sqlFiles?: string[]
+}
+
+/**
+ * Resolve the atlas.wasm binary.
+ * Binary mode: ATLAS_WASM_PATH env var set by binary entry point.
+ * Dev mode: walk up from current directory to find atlas.wasm.
+ */
+function resolveWasm(): string {
+  // Binary mode: WASM path set by binary entry point
+  if (process.env.ATLAS_WASM_PATH) {
+    return process.env.ATLAS_WASM_PATH
+  }
+
+  // Dev mode: walk up from current directory to find atlas.wasm
+  let dir = path.dirname(fileURLToPath(import.meta.url))
+  while (true) {
+    for (const candidate of [
+      path.join(dir, 'wasm', 'atlas.wasm'),
+      path.join(dir, '..', 'wasm', 'atlas.wasm'),
+      path.join(dir, 'node_modules', '@sqldoc', 'atlas', 'wasm', 'atlas.wasm'),
+      path.join(dir, 'packages', 'atlas', 'wasm', 'atlas.wasm'),
+    ]) {
+      if (fs.existsSync(candidate)) return candidate
+    }
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  throw new Error(
+    'atlas.wasm not found. Set ATLAS_WASM_PATH or build: cd atlas/cmd/atlas-wasi && GOOS=wasip1 GOARCH=wasm go build -o atlas.wasm .',
+  )
+}
+
+/**
+ * Create an Atlas runner with sensible defaults.
+ * Resolves the wasm binary, detects extensions from SQL files,
+ * validates them, and creates the appropriate DB adapter.
+ */
+export async function createRunner(config: CreateRunnerConfig = {}): Promise<import('./runner').AtlasRunner> {
+  const wasmPath = resolveWasm()
+  const dialect = config.dialect ?? 'postgres'
+  const devUrl = config.devUrl ?? 'pglite'
+
+  // Extract extensions from SQL (postgres only)
+  const { extensions } =
+    dialect === 'postgres' && config.sqlFiles ? extractExtensions(config.sqlFiles) : { extensions: [] }
+
+  let db: import('./db/types').DatabaseAdapter
+
+  if (devUrl.startsWith('docker://') || devUrl.startsWith('dockerfile://')) {
+    db = await createDockerAdapter(devUrl)
+    // Docker postgres — validate extensions are available
+    if (extensions.length > 0) {
+      await validatePostgresExtensions(extensions, (sql) => db.query(sql))
+    }
+  } else if (devUrl.startsWith('postgres://') || devUrl.startsWith('postgresql://')) {
+    db = await createPostgresAdapter(devUrl)
+    // External postgres — validate extensions are available
+    if (extensions.length > 0) {
+      await validatePostgresExtensions(extensions, (sql) => db.query(sql))
+    }
+  } else {
+    // pglite — validate and load extensions
+    const validExtensions = extensions.length > 0 ? await validatePgliteExtensions(extensions) : []
+    db = await createPgliteAdapter(validExtensions.length > 0 ? validExtensions : undefined)
+  }
+
+  return createAtlasRunner({ wasmPath, db })
+}

package/src/runner.ts

@@ -0,0 +1,263 @@
+/**
+ * High-level Atlas runner API.
+ *
+ * Provides inspect() and diff() functions that:
+ * 1. Spawn a worker thread running the Atlas WASI module
+ * 2. Handle the SharedArrayBuffer bridge loop on the main thread
+ * 3. Execute SQL requests from the WASI module via the DatabaseAdapter
+ * 4. Return parsed AtlasResult
+ *
+ * The compiled WebAssembly.Module is cached across commands.
+ */
+
+import * as fs from 'node:fs'
+import { createRequire } from 'node:module'
+import * as path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Worker } from 'node:worker_threads'
+import {
+  type BridgeBuffers,
+  bridgeReadRequest,
+  bridgeRespond,
+  bridgeWaitForSignal,
+  createBridgeBuffers,
+  SIGNAL_DONE,
+  SIGNAL_REQUEST,
+} from './bridge.ts'
+import type { DatabaseAdapter } from './db/types.ts'
+import type { AtlasCommand, AtlasRename, AtlasResult } from './types.ts'
+
+export interface AtlasRunnerOptions {
+  /** Path to atlas.wasm binary */
+  wasmPath: string
+  /** Database adapter (pglite or pg) */
+  db: DatabaseAdapter
+}
+
+export interface AtlasRunner {
+  /** Execute SQL files and return parsed schema with tags */
+  inspect(files: string[], options?: { schema?: string; dialect?: string; fileNames?: string[] }): Promise<AtlasResult>
+
+  /** Compare two schema states and return migration SQL */
+  diff(
+    from: string[],
+    to: string[],
+    options?: { schema?: string; dialect?: string; renames?: AtlasRename[] },
+  ): Promise<AtlasResult>
+
+  /** Clean up resources */
+  close(): Promise<void>
+}
+
+/**
+ * Resolve the path to the worker file (.js or .ts).
+ *
+ * Prefers compiled .js (production / Bun binary). Falls back to raw .ts
+ * for workspace development (vitest, tsx, Node --experimental-strip-types).
+ */
+function resolveWorkerPath(): { workerPath: string; execArgv: string[] } {
+  const thisDir = path.dirname(fileURLToPath(import.meta.url))
+  const candidates = [
+    path.resolve(thisDir, 'worker.js'), // dist/worker.js (production)
+    path.resolve(thisDir, '../dist/worker.js'), // src/../dist/worker.js (legacy)
+    path.resolve(thisDir, 'worker.ts'), // src/worker.ts (raw .ts dev)
+  ]
+
+  const isBun = typeof (globalThis as any).Bun !== 'undefined'
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      if (candidate.endsWith('.ts') && !isBun) {
+        // Node 22.21+ runs .ts natively — no loader needed for workers
+        // Older Node needs tsx/cjs to register TypeScript transform
+        const [major, minor] = (process.versions?.node ?? '0.0').split('.').map(Number)
+        if (major > 22 || (major === 22 && minor >= 21)) {
+          return { workerPath: candidate, execArgv: [] }
+        }
+        const atlasRequire = createRequire(candidate)
+        const tsxCjs = atlasRequire.resolve('tsx/cjs')
+        return { workerPath: candidate, execArgv: ['--require', tsxCjs] }
+      }
+      return { workerPath: candidate, execArgv: [] }
+    }
+  }
+
+  throw new Error(`Cannot find worker file.\nLooked in:\n${candidates.map((c) => `  ${c}`).join('\n')}`)
+}
+
+/**
+ * Run a single Atlas command via a worker thread.
+ *
+ * Main thread bridge loop:
+ * 1. Wait for worker to signal a request via Atomics
+ * 2. Read SQL from shared buffer
+ * 3. Execute via DatabaseAdapter
+ * 4. Write response to shared buffer
+ * 5. Repeat until DONE signal
+ */
+async function runCommand(wasmPath: string, db: DatabaseAdapter, command: AtlasCommand): Promise<AtlasResult> {
+  const buffers = createBridgeBuffers()
+  const stdinData = JSON.stringify(command)
+  const { workerPath, execArgv } = resolveWorkerPath()
+
+  return new Promise<AtlasResult>((resolve, reject) => {
+    const worker = new Worker(workerPath, {
+      workerData: {
+        wasmPath,
+        controlBuffer: buffers.control,
+        dataBuffer: buffers.data,
+        stdinData,
+      },
+      execArgv,
+    })
+
+    let settled = false
+
+    worker.on('message', (msg: { type: string; stdout?: string; error?: string }) => {
+      if (settled) return
+      settled = true
+
+      if (msg.type === 'error') {
+        reject(new Error(`Atlas worker error: ${msg.error}`))
+      } else if (msg.type === 'result') {
+        try {
+          const stdout = (msg.stdout ?? '').trim()
+          if (!stdout) {
+            resolve({})
+          } else {
+            resolve(JSON.parse(stdout))
+          }
+        } catch (_err: unknown) {
+          reject(new Error(`Failed to parse Atlas output: ${msg.stdout}`))
+        }
+      }
+    })
+
+    worker.on('error', (err) => {
+      if (settled) return
+      settled = true
+      reject(err)
+    })
+
+    worker.on('exit', (code) => {
+      if (settled) return
+      settled = true
+      if (code !== 0) {
+        reject(new Error(`Atlas worker exited with code ${code}`))
+      }
+    })
+
+    // Start the bridge loop (runs on main thread, async)
+    handleBridgeLoop(buffers, db).catch((err) => {
+      if (!settled) {
+        settled = true
+        worker.terminate()
+        reject(err)
+      }
+    })
+  })
+}
+
+/**
+ * Main-thread bridge loop: handles atlas_sql requests from the worker.
+ * Runs until the worker signals DONE.
+ */
+async function handleBridgeLoop(buffers: BridgeBuffers, db: DatabaseAdapter): Promise<void> {
+  while (true) {
+    const signal = await bridgeWaitForSignal(buffers)
+
+    if (signal === SIGNAL_DONE) {
+      break
+    }
+
+    if (signal !== SIGNAL_REQUEST) {
+      // Unexpected signal -- wait again
+      // Reset to idle so bridgeWaitForSignal can poll again
+      const _control = new Int32Array(buffers.control)
+      // If it's RESPONSE, the worker hasn't reset yet. Wait briefly.
+      await new Promise((r) => setTimeout(r, 1))
+      continue
+    }
+
+    // Read SQL request from shared buffer
+    const reqJson = bridgeReadRequest(buffers)
+
+    let response: Record<string, unknown>
+    try {
+      const req = JSON.parse(reqJson) as { type: string; sql: string; args?: unknown[] }
+
+      if (req.type === 'query') {
+        const result = await db.query(req.sql, req.args)
+        response = { columns: result.columns, rows: result.rows }
+      } else {
+        const result = await db.exec(req.sql, req.args)
+        response = { rows_affected: result.rowsAffected }
+      }
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err)
+      response = { error: message }
+    }
+
+    // Write response and notify worker (handle BigInt from pglite)
+    bridgeRespond(
+      buffers,
+      JSON.stringify(response, (_k, v) => (typeof v === 'bigint' ? v.toString() : v)),
+    )
+
+    // After responding, the worker will reset signal to IDLE.
+    // We need to wait for it to do so before calling bridgeWaitForSignal again.
+    // Small yield to allow worker to process.
+    await new Promise((r) => setTimeout(r, 0))
+  }
+}
+
+/**
+ * Create an AtlasRunner instance.
+ *
+ * The runner caches the compiled WebAssembly.Module (compiles atlas.wasm once).
+ * Each inspect/diff call spawns a worker thread that reuses the cached module.
+ */
+export async function createAtlasRunner(options: AtlasRunnerOptions): Promise<AtlasRunner> {
+  const { wasmPath, db } = options
+
+  // Verify wasm file exists
+  if (!fs.existsSync(wasmPath)) {
+    throw new Error(`Atlas WASM binary not found: ${wasmPath}`)
+  }
+
+  return {
+    async inspect(
+      files: string[],
+      opts?: { schema?: string; dialect?: string; fileNames?: string[] },
+    ): Promise<AtlasResult> {
+      const command: AtlasCommand = {
+        type: 'inspect',
+        dialect: (opts?.dialect as AtlasCommand['dialect']) ?? 'postgres',
+        files,
+        fileNames: opts?.fileNames,
+        schema: opts?.schema,
+      }
+      return runCommand(wasmPath, db, command)
+    },
+
+    async diff(
+      from: string[],
+      to: string[],
+      opts?: { schema?: string; dialect?: string; renames?: AtlasRename[] },
+    ): Promise<AtlasResult> {
+      const command: AtlasCommand = {
+        type: 'diff',
+        dialect: (opts?.dialect as AtlasCommand['dialect']) ?? 'postgres',
+        from,
+        to,
+        schema: opts?.schema,
+        renames: opts?.renames,
+      }
+      return runCommand(wasmPath, db, command)
+    },
+
+    async close(): Promise<void> {
+      await db.close()
+    },
+  }
+}

package/src/types.ts

@@ -0,0 +1,305 @@
+// ── Atlas WASI command/result types ─────────────────────────────────
+// Hand-crafted from atlas/cmd/atlas-wasi/marshal.go (cycle-free flat types).
+// Schema fields use lowercase json tags from the flat marshaler.
+// Attr variants (Tag, Comment, Check) use PascalCase from map[string]string.
+
+/**
+ * A known rename (from @docs.previously tags) to pass to Atlas before diffing.
+ */
+export interface AtlasRename {
+  type: 'column' | 'table'
+  table: string
+  oldName: string
+  newName: string
+}
+
+/**
+ * A potential rename detected by Atlas during diff (drop+add pair with same type).
+ */
+export interface AtlasRenameCandidate {
+  type: 'column' | 'table'
+  table: string
+  oldName: string
+  newName: string
+  colType?: string
+}
+
+/**
+ * Command sent to Atlas WASI module via stdin.
+ */
+export interface AtlasCommand {
+  type: 'inspect' | 'diff' | 'apply'
+  dialect: 'postgres' | 'mysql' | 'sqlite'
+  schema?: string
+  files?: string[]
+  fileNames?: string[]
+  from?: string[]
+  to?: string[]
+  renames?: AtlasRename[]
+}
+
+/**
+ * A structured schema change description returned from Atlas diff.
+ */
+export interface AtlasChange {
+  type:
+    | 'add_table'
+    | 'drop_table'
+    | 'rename_table'
+    | 'add_column'
+    | 'drop_column'
+    | 'rename_column'
+    | 'modify_column'
+    | 'add_index'
+    | 'drop_index'
+    | 'add_view'
+    | 'drop_view'
+    | 'add_function'
+    | 'drop_function'
+  table: string
+  name?: string
+  detail?: string
+}
+
+/**
+ * Result returned from Atlas WASI module via stdout.
+ * Top-level fields use lowercase json tags.
+ */
+export interface AtlasResult {
+  schema?: AtlasRealm
+  statements?: string[]
+  changes?: AtlasChange[]
+  renameCandidates?: AtlasRenameCandidate[]
+  error?: string
+}
+
+// ── Schema types — lowercase (json tags in marshal.go flat types) ───
+
+/**
+ * A Realm describes a domain of schema resources (physical database instance).
+ * Maps to flatRealm in marshal.go.
+ */
+export interface AtlasRealm {
+  schemas: AtlasSchema[]
+  attrs?: AtlasAttr[]
+}
+
+/**
+ * A Schema describes a named database schema (e.g. "public").
+ * Maps to flatSchema in marshal.go.
+ */
+export interface AtlasSchema {
+  name: string
+  tables?: AtlasTable[]
+  views?: AtlasView[]
+  funcs?: AtlasFunc[]
+  procs?: AtlasProc[]
+  attrs?: AtlasAttr[]
+}
+
+/**
+ * A Table represents a table definition.
+ * Maps to flatTable in marshal.go.
+ */
+export interface AtlasTable {
+  name: string
+  columns?: AtlasColumn[]
+  indexes?: AtlasIndex[]
+  primary_key?: AtlasIndex
+  foreign_keys?: AtlasForeignKey[]
+  attrs?: AtlasAttr[]
+  triggers?: AtlasTrigger[]
+}
+
+/**
+ * A Column represents a column definition.
+ * Maps to flatColumn in marshal.go.
+ */
+export interface AtlasColumn {
+  name: string
+  type?: AtlasColumnType
+  default?: AtlasExpr
+  attrs?: AtlasAttr[]
+}
+
+/**
+ * ColumnType represents a column type.
+ * Maps to flatColumnType in marshal.go.
+ * The `T` field is the type name (e.g., "bigint", "text").
+ */
+export type TypeCategory =
+  | 'string'
+  | 'integer'
+  | 'float'
+  | 'decimal'
+  | 'boolean'
+  | 'time'
+  | 'binary'
+  | 'json'
+  | 'uuid'
+  | 'spatial'
+  | 'enum'
+  | 'composite'
+  | 'unknown'
+
+export interface AtlasColumnType {
+  T?: string
+  raw?: string
+  null?: boolean
+  /** Normalized type category — dialect-independent */
+  category?: TypeCategory
+  /** Whether this is a user-defined type (enum, composite, domain) */
+  is_custom?: boolean
+  /** Enum values (when category is 'enum') */
+  enum_values?: string[]
+  /** Composite type fields (when category is 'composite') */
+  composite_fields?: Array<{ name: string; type: string }>
+}
+
+/**
+ * An Index represents an index definition.
+ * Maps to flatIndex in marshal.go.
+ */
+export interface AtlasIndex {
+  name?: string
+  unique?: boolean
+  parts?: AtlasIndexPart[]
+  attrs?: AtlasAttr[]
+}
+
+/**
+ * An IndexPart represents a single part of an index.
+ * Maps to flatIndexPart in marshal.go.
+ */
+export interface AtlasIndexPart {
+  column?: string
+  desc?: boolean
+  attrs?: AtlasAttr[]
+}
+
+/**
+ * A ForeignKey represents a foreign key constraint.
+ * Maps to flatForeignKey in marshal.go.
+ */
+export interface AtlasForeignKey {
+  symbol?: string
+  columns?: string[]
+  ref_columns?: string[]
+  ref_table?: string
+  on_update?: string
+  on_delete?: string
+}
+
+/**
+ * A View represents a view definition.
+ * Maps to flatView in marshal.go.
+ */
+export interface AtlasView {
+  name: string
+  def?: string
+  columns?: AtlasColumn[]
+  attrs?: AtlasAttr[]
+}
+
+/**
+ * A Func represents a function definition.
+ * Maps to flatFunc in marshal.go.
+ */
+export interface AtlasFunc {
+  name: string
+  args?: AtlasFuncArg[]
+  ret?: AtlasColumnType
+  lang?: string
+  attrs?: AtlasAttr[]
+}
+
+export interface AtlasFuncArg {
+  name?: string
+  type?: AtlasColumnType
+  mode?: string
+}
+
+/**
+ * A Proc represents a procedure definition.
+ * Maps to flatProc in marshal.go.
+ */
+export interface AtlasProc {
+  name: string
+  attrs?: AtlasAttr[]
+}
+
+/**
+ * A Trigger represents a trigger definition.
+ * Maps to flatTrigger in marshal.go.
+ */
+export interface AtlasTrigger {
+  name: string
+  attrs?: AtlasAttr[]
+}
+
+/**
+ * An expression in schema DDL.
+ * Go serializes RawExpr as { X: string }, Literal as { V: string }.
+ */
+export type AtlasExpr = { X: string } | { V: string } | unknown
+
+// ── Attr union — PascalCase (map[string]string in Go marshal) ───────
+
+/**
+ * Attrs is a heterogeneous array (Tag, Comment, Check all mixed).
+ * We model the known variants as a discriminated union with a fallback.
+ * Note: Attr fields use PascalCase (serialized via map[string]string in Go).
+ */
+export type AtlasAttr = AtlasTag | AtlasComment | AtlasCheck | Record<string, unknown>
+
+/**
+ * Tag attr. Serialized as { Name: string, Args: string }.
+ * PascalCase because Go marshal uses map[string]string{"Name": ..., "Args": ...}.
+ */
+export interface AtlasTag {
+  Name: string
+  Args: string
+}
+
+/**
+ * Comment attr. Serialized as { Text: string }.
+ */
+export interface AtlasComment {
+  Text: string
+}
+
+/**
+ * Check constraint attr. Serialized as { Name?: string, Expr: string }.
+ */
+export interface AtlasCheck {
+  Name?: string
+  Expr: string
+}
+
+// ── Helper functions ────────────────────────────────────────────────
+
+/**
+ * Type guard: returns true if the given attr is a Tag.
+ * Tags have `Name` and `Args` fields but NOT an `Expr` field
+ * (which would indicate a Check constraint instead).
+ */
+export function isTag(attr: AtlasAttr): attr is AtlasTag {
+  return (
+    typeof attr === 'object' &&
+    attr !== null &&
+    'Name' in attr &&
+    typeof (attr as AtlasTag).Name === 'string' &&
+    'Args' in attr &&
+    typeof (attr as AtlasTag).Args === 'string' &&
+    !('Expr' in attr)
+  )
+}
+
+/**
+ * Extract all Tag attrs from a mixed Attrs array.
+ * Returns an empty array if attrs is undefined or empty.
+ */
+export function findTags(attrs?: AtlasAttr[]): AtlasTag[] {
+  if (!attrs) return []
+  return attrs.filter(isTag)
+}