@pikku/deploy-standalone 0.12.13 → 0.12.19

package/src/runtime/cli.test.ts

@@ -0,0 +1,222 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert'
+import { mkdtempSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  parseStandaloneCommand,
+  resolveMigrationsDir,
+  runDbCommand,
+  runBackupCommand,
+  runStandaloneCommand,
+  MIGRATIONS_DIR_ENV,
+  type StandaloneSqliteDb,
+} from './cli.js'
+
+const collector = () => {
+  const lines: string[] = []
+  return { lines, out: { write: (line: string) => lines.push(line) } }
+}
+
+const parse = (argv: string[], overrides: Record<string, unknown> = {}) => {
+  const { lines, out } = collector()
+  const command = parseStandaloneCommand(argv, {
+    version: '1.2.3',
+    hasDb: true,
+    engine: 'sqlite',
+    write: out.write,
+    ...overrides,
+  } as never)
+  return { command, lines }
+}
+
+describe('parseStandaloneCommand', () => {
+  it('no arguments means serve, so `node bundle.js` keeps its meaning', () => {
+    assert.deepEqual(parse([]).command, { kind: 'serve' })
+    assert.deepEqual(parse(['serve']).command, { kind: 'serve' })
+  })
+
+  it('version prints and stops before anything is opened', () => {
+    const { command, lines } = parse(['version'])
+    assert.deepEqual(command, { kind: 'exit', code: 0 })
+    assert.deepEqual(lines, ['1.2.3'])
+  })
+
+  it('help lists the db commands only when there is a database', () => {
+    assert.match(parse(['help']).lines.join('\n'), /db migrate/)
+    assert.doesNotMatch(
+      parse(['help'], { hasDb: false, engine: undefined }).lines.join('\n'),
+      /db migrate/
+    )
+  })
+
+  it('backup is offered on sqlite and refused on postgres', () => {
+    assert.deepEqual(parse(['backup', '/tmp/x.db']).command, {
+      kind: 'backup',
+      destination: '/tmp/x.db',
+    })
+
+    const pg = parse(['backup', '/tmp/x.db'], { engine: 'postgres' })
+    assert.deepEqual(pg.command, { kind: 'exit', code: 1 })
+    assert.match(pg.lines.join('\n'), /pg_dump/)
+  })
+
+  it('a db command on a build with no database fails by saying so', () => {
+    const { command, lines } = parse(['db', 'migrate'], {
+      hasDb: false,
+      engine: undefined,
+    })
+    assert.deepEqual(command, { kind: 'exit', code: 1 })
+    assert.match(lines.join('\n'), /opens no database/)
+  })
+
+  it('an unknown db action names the ones that exist', () => {
+    const { command, lines } = parse(['db', 'rollback'])
+    assert.deepEqual(command, { kind: 'exit', code: 1 })
+    assert.match(lines.join('\n'), /Expected migrate or status/)
+  })
+
+  it('an unknown command exits non-zero with the usage', () => {
+    const { command, lines } = parse(['start'])
+    assert.deepEqual(command, { kind: 'exit', code: 1 })
+    assert.match(lines.join('\n'), /Unknown command: start/)
+    assert.match(lines.join('\n'), /Usage:/)
+  })
+})
+
+describe('resolveMigrationsDir', () => {
+  it('defaults to the directory beside the bundle', () => {
+    assert.equal(resolveMigrationsDir('/app/db/sqlite', {}), '/app/db/sqlite')
+  })
+
+  it('an operator who moved them wins', () => {
+    assert.equal(
+      resolveMigrationsDir('/app/db/sqlite', {
+        [MIGRATIONS_DIR_ENV]: '/srv/migrations',
+      }),
+      '/srv/migrations'
+    )
+  })
+})
+
+const sqliteFixture = (
+  migrations: Record<string, string>
+): StandaloneSqliteDb => {
+  const root = mkdtempSync(join(tmpdir(), 'pikku-cli-'))
+  const migrationsDir = join(root, 'db', 'sqlite')
+  mkdirSync(migrationsDir, { recursive: true })
+  for (const [name, sql] of Object.entries(migrations)) {
+    writeFileSync(join(migrationsDir, name), sql)
+  }
+  return {
+    engine: 'sqlite',
+    migrationsDir,
+    databaseFile: join(root, 'pikku.db'),
+  }
+}
+
+describe('the sqlite db commands', () => {
+  const migrations = {
+    '0001_widgets.sql': 'CREATE TABLE widget (id TEXT PRIMARY KEY);',
+    '0002_labels.sql': 'ALTER TABLE widget ADD COLUMN label TEXT;',
+  }
+
+  it('migrate applies every file, and a second run applies none', async () => {
+    const db = sqliteFixture(migrations)
+
+    const first = collector()
+    await runDbCommand('migrate', db, first.out)
+    assert.deepEqual(first.lines, [
+      'applied  0001_widgets.sql',
+      'applied  0002_labels.sql',
+      'Applied 2 migration(s).',
+    ])
+
+    const second = collector()
+    await runDbCommand('migrate', db, second.out)
+    assert.deepEqual(second.lines, ['Already up to date (2 applied previously).'])
+  })
+
+  it('status separates what is applied from what is waiting', async () => {
+    const db = sqliteFixture({ '0001_widgets.sql': migrations['0001_widgets.sql']! })
+
+    await runDbCommand('migrate', db)
+    writeFileSync(
+      join(db.migrationsDir, '0002_labels.sql'),
+      migrations['0002_labels.sql']!
+    )
+
+    const { lines, out } = collector()
+    await runDbCommand('status', db, out)
+    assert.match(lines[0]!, /^applied {2}0001_widgets\.sql {2}\S/)
+    assert.equal(lines[1], 'pending  0002_labels.sql')
+    assert.equal(lines[2], '1 applied, 1 pending.')
+  })
+
+  it('an edited migration is refused rather than silently re-run', async () => {
+    const db = sqliteFixture(migrations)
+    await runDbCommand('migrate', db)
+
+    writeFileSync(
+      join(db.migrationsDir, '0001_widgets.sql'),
+      'CREATE TABLE widget (id TEXT PRIMARY KEY, tampered TEXT);'
+    )
+
+    await assert.rejects(
+      () => runDbCommand('migrate', db),
+      /PKU-DB-DRIFT/
+    )
+  })
+
+  it('backup writes a database a fresh process can open', async () => {
+    const db = sqliteFixture(migrations)
+    await runDbCommand('migrate', db)
+
+    const destination = join(db.migrationsDir, '..', '..', 'copy.db')
+    const { lines, out } = collector()
+    await runBackupCommand(destination, db, out)
+
+    assert.ok(existsSync(destination))
+    assert.match(lines.join('\n'), /Copied /)
+
+    const copy = collector()
+    await runDbCommand('status', { ...db, databaseFile: destination }, copy.out)
+    assert.equal(copy.lines.at(-1), '2 applied, 0 pending.')
+  })
+})
+
+describe('runStandaloneCommand', () => {
+  it('hands serve back to the caller rather than doing anything', async () => {
+    assert.equal(
+      await runStandaloneCommand({ kind: 'serve' }, undefined),
+      'serve'
+    )
+  })
+
+  it('a completed command stops the caller from opening a port', async () => {
+    const db = sqliteFixture({
+      '0001_widgets.sql': 'CREATE TABLE widget (id TEXT PRIMARY KEY);',
+    })
+    const { out } = collector()
+    assert.equal(
+      await runStandaloneCommand({ kind: 'db', action: 'migrate' }, db, out),
+      'done'
+    )
+  })
+
+  it('backup on a postgres build is refused, not attempted', async () => {
+    await assert.rejects(
+      () =>
+        runStandaloneCommand(
+          { kind: 'backup', destination: '/tmp/x' },
+          {
+            engine: 'postgres',
+            migrationsDir: '/tmp',
+            sql: {} as never,
+          }
+        ),
+      /only available on a SQLite build/
+    )
+  })
+})

