@deterministic-code/migraters 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1 @@
+Migrate executables for deterministic-code.

package/cli.yaml

@@ -0,0 +1,264 @@
+# Source of truth for migrate command names, argv layout, and --help copy.
+# TypeScript, Rust, and C# parsers must match this file.
+# IMigrater (setup, up, down, create) lives in api.yaml. SQL spelling is a provider detail.
+# Help templates in shared/templates/help are generated:
+#   npm run generate:help
+# Usage line for each verb: `Usage: migrate-<verb> ` + args in order.
+
+command: migrate-{verb}
+
+providers:
+  - sqlite
+  - postgres
+  - mysql
+  - sqlserver
+  - oracle
+
+# Lookup: lowercase, strip spaces/underscores/hyphens, then match a provider or alias.
+provider_aliases:
+  sqlite3: sqlite
+  mariadb: mysql
+  postgresql: postgres
+  pg: postgres
+  mssql: sqlserver
+  mssqlserver: sqlserver
+  ora: oracle
+
+exit_codes:
+  success: 0
+  usage: 2
+  runtime: 1
+
+help:
+  - -h
+  - --help
+
+help_stream: stderr
+
+# Canonical argv is `--flag value`. `--flag=value` is optional extra syntax.
+aliases:
+  --migrate-path: --migrations-path
+  --migrate-root: --migrations-root
+
+env_var_list_separator: " / "
+
+migrations:
+  path_flag: --migrations-path
+  root_flag: --migrations-root
+  root_default: sql
+  layout: "<root>/<provider>/migrations"
+  discovery: top_level_up_down_pairs
+  missing_directory: errors/migrate-path-not-dir
+
+create:
+  name_pattern: "^[a-z][a-z0-9_]*$"
+  sequence_digits: 4
+
+checksum:
+  algorithm: sha256
+  drift_bypass: MIGRATE_ALLOW_CHECKSUM_DRIFT
+
+# Documented when a command sets show_connection_env: true.
+connection_environment:
+  sqlite: [SQLITE_PATH, DB_PATH]
+  postgres: [PG_CONNECTION_STRING, DATABASE_URL]
+  mysql: [MYSQL_URL, DATABASE_URL]
+  sqlserver: [MSSQL_URL, DATABASE_URL]
+  oracle: [ORACLE_CONNECT_STRING, DATABASE_URL]
+
+commands:
+  - verb: init
+    summary: |
+      Selects the dialects this tree will compile and install. Repeat --dialect
+      once per provider. Re-running replaces the previous set. --all restores
+      every dialect. Does not take --connection.
+    examples: |
+      {{command}} --dialect sqlite --dialect postgres
+      {{command}} --dialect oracle
+      {{command}} --all
+    args:
+      - flag: --dialect
+        placeholder: providers
+        required: false
+        help: "Dialect to enable. Repeat for each dialect. Aliases from this file apply."
+      - flag: --all
+        required: false
+        help: "Enable every dialect. Restores the committed full-provider set."
+
+  - verb: setup
+    show_connection_env: true
+    summary: |
+      Creates the bookkeeping tables (migrates, migrate_logs) for the chosen dialect
+      and the migrations directory (mkdir -p). Idempotent — re-running against an
+      already-setup database is a no-op. For sqlite, also mkdir -p of the parent
+      directory of --connection so a fresh-tree path like ./.test/foo.sqlite works.
+    examples: |
+      # sqlite — bare path or sqlite:// URL; both create a file on disk.
+      {{command}} --provider sqlite --connection ./app.sqlite
+      {{command}} --provider sqlite --connection sqlite:///absolute/path/app.sqlite
+
+      # postgres — URL or keyword form.
+      {{command}} --provider postgres --connection postgresql://user:pass@host:5432/dbname
+
+      # mysql — URL form.
+      {{command}} --provider mysql --connection mysql://user:pass@host:3306/dbname
+
+      # sqlserver / oracle — pass a driver-native connection string.
+      {{command}} --provider sqlserver --connection "Server=host;Database=dbname;User Id=user;Password=pass;"
+      {{command}} --provider oracle   --connection "user/pass@host:1521/service"
+
+      # env-var fallback when --connection is omitted:
+      SQLITE_PATH=./app.sqlite       {{command}} --provider sqlite
+      DATABASE_URL=postgresql://...  {{command}} --provider postgres
+      DATABASE_URL=mysql://...       {{command}} --provider mysql
+
+      # explicit in-memory sqlite:
+      {{command}} --provider sqlite --connection :memory:
+    args:
+      - flag: --provider
+        placeholder: providers
+        required: true
+        help: "Database dialect. Required."
+      - flag: --connection
+        placeholder: url
+        required: true
+        help: "Connection string. Required (or set the per-dialect env var below)."
+      - flag: --migrations-path
+        placeholder: dir
+        required: false
+        help: "Migrations directory (default: ./sql/<dialect>/migrations)."
+      - flag: --and-up
+        required: false
+        help: "After setup, immediately invoke migrate-up so the chain is applied in one step."
+
+  - verb: up
+    show_connection_env: true
+    summary: |
+      Applies ALL pending migrations in sequence, each in its own transaction.
+    examples: |
+      # sqlite — bare path or sqlite:// URL; both create a file on disk.
+      {{command}} --provider sqlite --connection ./app.sqlite
+      {{command}} --provider sqlite --connection sqlite:///absolute/path/app.sqlite
+
+      # postgres — URL or keyword form.
+      {{command}} --provider postgres --connection postgresql://user:pass@host:5432/dbname
+
+      # mysql — URL form.
+      {{command}} --provider mysql --connection mysql://user:pass@host:3306/dbname
+
+      # sqlserver / oracle — pass a driver-native connection string.
+      {{command}} --provider sqlserver --connection "Server=host;Database=dbname;User Id=user;Password=pass;"
+      {{command}} --provider oracle   --connection "user/pass@host:1521/service"
+
+      # env-var fallback when --connection is omitted:
+      SQLITE_PATH=./app.sqlite       {{command}} --provider sqlite
+      DATABASE_URL=postgresql://...  {{command}} --provider postgres
+
+      # custom migrations layout (default looks under sql/<dialect>/migrations):
+      {{command}} --provider sqlite --connection ./app.sqlite --migrations-path ./db/changes/sqlite
+      {{command}} --provider sqlite --connection ./app.sqlite --migrations-root ./db/changes
+
+      # one-shot: apply the next pending migration only, then exit.
+      {{command}} --provider sqlite --connection ./app.sqlite --one
+    args:
+      - flag: --provider
+        placeholder: providers
+        required: true
+        help: "Database dialect. Required."
+      - flag: --connection
+        placeholder: url
+        required: true
+        help: "Connection string. Required (or set the per-dialect env var below)."
+      - flag: --migrations-path
+        placeholder: dir
+        required: false
+        help: "Full path to the migrations directory (e.g. sql/sqlite/migrations)."
+      - flag: --migrations-root
+        placeholder: dir
+        required: false
+        help: |
+          Root prefix; the script then looks at <migrations-root>/<dialect>/migrations.
+          Defaults to 'sql'. Ignored when --migrations-path is also set.
+      - flag: --one
+        required: false
+        help: "Apply only the next pending migration, then exit. Default is to apply all pending migrations."
+
+  - verb: down
+    show_connection_env: true
+    summary: |
+      Rolls back the MOST RECENTLY applied migration (one step). DESTRUCTIVE: prints a
+      random 4-letter uppercase token on stderr and refuses to proceed unless the
+      operator types it back on stdin (or passes --confirm <TOKEN> matching it).
+    examples: |
+      # sqlite — bare path or sqlite:// URL.
+      {{command}} --provider sqlite --connection ./app.sqlite
+      {{command}} --provider sqlite --connection sqlite:///absolute/path/app.sqlite
+
+      # postgres — URL or keyword form.
+      {{command}} --provider postgres --connection postgresql://user:pass@host:5432/dbname
+
+      # mysql — URL form.
+      {{command}} --provider mysql --connection mysql://user:pass@host:3306/dbname
+
+      # sqlserver / oracle — pass a driver-native connection string.
+      {{command}} --provider sqlserver --connection "Server=host;Database=dbname;User Id=user;Password=pass;"
+      {{command}} --provider oracle   --connection "user/pass@host:1521/service"
+
+      # env-var fallback when --connection is omitted:
+      SQLITE_PATH=./app.sqlite       {{command}} --provider sqlite
+      DATABASE_URL=postgresql://...  {{command}} --provider postgres
+
+      # custom migrations layout (default looks under sql/<dialect>/migrations):
+      {{command}} --provider sqlite --connection ./app.sqlite --migrations-path ./db/changes/sqlite
+    args:
+      - flag: --provider
+        placeholder: providers
+        required: true
+        help: "Database dialect. Required."
+      - flag: --connection
+        placeholder: url
+        required: true
+        help: "Connection string. Required (or set the per-dialect env var below)."
+      - flag: --migrations-path
+        placeholder: dir
+        required: false
+        help: "Full path to the migrations directory."
+      - flag: --migrations-root
+        placeholder: dir
+        required: false
+        help: |
+          Root prefix; the script then looks at <migrations-root>/<dialect>/migrations.
+          Defaults to 'sql'. Ignored when --migrations-path is also set.
+      - flag: --confirm
+        placeholder: TOKEN
+        required: false
+        help: |
+          Skip the interactive prompt. The TOKEN must match the value
+          printed on stderr at runtime — there is no fixed bypass value.
+
+  - verb: create
+    summary: |
+      Creates a new <NNNN>_<name>_up.sql + <NNNN>_<name>_down.sql pair scaffolded
+      with TODO placeholders. NNNN is one greater than the highest 1-4-digit
+      sequence prefix already present in the migrations directory (starts at 0001).
+      Legacy timestamp-prefixed filenames are ignored for numbering.
+    examples: |
+      {{command}} --provider sqlite --name add_users
+      {{command}} --provider postgres --name backfill_email_lower --migrations-path ./db/changes/postgres
+    args:
+      - flag: --provider
+        placeholder: providers
+        required: true
+        help: "Database dialect. Required."
+      - flag: --name
+        placeholder: snake_case_slug
+        required: true
+        help: |
+          snake_case slug for the new migration. Required. Must
+          match /^[a-z][a-z0-9_]*$/.
+      - flag: --migrations-path
+        placeholder: dir
+        required: false
+        help: |
+          Migrations directory (default: ./sql/<dialect>/migrations).
+          Created with mkdir -p if it does not exist.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deterministic-code/migraters",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "TypeScript migrate executables for deterministic-code.",
   "type": "module",
   "exports": {
@@ -19,14 +19,11 @@
   },
   "files": [
     "dist",
-    "src",
     "cli.yaml",
-    "bundle.yaml",
-    "tsconfig.build.json"
+    "bundle.yaml"
   ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && cp -R ../shared/templates dist/templates",
-    "prepare": "npm run build",
     "typecheck": "tsc -p tsconfig.build.json --noEmit",
     "test": "vitest run --coverage",
     "test:proof": "vitest run --config vitest.proof.config.ts",
@@ -76,5 +73,9 @@
     "prettier": "^3.9.6",
     "typescript": "^5.8.0",
     "vitest": "^3.2.4"
-  }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
 }

