@happyvertical/smrt-core 0.30.0

package/dist/migrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EACL,KAAK,cAAc,EACnB,eAAe,EACf,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,eAAe,EACf,YAAY,EACZ,aAAa,EACb,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,0BAA0B,EAC1B,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,0BAA0B,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,kBAAkB,EAClB,KAAK,6BAA6B,GACnC,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAGxE,YAAY,EACV,sBAAsB,EACtB,wBAAwB,EACxB,UAAU,EACV,cAAc,EACd,iBAAiB,EAEjB,aAAa,EACb,mBAAmB,EACnB,sBAAsB,EACtB,WAAW,EACX,cAAc,EACd,eAAe,EACf,SAAS,EACT,mBAAmB,EACnB,aAAa,EACb,eAAe,EAEf,eAAe,EACf,gBAAgB,EAEhB,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,YAAY,EACZ,UAAU,EACV,qBAAqB,EACrB,yBAAyB,EACzB,eAAe,GAChB,MAAM,YAAY,CAAC"}

package/dist/migrations/orchestrate.d.ts

@@ -0,0 +1,148 @@
+import { DatabaseInterface } from '@happyvertical/sql';
+import { DatabaseEngine } from '../schema/ddl/types.js';
+import { MigrationResult, SchemaChange } from '../schema/types.js';
+import { generateSchemaDiff } from './differ.js';
+export interface MigrateSmrtSchemasOptions {
+    db: DatabaseInterface;
+    /** Stored on the migration record so the audit log shows which app applied it. */
+    packageName: string;
+    /**
+     * Stored on the migration record. Typically the app's package.json
+     * version. Optional because most apps don't have a runtime-readable
+     * version handy and would hardcode a stale string if forced to supply
+     * one — `'unknown'` is honest. Pass an explicit value when you can
+     * (e.g. `version: process.env.APP_VERSION`).
+     */
+    version?: string;
+    /** Override the description on the synthetic migration definition. */
+    description?: string;
+    /** Override the migration name (default: `<timestamp>_smrt_schema_sync`). */
+    name?: string;
+    /** Forwarded to MigrationTracker — defaults to true for pg-safe runs. */
+    postgresSafe?: boolean;
+    /** Forwarded to MigrationTracker — defaults to true. */
+    reconcile?: boolean;
+    /** Forwarded to MigrationTracker — defaults to true for `CREATE INDEX CONCURRENTLY`. */
+    useConcurrentIndexes?: boolean;
+    /**
+     * Forwarded to MigrationTracker (Postgres lock timeout, milliseconds).
+     * Lets apps that customize tracker timeouts directly preserve their
+     * tuning when going through the orchestrator. Falls back to the
+     * tracker's default (30000ms) when omitted.
+     */
+    lockTimeout?: number;
+    /**
+     * Forwarded to MigrationTracker (Postgres statement timeout, ms). Falls
+     * back to the tracker's default (60000ms) when omitted.
+     */
+    statementTimeout?: number;
+    /**
+     * Explicit engine hint forwarded to `detectEngine`, `SchemaComparer`, and
+     * `MigrationTracker`. Useful when `db.url` doesn't unambiguously identify
+     * the engine (e.g. the JSON adapter, which uses DuckDB internally and may
+     * not be recognizable by URL alone). All three layers honor the same hint
+     * so the generated DDL, drift comparison, and execution path stay
+     * consistent — without it, an empty-URL connection could produce
+     * Postgres-flavored DDL but run through the SQLite tracker path.
+     *
+     * Typed as `DatabaseEngine` so unsupported values (e.g. `'mysql'`) fail at
+     * compile time rather than silently falling back to `'sqlite'` at runtime.
+     */
+    engineHint?: DatabaseEngine;
+}
+export interface MigrateSmrtSchemasResult {
+    applied: boolean;
+    results: MigrationResult[];
+    statements: string[];
+    schemaCount: number;
+    /**
+     * Schema changes the orchestrator detected but cannot apply automatically
+     * (incompatible type mismatches, SQLite type upgrades that require table
+     * recreation, etc.). Empty when the schema is fully reconciled. Inspect
+     * this to surface a "manual migration required" warning in CLI output.
+     */
+    unactionableChanges: SchemaChange[];
+    /**
+     * Convenience: `unactionableChanges.length > 0`. Lets a caller write
+     * `if (result.hasManualDrift) ...` without iterating the array first,
+     * and makes the case visible to anyone scanning the result shape (the
+     * full array is easy to gloss over when `applied: false`).
+     */
+    hasManualDrift: boolean;
+}
+export interface PendingSchemaStatementsResult {
+    diff: Awaited<ReturnType<typeof generateSchemaDiff>>;
+    statements: string[];
+    schemaCount: number;
+    hasChanges: boolean;
+    /**
+     * Schema changes the differ detected but that have no executable SQL
+     * (incompatible `type_mismatch` entries, or `type_upgrade` entries whose
+     * only generated SQL is an advisory comment because the engine cannot
+     * upgrade the column in place — e.g. SQLite type widening). Surfacing
+     * these lets status commands distinguish "no drift" from "drift the
+     * orchestrator can't fix on its own."
+     */
+    unactionableChanges: SchemaChange[];
+    /**
+     * Convenience: `unactionableChanges.length > 0`. Mirrors the
+     * `MigrateSmrtSchemasResult.hasManualDrift` shortcut.
+     */
+    hasManualDrift: boolean;
+}
+/**
+ * Compute the SQL statements needed to bring `db` in sync with the
+ * currently-registered SMRT object schemas. Pure inspection — no writes.
+ *
+ * Useful for status commands ("how far behind is the schema?") and as the
+ * inner step of `migrateSmrtSchemas`.
+ *
+ * **Note on the returned `statements`:** these are the engine-correct DDL
+ * statements as the differ + DDL strategy produce them, *prior to* any
+ * Postgres-specific rewrites the `MigrationTracker` applies at execution
+ * time (e.g. rewriting `CREATE INDEX` → `CREATE INDEX CONCURRENTLY` and
+ * moving CONCURRENTLY statements outside the surrounding transaction).
+ * The list is suitable for preview/status/"what would change?" use cases.
+ * For the exact byte-for-byte SQL the tracker ran, inspect the
+ * `MigrationResult`s from `migrateSmrtSchemas` or the tracker's own logs.
+ */
+export declare function getPendingSchemaStatements(db: DatabaseInterface, options?: {
+    engineHint?: DatabaseEngine;
+}): Promise<PendingSchemaStatementsResult>;
+/**
+ * Apply any pending schema changes from `ObjectRegistry` to `db`.
+ *
+ * Returns `applied: false` (with no error) if the database is already in
+ * sync. Throws on the first migration failure with the underlying error
+ * preserved (callers should let it propagate to the CLI).
+ *
+ * **Note on the returned `statements`:** mirrors `getPendingSchemaStatements`
+ * — the list is the planned DDL, prior to Postgres-specific tracker rewrites
+ * (CONCURRENTLY, transaction reordering). The actual executed SQL is
+ * tracked in the returned `results`.
+ *
+ * **Note on `applied` semantics under `reconcile: true` (the default):**
+ * the tracker may re-execute a migration that is already in `completed`
+ * state when the checksum matches — that counts as `applied: true` in the
+ * returned `MigrationResult`. So `result.applied === true` means "the
+ * tracker ran the migration", not specifically "the database changed for
+ * the first time." Pass `reconcile: false` if you need to distinguish a
+ * fresh apply from a reconcile-replay over an existing completed record.
+ *
+ * **Note on repeated failures:** the migration name defaults to a fresh
+ * timestamp on every call, so a sequence of failed runs leaves one
+ * `failed` row in `_smrt_schema_migrations` per attempt. Pass an explicit
+ * `name` if you want to overwrite the same record across retries.
+ *
+ * **Note on `unactionableChanges`:** the differ can detect schema drift
+ * the migration step can't auto-resolve — incompatible type mismatches,
+ * SQLite type widening that needs table recreation, etc. Those changes
+ * appear in `result.unactionableChanges` and are NOT applied (the
+ * statements list is filtered to executable DDL only). When the diff
+ * contains *only* unactionable changes, the function returns
+ * `applied: false` with a populated `unactionableChanges` so callers can
+ * surface a "manual migration required" signal. Without inspecting that
+ * field, the result would look indistinguishable from "already in sync."
+ */
+export declare function migrateSmrtSchemas(options: MigrateSmrtSchemasOptions): Promise<MigrateSmrtSchemasResult>;
+//# sourceMappingURL=orchestrate.d.ts.map