package/src/runtime/cli.ts

@@ -0,0 +1,311 @@
+/**
+ * The command line a shipped standalone artifact answers on.
+ *
+ * A hosted deploy has a control plane to run migrations and read state; a
+ * standalone artifact is a file on a machine, and the operator holding it has
+ * nothing but the process itself. Without this, applying a migration to the
+ * database the bundle opens means installing the CLI and a checkout beside it
+ * on the production host, which is the thing shipping a single bundle was
+ * supposed to remove.
+ *
+ * The set is deliberately small. `serve` is the default so `node bundle.js`
+ * keeps meaning what it has always meant, and every other command exits rather
+ * than opening a port.
+ *
+ * Notably absent is a way to invoke an RPC. A running server already answers
+ * them over its own wire with auth, sessions and middleware applied; an
+ * in-process invoke would answer them with none of that, which on a production
+ * box is a way to run any function as nobody.
+ */
+import type { MigrationExecutor } from '@pikku/migrator-sql'
+import type { PostgresMigrationClient } from '@pikku/migrator-sql/postgres'
+
+/** Where the migrations live, when the operator has moved them. */
+export const MIGRATIONS_DIR_ENV = 'PIKKU_MIGRATIONS_DIR'
+
+export interface StandaloneSqliteDb {
+  engine: 'sqlite'
+  migrationsDir: string
+  /** The file the app itself opens, so a migration cannot target another one. */
+  databaseFile: string
+}
+
+/**
+ * The postgres.js tagged template the app is already connected through.
+ *
+ * Taken rather than constructed so a migration runs on the app's own pool: a
+ * second connection would need the credentials resolved twice and could reach a
+ * different database than the one the next `serve` opens.
+ */
+export interface PostgresSql {
+  unsafe(query: string, parameters?: unknown[]): Promise<any> & {
+    simple(): Promise<any>
+  }
+  begin<T>(handler: (sql: PostgresSql) => Promise<T>): Promise<T>
+}
+
+export interface StandalonePostgresDb {
+  engine: 'postgres'
+  migrationsDir: string
+  sql: PostgresSql
+}
+
+export type StandaloneDb = StandaloneSqliteDb | StandalonePostgresDb
+
+export type StandaloneCommand =
+  | { kind: 'serve' }
+  | { kind: 'db'; action: 'migrate' | 'status' }
+  | { kind: 'backup'; destination: string }
+  | { kind: 'exit'; code: number }
+
+export interface ParseOptions {
+  version: string
+  /** False for a build with no database, whose db commands cannot be answered. */
+  hasDb: boolean
+  engine?: 'sqlite' | 'postgres'
+  write?: (line: string) => void
+}
+
+const usage = (hasDb: boolean, engine?: 'sqlite' | 'postgres'): string =>
+  [
+    'Usage: <bundle> [command]',
+    '',
+    '  serve            Start the server. The default when no command is given.',
+    '  version          Print the version this artifact was built from.',
+    '  help             Print this.',
+    ...(hasDb
+      ? [
+          '',
+          '  db migrate       Apply pending migrations to the database this build opens.',
+          '  db status        List applied and pending migrations.',
+          ...(engine === 'sqlite'
+            ? ['  backup <path>    Copy the database to <path>, consistently.']
+            : []),
+        ]
+      : []),
+    '',
+    'Environment:',
+    `  ${MIGRATIONS_DIR_ENV}   Migrations directory, when not the one beside the bundle.`,
+  ].join('\n')
+
+export function parseStandaloneCommand(
+  argv: string[],
+  options: ParseOptions
+): StandaloneCommand {
+  const write = options.write ?? ((line: string) => console.log(line))
+  const [command, ...rest] = argv
+
+  if (command === undefined || command === 'serve') return { kind: 'serve' }
+
+  if (command === 'version' || command === '--version' || command === '-v') {
+    write(options.version)
+    return { kind: 'exit', code: 0 }
+  }
+
+  if (command === 'help' || command === '--help' || command === '-h') {
+    write(usage(options.hasDb, options.engine))
+    return { kind: 'exit', code: 0 }
+  }
+
+  const needsDb = command === 'db' || command === 'backup'
+  if (needsDb && !options.hasDb) {
+    write(
+      `This build opens no database, so there is nothing for \`${command}\` to act on.`
+    )
+    return { kind: 'exit', code: 1 }
+  }
+
+  if (command === 'db') {
+    const action = rest[0]
+    if (action === 'migrate' || action === 'status') {
+      return { kind: 'db', action }
+    }
+    write(
+      action === undefined
+        ? 'db needs an action: migrate or status.'
+        : `Unknown db action: ${action}. Expected migrate or status.`
+    )
+    return { kind: 'exit', code: 1 }
+  }
+
+  if (command === 'backup') {
+    // Postgres has pg_dump, which understands roles, extensions and large
+    // objects that copying bytes out from in here would silently drop. Offering
+    // the word for both engines would promise a backup on one of them that is
+    // not one.
+    if (options.engine !== 'sqlite') {
+      write(
+        'backup is for the SQLite builds, whose database is a file this process owns. Use pg_dump against DATABASE_URL.'
+      )
+      return { kind: 'exit', code: 1 }
+    }
+    const destination = rest[0]
+    if (!destination) {
+      write('backup needs a path to write the copy to.')
+      return { kind: 'exit', code: 1 }
+    }
+    return { kind: 'backup', destination }
+  }
+
+  write(`Unknown command: ${command}\n\n${usage(options.hasDb, options.engine)}`)
+  return { kind: 'exit', code: 1 }
+}
+
+/**
+ * The migrations directory, honouring an operator who keeps them elsewhere.
+ *
+ * `bundleDir` is where the build put them, which is the same `db/<engine>/`
+ * path Fabric's build container stages into an artifact — so an artifact from
+ * either producer answers `db migrate` without being told where to look.
+ */
+export const resolveMigrationsDir = (
+  bundleDir: string,
+  env: Record<string, string | undefined> = process.env
+): string => env[MIGRATIONS_DIR_ENV] ?? bundleDir
+
+/**
+ * The migration executor for whichever database this build opens.
+ *
+ * Both drivers are reached by dynamic import so a SQLite build never carries
+ * the Postgres one into its bundle, and vice versa.
+ */
+const executorFor = async (
+  db: StandaloneDb
+): Promise<{ executor: MigrationExecutor; close: () => void }> => {
+  if (db.engine === 'sqlite') {
+    const { SqliteMigrationExecutor, loadSqliteRuntime } = await import(
+      '@pikku/migrator-sql/sqlite'
+    )
+    const runtime = await loadSqliteRuntime()
+    const handle = runtime.open(db.databaseFile)
+    return {
+      executor: new SqliteMigrationExecutor(handle),
+      close: () => handle.close(),
+    }
+  }
+
+  const { PostgresMigrationExecutor } = await import(
+    '@pikku/migrator-sql/postgres'
+  )
+  return {
+    executor: new PostgresMigrationExecutor(postgresClient(db.sql)),
+    close: () => {},
+  }
+}
+
+/**
+ * A `PostgresMigrationClient` over the app's own postgres.js connection.
+ *
+ * `begin` is what makes a failed migration roll back: postgres.js hands the
+ * handler a single reserved connection, so the DDL and the bookkeeping row are
+ * one transaction rather than statements a pool may spread across three.
+ *
+ * `simple()` on the plain path is deliberate — a migration file is many
+ * statements, and the extended protocol accepts only one per message.
+ */
+const postgresClient = (sql: PostgresSql): PostgresMigrationClient => ({
+  async query<T = unknown>(text: string, params?: unknown[]) {
+    const rows = (await sql.unsafe(text, params ?? [])) as T[]
+    return { rows }
+  },
+  async exec(text: string) {
+    return sql.unsafe(text).simple()
+  },
+  begin<T>(handler: (client: PostgresMigrationClient) => Promise<T>) {
+    return sql.begin((tx) => handler(postgresClient(tx)))
+  },
+})
+
+export interface CommandOutput {
+  write(line: string): void
+}
+
+const stdout: CommandOutput = { write: (line) => console.log(line) }
+
+export async function runDbCommand(
+  action: 'migrate' | 'status',
+  db: StandaloneDb,
+  out: CommandOutput = stdout
+): Promise<void> {
+  const { migrate, pendingMigrations } = await import('@pikku/migrator-sql')
+  const { executor, close } = await executorFor(db)
+
+  try {
+    if (action === 'migrate') {
+      const { applied, skipped } = await migrate(executor, db.migrationsDir)
+      for (const name of applied) out.write(`applied  ${name}`)
+      out.write(
+        applied.length === 0
+          ? `Already up to date (${skipped.length} applied previously).`
+          : `Applied ${applied.length} migration(s).`
+      )
+      return
+    }
+
+    await executor.ensureTrackingTable()
+    const applied = await executor.getApplied()
+    const pending = pendingMigrations(db.migrationsDir, applied)
+
+    for (const row of applied) {
+      out.write(`applied  ${row.name}  ${row.applied_at}`)
+    }
+    for (const name of pending) out.write(`pending  ${name}`)
+    out.write(`${applied.length} applied, ${pending.length} pending.`)
+  } finally {
+    close()
+  }
+}
+
+/**
+ * Copy the SQLite database somewhere else, while the app may be running.
+ *
+ * `VACUUM INTO` rather than copying the file: a plain copy taken while another
+ * process is mid-write captures a torn page and a write-ahead log it has no
+ * copy of, which restores as a corrupt database and only says so later.
+ */
+export async function runBackupCommand(
+  destination: string,
+  db: StandaloneSqliteDb,
+  out: CommandOutput = stdout
+): Promise<void> {
+  const { loadSqliteRuntime } = await import('@pikku/migrator-sql/sqlite')
+  const runtime = await loadSqliteRuntime()
+  const handle = runtime.open(db.databaseFile)
+  try {
+    handle.exec(`VACUUM INTO '${destination.replace(/'/g, "''")}'`)
+    out.write(`Copied ${db.databaseFile} to ${destination}.`)
+  } finally {
+    handle.close()
+  }
+}
+
+/**
+ * Run whatever the argv asked for, and say whether the caller should serve.
+ *
+ * The database is passed already open, because the entry has to open it the one
+ * way the app does — a command that resolved its own connection could migrate a
+ * different database than the next `serve` reads.
+ */
+export async function runStandaloneCommand(
+  command: StandaloneCommand,
+  db: StandaloneDb | undefined,
+  out: CommandOutput = stdout
+): Promise<'serve' | 'done'> {
+  if (command.kind === 'serve') return 'serve'
+  if (command.kind === 'exit') process.exit(command.code)
+
+  if (!db) {
+    throw new Error('This build opens no database.')
+  }
+
+  if (command.kind === 'db') {
+    await runDbCommand(command.action, db, out)
+    return 'done'
+  }
+
+  if (db.engine !== 'sqlite') {
+    throw new Error('backup is only available on a SQLite build.')
+  }
+  await runBackupCommand(command.destination, db, out)
+  return 'done'
+}

package/src/runtime/index.ts

@@ -11,3 +11,21 @@ export {
   watchParentProcess,
 } from './parent-watch.js'
 export type { ParentWatch, ParentWatchOptions } from './parent-watch.js'
+
+export {
+  parseStandaloneCommand,
+  runStandaloneCommand,
+  runDbCommand,
+  runBackupCommand,
+  resolveMigrationsDir,
+  MIGRATIONS_DIR_ENV,
+} from './cli.js'
+export type {
+  StandaloneCommand,
+  StandaloneDb,
+  StandaloneSqliteDb,
+  StandalonePostgresDb,
+  PostgresSql,
+  CommandOutput,
+  ParseOptions,
+} from './cli.js'