ic-mops 2.10.0 → 2.11.0

package/dist/helpers/migrations.js

@@ -0,0 +1,109 @@
+import { existsSync, mkdirSync, readdirSync, symlinkSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { rm } from "node:fs/promises";
+import chalk from "chalk";
+import { cliError } from "../error.js";
+import { resolveConfigPath } from "../mops.js";
+const MIGRATIONS_TEMP_DIR = ".mops/.migrations";
+export function getMigrationFiles(dir) {
+    if (!existsSync(dir)) {
+        return [];
+    }
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".mo"))
+        .sort();
+}
+export function getNextMigrationFile(nextDir) {
+    if (!existsSync(nextDir)) {
+        return null;
+    }
+    const files = readdirSync(nextDir).filter((f) => f.endsWith(".mo"));
+    if (files.length > 1) {
+        cliError(`next-migration directory must contain at most 1 .mo file, found ${files.length} in ${nextDir}`);
+    }
+    return files[0] ?? null;
+}
+export function validateNextMigrationOrder(chainDirOrFiles, nextFile) {
+    const chainFiles = typeof chainDirOrFiles === "string"
+        ? getMigrationFiles(chainDirOrFiles)
+        : chainDirOrFiles;
+    const lastChainFile = chainFiles[chainFiles.length - 1];
+    if (lastChainFile && nextFile <= lastChainFile) {
+        cliError(`Next migration "${nextFile}" must sort after all files in the chain.\n` +
+            `Last chain file: "${lastChainFile}".\n` +
+            "Use a timestamp prefix (e.g. YYYYMMDD_HHMMSS_Name.mo) to ensure correct ordering.");
+    }
+}
+export function validateMigrationsConfig(migrations, canisterName) {
+    if (!migrations.chain) {
+        cliError(`[canisters.${canisterName}.migrations] is missing required field "chain"`);
+    }
+    for (const field of ["check-limit", "build-limit"]) {
+        const value = migrations[field];
+        if (value !== undefined && (!Number.isInteger(value) || value <= 0)) {
+            cliError(`[canisters.${canisterName}.migrations] ${field} must be a positive integer`);
+        }
+    }
+}
+export async function prepareMigrationArgs(migrations, canisterName, mode, verbose) {
+    const noOp = {
+        migrationArgs: [],
+        cleanup: async () => { },
+    };
+    if (!migrations) {
+        return noOp;
+    }
+    validateMigrationsConfig(migrations, canisterName);
+    const chainDir = resolveConfigPath(migrations.chain);
+    const nextDir = migrations.next
+        ? resolveConfigPath(migrations.next)
+        : undefined;
+    const nextFile = nextDir ? getNextMigrationFile(nextDir) : null;
+    if (!existsSync(chainDir) && !nextFile) {
+        cliError(`Migration chain directory not found: ${chainDir}\n` +
+            "Run `mops migrate new <Name>` to initialize the migration chain.");
+    }
+    const chainFiles = getMigrationFiles(chainDir);
+    if (nextFile) {
+        validateNextMigrationOrder(chainFiles, nextFile);
+    }
+    const allMigrations = chainFiles.map((f) => ({
+        file: f,
+        dir: chainDir,
+    }));
+    if (nextFile && nextDir) {
+        allMigrations.push({ file: nextFile, dir: nextDir });
+    }
+    const limit = mode === "check" ? migrations["check-limit"] : migrations["build-limit"];
+    const isTrimming = limit !== undefined && limit < allMigrations.length;
+    const needsTempDir = nextFile !== null || isTrimming;
+    if (!needsTempDir) {
+        return {
+            migrationArgs: [`--enhanced-migration=${chainDir}`],
+            cleanup: async () => { },
+        };
+    }
+    const tempDir = join(MIGRATIONS_TEMP_DIR, canisterName);
+    await rm(tempDir, { recursive: true, force: true });
+    mkdirSync(tempDir, { recursive: true });
+    const filesToInclude = isTrimming
+        ? allMigrations.slice(-limit)
+        : allMigrations;
+    for (const { file, dir } of filesToInclude) {
+        symlinkSync(resolve(dir, file), join(tempDir, file));
+    }
+    if (verbose) {
+        console.log(chalk.blue("migrations"), chalk.gray(`Prepared ${filesToInclude.length} migration(s) for ${canisterName}` +
+            (isTrimming ? ` (trimmed from ${allMigrations.length})` : "")));
+    }
+    const migrationArgs = [`--enhanced-migration=${tempDir}`];
+    if (isTrimming) {
+        migrationArgs.push("-A=M0254");
+    }
+    return {
+        migrationArgs,
+        cleanup: async () => {
+            await rm(tempDir, { recursive: true, force: true });
+        },
+    };
+}

