@fuzdev/fuz_app 0.101.0 → 0.101.1

package/dist/db/status.d.ts

@@ -4,10 +4,41 @@
  * Queries migration state and table info without a running server.
  * Returns structured data that consumer scripts can print however they like.
  *
+ * The migration check is **name-divergence aware**: it name-prefix-verifies the
+ * applied migrations against the code's list (mirroring `run_migrations`), so a
+ * divergent history (same count, different names) reports a `divergence` and
+ * renders `DIVERGED` rather than a false `up_to_date`.
+ *
  * @module
  */
 import type { Db } from './db.js';
 import type { MigrationNamespace } from './migrate.js';
+/**
+ * A divergence between the recorded migration tracker and the code's list.
+ *
+ * Either variant is a state the migration runner refuses to boot against — a
+ * re-bootstrap (drop + migrate) is needed. Structured (not a pre-formatted
+ * string) so programmatic consumers can branch on `kind`; `format_db_status`
+ * renders the operator-facing line. The discriminated-union twin of the Rust
+ * `fuz_db` `Divergence` enum.
+ */
+export type Divergence = {
+    /** An applied name doesn't match the code's name at `position`. */
+    kind: 'name_mismatch';
+    /** Sequence position of the first mismatch. */
+    position: number;
+    /** The name recorded in the tracker at `position`. */
+    applied: string;
+    /** The name the code declares at `position`. */
+    expected: string;
+} | {
+    /** The tracker records more migrations than the code declares. */
+    kind: 'binary_older';
+    /** Count recorded in the tracker. */
+    applied: number;
+    /** Count the code declares. */
+    declared: number;
+};
 /**
  * Migration status for a single namespace.
  */
@@ -17,8 +48,18 @@ export interface MigrationStatus {
     applied_names: Array<string>;
     /** Names of code migrations not yet applied (suffix of the code array). */
     pending_names: Array<string>;
-    /** Whether `applied_names` is the full code array (no pending work). */
+    /**
+     * Whether `applied_names` is the full code array with no name divergence
+     * (no pending work, no diverged history).
+     */
     up_to_date: boolean;
+    /**
+     * The first applied/code divergence, if any. Absent when the applied names
+     * are a clean prefix of the code's list (the only state the runner boots
+     * against). Present means a divergent bootstrap history — a re-bootstrap
+     * (drop + migrate) is needed.
+     */
+    divergence?: Divergence;
 }
 /**
  * Table info with row count.

package/dist/db/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/status.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,SAAS,CAAC;AAChC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,cAAc,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,2EAA2E;IAC3E,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,wEAAwE;IACxE,UAAU,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,yCAAyC;IACzC,SAAS,EAAE,OAAO,CAAC;IACnB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC3B,sCAAsC;IACtC,UAAU,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IACnC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC5B;AA8BD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GAC3B,IAAI,EAAE,EACN,aAAa,KAAK,CAAC,kBAAkB,CAAC,KACpC,OAAO,CAAC,QAAQ,CAmFlB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,QAAQ,KAAG,MA8CnD,CAAC"}
+{"version":3,"file":"status.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,SAAS,CAAC;AAChC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,cAAc,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GACnB;IACA,mEAAmE;IACnE,IAAI,EAAE,eAAe,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;CAChB,GACD;IACA,kEAAkE;IAClE,IAAI,EAAE,cAAc,CAAC;IACrB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;CAChB,CAAC;AAEL;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,2EAA2E;IAC3E,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,yCAAyC;IACzC,SAAS,EAAE,OAAO,CAAC;IACnB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC3B,sCAAsC;IACtC,UAAU,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IACnC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC5B;AA8BD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GAC3B,IAAI,EAAE,EACN,aAAa,KAAK,CAAC,kBAAkB,CAAC,KACpC,OAAO,CAAC,QAAQ,CA2GlB,CAAC;AAeF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,QAAQ,KAAG,MAoDnD,CAAC"}

package/dist/db/status.js

@@ -4,6 +4,11 @@
  * Queries migration state and table info without a running server.
  * Returns structured data that consumer scripts can print however they like.
  *
+ * The migration check is **name-divergence aware**: it name-prefix-verifies the
+ * applied migrations against the code's list (mirroring `run_migrations`), so a
+ * divergent history (same count, different names) reports a `divergence` and
+ * renders `DIVERGED` rather than a false `up_to_date`.
+ *
  * @module
  */
 import { to_error_message } from '@fuzdev/fuz_util/error.ts';
@@ -78,14 +83,37 @@ export const query_db_status = async (db, namespaces) => {
 					 ORDER BY sequence ASC`, [namespace]);
                 const applied_names = rows.map((r) => r.name);
                 const code_names = ns_migrations.map((m) => m.name);
-                // pending = the suffix of code names beyond applied.length (callers
-                // see the boot algorithm's tail without paying for verify here)
-                const pending_names = code_names.slice(applied_names.length);
+                const total = code_names.length;
+                const applied = applied_names.length;
+                // Name-prefix verify, mirroring the migration runner: the applied
+                // names must equal the first `applied` code names by position. A
+                // divergent history (a renamed/reordered migration, same count or not)
+                // is the exact state `run_migrations` refuses to boot against, so a
+                // count-only check would report a DB the runner rejects as up-to-date.
+                let divergence;
+                if (applied > total) {
+                    divergence = { kind: 'binary_older', applied, declared: total };
+                }
+                else {
+                    const position = applied_names.findIndex((name, i) => name !== code_names[i]);
+                    if (position !== -1) {
+                        divergence = {
+                            kind: 'name_mismatch',
+                            position,
+                            applied: applied_names[position],
+                            expected: code_names[position],
+                        };
+                    }
+                }
+                // pending = the suffix of code names past the applied count (clamped:
+                // a binary-older history has no pending tail)
+                const pending_names = code_names.slice(Math.min(applied, total));
                 migrations.push({
                     namespace,
                     applied_names,
                     pending_names,
-                    up_to_date: applied_names.length === code_names.length && pending_names.length === 0,
+                    up_to_date: applied === total && pending_names.length === 0 && divergence === undefined,
+                    ...(divergence ? { divergence } : {}),
                 });
             }
         }
@@ -110,6 +138,18 @@ export const query_db_status = async (db, namespaces) => {
         ...(old_tracker_shape ? { old_tracker_shape: true } : {}),
     };
 };
+/**
+ * Render a `Divergence` as the operator-facing detail line. Twin of the Rust
+ * `Divergence` `Display`.
+ */
+const format_divergence = (divergence) => {
+    switch (divergence.kind) {
+        case 'name_mismatch':
+            return `position ${divergence.position}: database has '${divergence.applied}', code has '${divergence.expected}'`;
+        case 'binary_older':
+            return `database has ${divergence.applied} applied but code declares ${divergence.declared} (binary older than database)`;
+    }
+};
 /**
  * Format a `DbStatus` as a human-readable string for CLI output.
  *
@@ -141,7 +181,10 @@ export const format_db_status = (status) => {
         lines.push('  Migrations:');
         for (const m of status.migrations) {
             const total = m.applied_names.length + m.pending_names.length;
-            if (m.up_to_date) {
+            if (m.divergence) {
+                lines.push(`    ${m.namespace}: DIVERGED (${m.applied_names.length}/${total}) — ${format_divergence(m.divergence)}`);
+            }
+            else if (m.up_to_date) {
                 lines.push(`    ${m.namespace}: up to date (${m.applied_names.length}/${total})`);
             }
             else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.101.0",
+  "version": "0.101.1",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",