package/src/abstractions/migrater.ts

@@ -1,13 +0,0 @@
-export type SetupArg = { connection: string; migrationsPath: string };
-export type UpArg = { connection: string; migrationsPath: string; one?: boolean };
-export type DownArg = { connection: string; migrationsPath: string };
-export type CreateArg = { name: string; migrationsPath: string };
-export type CreateResponse = { upName: string; downName: string };
-
-export interface IMigrater {
-  readonly name: string;
-  setup(args: SetupArg): Promise<void>;
-  up(args: UpArg): Promise<string[]>;
-  down(args: DownArg): Promise<string | null>;
-  create(args: CreateArg): Promise<CreateResponse>;
-}

package/src/abstractions/sql-dialect-base.ts

@@ -1,36 +0,0 @@
-import type { SqlDialect } from '../sql.ts';
-import type { ISqlDialect } from './sql-dialect.ts';
-
-export abstract class SqlDialectBase implements ISqlDialect {
-  abstract readonly name: SqlDialect;
-  abstract readonly connectionEnvironmentVariables: readonly string[];
-  abstract readonly migratesDdl: string;
-  abstract readonly migrateLogsDdl: string;
-  readonly usesLastInsertRowid: boolean = false;
-
-  quoteIdent(ident: string): string {
-    return `"${ident}"`;
-  }
-
-  nowExpr(): string {
-    return 'CURRENT_TIMESTAMP';
-  }
-
-  limitClause(n: number): string {
-    return `LIMIT ${n}`;
-  }
-
-  translatePlaceholders(sql: string): string {
-    return sql;
-  }
-
-  async prerequisiteError(_connection: string): Promise<string | null> {
-    return null;
-  }
-
-  async prepareSetup(_connection: string): Promise<void> {}
-
-  abstract createClient(
-    connection: string,
-  ): Promise<import('../migration-client.ts').MigrationClient>;
-}

