ic-mops 2.10.0 → 2.12.0

package/dist/helpers/migrations.js

@@ -0,0 +1,125 @@
+import { existsSync, mkdirSync, readdirSync, symlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { rm } from "node:fs/promises";
+import chalk from "chalk";
+import { cliError } from "../error.js";
+import { getRootDir, resolveConfigPath } from "../mops.js";
+function stagedMigrationsDir(chainDir, canisterName) {
+    return join(dirname(chainDir), `.migrations-${canisterName}`);
+}
+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`);
+        }
+    }
+    if (migrations.next) {
+        const parentOf = (p) => dirname(resolve(getRootDir(), p));
+        const chainParent = parentOf(migrations.chain);
+        const nextParent = parentOf(migrations.next);
+        if (chainParent !== nextParent) {
+            cliError(`[canisters.${canisterName}.migrations] "chain" and "next" must live in the same parent directory.\n` +
+                `  chain = "${migrations.chain}" (parent: ${chainParent})\n` +
+                `  next  = "${migrations.next}" (parent: ${nextParent})\n` +
+                "Place them in the same parent directory, e.g.:\n" +
+                '  chain = "migrations"\n' +
+                '  next  = "next-migration"');
+        }
+    }
+}
+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 = stagedMigrationsDir(chainDir, canisterName);
+    await rm(tempDir, { recursive: true, force: true });
+    mkdirSync(tempDir, { recursive: true });
+    writeFileSync(join(tempDir, ".gitignore"), "*\n");
+    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.12.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,181 @@
+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("sibling validation", () => {
+        async function patchNextDir(cwd, nextValue) {
+            const tomlPath = path.join(cwd, "mops.toml");
+            const toml = readFileSync(tomlPath, "utf-8");
+            await writeFile(tomlPath, toml.replace('next = "next-migration"', `next = "${nextValue}"`));
+        }
+        test("errors from `mops check` when chain and next have different parents", async () => {
+            const cwd = await makeTempFixture("with-next");
+            await patchNextDir(cwd, "other/next-migration");
+            const result = await cli(["check"], { cwd });
+            expect(result.exitCode).toBe(1);
+            expect(result.stderr).toMatch(/same parent directory/i);
+        });
+        test("errors from `mops migrate new` too — validation runs in every entry point", async () => {
+            const cwd = await makeTempFixture("basic");
+            await patchNextDir(cwd, "other/next-migration");
+            const result = await cli(["migrate", "new", "Test"], { cwd });
+            expect(result.exitCode).toBe(1);
+            expect(result.stderr).toMatch(/same parent directory/i);
+        });
+    });
+    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,190 @@
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { rm } from "node:fs/promises";
+import chalk from "chalk";
+import { cliError } from "../error.js";
+import { getRootDir, resolveConfigPath } from "../mops.js";
+import { MigrationsConfig } from "../types.js";
+
+function stagedMigrationsDir(chainDir: string, canisterName: string): string {
+  return join(dirname(chainDir), `.migrations-${canisterName}`);
+}
+
+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`,
+      );
+    }
+  }
+  if (migrations.next) {
+    const parentOf = (p: string) => dirname(resolve(getRootDir(), p));
+    const chainParent = parentOf(migrations.chain);
+    const nextParent = parentOf(migrations.next);
+    if (chainParent !== nextParent) {
+      cliError(
+        `[canisters.${canisterName}.migrations] "chain" and "next" must live in the same parent directory.\n` +
+          `  chain = "${migrations.chain}" (parent: ${chainParent})\n` +
+          `  next  = "${migrations.next}" (parent: ${nextParent})\n` +
+          "Place them in the same parent directory, e.g.:\n" +
+          '  chain = "migrations"\n' +
+          '  next  = "next-migration"',
+      );
+    }
+  }
+}
+
+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 = stagedMigrationsDir(chainDir, canisterName);
+  await rm(tempDir, { recursive: true, force: true });
+  mkdirSync(tempDir, { recursive: true });
+  writeFileSync(join(tempDir, ".gitignore"), "*\n");
+
+  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.12.0",
   "type": "module",
   "bin": {
     "mops": "dist/bin/mops.js",