@happyvertical/smrt-core 0.30.0

package/dist/mcp-advisor/types.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Type definitions for SMRT Framework Advisor MCP server
+ *
+ * These types define the inputs and outputs for all advisor tools
+ */
+/**
+ * Base response type for all tools
+ */
+export interface ToolResponse {
+    success: boolean;
+    data?: any;
+    error?: string;
+    warnings?: string[];
+}
+/**
+ * Input for generate-smrt-class tool
+ */
+export interface GenerateSmrtClassInput {
+    className: string;
+    properties: Array<{
+        name: string;
+        type: 'text' | 'integer' | 'decimal' | 'boolean' | 'datetime' | 'json';
+        required?: boolean;
+        description?: string;
+    }>;
+    baseClass?: 'SmrtObject' | 'SmrtCollection';
+    includeApiConfig?: boolean;
+    includeMcpConfig?: boolean;
+    includeCliConfig?: boolean;
+}
+/**
+ * Input for add-ai-methods tool
+ */
+export interface AddAiMethodsInput {
+    className: string;
+    methods: Array<'is' | 'do' | 'tool'>;
+    filePath?: string;
+}
+/**
+ * Input for generate-field-definitions tool
+ */
+export interface GenerateFieldDefinitionsInput {
+    fields: Array<{
+        name: string;
+        type: 'text' | 'integer' | 'decimal' | 'boolean' | 'datetime' | 'json' | 'foreignKey';
+        _meta?: Record<string, any>;
+    }>;
+}
+/**
+ * Input for generate-collection tool
+ */
+export interface GenerateCollectionInput {
+    collectionName: string;
+    itemClassName: string;
+    itemClassPath: string;
+    includeCustomMethods?: boolean;
+}
+/**
+ * Input for configure-decorators tool
+ */
+export interface ConfigureDecoratorsInput {
+    className: string;
+    api?: {
+        include?: string[];
+        exclude?: string[];
+        routes?: Record<string, {
+            scope?: 'item' | 'collection';
+            method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+            path?: string;
+        }>;
+    };
+    mcp?: {
+        include?: string[];
+        exclude?: string[];
+    };
+    cli?: boolean;
+    hooks?: {
+        beforeSave?: string;
+        afterSave?: string;
+        beforeDelete?: string;
+        afterDelete?: string;
+    };
+}
+/**
+ * Input for validate-smrt-object tool
+ */
+export interface ValidateSmrtObjectInput {
+    filePath: string;
+    strictMode?: boolean;
+}
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: Array<{
+        type: 'error' | 'warning';
+        message: string;
+        line?: number;
+        suggestion?: string;
+    }>;
+    className?: string;
+    hasDecorator?: boolean;
+    hasRequiredMethods?: boolean;
+    fieldCount?: number;
+}
+/**
+ * Input for preview-api-endpoints tool
+ */
+export interface PreviewApiEndpointsInput {
+    className: string;
+    basePath?: string;
+}
+/**
+ * API endpoint definition
+ */
+export interface ApiEndpoint {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    path: string;
+    description: string;
+    parameters?: Array<{
+        name: string;
+        type: string;
+        required: boolean;
+        location: 'path' | 'query' | 'body';
+    }>;
+}
+/**
+ * Input for preview-mcp-tools tool
+ */
+export interface PreviewMcpToolsInput {
+    className: string;
+}
+/**
+ * MCP tool definition
+ */
+export interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: Record<string, any>;
+        required?: string[];
+    };
+}
+/**
+ * Input for list-registered-objects tool
+ */
+export interface ListRegisteredObjectsInput {
+    filter?: 'all' | 'objects' | 'collections';
+}
+/**
+ * Registered object info
+ */
+export interface RegisteredObjectInfo {
+    name: string;
+    type: 'object' | 'collection';
+    hasDecorator: boolean;
+    fieldCount: number;
+    apiEnabled: boolean;
+    mcpEnabled: boolean;
+    cliEnabled: boolean;
+}
+/**
+ * Input for get-object-schema tool
+ */
+export interface GetObjectSchemaInput {
+    className: string;
+    format?: 'json' | 'typescript' | 'table';
+}
+/**
+ * Field definition
+ */
+export interface FieldDefinition {
+    name: string;
+    type: string;
+    required: boolean;
+    default?: any;
+    description?: string;
+    constraints?: Record<string, any>;
+}
+/**
+ * Input for get-object-config tool
+ */
+export interface GetObjectConfigInput {
+    className: string;
+    format?: 'json' | 'yaml';
+}
+/**
+ * Object configuration
+ */
+export interface ObjectConfig {
+    className: string;
+    decorator: {
+        api?: boolean | {
+            include?: string[];
+            exclude?: string[];
+        };
+        mcp?: boolean | {
+            include?: string[];
+            exclude?: string[];
+        };
+        cli?: boolean;
+        hooks?: Record<string, string>;
+    };
+    fields: FieldDefinition[];
+    customMethods: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/mcp-advisor/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/mcp-advisor/types.ts"],"names":[],"mappings":"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"}

package/dist/migrations/backfill-tracker.d.ts

@@ -0,0 +1,84 @@
+import { DatabaseInterface } from '@happyvertical/sql';
+export interface BackfillTrackerOptions {
+    db: DatabaseInterface;
+}
+export interface BackfillRecord {
+    name: string;
+    appliedAt: string;
+    description: string | null;
+    packageName: string | null;
+}
+export declare class BackfillTracker {
+    private readonly db;
+    /**
+     * Memoized initialization promise. Storing the promise (rather than a
+     * `boolean` flag set after the DDL completes) makes `initialize()` safe
+     * under concurrency: multiple parallel callers all `await` the same
+     * in-flight 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;
+    constructor(options: BackfillTrackerOptions);
+    /**
+     * Create the `_smrt_backfills` table if it doesn't already exist.
+     * Safe to call repeatedly and concurrently.
+     */
+    initialize(): Promise<void>;
+    /** Has the backfill named `name` already run? */
+    isApplied(name: string): Promise<boolean>;
+    /**
+     * Record that the backfill named `name` ran. Uses INSERT ... ON CONFLICT
+     * so callers don't need to check `isApplied` first if they don't care
+     * about distinguishing "already applied" from "just applied".
+     */
+    recordApplied(name: string, options?: {
+        description?: string;
+        packageName?: string;
+    }): Promise<void>;
+    /**
+     * Convenience wrapper: if `name` hasn't been applied, run `fn` and
+     * record the result. Returns `{ ran, result }`:
+     *   - `{ ran: true,  result: T }`    — backfill was pending and `fn` ran
+     *   - `{ ran: false, result: null }` — backfill was already applied
+     *
+     * The discriminator avoids the `T | null` ambiguity an earlier shape had
+     * (a backfill that legitimately returns `null` was indistinguishable
+     * from "already applied"). Callers check `ran` to decide whether `fn`
+     * executed; `result` carries whatever `fn` returned.
+     *
+     * This is the common pattern an app's migrate orchestration follows:
+     * a list of `(name, runner)` pairs, each guarded by isApplied/run/record.
+     *
+     * **Single-runner only.** This is a check-then-act pattern with no
+     * locking: two processes that call `runIfPending` for the same `name`
+     * concurrently can both observe `isApplied === false`, both execute
+     * `fn`, and only then race to `recordApplied`. The `ON CONFLICT DO
+     * NOTHING` in `recordApplied` keeps the table clean but does NOT prevent
+     * `fn` from running twice. Acceptable when backfills are run from a
+     * single deploy-time migration step (the common case); if you need to
+     * fan out backfills across multiple workers, wrap the call in your own
+     * mutex (e.g. a Postgres advisory lock keyed by backfill name).
+     *
+     * **`fn` MUST be idempotent.** The order is `fn` → `recordApplied`, with
+     * no surrounding transaction. If `fn` succeeds but `recordApplied`
+     * throws (DB connection drops, transient error), the work has happened
+     * but is not recorded — the next call sees `isApplied === false` and
+     * re-runs `fn`. For non-idempotent work (slug rewrites that consume
+     * source rows, one-shot lookups), wrap the entire call in a transaction
+     * yourself or structure `fn` so a second execution is a no-op.
+     */
+    runIfPending<T>(name: string, fn: () => Promise<T>, options?: {
+        description?: string;
+        packageName?: string;
+    }): Promise<{
+        ran: false;
+        result: null;
+    } | {
+        ran: true;
+        result: T;
+    }>;
+    /** List every recorded backfill, oldest first. */
+    listApplied(): Promise<BackfillRecord[]>;
+}
+//# sourceMappingURL=backfill-tracker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backfill-tracker.d.ts","sourceRoot":"","sources":["../../src/migrations/backfill-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG5D,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,iBAAiB,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAoB;IACvC;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB,CAA8B;gBAE3C,OAAO,EAAE,sBAAsB;IAI3C;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAajC,iDAAiD;IAC3C,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS/C;;;;OAIG;IACG,aAAa,CACjB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO,GAC3D,OAAO,CAAC,IAAI,CAAC;IAYhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,YAAY,CAAC,CAAC,EAClB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO,GAC3D,OAAO,CAAC;QAAE,GAAG,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,CAAC,CAAA;KAAE,CAAC;IAOnE,kDAAkD;IAC5C,WAAW,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;CAY/C"}

package/dist/migrations/backfill-tracker.js

@@ -0,0 +1,118 @@
+import { CREATE_SMRT_BACKFILLS_TABLE } from "../system/schema.js";
+class BackfillTracker {
+  db;
+  /**
+   * Memoized initialization promise. Storing the promise (rather than a
+   * `boolean` flag set after the DDL completes) makes `initialize()` safe
+   * under concurrency: multiple parallel callers all `await` the same
+   * in-flight 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.
+   */
+  initializePromise = null;
+  constructor(options) {
+    this.db = options.db;
+  }
+  /**
+   * Create the `_smrt_backfills` table if it doesn't already exist.
+   * Safe to call repeatedly and concurrently.
+   */
+  async initialize() {
+    if (!this.initializePromise) {
+      this.initializePromise = this.db.query(CREATE_SMRT_BACKFILLS_TABLE).then(() => void 0).catch((error) => {
+        this.initializePromise = null;
+        throw error;
+      });
+    }
+    return this.initializePromise;
+  }
+  /** Has the backfill named `name` already run? */
+  async isApplied(name) {
+    await this.initialize();
+    const result = await this.db.query(
+      "SELECT 1 FROM _smrt_backfills WHERE name = ? LIMIT 1",
+      name
+    );
+    return result.rows.length > 0;
+  }
+  /**
+   * Record that the backfill named `name` ran. Uses INSERT ... ON CONFLICT
+   * so callers don't need to check `isApplied` first if they don't care
+   * about distinguishing "already applied" from "just applied".
+   */
+  async recordApplied(name, options = {}) {
+    await this.initialize();
+    await this.db.query(
+      `INSERT INTO _smrt_backfills (name, description, package_name)
+       VALUES (?, ?, ?)
+       ON CONFLICT (name) DO NOTHING`,
+      name,
+      options.description ?? null,
+      options.packageName ?? null
+    );
+  }
+  /**
+   * Convenience wrapper: if `name` hasn't been applied, run `fn` and
+   * record the result. Returns `{ ran, result }`:
+   *   - `{ ran: true,  result: T }`    — backfill was pending and `fn` ran
+   *   - `{ ran: false, result: null }` — backfill was already applied
+   *
+   * The discriminator avoids the `T | null` ambiguity an earlier shape had
+   * (a backfill that legitimately returns `null` was indistinguishable
+   * from "already applied"). Callers check `ran` to decide whether `fn`
+   * executed; `result` carries whatever `fn` returned.
+   *
+   * This is the common pattern an app's migrate orchestration follows:
+   * a list of `(name, runner)` pairs, each guarded by isApplied/run/record.
+   *
+   * **Single-runner only.** This is a check-then-act pattern with no
+   * locking: two processes that call `runIfPending` for the same `name`
+   * concurrently can both observe `isApplied === false`, both execute
+   * `fn`, and only then race to `recordApplied`. The `ON CONFLICT DO
+   * NOTHING` in `recordApplied` keeps the table clean but does NOT prevent
+   * `fn` from running twice. Acceptable when backfills are run from a
+   * single deploy-time migration step (the common case); if you need to
+   * fan out backfills across multiple workers, wrap the call in your own
+   * mutex (e.g. a Postgres advisory lock keyed by backfill name).
+   *
+   * **`fn` MUST be idempotent.** The order is `fn` → `recordApplied`, with
+   * no surrounding transaction. If `fn` succeeds but `recordApplied`
+   * throws (DB connection drops, transient error), the work has happened
+   * but is not recorded — the next call sees `isApplied === false` and
+   * re-runs `fn`. For non-idempotent work (slug rewrites that consume
+   * source rows, one-shot lookups), wrap the entire call in a transaction
+   * yourself or structure `fn` so a second execution is a no-op.
+   */
+  async runIfPending(name, fn, options = {}) {
+    if (await this.isApplied(name)) return { ran: false, result: null };
+    const result = await fn();
+    await this.recordApplied(name, options);
+    return { ran: true, result };
+  }
+  /** List every recorded backfill, oldest first. */
+  async listApplied() {
+    await this.initialize();
+    const result = await this.db.query(
+      "SELECT name, applied_at, description, package_name FROM _smrt_backfills ORDER BY applied_at ASC, name ASC"
+    );
+    return result.rows.map((row) => ({
+      name: String(row.name ?? ""),
+      appliedAt: normalizeAppliedAt(row.applied_at),
+      description: row.description == null ? null : String(row.description),
+      packageName: row.package_name == null ? null : String(row.package_name)
+    }));
+  }
+}
+function normalizeAppliedAt(value) {
+  if (value == null || value === "") return "";
+  const raw = String(value);
+  const parsed = new Date(raw);
+  if (Number.isNaN(parsed.getTime())) {
+    return raw;
+  }
+  return parsed.toISOString();
+}
+export {
+  BackfillTracker
+};
+//# sourceMappingURL=backfill-tracker.js.map

package/dist/migrations/backfill-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backfill-tracker.js","sources":["../../src/migrations/backfill-tracker.ts"],"sourcesContent":["/**\n * Tracks application-specific data backfills (not schema migrations).\n *\n * Sits next to `MigrationTracker` but is intentionally minimal — backfills\n * have no checksum, no rollback semantics, no DDL. They're \"this data\n * correction has run, don't run it again\" markers, keyed by a stable\n * backfill name the app chooses.\n *\n * Backed by the `_smrt_backfills` system table (see\n * `../system/schema.ts`). The table is created lazily on first use —\n * every public method (`isApplied`, `recordApplied`, `runIfPending`,\n * `listApplied`) awaits `initialize()` itself, so consumers never need\n * to call `initialize()` explicitly.\n */\nimport type { DatabaseInterface } from '@happyvertical/sql';\nimport { CREATE_SMRT_BACKFILLS_TABLE } from '../system/schema.js';\n\nexport interface BackfillTrackerOptions {\n  db: DatabaseInterface;\n}\n\nexport interface BackfillRecord {\n  name: string;\n  appliedAt: string;\n  description: string | null;\n  packageName: string | null;\n}\n\nexport class BackfillTracker {\n  private readonly db: DatabaseInterface;\n  /**\n   * Memoized initialization promise. Storing the promise (rather than a\n   * `boolean` flag set after the DDL completes) makes `initialize()` safe\n   * under concurrency: multiple parallel callers all `await` the same\n   * in-flight promise instead of independently re-running the DDL. On\n   * error the slot is cleared so the next caller retries — a transient\n   * failure doesn't permanently poison the instance.\n   */\n  private initializePromise: Promise<void> | null = null;\n\n  constructor(options: BackfillTrackerOptions) {\n    this.db = options.db;\n  }\n\n  /**\n   * Create the `_smrt_backfills` table if it doesn't already exist.\n   * Safe to call repeatedly and concurrently.\n   */\n  async initialize(): Promise<void> {\n    if (!this.initializePromise) {\n      this.initializePromise = this.db\n        .query(CREATE_SMRT_BACKFILLS_TABLE)\n        .then(() => undefined)\n        .catch((error) => {\n          this.initializePromise = null;\n          throw error;\n        });\n    }\n    return this.initializePromise;\n  }\n\n  /** Has the backfill named `name` already run? */\n  async isApplied(name: string): Promise<boolean> {\n    await this.initialize();\n    const result = await this.db.query(\n      'SELECT 1 FROM _smrt_backfills WHERE name = ? LIMIT 1',\n      name,\n    );\n    return result.rows.length > 0;\n  }\n\n  /**\n   * Record that the backfill named `name` ran. Uses INSERT ... ON CONFLICT\n   * so callers don't need to check `isApplied` first if they don't care\n   * about distinguishing \"already applied\" from \"just applied\".\n   */\n  async recordApplied(\n    name: string,\n    options: { description?: string; packageName?: string } = {},\n  ): Promise<void> {\n    await this.initialize();\n    await this.db.query(\n      `INSERT INTO _smrt_backfills (name, description, package_name)\n       VALUES (?, ?, ?)\n       ON CONFLICT (name) DO NOTHING`,\n      name,\n      options.description ?? null,\n      options.packageName ?? null,\n    );\n  }\n\n  /**\n   * Convenience wrapper: if `name` hasn't been applied, run `fn` and\n   * record the result. Returns `{ ran, result }`:\n   *   - `{ ran: true,  result: T }`    — backfill was pending and `fn` ran\n   *   - `{ ran: false, result: null }` — backfill was already applied\n   *\n   * The discriminator avoids the `T | null` ambiguity an earlier shape had\n   * (a backfill that legitimately returns `null` was indistinguishable\n   * from \"already applied\"). Callers check `ran` to decide whether `fn`\n   * executed; `result` carries whatever `fn` returned.\n   *\n   * This is the common pattern an app's migrate orchestration follows:\n   * a list of `(name, runner)` pairs, each guarded by isApplied/run/record.\n   *\n   * **Single-runner only.** This is a check-then-act pattern with no\n   * locking: two processes that call `runIfPending` for the same `name`\n   * concurrently can both observe `isApplied === false`, both execute\n   * `fn`, and only then race to `recordApplied`. The `ON CONFLICT DO\n   * NOTHING` in `recordApplied` keeps the table clean but does NOT prevent\n   * `fn` from running twice. Acceptable when backfills are run from a\n   * single deploy-time migration step (the common case); if you need to\n   * fan out backfills across multiple workers, wrap the call in your own\n   * mutex (e.g. a Postgres advisory lock keyed by backfill name).\n   *\n   * **`fn` MUST be idempotent.** The order is `fn` → `recordApplied`, with\n   * no surrounding transaction. If `fn` succeeds but `recordApplied`\n   * throws (DB connection drops, transient error), the work has happened\n   * but is not recorded — the next call sees `isApplied === false` and\n   * re-runs `fn`. For non-idempotent work (slug rewrites that consume\n   * source rows, one-shot lookups), wrap the entire call in a transaction\n   * yourself or structure `fn` so a second execution is a no-op.\n   */\n  async runIfPending<T>(\n    name: string,\n    fn: () => Promise<T>,\n    options: { description?: string; packageName?: string } = {},\n  ): Promise<{ ran: false; result: null } | { ran: true; result: T }> {\n    if (await this.isApplied(name)) return { ran: false, result: null };\n    const result = await fn();\n    await this.recordApplied(name, options);\n    return { ran: true, result };\n  }\n\n  /** List every recorded backfill, oldest first. */\n  async listApplied(): Promise<BackfillRecord[]> {\n    await this.initialize();\n    const result = await this.db.query(\n      'SELECT name, applied_at, description, package_name FROM _smrt_backfills ORDER BY applied_at ASC, name ASC',\n    );\n    return result.rows.map((row) => ({\n      name: String(row.name ?? ''),\n      appliedAt: normalizeAppliedAt(row.applied_at),\n      description: row.description == null ? null : String(row.description),\n      packageName: row.package_name == null ? null : String(row.package_name),\n    }));\n  }\n}\n\n/**\n * Convert a raw `applied_at` cell into an ISO 8601 string.\n *\n * Different DB drivers return this column in different shapes:\n *  - Postgres `node-pg` returns a JS `Date` directly.\n *  - SQLite drivers typically return the `CURRENT_TIMESTAMP` literal\n *    `'YYYY-MM-DD HH:MM:SS'` (no `T`, no timezone). V8's `Date`\n *    constructor parses this as local time, but that's\n *    implementation-defined and other runtimes may return Invalid Date.\n *  - A corrupted row could return any string.\n *\n * If the value parses to a valid Date we return `toISOString()`. If it\n * doesn't (or the column is null/empty), we fall back to the raw string —\n * better to surface a non-ISO timestamp than crash `listApplied()` with a\n * `RangeError` and take down the caller.\n */\nfunction normalizeAppliedAt(value: unknown): string {\n  if (value == null || value === '') return '';\n  const raw = String(value);\n  const parsed = new Date(raw);\n  if (Number.isNaN(parsed.getTime())) {\n    return raw;\n  }\n  return parsed.toISOString();\n}\n"],"names":[],"mappings":";AA4BO,MAAM,gBAAgB;AAAA,EACV;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAST,oBAA0C;AAAA,EAElD,YAAY,SAAiC;AAC3C,SAAK,KAAK,QAAQ;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,aAA4B;AAChC,QAAI,CAAC,KAAK,mBAAmB;AAC3B,WAAK,oBAAoB,KAAK,GAC3B,MAAM,2BAA2B,EACjC,KAAK,MAAM,MAAS,EACpB,MAAM,CAAC,UAAU;AAChB,aAAK,oBAAoB;AACzB,cAAM;AAAA,MACR,CAAC;AAAA,IACL;AACA,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,MAAM,UAAU,MAAgC;AAC9C,UAAM,KAAK,WAAA;AACX,UAAM,SAAS,MAAM,KAAK,GAAG;AAAA,MAC3B;AAAA,MACA;AAAA,IAAA;AAEF,WAAO,OAAO,KAAK,SAAS;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,cACJ,MACA,UAA0D,IAC3C;AACf,UAAM,KAAK,WAAA;AACX,UAAM,KAAK,GAAG;AAAA,MACZ;AAAA;AAAA;AAAA,MAGA;AAAA,MACA,QAAQ,eAAe;AAAA,MACvB,QAAQ,eAAe;AAAA,IAAA;AAAA,EAE3B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkCA,MAAM,aACJ,MACA,IACA,UAA0D,CAAA,GACQ;AAClE,QAAI,MAAM,KAAK,UAAU,IAAI,UAAU,EAAE,KAAK,OAAO,QAAQ,KAAA;AAC7D,UAAM,SAAS,MAAM,GAAA;AACrB,UAAM,KAAK,cAAc,MAAM,OAAO;AACtC,WAAO,EAAE,KAAK,MAAM,OAAA;AAAA,EACtB;AAAA;AAAA,EAGA,MAAM,cAAyC;AAC7C,UAAM,KAAK,WAAA;AACX,UAAM,SAAS,MAAM,KAAK,GAAG;AAAA,MAC3B;AAAA,IAAA;AAEF,WAAO,OAAO,KAAK,IAAI,CAAC,SAAS;AAAA,MAC/B,MAAM,OAAO,IAAI,QAAQ,EAAE;AAAA,MAC3B,WAAW,mBAAmB,IAAI,UAAU;AAAA,MAC5C,aAAa,IAAI,eAAe,OAAO,OAAO,OAAO,IAAI,WAAW;AAAA,MACpE,aAAa,IAAI,gBAAgB,OAAO,OAAO,OAAO,IAAI,YAAY;AAAA,IAAA,EACtE;AAAA,EACJ;AACF;AAkBA,SAAS,mBAAmB,OAAwB;AAClD,MAAI,SAAS,QAAQ,UAAU,GAAI,QAAO;AAC1C,QAAM,MAAM,OAAO,KAAK;AACxB,QAAM,SAAS,IAAI,KAAK,GAAG;AAC3B,MAAI,OAAO,MAAM,OAAO,QAAA,CAAS,GAAG;AAClC,WAAO;AAAA,EACT;AACA,SAAO,OAAO,YAAA;AAChB;"}

package/dist/migrations/checksum.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Migration Checksum Utilities
+ *
+ * Provides SHA-256 checksum computation for migration idempotency
+ * and drift detection.
+ */
+/**
+ * Compute SHA-256 checksum of migration SQL statements
+ *
+ * Normalizes SQL before hashing to ensure consistent checksums:
+ * - Removes single-line and multi-line comments
+ * - Collapses whitespace
+ * - Trims each statement
+ */
+export declare function computeChecksum(statements: string[]): string;
+/**
+ * Normalize SQL statements for consistent checksums
+ *
+ * Steps:
+ * 1. Remove single-line comments (-- ...)
+ * 2. Remove multi-line comments (/* ... *\/)
+ * 3. Collapse multiple whitespace to single space
+ * 4. Trim each statement
+ * 5. Filter empty statements
+ * 6. Join with semicolons
+ */
+export declare function normalizeSQL(statements: string[]): string;
+/**
+ * Verify that a migration file hasn't been modified since application
+ *
+ * @param definitionChecksum - Checksum from current migration definition
+ * @param recordChecksum - Checksum stored when migration was applied
+ * @param appliedChecksum - Checksum of what was actually applied (for drift)
+ */
+export declare function verifyChecksum(definitionChecksum: string, recordChecksum: string, appliedChecksum?: string | null): {
+    valid: boolean;
+    drift?: 'file_modified' | 'db_modified';
+};
+/**
+ * Generate a short checksum for display (first 8 characters)
+ */
+export declare function shortChecksum(checksum: string): string;
+//# sourceMappingURL=checksum.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.d.ts","sourceRoot":"","sources":["../../src/migrations/checksum.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAG5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAazD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,kBAAkB,EAAE,MAAM,EAC1B,cAAc,EAAE,MAAM,EACtB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,GAC9B;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,eAAe,GAAG,aAAa,CAAA;CAAE,CAY7D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/migrations/checksum.js

@@ -0,0 +1,32 @@
+import { createHash } from "node:crypto";
+function computeChecksum(statements) {
+  const normalized = normalizeSQL(statements);
+  return createHash("sha256").update(normalized).digest("hex");
+}
+function normalizeSQL(statements) {
+  return statements.map((sql) => {
+    let normalized = sql.replace(/--.*$/gm, "");
+    normalized = normalized.replace(/\/\*[\s\S]*?\*\//g, "");
+    normalized = normalized.replace(/\s+/g, " ").trim();
+    return normalized;
+  }).filter((sql) => sql.length > 0).join(";");
+}
+function verifyChecksum(definitionChecksum, recordChecksum, appliedChecksum) {
+  if (definitionChecksum !== recordChecksum) {
+    return { valid: false, drift: "file_modified" };
+  }
+  if (appliedChecksum && appliedChecksum !== recordChecksum) {
+    return { valid: false, drift: "db_modified" };
+  }
+  return { valid: true };
+}
+function shortChecksum(checksum) {
+  return checksum.substring(0, 8);
+}
+export {
+  computeChecksum,
+  normalizeSQL,
+  shortChecksum,
+  verifyChecksum
+};
+//# sourceMappingURL=checksum.js.map

package/dist/migrations/checksum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.js","sources":["../../src/migrations/checksum.ts"],"sourcesContent":["/**\n * Migration Checksum Utilities\n *\n * Provides SHA-256 checksum computation for migration idempotency\n * and drift detection.\n */\n\nimport { createHash } from 'node:crypto';\n\n/**\n * Compute SHA-256 checksum of migration SQL statements\n *\n * Normalizes SQL before hashing to ensure consistent checksums:\n * - Removes single-line and multi-line comments\n * - Collapses whitespace\n * - Trims each statement\n */\nexport function computeChecksum(statements: string[]): string {\n  const normalized = normalizeSQL(statements);\n  return createHash('sha256').update(normalized).digest('hex');\n}\n\n/**\n * Normalize SQL statements for consistent checksums\n *\n * Steps:\n * 1. Remove single-line comments (-- ...)\n * 2. Remove multi-line comments (/* ... *\\/)\n * 3. Collapse multiple whitespace to single space\n * 4. Trim each statement\n * 5. Filter empty statements\n * 6. Join with semicolons\n */\nexport function normalizeSQL(statements: string[]): string {\n  return statements\n    .map((sql) => {\n      // Remove single-line comments\n      let normalized = sql.replace(/--.*$/gm, '');\n      // Remove multi-line comments\n      normalized = normalized.replace(/\\/\\*[\\s\\S]*?\\*\\//g, '');\n      // Collapse whitespace\n      normalized = normalized.replace(/\\s+/g, ' ').trim();\n      return normalized;\n    })\n    .filter((sql) => sql.length > 0)\n    .join(';');\n}\n\n/**\n * Verify that a migration file hasn't been modified since application\n *\n * @param definitionChecksum - Checksum from current migration definition\n * @param recordChecksum - Checksum stored when migration was applied\n * @param appliedChecksum - Checksum of what was actually applied (for drift)\n */\nexport function verifyChecksum(\n  definitionChecksum: string,\n  recordChecksum: string,\n  appliedChecksum?: string | null,\n): { valid: boolean; drift?: 'file_modified' | 'db_modified' } {\n  // Check if definition file was modified after application\n  if (definitionChecksum !== recordChecksum) {\n    return { valid: false, drift: 'file_modified' };\n  }\n\n  // Check if what was applied differs from what we expected\n  if (appliedChecksum && appliedChecksum !== recordChecksum) {\n    return { valid: false, drift: 'db_modified' };\n  }\n\n  return { valid: true };\n}\n\n/**\n * Generate a short checksum for display (first 8 characters)\n */\nexport function shortChecksum(checksum: string): string {\n  return checksum.substring(0, 8);\n}\n"],"names":[],"mappings":";AAiBO,SAAS,gBAAgB,YAA8B;AAC5D,QAAM,aAAa,aAAa,UAAU;AAC1C,SAAO,WAAW,QAAQ,EAAE,OAAO,UAAU,EAAE,OAAO,KAAK;AAC7D;AAaO,SAAS,aAAa,YAA8B;AACzD,SAAO,WACJ,IAAI,CAAC,QAAQ;AAEZ,QAAI,aAAa,IAAI,QAAQ,WAAW,EAAE;AAE1C,iBAAa,WAAW,QAAQ,qBAAqB,EAAE;AAEvD,iBAAa,WAAW,QAAQ,QAAQ,GAAG,EAAE,KAAA;AAC7C,WAAO;AAAA,EACT,CAAC,EACA,OAAO,CAAC,QAAQ,IAAI,SAAS,CAAC,EAC9B,KAAK,GAAG;AACb;AASO,SAAS,eACd,oBACA,gBACA,iBAC6D;AAE7D,MAAI,uBAAuB,gBAAgB;AACzC,WAAO,EAAE,OAAO,OAAO,OAAO,gBAAA;AAAA,EAChC;AAGA,MAAI,mBAAmB,oBAAoB,gBAAgB;AACzD,WAAO,EAAE,OAAO,OAAO,OAAO,cAAA;AAAA,EAChC;AAEA,SAAO,EAAE,OAAO,KAAA;AAClB;AAKO,SAAS,cAAc,UAA0B;AACtD,SAAO,SAAS,UAAU,GAAG,CAAC;AAChC;"}