package/src/abstractions/sql-dialect-factory.ts

@@ -1,29 +0,0 @@
-import { normalizeDialect, type SqlDialect } from '../sql.ts';
-import type { ISqlDialect } from './sql-dialect.ts';
-
-const VALID = 'sqlite, mysql, postgres, sqlserver, oracle';
-
-export class SqlDialectFactory {
-  private readonly byName: Map<SqlDialect, ISqlDialect>;
-
-  constructor(dialects: readonly ISqlDialect[]) {
-    this.byName = new Map(dialects.map((d) => [d.name, d]));
-  }
-
-  tryGet(raw: string): ISqlDialect | undefined {
-    const key = normalizeDialect(raw);
-    return key ? this.byName.get(key) : undefined;
-  }
-
-  get(raw: string): ISqlDialect {
-    const dialect = this.tryGet(raw);
-    if (!dialect) {
-      throw new Error(`Unknown SQL dialect "${raw}". Valid: ${VALID}.`);
-    }
-    return dialect;
-  }
-
-  all(): readonly ISqlDialect[] {
-    return [...this.byName.values()];
-  }
-}

package/src/abstractions/sql-dialect.ts

@@ -1,17 +0,0 @@
-import type { MigrationClient } from '../migration-client.ts';
-import type { SqlDialect } from '../sql.ts';
-
-export interface ISqlDialect {
-  readonly name: SqlDialect;
-  readonly connectionEnvironmentVariables: readonly string[];
-  readonly migratesDdl: string;
-  readonly migrateLogsDdl: string;
-  readonly usesLastInsertRowid: boolean;
-  quoteIdent(ident: string): string;
-  nowExpr(): string;
-  limitClause(n: number): string;
-  translatePlaceholders(sql: string): string;
-  prerequisiteError(connection: string): Promise<string | null>;
-  prepareSetup(connection: string): Promise<void>;
-  createClient(connection: string): Promise<MigrationClient>;
-}

