@memberjunction/cli 5.37.0 → 5.39.0

package/README.md

@@ -435,6 +435,80 @@ mj app install https://github.com/BlueCypress/SaaS \
   --dangerously-ignore-dbl-underscore-schema-rule
 ```
 
+### mj baseline
+
+Build, compare, and round-trip **baseline migrations** — a single SQL script that captures the end-state of an entire V-stack (schema + every row of every table) into one deterministic `B`-prefixed file that Flyway/Skyway can apply to a fresh database in place of the long migration chain.
+
+> Niche command — only needed when **collapsing a V-stack into a new baseline** (within-major rebaseline) or **cutting a new major version** (e.g. v5 → v6). Day-to-day MJ development never touches this; use `mj migrate` for routine schema changes.
+
+Three subcommands:
+
+- `mj baseline build` — connect to a live MSSQL database, introspect everything, dump every row of every table, and emit a canonical T-SQL script.
+- `mj baseline compare` — diff two live databases object-by-object **and** row-by-row.
+- `mj baseline roundtrip` — `build` + apply to a fresh DB + `compare` in one shot. Proves the new baseline is byte-equivalent to the V-stack it replaces.
+
+#### Two operating modes
+
+| Mode | Trigger | Version source | Timestamp | Output folder |
+| --- | --- | --- | --- | --- |
+| **AUTO — within-major rebaseline** (default) | `--baseline-version` omitted | `Major.Minor` parsed from the latest V-file in `--source-dir` | latest V-file's timestamp **+ 1 minute** | the **same** `migrations/v{N}/` it scanned |
+| **EXPLICIT — major-boundary baseline** | `--baseline-version M.N` provided | the flag value | `Date.now()` UTC | `migrations/v{N+1}/` (new) |
+
+AUTO mode is the right choice 99% of the time. EXPLICIT is for starting a new major version (e.g. `v6.0`).
+
+Filename format: `B{YYYYMMDDHHMM}__v{Major}.{Minor}.x__Baseline.sql` (literal lowercase `x` matches the V-file patch convention — patches don't carry migrations).
+
+#### mj baseline build
+
+```bash
+# AUTO — within-major rebaseline (writes back into ./migrations/v5/)
+mj baseline build --out ./migrations/v5/
+
+# EXPLICIT — start a new major version (writes into ./migrations/v6/)
+mj baseline build --baseline-version 6.0 --out ./migrations/v6/
+
+# Schema-only, no data inserts
+mj baseline build --no-data --out ./baselines/
+```
+
+Key flags: `--baseline-version`, `--source-dir`, `--database`, `--out`, `--exclude-data <csv>`, `--batch-size`, `--no-data`, `--dry-run`, `--verbose`. Run `mj baseline build --help` for the full list with defaults.
+
+Database host/user/password come from the MJ config (`mj.config.cjs` / `.env`); `--database` overrides only the database name.
+
+#### mj baseline compare
+
+```bash
+# Full row-by-row diff (default)
+mj baseline compare --left MJ_BL_Stack --right MJ_BL_New
+
+# Counts-only (fastest)
+mj baseline compare --left A --right B --row-compare counts
+
+# CI use — fail the build on any diff, write reports
+mj baseline compare --left A --right B --fail-on-diff --out ./diffs/
+```
+
+Row-compare modes: `full` | `hash` | `counts` | `none`. Hash mode supports `--row-hash-algo sha256|md5|checksum_agg`. `--dialect mssql|postgres` (both sides must match).
+
+#### mj baseline roundtrip
+
+```bash
+# AUTO — verify the current v5.x V-stack collapses cleanly
+mj baseline roundtrip --source MJ_BL_Stack --target MJ_BL_New
+
+# EXPLICIT — verify a v6.0 baseline
+mj baseline roundtrip --baseline-version 6.0 --source MJ_BL_Stack --target MJ_BL_New
+```
+
+`--source` is the gold-standard DB with the V-stack already applied; `--target` is an empty DB the new baseline will be applied to and compared against. Add `--keep-target` to inspect the post-apply DB after a failed diff. `--apply-cmd` lets you override the default `sqlcmd` apply step (tokens: `{file}`, `{database}`).
+
+#### Related tooling
+
+- **Slash command** — [`/create-new-baseline-migration`](../../.claude/commands/create-new-baseline-migration.md) drives the workbench end-to-end from a local Claude Code session (spins up the workbench, runs the roundtrip, stages the file in `migrations/` only if byte-equivalent).
+- **Workbench script** — [`docker/workbench/baseline-roundtrip.sh`](../../docker/workbench/baseline-roundtrip.sh) (aliases `mjbaseline`, `mjbaseline-mssql`, `mjbaseline-pg` inside the workbench container) is the 7-phase end-to-end runner the slash command invokes.
+- **Design record** — [`packages/MJCLI/src/commands/baseline/PLAN.md`](src/commands/baseline/PLAN.md) documents the architecture, decisions, and component layout.
+- **PostgreSQL** — the T-SQL baseline is converted via `mj migrate convert` (see `/pg-migrate` skill) before being applied to a PG target.
+
 ## Hooks
 
 | Hook | Timing | Purpose |

package/dist/baseline/cli-helpers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared helpers for the `mj baseline ...` oclif commands.
+ *
+ * - Resolve a DbConnectionParams from the merged MJ config (env + mj.config.cjs)
+ *   with optional flag overrides (db name, host, etc).
+ * - Detect TTY for spinner vs. plain log output.
+ */
+import type { DbConnectionParams, DbConnectionOverrides } from './connection.js';
+import type { Dialect } from './types.js';
+export declare function resolveConnection(overrides?: DbConnectionOverrides, dialectFlag?: Dialect): DbConnectionParams;
+export declare function isTty(): boolean;
+//# sourceMappingURL=cli-helpers.d.ts.map

package/dist/baseline/cli-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-helpers.d.ts","sourceRoot":"","sources":["../../src/baseline/cli-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,wBAAgB,iBAAiB,CAAC,SAAS,GAAE,qBAA0B,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAwBlH;AAED,wBAAgB,KAAK,IAAI,OAAO,CAE/B"}

package/dist/baseline/cli-helpers.js

@@ -0,0 +1,40 @@
+/**
+ * Shared helpers for the `mj baseline ...` oclif commands.
+ *
+ * - Resolve a DbConnectionParams from the merged MJ config (env + mj.config.cjs)
+ *   with optional flag overrides (db name, host, etc).
+ * - Detect TTY for spinner vs. plain log output.
+ */
+import { getValidatedConfig } from '../config.js';
+export function resolveConnection(overrides = {}, dialectFlag) {
+    const config = getValidatedConfig();
+    const dialect = dialectFlag
+        ?? (config.dbPlatform === 'postgresql' ? 'postgres' : 'mssql');
+    const host = overrides.host ?? config.dbHost;
+    const port = overrides.port ?? (config.dbPort ? Number(config.dbPort) : undefined);
+    const database = overrides.database ?? config.dbDatabase;
+    const user = overrides.user ?? config.codeGenLogin;
+    const password = overrides.password ?? config.codeGenPassword;
+    if (!host)
+        throw new Error('No DB host configured (set DB_HOST or dbHost in mj.config.cjs).');
+    if (!database)
+        throw new Error('No DB database configured (set DB_DATABASE or dbDatabase, or pass --database).');
+    if (!user)
+        throw new Error('No DB user configured (set CODEGEN_DB_USERNAME).');
+    if (!password)
+        throw new Error('No DB password configured (set CODEGEN_DB_PASSWORD).');
+    return {
+        dialect,
+        host,
+        port,
+        database,
+        user,
+        password,
+        encrypt: overrides.encrypt ?? Boolean(config.dbEncrypt),
+        trustServerCertificate: overrides.trustServerCertificate ?? Boolean(config.dbTrustServerCertificate),
+    };
+}
+export function isTty() {
+    return Boolean(process.stdout.isTTY) && process.env.CI !== 'true';
+}
+//# sourceMappingURL=cli-helpers.js.map

package/dist/baseline/cli-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-helpers.js","sourceRoot":"","sources":["../../src/baseline/cli-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAI/C,MAAM,UAAU,iBAAiB,CAAC,YAAmC,EAAE,EAAE,WAAqB;IAC5F,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAC;IACpC,MAAM,OAAO,GAAY,WAAW;WAC/B,CAAC,MAAM,CAAC,UAAU,KAAK,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAEjE,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC;IAC7C,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACnF,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,IAAI,MAAM,CAAC,UAAU,CAAC;IACzD,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,IAAK,MAAoC,CAAC,YAAY,CAAC;IAClF,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,IAAK,MAAuC,CAAC,eAAe,CAAC;IAChG,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAC;IAC9F,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,gFAAgF,CAAC,CAAC;IACjH,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IAC/E,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IACvF,OAAO;QACL,OAAO;QACP,IAAI;QACJ,IAAI;QACJ,QAAQ;QACR,IAAI;QACJ,QAAQ;QACR,OAAO,EAAE,SAAS,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC;QACvD,sBAAsB,EAAE,SAAS,CAAC,sBAAsB,IAAI,OAAO,CAAC,MAAM,CAAC,wBAAwB,CAAC;KACrG,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,KAAK;IACnB,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,MAAM,CAAC;AACpE,CAAC"}

package/dist/baseline/comparator.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Schema and data comparator.
+ *
+ * Produces a DiffReport from two SchemaSnapshots. Operates dialect-agnostically
+ * because the snapshot shape is normalized; tagging is preserved on each side
+ * but equality is decided structurally.
+ *
+ * Row-by-row comparison (when row data is supplied) walks each table's rows
+ * in their canonical order and reports value-level diffs.
+ */
+import type { BaselineCompareOptions, DiffReport, SchemaSnapshot, TableDataDump } from './types.js';
+export interface CompareInput {
+    left: {
+        snapshot: SchemaSnapshot;
+        data: readonly TableDataDump[];
+        label: string;
+    };
+    right: {
+        snapshot: SchemaSnapshot;
+        data: readonly TableDataDump[];
+        label: string;
+    };
+    options: BaselineCompareOptions;
+}
+export declare function compareSnapshots(input: CompareInput): DiffReport;
+//# sourceMappingURL=comparator.d.ts.map

package/dist/baseline/comparator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparator.d.ts","sourceRoot":"","sources":["../../src/baseline/comparator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EACV,sBAAsB,EAGtB,UAAU,EAMV,cAAc,EACd,aAAa,EAKd,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE;QAAE,QAAQ,EAAE,cAAc,CAAC;QAAC,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAClF,KAAK,EAAE;QAAE,QAAQ,EAAE,cAAc,CAAC;QAAC,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACnF,OAAO,EAAE,sBAAsB,CAAC;CACjC;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,CAoMhE"}