package/dist/migrations/orchestrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrate.d.ts","sourceRoot":"","sources":["../../src/migrations/orchestrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,EACL,kBAAkB,EAGnB,MAAM,aAAa,CAAC;AAOrB,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,iBAAiB,CAAC;IACtB,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,wDAAwD;IACxD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,wFAAwF;IACxF,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,mBAAmB,EAAE,YAAY,EAAE,CAAC;IACpC;;;;;OAKG;IACH,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC;IACrD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;;;OAOG;IACH,mBAAmB,EAAE,YAAY,EAAE,CAAC;IACpC;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,0BAA0B,CAC9C,EAAE,EAAE,iBAAiB,EACrB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,cAAc,CAAA;CAAO,GAC5C,OAAO,CAAC,6BAA6B,CAAC,CAoBxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAyDnC"}

package/dist/migrations/orchestrate.js

@@ -0,0 +1,118 @@
+import { ObjectRegistry } from "../registry.js";
+import { getDDLStrategy, detectEngine } from "../schema/ddl/index.js";
+import { generateSchemaDiff, hasActionableChanges, getSQLFromDiff } from "./differ.js";
+import { createMigrationDefinition, generateMigrationTimestamp } from "./generator.js";
+import { MigrationTracker } from "./tracker.js";
+async function getPendingSchemaStatements(db, options = {}) {
+  const schemas = ObjectRegistry.getAllSchemasAsDefinitions();
+  const diff = await generateSchemaDiff(db, schemas, {
+    engineHint: options.engineHint
+  });
+  const statements = collectStatementsFromDiff(diff, db, options.engineHint);
+  const unactionableChanges = collectUnactionableChanges(diff);
+  return {
+    diff,
+    schemaCount: Object.keys(schemas).length,
+    statements,
+    hasChanges: hasActionableChanges(diff),
+    unactionableChanges,
+    hasManualDrift: unactionableChanges.length > 0
+  };
+}
+async function migrateSmrtSchemas(options) {
+  const pending = await getPendingSchemaStatements(options.db, {
+    engineHint: options.engineHint
+  });
+  if (!pending.hasChanges || pending.statements.length === 0) {
+    return {
+      applied: false,
+      results: [],
+      statements: [],
+      schemaCount: pending.schemaCount,
+      unactionableChanges: pending.unactionableChanges,
+      hasManualDrift: pending.hasManualDrift
+    };
+  }
+  const tracker = new MigrationTracker({
+    db: options.db,
+    engineHint: options.engineHint,
+    lockTimeout: options.lockTimeout,
+    statementTimeout: options.statementTimeout,
+    useConcurrentIndexes: options.useConcurrentIndexes ?? true
+  });
+  const migration = createMigrationDefinition(
+    options.name ?? `${generateMigrationTimestamp()}_smrt_schema_sync`,
+    pending.statements,
+    [],
+    {
+      description: options.description ?? "Synchronize SMRT object schemas",
+      packageName: options.packageName,
+      version: options.version ?? "unknown"
+    }
+  );
+  const results = await tracker.applyAll([migration], {
+    postgresSafe: options.postgresSafe ?? true,
+    reconcile: options.reconcile ?? true
+  });
+  const failed = results.find((result) => !result.success);
+  if (failed) {
+    throw failed.error instanceof Error ? failed.error : new Error(String(failed.error ?? `Migration ${failed.name} failed`));
+  }
+  const applied = results.some(
+    (result) => result.applied !== false && result.skipped !== true
+  );
+  return {
+    applied,
+    results,
+    statements: pending.statements,
+    schemaCount: pending.schemaCount,
+    unactionableChanges: pending.unactionableChanges,
+    hasManualDrift: pending.hasManualDrift
+  };
+}
+function resolveDatabaseUrl(db) {
+  const dbWithConfig = db;
+  return db.url || dbWithConfig.config?.url || "";
+}
+function collectStatementsFromDiff(diff, db, engineHint) {
+  const strategy = getDDLStrategy(
+    detectEngine(resolveDatabaseUrl(db), engineHint)
+  );
+  const statements = [];
+  for (const schema of diff.added_tables) {
+    statements.push(strategy.generateCreateTable(schema));
+    statements.push(...strategy.generateIndexes(schema));
+    statements.push(...strategy.generateTriggers(schema));
+  }
+  statements.push(...getSQLFromDiff(diff));
+  return statements.filter((statement) => {
+    const trimmed = statement.trim();
+    if (trimmed.length === 0) return false;
+    return !isCommentOnlySql(trimmed);
+  });
+}
+function isCommentOnlySql(sql) {
+  const withoutBlockComments = sql.replace(/\/\*[\s\S]*?\*\//g, "");
+  const lines = withoutBlockComments.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+  if (lines.length === 0) return sql.trim().length > 0;
+  return lines.every((line) => line.startsWith("--"));
+}
+function collectUnactionableChanges(diff) {
+  const unactionable = [];
+  for (const change of diff.changes) {
+    if (change.type === "type_mismatch") {
+      unactionable.push(change);
+      continue;
+    }
+    const statements = change.sqlStatements ?? (change.sql ? [change.sql] : []);
+    if (statements.length > 0 && statements.every((stmt) => isCommentOnlySql(stmt.trim()))) {
+      unactionable.push(change);
+    }
+  }
+  return unactionable;
+}
+export {
+  getPendingSchemaStatements,
+  migrateSmrtSchemas
+};
+//# sourceMappingURL=orchestrate.js.map

package/dist/migrations/orchestrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrate.js","sources":["../../src/migrations/orchestrate.ts"],"sourcesContent":["/**\n * High-level \"make my SMRT app's schema match its database\" orchestration.\n *\n * Wraps `ObjectRegistry.getAllSchemasAsDefinitions()` → `generateSchemaDiff`\n * → `MigrationTracker.applyAll`. Apps that just want to run pending\n * schema changes call `migrateSmrtSchemas({ db, packageName, version })`\n * and don't have to assemble the migration definition by hand.\n *\n * The migration name is timestamped, so re-running on an up-to-date\n * database is a no-op (the diff is empty, no statements are generated,\n * `applied: false` is returned).\n */\nimport type { DatabaseInterface } from '@happyvertical/sql';\nimport { ObjectRegistry } from '../registry.js';\nimport { detectEngine, getDDLStrategy } from '../schema/ddl/index.js';\nimport type { DatabaseEngine } from '../schema/ddl/types.js';\nimport type { MigrationResult, SchemaChange } from '../schema/types.js';\nimport {\n  generateSchemaDiff,\n  getSQLFromDiff,\n  hasActionableChanges,\n} from './differ.js';\nimport {\n  createMigrationDefinition,\n  generateMigrationTimestamp,\n} from './generator.js';\nimport { MigrationTracker } from './tracker.js';\n\nexport interface MigrateSmrtSchemasOptions {\n  db: DatabaseInterface;\n  /** Stored on the migration record so the audit log shows which app applied it. */\n  packageName: string;\n  /**\n   * Stored on the migration record. Typically the app's package.json\n   * version. Optional because most apps don't have a runtime-readable\n   * version handy and would hardcode a stale string if forced to supply\n   * one — `'unknown'` is honest. Pass an explicit value when you can\n   * (e.g. `version: process.env.APP_VERSION`).\n   */\n  version?: string;\n  /** Override the description on the synthetic migration definition. */\n  description?: string;\n  /** Override the migration name (default: `<timestamp>_smrt_schema_sync`). */\n  name?: string;\n  /** Forwarded to MigrationTracker — defaults to true for pg-safe runs. */\n  postgresSafe?: boolean;\n  /** Forwarded to MigrationTracker — defaults to true. */\n  reconcile?: boolean;\n  /** Forwarded to MigrationTracker — defaults to true for `CREATE INDEX CONCURRENTLY`. */\n  useConcurrentIndexes?: boolean;\n  /**\n   * Forwarded to MigrationTracker (Postgres lock timeout, milliseconds).\n   * Lets apps that customize tracker timeouts directly preserve their\n   * tuning when going through the orchestrator. Falls back to the\n   * tracker's default (30000ms) when omitted.\n   */\n  lockTimeout?: number;\n  /**\n   * Forwarded to MigrationTracker (Postgres statement timeout, ms). Falls\n   * back to the tracker's default (60000ms) when omitted.\n   */\n  statementTimeout?: number;\n  /**\n   * Explicit engine hint forwarded to `detectEngine`, `SchemaComparer`, and\n   * `MigrationTracker`. Useful when `db.url` doesn't unambiguously identify\n   * the engine (e.g. the JSON adapter, which uses DuckDB internally and may\n   * not be recognizable by URL alone). All three layers honor the same hint\n   * so the generated DDL, drift comparison, and execution path stay\n   * consistent — without it, an empty-URL connection could produce\n   * Postgres-flavored DDL but run through the SQLite tracker path.\n   *\n   * Typed as `DatabaseEngine` so unsupported values (e.g. `'mysql'`) fail at\n   * compile time rather than silently falling back to `'sqlite'` at runtime.\n   */\n  engineHint?: DatabaseEngine;\n}\n\nexport interface MigrateSmrtSchemasResult {\n  applied: boolean;\n  results: MigrationResult[];\n  statements: string[];\n  schemaCount: number;\n  /**\n   * Schema changes the orchestrator detected but cannot apply automatically\n   * (incompatible type mismatches, SQLite type upgrades that require table\n   * recreation, etc.). Empty when the schema is fully reconciled. Inspect\n   * this to surface a \"manual migration required\" warning in CLI output.\n   */\n  unactionableChanges: SchemaChange[];\n  /**\n   * Convenience: `unactionableChanges.length > 0`. Lets a caller write\n   * `if (result.hasManualDrift) ...` without iterating the array first,\n   * and makes the case visible to anyone scanning the result shape (the\n   * full array is easy to gloss over when `applied: false`).\n   */\n  hasManualDrift: boolean;\n}\n\nexport interface PendingSchemaStatementsResult {\n  diff: Awaited<ReturnType<typeof generateSchemaDiff>>;\n  statements: string[];\n  schemaCount: number;\n  hasChanges: boolean;\n  /**\n   * Schema changes the differ detected but that have no executable SQL\n   * (incompatible `type_mismatch` entries, or `type_upgrade` entries whose\n   * only generated SQL is an advisory comment because the engine cannot\n   * upgrade the column in place — e.g. SQLite type widening). Surfacing\n   * these lets status commands distinguish \"no drift\" from \"drift the\n   * orchestrator can't fix on its own.\"\n   */\n  unactionableChanges: SchemaChange[];\n  /**\n   * Convenience: `unactionableChanges.length > 0`. Mirrors the\n   * `MigrateSmrtSchemasResult.hasManualDrift` shortcut.\n   */\n  hasManualDrift: boolean;\n}\n\n/**\n * Compute the SQL statements needed to bring `db` in sync with the\n * currently-registered SMRT object schemas. Pure inspection — no writes.\n *\n * Useful for status commands (\"how far behind is the schema?\") and as the\n * inner step of `migrateSmrtSchemas`.\n *\n * **Note on the returned `statements`:** these are the engine-correct DDL\n * statements as the differ + DDL strategy produce them, *prior to* any\n * Postgres-specific rewrites the `MigrationTracker` applies at execution\n * time (e.g. rewriting `CREATE INDEX` → `CREATE INDEX CONCURRENTLY` and\n * moving CONCURRENTLY statements outside the surrounding transaction).\n * The list is suitable for preview/status/\"what would change?\" use cases.\n * For the exact byte-for-byte SQL the tracker ran, inspect the\n * `MigrationResult`s from `migrateSmrtSchemas` or the tracker's own logs.\n */\nexport async function getPendingSchemaStatements(\n  db: DatabaseInterface,\n  options: { engineHint?: DatabaseEngine } = {},\n): Promise<PendingSchemaStatementsResult> {\n  const schemas = ObjectRegistry.getAllSchemasAsDefinitions();\n  // Forward engineHint into the diff itself so the SchemaComparer's\n  // existing-table SQL (ALTER/index drift) uses the same DDL strategy\n  // we use for newly-added tables — otherwise the two halves of the\n  // statement list can land on different engines (split-brain) when\n  // `db.url` is empty or ambiguous.\n  const diff = await generateSchemaDiff(db, schemas, {\n    engineHint: options.engineHint,\n  });\n  const statements = collectStatementsFromDiff(diff, db, options.engineHint);\n  const unactionableChanges = collectUnactionableChanges(diff);\n  return {\n    diff,\n    schemaCount: Object.keys(schemas).length,\n    statements,\n    hasChanges: hasActionableChanges(diff),\n    unactionableChanges,\n    hasManualDrift: unactionableChanges.length > 0,\n  };\n}\n\n/**\n * Apply any pending schema changes from `ObjectRegistry` to `db`.\n *\n * Returns `applied: false` (with no error) if the database is already in\n * sync. Throws on the first migration failure with the underlying error\n * preserved (callers should let it propagate to the CLI).\n *\n * **Note on the returned `statements`:** mirrors `getPendingSchemaStatements`\n * — the list is the planned DDL, prior to Postgres-specific tracker rewrites\n * (CONCURRENTLY, transaction reordering). The actual executed SQL is\n * tracked in the returned `results`.\n *\n * **Note on `applied` semantics under `reconcile: true` (the default):**\n * the tracker may re-execute a migration that is already in `completed`\n * state when the checksum matches — that counts as `applied: true` in the\n * returned `MigrationResult`. So `result.applied === true` means \"the\n * tracker ran the migration\", not specifically \"the database changed for\n * the first time.\" Pass `reconcile: false` if you need to distinguish a\n * fresh apply from a reconcile-replay over an existing completed record.\n *\n * **Note on repeated failures:** the migration name defaults to a fresh\n * timestamp on every call, so a sequence of failed runs leaves one\n * `failed` row in `_smrt_schema_migrations` per attempt. Pass an explicit\n * `name` if you want to overwrite the same record across retries.\n *\n * **Note on `unactionableChanges`:** the differ can detect schema drift\n * the migration step can't auto-resolve — incompatible type mismatches,\n * SQLite type widening that needs table recreation, etc. Those changes\n * appear in `result.unactionableChanges` and are NOT applied (the\n * statements list is filtered to executable DDL only). When the diff\n * contains *only* unactionable changes, the function returns\n * `applied: false` with a populated `unactionableChanges` so callers can\n * surface a \"manual migration required\" signal. Without inspecting that\n * field, the result would look indistinguishable from \"already in sync.\"\n */\nexport async function migrateSmrtSchemas(\n  options: MigrateSmrtSchemasOptions,\n): Promise<MigrateSmrtSchemasResult> {\n  const pending = await getPendingSchemaStatements(options.db, {\n    engineHint: options.engineHint,\n  });\n  if (!pending.hasChanges || pending.statements.length === 0) {\n    return {\n      applied: false,\n      results: [],\n      statements: [],\n      schemaCount: pending.schemaCount,\n      unactionableChanges: pending.unactionableChanges,\n      hasManualDrift: pending.hasManualDrift,\n    };\n  }\n\n  const tracker = new MigrationTracker({\n    db: options.db,\n    engineHint: options.engineHint,\n    lockTimeout: options.lockTimeout,\n    statementTimeout: options.statementTimeout,\n    useConcurrentIndexes: options.useConcurrentIndexes ?? true,\n  });\n  const migration = createMigrationDefinition(\n    options.name ?? `${generateMigrationTimestamp()}_smrt_schema_sync`,\n    pending.statements,\n    [],\n    {\n      description: options.description ?? 'Synchronize SMRT object schemas',\n      packageName: options.packageName,\n      version: options.version ?? 'unknown',\n    },\n  );\n\n  const results = await tracker.applyAll([migration], {\n    postgresSafe: options.postgresSafe ?? true,\n    reconcile: options.reconcile ?? true,\n  });\n\n  const failed = results.find((result) => !result.success);\n  if (failed) {\n    throw failed.error instanceof Error\n      ? failed.error\n      : new Error(String(failed.error ?? `Migration ${failed.name} failed`));\n  }\n\n  const applied = results.some(\n    (result) => result.applied !== false && result.skipped !== true,\n  );\n\n  return {\n    applied,\n    results,\n    statements: pending.statements,\n    schemaCount: pending.schemaCount,\n    unactionableChanges: pending.unactionableChanges,\n    hasManualDrift: pending.hasManualDrift,\n  };\n}\n\n/** Mirror of the `getDatabaseUrl` helper in class.ts — some adapters\n * (JSON, certain in-memory wrappers) leave `db.url` undefined and expose\n * the URL on `db.config?.url` instead. Detecting the engine from a raw\n * `db.url` would throw or silently fall through to the sqlite default.\n */\nfunction resolveDatabaseUrl(db: DatabaseInterface): string {\n  const dbWithConfig = db as DatabaseInterface & {\n    config?: { url?: string };\n  };\n  return db.url || dbWithConfig.config?.url || '';\n}\n\n/**\n * Materialize the diff into the engine-correct SQL statements.\n *\n * For new tables we delegate to the engine's `DDLStrategy` so column types\n * (`REAL` → `DOUBLE PRECISION` on Postgres, `JSON` → `JSONB`, etc.),\n * partial-index `WHERE` clauses, and trigger syntax all match what the\n * SchemaComparer would expect on subsequent runs. Emitting the raw\n * abstract `SchemaDefinition.ddl` here would cause immediate type-drift\n * migrations on Postgres/DuckDB.\n *\n * Column/index/trigger changes for existing tables continue to come from\n * `getSQLFromDiff`, which is already engine-aware via the differ's per-\n * change `sqlStatements`.\n */\nfunction collectStatementsFromDiff(\n  diff: Awaited<ReturnType<typeof generateSchemaDiff>>,\n  db: DatabaseInterface,\n  engineHint?: DatabaseEngine,\n): string[] {\n  const strategy = getDDLStrategy(\n    detectEngine(resolveDatabaseUrl(db), engineHint),\n  );\n  const statements: string[] = [];\n  for (const schema of diff.added_tables) {\n    statements.push(strategy.generateCreateTable(schema));\n    statements.push(...strategy.generateIndexes(schema));\n    statements.push(...strategy.generateTriggers(schema));\n  }\n  statements.push(...getSQLFromDiff(diff));\n  // Drop empty and comment-only entries. SQLite type-widening upgrades\n  // surface as `-- SQLite: Type upgrade for X requires table recreation`\n  // — passing those through to the tracker records a successful migration\n  // without actually fixing the column, so the same drift re-appears on\n  // every subsequent run. Those changes are surfaced separately via\n  // `unactionableChanges` so callers can prompt for manual remediation.\n  return statements.filter((statement) => {\n    const trimmed = statement.trim();\n    if (trimmed.length === 0) return false;\n    return !isCommentOnlySql(trimmed);\n  });\n}\n\n/**\n * True if `sql` contains no executable DDL — only line comments (`--`)\n * and/or block comments (`/* … *​/`). Used to discard advisory comments\n * the differ emits when a column upgrade can't be performed in place\n * (e.g. SQLite type widening). Defensive: strips block comments first so\n * a future differ that emits `/* type_upgrade: no-op *​/` doesn't slip\n * through.\n */\nfunction isCommentOnlySql(sql: string): boolean {\n  // Strip /* ... */ block comments (non-greedy, spans newlines).\n  const withoutBlockComments = sql.replace(/\\/\\*[\\s\\S]*?\\*\\//g, '');\n  const lines = withoutBlockComments\n    .split('\\n')\n    .map((line) => line.trim())\n    .filter((line) => line.length > 0);\n  if (lines.length === 0) return sql.trim().length > 0;\n  return lines.every((line) => line.startsWith('--'));\n}\n\n/**\n * Surface changes the differ produced but that the migrator cannot apply\n * automatically — either `type_mismatch` entries (the differ explicitly\n * gives up on these) or `type_upgrade` entries whose generated SQL is\n * advisory-comment-only (SQLite table-recreation cases, etc.). Callers\n * use this to distinguish \"schema is in sync\" from \"schema is drifted but\n * we can't fix it from here.\"\n */\nfunction collectUnactionableChanges(\n  diff: Awaited<ReturnType<typeof generateSchemaDiff>>,\n): SchemaChange[] {\n  const unactionable: SchemaChange[] = [];\n  for (const change of diff.changes) {\n    if (change.type === 'type_mismatch') {\n      unactionable.push(change);\n      continue;\n    }\n    const statements = change.sqlStatements ?? (change.sql ? [change.sql] : []);\n    if (\n      statements.length > 0 &&\n      statements.every((stmt) => isCommentOnlySql(stmt.trim()))\n    ) {\n      unactionable.push(change);\n    }\n  }\n  return unactionable;\n}\n"],"names":[],"mappings":"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"}

package/dist/migrations/tracker.d.ts

@@ -0,0 +1,134 @@
+import { DatabaseEngine } from '../schema/ddl/types.js';
+import { DriftReport, MigrationDefinition, MigrationResult, MigrationStatus, SchemaMigrationRecord } from '../schema/types.js';
+import { ApplyMigrationsOptions, MigrationTrackerOptions, RollbackOptions } from './types.js';
+/**
+ * MigrationTracker class
+ *
+ * Provides migration tracking and state management:
+ * - Initializes the _smrt_schema_migrations tracking table
+ * - Tracks applied migrations with checksums
+ * - Provides idempotent migration application
+ * - Supports rollback via DOWN scripts
+ * - Handles PostgreSQL-specific concerns (CONCURRENTLY, lock timeout)
+ */
+export declare class MigrationTracker {
+    private db;
+    private options;
+    private engineHint?;
+    private dbEngine;
+    /**
+     * Memoized initialization promise. Storing the in-flight promise (rather
+     * than a `boolean` flag set after the DDL completes) makes `initialize()`
+     * safe under concurrency: multiple parallel callers all `await` the same
+     * promise instead of independently re-running the DDL. On error the slot
+     * is cleared so the next caller retries — a transient failure doesn't
+     * permanently poison the instance.
+     */
+    private initializePromise;
+    private currentBatch;
+    constructor(options: MigrationTrackerOptions);
+    /**
+     * Detect the database engine. Honors an explicit `engineHint` (passed via
+     * `MigrationTrackerOptions`) before falling back to URL parsing — this is
+     * the same `detectEngine` contract used by `SchemaComparer` and the rest
+     * of the migration stack, so the tracker stays consistent with the DDL
+     * the orchestrator generated.
+     */
+    private detectDbEngine;
+    /**
+     * Get the current database engine
+     */
+    getEngine(): DatabaseEngine;
+    /**
+     * Initialize the migrations tracking table
+     */
+    initialize(): Promise<void>;
+    private runInitializeDdl;
+    /**
+     * Get all applied migrations ordered by applied_at
+     */
+    getAppliedMigrations(): Promise<SchemaMigrationRecord[]>;
+    /**
+     * Get pending migrations (defined but not applied)
+     */
+    getPendingMigrations(definitions: MigrationDefinition[]): Promise<MigrationDefinition[]>;
+    /**
+     * Check if a migration has been applied
+     */
+    isApplied(migrationId: string): Promise<boolean>;
+    /**
+     * Get a single migration record by name
+     */
+    getMigration(name: string): Promise<SchemaMigrationRecord | null>;
+    /**
+     * Get the next batch number
+     */
+    getNextBatch(): Promise<number>;
+    /**
+     * Detect drift between migration definitions and applied migrations
+     */
+    detectDrift(definitions: MigrationDefinition[]): Promise<DriftReport[]>;
+    /**
+     * Apply a single migration
+     */
+    apply(definition: MigrationDefinition, options?: ApplyMigrationsOptions): Promise<MigrationResult>;
+    /**
+     * Apply multiple migrations in order
+     */
+    applyAll(definitions: MigrationDefinition[], options?: ApplyMigrationsOptions): Promise<MigrationResult[]>;
+    /**
+     * Rollback a migration
+     */
+    rollback(name: string, definition: MigrationDefinition, options?: RollbackOptions): Promise<MigrationResult>;
+    /**
+     * Get migration history with optional filtering
+     */
+    getHistory(options?: {
+        limit?: number;
+        since?: Date;
+        status?: MigrationStatus;
+    }): Promise<SchemaMigrationRecord[]>;
+    /**
+     * Execute SQL statements with appropriate transaction handling
+     */
+    private executeStatements;
+    /**
+     * Execute statements within a transaction (SQLite/DuckDB)
+     */
+    private executeWithTransaction;
+    /**
+     * Execute statements with PostgreSQL-specific handling
+     *
+     * - CONCURRENTLY statements run outside transaction
+     * - Regular statements run in transaction with lock_timeout
+     *
+     * Both CREATE and DROP variants of CONCURRENTLY must be detected — Postgres
+     * forbids `DROP INDEX CONCURRENTLY` inside a transaction block, just like
+     * the create variant. Issue #1165: the migration generator emits
+     * `DROP INDEX CONCURRENTLY` for shape-drift recreates and orphan-index
+     * cleanups, so the regex needs to cover both keywords.
+     */
+    private executePostgresStatements;
+}
+/**
+ * Split a batch of SQL statements into a transaction-safe set and a
+ * concurrent set, applying `--postgres-safe` rewriting if requested.
+ *
+ * Exported for unit testing and to give external callers a way to
+ * reason about what the tracker would execute in PostgreSQL safe mode.
+ *
+ * Rules:
+ * - Statements already containing `CONCURRENTLY` for CREATE/DROP INDEX or
+ *   REINDEX operations always go to the concurrent set — Postgres rejects
+ *   them inside transactions.
+ * - When `useConcurrentIndexes` is true, plain `CREATE INDEX` and plain
+ *   `DROP INDEX` are rewritten to use `CONCURRENTLY`, then routed to
+ *   the concurrent set. This is what the CLI `--postgres-safe` flag and
+ *   the auto-migrate path rely on for issue #1165's shape-drift drops.
+ * - All other statements stay in the regular (transaction) set.
+ */
+export declare function planPostgresStatements(statements: string[], useConcurrentIndexes: boolean): {
+    concurrent: string[];
+    regular: string[];
+};
+//# sourceMappingURL=tracker.d.ts.map

package/dist/migrations/tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/migrations/tracker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EACV,WAAW,EACX,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,qBAAqB,EACtB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EACV,sBAAsB,EAEtB,uBAAuB,EACvB,eAAe,EAChB,MAAM,YAAY,CAAC;AAkEpB;;;;;;;;;GASG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,EAAE,CAAoB;IAC9B,OAAO,CAAC,OAAO,CAA+D;IAC9E,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAiB;IACjC;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB,CAA8B;IACvD,OAAO,CAAC,YAAY,CAAuB;gBAE/B,OAAO,EAAE,uBAAuB;IAa5C;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAQtB;;OAEG;IACH,SAAS,IAAI,cAAc;IAI3B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAUnB,gBAAgB;IAW9B;;OAEG;IACG,oBAAoB,IAAI,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAe9D;;OAEG;IACG,oBAAoB,CACxB,WAAW,EAAE,mBAAmB,EAAE,GACjC,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAMjC;;OAEG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWtD;;OAEG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;IAmBvE;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAWrC;;OAEG;IACG,WAAW,CACf,WAAW,EAAE,mBAAmB,EAAE,GACjC,OAAO,CAAC,WAAW,EAAE,CAAC;IAkDzB;;OAEG;IACG,KAAK,CACT,UAAU,EAAE,mBAAmB,EAC/B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC;IAyL3B;;OAEG;IACG,QAAQ,CACZ,WAAW,EAAE,mBAAmB,EAAE,EAClC,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,EAAE,CAAC;IAsF7B;;OAEG;IACG,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,mBAAmB,EAC/B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,eAAe,CAAC;IAiF3B;;OAEG;IACG,UAAU,CACd,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,IAAI,CAAC;QAAC,MAAM,CAAC,EAAE,eAAe,CAAA;KAAO,GACvE,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAiCnC;;OAEG;YACW,iBAAiB;IAW/B;;OAEG;YACW,sBAAsB;IAepC;;;;;;;;;;;OAWG;YACW,yBAAyB;CAqCxC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAAE,EACpB,oBAAoB,EAAE,OAAO,GAC5B;IAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAgC7C"}