package/src/bin/migrate-create.ts

@@ -1,80 +0,0 @@
-#!/usr/bin/env node
-// Scaffolds a new <NNNN>_<name>_{up,down}.sql pair in the migrations directory. Numbering is max(1-4-digit prefix in dir)+1; legacy timestamp prefixes are ignored.
-
-import { missingProviderMsg, requireDialect, takeFlag } from '../cli.ts';
-import { isMigrationName } from '../create-sequence.ts';
-import { fillTemplate, loadMessage } from '../infrastructure/message-templates.ts';
-import { loadHelp, Migrater } from '../index.ts';
-
-const [HELP_TEXT, unknownArgTpl, missingNameMsg, invalidNameTpl, createdTpl] = await Promise.all([
-  loadHelp('migrate-create'),
-  loadMessage('errors/unknown-arg'),
-  loadMessage('errors/missing-name'),
-  loadMessage('errors/invalid-name'),
-  loadMessage('status/created'),
-]);
-
-const parseArgs = (argv: string[]) => {
-  const args: {
-    provider: string | null;
-    name: string | null;
-    migrationsPath: string | null;
-  } = { provider: null, name: null, migrationsPath: null };
-  const rest = argv.slice(2);
-  for (let i = 0; i < rest.length; i++) {
-    const a = rest[i] as string;
-    if (a === '-h' || a === '--help') {
-      process.stderr.write(HELP_TEXT);
-      process.exit(0);
-    }
-    let taken;
-    if ((taken = takeFlag(rest, i, a, '--provider'))) {
-      args.provider = taken.value;
-      i = taken.next;
-    } else if ((taken = takeFlag(rest, i, a, '--name'))) {
-      args.name = taken.value;
-      i = taken.next;
-    } else if (
-      (taken = takeFlag(rest, i, a, '--migrations-path')) ||
-      (taken = takeFlag(rest, i, a, '--migrate-path'))
-    ) {
-      args.migrationsPath = taken.value;
-      i = taken.next;
-    } else {
-      process.stderr.write(fillTemplate(unknownArgTpl, { arg: a }));
-      process.exit(2);
-    }
-  }
-  return args;
-};
-
-const main = async () => {
-  const args = parseArgs(process.argv);
-  if (!args.provider) {
-    process.stderr.write(missingProviderMsg);
-    process.exit(2);
-  }
-  const dialect = requireDialect(args.provider);
-  if (!args.name) {
-    process.stderr.write(missingNameMsg);
-    process.exit(2);
-  }
-  if (!isMigrationName(args.name)) {
-    process.stderr.write(fillTemplate(invalidNameTpl, { name: args.name }));
-    process.exit(2);
-  }
-
-  const migrationsPath = args.migrationsPath ?? `./sql/${dialect.name}/migrations`;
-  const { upName, downName } = await new Migrater(dialect).create({
-    name: args.name,
-    migrationsPath,
-  });
-  process.stdout.write(fillTemplate(createdTpl, { file: upName }));
-  process.stdout.write(fillTemplate(createdTpl, { file: downName }));
-};
-
-main().catch((e: unknown) => {
-  const err = e as Error;
-  process.stderr.write(`${err?.stack ?? err?.message ?? String(e)}\n`);
-  process.exit(1);
-});