package/dist/helpers/resolve-canisters.d.ts

@@ -6,4 +6,4 @@ export declare function resolveSingleCanister(config: Config, canisterName?: str
     canister: CanisterConfig;
 };
 export declare function looksLikeFile(arg: string): boolean;
-export declare function validateCanisterArgs(canister: CanisterConfig, canisterName: string): void;
+export declare function validateCanisterArgs(canister: CanisterConfig, canisterName: string, config?: Config): void;

package/dist/helpers/resolve-canisters.js

@@ -39,8 +39,22 @@ export function looksLikeFile(arg) {
         arg.includes("/") ||
         arg.includes("\\"));
 }
-export function validateCanisterArgs(canister, canisterName) {
+export function validateCanisterArgs(canister, canisterName, config) {
     if (canister.args && typeof canister.args === "string") {
         cliError(`Canister config 'args' should be an array of strings for canister ${canisterName}`);
     }
+    if (!canister.migrations) {
+        return;
+    }
+    const flagSources = [
+        [`[canisters.${canisterName}].args`, canister.args],
+        ["[moc].args", config?.moc?.args],
+        ["[build].args", config?.build?.args],
+    ];
+    for (const [section, args] of flagSources) {
+        if (args?.some((a) => a.startsWith("--enhanced-migration"))) {
+            cliError(`Canister '${canisterName}' has [migrations] config but --enhanced-migration in ${section}.\n` +
+                "Remove --enhanced-migration — it is managed automatically when [migrations] is configured.");
+        }
+    }
 }

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ic-mops",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "type": "module",
   "bin": {
     "mops": "bin/mops.js",

package/dist/tests/migrate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/migrate.test.js

@@ -0,0 +1,160 @@
+import { describe, expect, test, afterEach } from "@jest/globals";
+import { readdirSync, readFileSync } from "node:fs";
+import { cp, rm, writeFile } from "node:fs/promises";
+import path from "path";
+import { cli, cliSnapshot, normalizePaths } from "./helpers";
+const normalizeTimestamp = (text) => text.replace(/\d{8}_\d{6}/g, "<TIMESTAMP>");
+const fixturesDir = path.join(import.meta.dirname, "migrate");
+describe("migrate", () => {
+    const tempDirs = [];
+    async function makeTempFixture(fixture) {
+        const src = path.join(fixturesDir, fixture);
+        const dest = path.join(fixturesDir, `_tmp_${fixture}_${Date.now()}`);
+        await cp(src, dest, { recursive: true });
+        tempDirs.push(dest);
+        return dest;
+    }
+    async function patchMigrations(cwd, extra) {
+        const tomlPath = path.join(cwd, "mops.toml");
+        const toml = readFileSync(tomlPath, "utf-8");
+        await writeFile(tomlPath, toml.replace('next = "next-migration"', `next = "next-migration"\n${extra}`));
+    }
+    afterEach(async () => {
+        for (const dir of tempDirs) {
+            await rm(dir, { recursive: true, force: true });
+        }
+        tempDirs.length = 0;
+    });
+    describe("migrate new", () => {
+        test("creates a migration file with timestamp and template", async () => {
+            const cwd = await makeTempFixture("basic");
+            const result = await cli(["migrate", "new", "AddPhone"], { cwd });
+            expect(result.exitCode).toBe(0);
+            const nextDir = path.join(cwd, "next-migration");
+            const files = readdirSync(nextDir).filter((f) => f.endsWith(".mo"));
+            expect(files).toHaveLength(1);
+            expect(files[0]).toMatch(/^\d{8}_\d{6}_AddPhone\.mo$/);
+            const content = readFileSync(path.join(nextDir, files[0]), "utf-8");
+            expect({
+                exitCode: result.exitCode,
+                stdout: normalizeTimestamp(normalizePaths(result.stdout)),
+                stderr: normalizePaths(result.stderr),
+                template: content,
+            }).toMatchSnapshot();
+        });
+        test("errors when next already has a file", async () => {
+            const cwd = await makeTempFixture("basic");
+            await cli(["migrate", "new", "First"], { cwd });
+            const result = await cli(["migrate", "new", "Second"], { cwd });
+            expect(result.exitCode).toBe(1);
+            expect(result.stderr).toMatch(/next migration already exists/i);
+        });
+        test("errors on invalid migration name", async () => {
+            const cwd = await makeTempFixture("basic");
+            for (const name of ["../evil", "has space", "123start", "foo/bar"]) {
+                const result = await cli(["migrate", "new", name], { cwd });
+                expect(result.exitCode).toBe(1);
+                expect(result.stderr).toMatch(/invalid migration name/i);
+            }
+        });
+        test("errors when [migrations] not configured", async () => {
+            const cwd = await makeTempFixture("basic");
+            const tomlPath = path.join(cwd, "mops.toml");
+            const toml = readFileSync(tomlPath, "utf-8");
+            await writeFile(tomlPath, toml.replace(/\[canisters\.backend\.migrations\][\s\S]*$/, ""));
+            const result = await cli(["migrate", "new", "Test"], { cwd });
+            expect(result.exitCode).toBe(1);
+            expect(result.stderr).toMatch(/\[migrations\]/i);
+        });
+    });
+    describe("migrate freeze", () => {
+        test("moves the file from next to chain", async () => {
+            const cwd = await makeTempFixture("with-next");
+            const result = await cli(["migrate", "freeze"], { cwd });
+            expect(result.exitCode).toBe(0);
+            const nextFiles = readdirSync(path.join(cwd, "next-migration")).filter((f) => f.endsWith(".mo"));
+            expect(nextFiles).toHaveLength(0);
+            const chainFiles = readdirSync(path.join(cwd, "migrations")).filter((f) => f.endsWith(".mo"));
+            expect(chainFiles).toContain("20250401_000000_RenameId.mo");
+            expect({
+                exitCode: result.exitCode,
+                stdout: normalizePaths(result.stdout),
+                stderr: normalizePaths(result.stderr),
+            }).toMatchSnapshot();
+        });
+        test("errors when next is empty", async () => {
+            const cwd = await makeTempFixture("basic");
+            const result = await cli(["migrate", "freeze"], { cwd });
+            expect(result.exitCode).toBe(1);
+            expect(result.stderr).toMatch(/no next migration/i);
+        });
+        test("errors when next-migration does not sort last", async () => {
+            const cwd = await makeTempFixture("basic");
+            await writeFile(path.join(cwd, "next-migration", "00000000_000000_Early.mo"), "module {\n  public func migration(_ : {}) : {} {\n    {}\n  }\n}\n");
+            const result = await cli(["migrate", "freeze"], { cwd });
+            expect(result.exitCode).toBe(1);
+            expect(result.stderr).toMatch(/must sort after/i);
+        });
+    });
+    describe("check", () => {
+        test("check fails without next migration, passes with it", async () => {
+            const cwd = await makeTempFixture("with-next");
+            const nextFile = readdirSync(path.join(cwd, "next-migration")).find((f) => f.endsWith(".mo"));
+            const nextPath = path.join(cwd, "next-migration", nextFile);
+            const nextContent = readFileSync(nextPath, "utf-8");
+            await rm(nextPath);
+            await cliSnapshot(["check"], { cwd }, 1);
+            await writeFile(nextPath, nextContent);
+            await cliSnapshot(["check"], { cwd }, 0);
+        });
+        test("check with trimming shows reduced chain", async () => {
+            const cwd = await makeTempFixture("basic");
+            await patchMigrations(cwd, "check-limit = 2");
+            await cliSnapshot(["check", "--verbose"], { cwd }, 0);
+        });
+    });
+    describe("build", () => {
+        test("build produces .most with full migration chain", async () => {
+            const cwd = await makeTempFixture("basic");
+            const result = await cli(["build"], { cwd });
+            expect(result.exitCode).toBe(0);
+            const most = readFileSync(path.join(cwd, ".mops", ".build", "backend.most"), "utf-8");
+            expect(most).toMatchSnapshot();
+        });
+        test("build with build-limit produces trimmed .most", async () => {
+            const cwd = await makeTempFixture("basic");
+            await patchMigrations(cwd, "build-limit = 2");
+            const result = await cli(["build"], { cwd });
+            expect(result.exitCode).toBe(0);
+            const most = readFileSync(path.join(cwd, ".mops", ".build", "backend.most"), "utf-8");
+            expect(most).toMatchSnapshot();
+        });
+        test("build-limit counts next migration as part of the chain", async () => {
+            const cwd = await makeTempFixture("with-next");
+            await patchMigrations(cwd, "build-limit = 2");
+            const result = await cli(["build"], { cwd });
+            expect(result.exitCode).toBe(0);
+            const most = readFileSync(path.join(cwd, ".mops", ".build", "backend.most"), "utf-8");
+            expect(most).toMatchSnapshot();
+        });
+    });
+    describe("stable check hint", () => {
+        test("stable check fails with hint when deployed.most is incompatible", async () => {
+            const cwd = await makeTempFixture("basic");
+            await writeFile(path.join(cwd, "deployed.most"), "// Version: 1.0.0\nactor {\n  stable var a : Nat;\n  stable var name : Int\n};\n");
+            await cliSnapshot(["check"], { cwd }, 1);
+        });
+    });
+    describe("conflict detection", () => {
+        test("errors when both [migrations] and --enhanced-migration in args", async () => {
+            const cwd = await makeTempFixture("basic");
+            const tomlPath = path.join(cwd, "mops.toml");
+            const toml = readFileSync(tomlPath, "utf-8");
+            await writeFile(tomlPath, toml.replace("[canisters.backend.migrations]", 'args = ["--enhanced-migration=migrations"]\n\n[canisters.backend.migrations]'));
+            const result = await cli(["check"], { cwd });
+            expect(result.exitCode).toBe(1);
+            expect(result.stderr).toMatch(/--enhanced-migration/);
+            expect(result.stderr).toMatch(/managed automatically/i);
+        });
+    });
+});

package/dist/types.d.ts

@@ -34,6 +34,12 @@ export type Config = {
         extra?: Record<string, string[]>;
     };
 };
+export type MigrationsConfig = {
+    chain: string;
+    next?: string;
+    "check-limit"?: number;
+    "build-limit"?: number;
+};
 export type CanisterConfig = {
     main?: string;
     args?: string[];
@@ -43,6 +49,7 @@ export type CanisterConfig = {
         path: string;
         skipIfMissing?: boolean;
     };
+    migrations?: MigrationsConfig;
 };
 export type Dependencies = Record<string, Dependency>;
 export type Dependency = {

package/helpers/migrations.ts

@@ -0,0 +1,166 @@
+import { existsSync, mkdirSync, readdirSync, symlinkSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { rm } from "node:fs/promises";
+import chalk from "chalk";
+import { cliError } from "../error.js";
+import { resolveConfigPath } from "../mops.js";
+import { MigrationsConfig } from "../types.js";
+
+const MIGRATIONS_TEMP_DIR = ".mops/.migrations";
+
+export interface MigrationArgsResult {
+  migrationArgs: string[];
+  cleanup: () => Promise<void>;
+}
+
+export function getMigrationFiles(dir: string): string[] {
+  if (!existsSync(dir)) {
+    return [];
+  }
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".mo"))
+    .sort();
+}
+
+export function getNextMigrationFile(nextDir: string): string | null {
+  if (!existsSync(nextDir)) {
+    return null;
+  }
+  const files = readdirSync(nextDir).filter((f) => f.endsWith(".mo"));
+  if (files.length > 1) {
+    cliError(
+      `next-migration directory must contain at most 1 .mo file, found ${files.length} in ${nextDir}`,
+    );
+  }
+  return files[0] ?? null;
+}
+
+export function validateNextMigrationOrder(
+  chainDirOrFiles: string | string[],
+  nextFile: string,
+): void {
+  const chainFiles =
+    typeof chainDirOrFiles === "string"
+      ? getMigrationFiles(chainDirOrFiles)
+      : chainDirOrFiles;
+  const lastChainFile = chainFiles[chainFiles.length - 1];
+  if (lastChainFile && nextFile <= lastChainFile) {
+    cliError(
+      `Next migration "${nextFile}" must sort after all files in the chain.\n` +
+        `Last chain file: "${lastChainFile}".\n` +
+        "Use a timestamp prefix (e.g. YYYYMMDD_HHMMSS_Name.mo) to ensure correct ordering.",
+    );
+  }
+}
+
+export function validateMigrationsConfig(
+  migrations: MigrationsConfig,
+  canisterName: string,
+): void {
+  if (!migrations.chain) {
+    cliError(
+      `[canisters.${canisterName}.migrations] is missing required field "chain"`,
+    );
+  }
+  for (const field of ["check-limit", "build-limit"] as const) {
+    const value = migrations[field];
+    if (value !== undefined && (!Number.isInteger(value) || value <= 0)) {
+      cliError(
+        `[canisters.${canisterName}.migrations] ${field} must be a positive integer`,
+      );
+    }
+  }
+}
+
+export async function prepareMigrationArgs(
+  migrations: MigrationsConfig | undefined,
+  canisterName: string,
+  mode: "check" | "build",
+  verbose?: boolean,
+): Promise<MigrationArgsResult> {
+  const noOp: MigrationArgsResult = {
+    migrationArgs: [],
+    cleanup: async () => {},
+  };
+
+  if (!migrations) {
+    return noOp;
+  }
+
+  validateMigrationsConfig(migrations, canisterName);
+
+  const chainDir = resolveConfigPath(migrations.chain);
+  const nextDir = migrations.next
+    ? resolveConfigPath(migrations.next)
+    : undefined;
+  const nextFile = nextDir ? getNextMigrationFile(nextDir) : null;
+
+  if (!existsSync(chainDir) && !nextFile) {
+    cliError(
+      `Migration chain directory not found: ${chainDir}\n` +
+        "Run `mops migrate new <Name>` to initialize the migration chain.",
+    );
+  }
+
+  const chainFiles = getMigrationFiles(chainDir);
+
+  if (nextFile) {
+    validateNextMigrationOrder(chainFiles, nextFile);
+  }
+
+  // Treat chain + next as one virtual merged list
+  type MigrationEntry = { file: string; dir: string };
+  const allMigrations: MigrationEntry[] = chainFiles.map((f) => ({
+    file: f,
+    dir: chainDir,
+  }));
+  if (nextFile && nextDir) {
+    allMigrations.push({ file: nextFile, dir: nextDir });
+  }
+
+  const limit =
+    mode === "check" ? migrations["check-limit"] : migrations["build-limit"];
+  const isTrimming = limit !== undefined && limit < allMigrations.length;
+  const needsTempDir = nextFile !== null || isTrimming;
+
+  if (!needsTempDir) {
+    return {
+      migrationArgs: [`--enhanced-migration=${chainDir}`],
+      cleanup: async () => {},
+    };
+  }
+
+  const tempDir = join(MIGRATIONS_TEMP_DIR, canisterName);
+  await rm(tempDir, { recursive: true, force: true });
+  mkdirSync(tempDir, { recursive: true });
+
+  const filesToInclude = isTrimming
+    ? allMigrations.slice(-limit)
+    : allMigrations;
+
+  for (const { file, dir } of filesToInclude) {
+    symlinkSync(resolve(dir, file), join(tempDir, file));
+  }
+
+  if (verbose) {
+    console.log(
+      chalk.blue("migrations"),
+      chalk.gray(
+        `Prepared ${filesToInclude.length} migration(s) for ${canisterName}` +
+          (isTrimming ? ` (trimmed from ${allMigrations.length})` : ""),
+      ),
+    );
+  }
+
+  const migrationArgs = [`--enhanced-migration=${tempDir}`];
+  if (isTrimming) {
+    migrationArgs.push("-A=M0254");
+  }
+
+  return {
+    migrationArgs,
+    cleanup: async () => {
+      await rm(tempDir, { recursive: true, force: true });
+    },
+  };
+}

package/helpers/resolve-canisters.ts

@@ -74,10 +74,27 @@ export function looksLikeFile(arg: string): boolean {
 export function validateCanisterArgs(
   canister: CanisterConfig,
   canisterName: string,
+  config?: Config,
 ): void {
   if (canister.args && typeof canister.args === "string") {
     cliError(
       `Canister config 'args' should be an array of strings for canister ${canisterName}`,
     );
   }
+  if (!canister.migrations) {
+    return;
+  }
+  const flagSources: [string, string[] | undefined][] = [
+    [`[canisters.${canisterName}].args`, canister.args],
+    ["[moc].args", config?.moc?.args],
+    ["[build].args", config?.build?.args],
+  ];
+  for (const [section, args] of flagSources) {
+    if (args?.some((a) => a.startsWith("--enhanced-migration"))) {
+      cliError(
+        `Canister '${canisterName}' has [migrations] config but --enhanced-migration in ${section}.\n` +
+          "Remove --enhanced-migration — it is managed automatically when [migrations] is configured.",
+      );
+    }
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ic-mops",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "type": "module",
   "bin": {
     "mops": "dist/bin/mops.js",

package/tests/__snapshots__/migrate.test.ts.snap

@@ -0,0 +1,119 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`migrate build build produces .most with full migration chain 1`] = `
+"// Version: 4.0.0
+{
+  "20250101_000000_Init" : {} -> {a : Nat};
+  "20250201_000000_AddName" : (old : {a : Nat}) -> {a : Nat; name : Text};
+  "20250301_000000_AddEmail" :
+    (old : {a : Nat; name : Text}) -> {a : Nat; email : Text; name : Text}
+}
+actor  {
+  stable a : Nat;
+  stable email : Text;
+  stable name : Text
+};
+"
+`;
+
+exports[`migrate build build with build-limit produces trimmed .most 1`] = `
+"// Version: 4.0.0
+{
+  "20250201_000000_AddName" : (old : {a : Nat}) -> {a : Nat; name : Text};
+  "20250301_000000_AddEmail" :
+    (old : {a : Nat; name : Text}) -> {a : Nat; email : Text; name : Text}
+}
+actor  {
+  stable a : Nat;
+  stable email : Text;
+  stable name : Text
+};
+"
+`;
+
+exports[`migrate build build-limit counts next migration as part of the chain 1`] = `
+"// Version: 4.0.0
+{
+  "20250301_000000_AddEmail" :
+    (old : {a : Nat; name : Text}) -> {a : Nat; email : Text; name : Text};
+  "20250401_000000_RenameId" :
+    (old : {a : Nat; email : Text; name : Text}) ->
+      {email : Text; id : Nat; name : Text}
+}
+actor  {
+  stable email : Text;
+  stable id : Nat;
+  stable name : Text
+};
+"
+`;
+
+exports[`migrate check check fails without next migration, passes with it 1`] = `
+{
+  "exitCode": 1,
+  "stderr": "src/main.mo:3.1-11.2: Compatibility error [M0169], the stable variable \`a\` of version \`20250301_000000_AddEmail\` cannot be implicitly discarded. The variable can only be dropped by an explicit migration function, please see https://internetcomputer.org/docs/motoko/fundamentals/actors/compatibility#explicit-migration-using-a-migration-function
+migrations/20250101_000000_Init.mo:0.1: warning [M0254], initial actor requires field \`id\` of type
+  Nat
+✗ Check failed for canister backend (exit code: 1)",
+  "stdout": "",
+}
+`;
+
+exports[`migrate check check fails without next migration, passes with it 2`] = `
+{
+  "exitCode": 0,
+  "stderr": "",
+  "stdout": "✓ backend
+✓ Stable compatibility check passed for canister 'backend'",
+}
+`;
+
+exports[`migrate check check with trimming shows reduced chain 1`] = `
+{
+  "exitCode": 0,
+  "stderr": "",
+  "stdout": "check Using --all-libs for richer diagnostics
+migrations Prepared 2 migration(s) for backend (trimmed from 3)
+check Checking canister backend:
+<CACHE>moc-wrapper ["src/main.mo","--check","--all-libs","--default-persistent-actors","--enhanced-migration=.mops/.migrations/backend","-A=M0254"]
+✓ backend
+check-stable Generating stable types for src/main.mo
+<CACHE>moc-wrapper ["--stable-types","-o",".mops/.check-stable/new.wasm","src/main.mo","--default-persistent-actors","--enhanced-migration=.mops/.migrations/backend","-A=M0254"]
+check-stable Comparing deployed.most ↔ .mops/.check-stable/new.most
+<CACHE>moc-wrapper ["--stable-compatible","deployed.most",".mops/.check-stable/new.most"]
+✓ Stable compatibility check passed for canister 'backend'",
+}
+`;
+
+exports[`migrate migrate freeze moves the file from next to chain 1`] = `
+{
+  "exitCode": 0,
+  "stderr": "",
+  "stdout": "✓ Frozen migration: 20250401_000000_RenameId.mo → migrations/",
+}
+`;
+
+exports[`migrate migrate new creates a migration file with timestamp and template 1`] = `
+{
+  "exitCode": 0,
+  "stderr": "",
+  "stdout": "✓ Created migration: next-migration/<TIMESTAMP>_AddPhone.mo",
+  "template": "module {
+  public func migration(old : {}) : {} {
+    {}
+  }
+}
+",
+}
+`;
+
+exports[`migrate stable check hint stable check fails with hint when deployed.most is incompatible 1`] = `
+{
+  "exitCode": 1,
+  "stderr": "(unknown location): Compatibility error [M0169], the stable variable \`a\` of the previous version cannot be implicitly discarded. The variable can only be dropped by an explicit migration function, please see https://internetcomputer.org/docs/motoko/fundamentals/actors/compatibility#explicit-migration-using-a-migration-function
+(unknown location): Compatibility error [M0169], the stable variable \`name\` of the previous version cannot be implicitly discarded. The variable can only be dropped by an explicit migration function, please see https://internetcomputer.org/docs/motoko/fundamentals/actors/compatibility#explicit-migration-using-a-migration-function
+Hint: You may need a migration. Run \`mops migrate new <Name>\` to create one.
+✗ Stable compatibility check failed for canister 'backend'",
+  "stdout": "✓ backend",
+}
+`;

package/tests/migrate/basic/deployed.most

@@ -0,0 +1,12 @@
+// Version: 4.0.0
+{
+  "20250101_000000_Init" : {} -> {a : Nat};
+  "20250201_000000_AddName" : (old : {a : Nat}) -> {a : Nat; name : Text};
+  "20250301_000000_AddEmail" :
+    (old : {a : Nat; name : Text}) -> {a : Nat; email : Text; name : Text}
+}
+actor  {
+  stable a : Nat;
+  stable email : Text;
+  stable name : Text
+};

package/tests/migrate/basic/migrations/20250101_000000_Init.mo

@@ -0,0 +1,5 @@
+module {
+  public func migration(_ : {}) : { a : Nat } {
+    { a = 0 };
+  };
+};