package/src/bin/migrate-down.ts

@@ -1,163 +0,0 @@
-#!/usr/bin/env node
-// Rolls back the most recently applied migration (one step). DESTRUCTIVE: prints a random 4-letter uppercase confirmation token and refuses to proceed unless the user types it back on stdin. Pass --confirm <TOKEN> matching the printed token to bypass the interactive prompt (CI / scripted use).
-
-import { resolve } from 'node:path';
-import { createInterface } from 'node:readline/promises';
-import { missingProviderMsg, requireConnection, requireDialect, takeFlag } from '../cli.ts';
-import { fillTemplate, loadMessage } from '../infrastructure/message-templates.ts';
-import { loadHelp, Migrater } from '../index.ts';
-
-const [
-  HELP_TEXT,
-  unknownArgTpl,
-  destructiveHeaderTpl,
-  confirmMismatchTpl,
-  confirmTtyRequiredTpl,
-  confirmPromptTpl,
-  confirmTokenMismatchMsg,
-  noRollbackMsg,
-  rolledBackTpl,
-] = await Promise.all([
-  loadHelp('migrate-down'),
-  loadMessage('errors/unknown-arg'),
-  loadMessage('down/destructive-header'),
-  loadMessage('down/confirm-mismatch'),
-  loadMessage('down/confirm-tty-required'),
-  loadMessage('down/confirm-prompt'),
-  loadMessage('down/confirm-token-mismatch'),
-  loadMessage('status/no-rollback'),
-  loadMessage('status/rolled-back'),
-]);
-
-const parseArgs = (argv: string[]) => {
-  const args: {
-    provider: string | null;
-    migratePath: string | null;
-    migrateRoot: string | null;
-    connection: string | null;
-    confirm: string | null;
-  } = {
-    provider: null,
-    migratePath: null,
-    migrateRoot: null,
-    connection: null,
-    confirm: null,
-  };
-  const rest = argv.slice(2);
-  for (let i = 0; i < rest.length; i++) {
-    const a = rest[i] as string;
-    if (a === '-h' || a === '--help') {
-      process.stderr.write(HELP_TEXT);
-      process.exit(0);
-    }
-    let taken;
-    if ((taken = takeFlag(rest, i, a, '--provider'))) {
-      args.provider = taken.value;
-      i = taken.next;
-    } else if (
-      (taken = takeFlag(rest, i, a, '--migrations-path')) ||
-      (taken = takeFlag(rest, i, a, '--migrate-path'))
-    ) {
-      args.migratePath = taken.value;
-      i = taken.next;
-    } else if (
-      (taken = takeFlag(rest, i, a, '--migrations-root')) ||
-      (taken = takeFlag(rest, i, a, '--migrate-root'))
-    ) {
-      args.migrateRoot = taken.value;
-      i = taken.next;
-    } else if ((taken = takeFlag(rest, i, a, '--connection'))) {
-      args.connection = taken.value;
-      i = taken.next;
-    } else if ((taken = takeFlag(rest, i, a, '--confirm'))) {
-      args.confirm = taken.value;
-      i = taken.next;
-    } else {
-      process.stderr.write(fillTemplate(unknownArgTpl, { arg: a }));
-      process.exit(2);
-    }
-  }
-  return args;
-};
-
-const resolveMigratePath = (
-  args: { migratePath: string | null; migrateRoot: string | null },
-  dialect: string,
-): string => {
-  if (args.migratePath) return args.migratePath;
-  const root = args.migrateRoot ?? 'sql';
-  return `${root}/${dialect}/migrations`;
-};
-
-const randomToken = (): string => {
-  const alphabet = 'ABCDEFGHJKLMNPQRSTUVWXYZ';
-  const buf = new Uint8Array(4);
-  globalThis.crypto.getRandomValues(buf);
-  let out = '';
-  for (let i = 0; i < 4; i++) out += alphabet[(buf[i] as number) % alphabet.length];
-  return out;
-};
-
-const promptConfirmation = async (token: string): Promise<boolean> => {
-  if (!process.stdin.isTTY) {
-    process.stderr.write(fillTemplate(confirmTtyRequiredTpl, { token }));
-    process.exit(2);
-  }
-  const rl = createInterface({ input: process.stdin, output: process.stderr });
-  try {
-    const answer = await rl.question(fillTemplate(confirmPromptTpl, { token }));
-    return answer.trim() === token;
-  } finally {
-    rl.close();
-  }
-};
-
-const main = async () => {
-  const args = parseArgs(process.argv);
-  if (!args.provider) {
-    process.stderr.write(missingProviderMsg);
-    process.exit(2);
-  }
-  const dialect = requireDialect(args.provider);
-  const connection = requireConnection(dialect, args.connection);
-
-  const missing = await dialect.prerequisiteError(connection);
-  if (missing !== null) {
-    process.stderr.write(`${missing}\n`);
-    process.exit(2);
-  }
-
-  const token = randomToken();
-  process.stderr.write(
-    fillTemplate(destructiveHeaderTpl, { dialect: dialect.name, token }),
-  );
-
-  if (args.confirm !== null) {
-    if (args.confirm !== token) {
-      process.stderr.write(
-        fillTemplate(confirmMismatchTpl, { supplied: args.confirm, token }),
-      );
-      process.exit(2);
-    }
-  } else {
-    const ok = await promptConfirmation(token);
-    if (!ok) {
-      process.stderr.write(confirmTokenMismatchMsg);
-      process.exit(2);
-    }
-  }
-
-  const migratePath = resolve(resolveMigratePath(args, dialect.name));
-  const name = await new Migrater(dialect).down({
-    connection,
-    migrationsPath: migratePath,
-  });
-  if (name == null) process.stdout.write(noRollbackMsg);
-  else process.stdout.write(fillTemplate(rolledBackTpl, { name }));
-};
-
-main().catch((e: unknown) => {
-  const err = e as Error;
-  process.stderr.write(`${err?.stack ?? err?.message ?? String(e)}\n`);
-  process.exit(1);
-});