cli: stage migrations next to chain dir so shared imports resolve (#500)

## Why

Migration files often want to share state types from a sibling folder:

```
migrations/20250101_000000_Init.mo  ─ import State \"../types/State\"
types/State.mo                      ─ shared type definitions
```

This fails as soon as a `next-migration` exists or chain trimming kicks
in. mops symlinks the chain into `.mops/.migrations/<canister>/` and
points moc at it, but moc resolves relative imports from the symlink's
parent — so `../types/State` becomes `.mops/types/State.mo` and errors.

## Fix

Stage into `<parent-of-chain>/.migrations-<canister>/` instead. The
staged files now sit at the same depth as the originals, so
`../types/State` resolves to the same target either way.

This requires `chain` and `next` to share the same parent — enforced
with a clear validation error at every entry point (`check`, `build`,
`migrate new/freeze`, `check-stable`).

The staged dir self-stamps a `.gitignore` (`*`) so it doesn't show up in
`git status`.

## Breaking

Any `[canisters.<name>.migrations]` whose `chain` and `next` had
different parents is rejected. The default layout (`chain =
\"migrations\"` + `next = \"next-migration\"`) is unaffected. `2.11.0`
introduced the migration feature one release ago, so adoption is small.

## Test plan

- [x] All 16 `migrate.test.ts` tests pass, including two new tests that
the sibling validation fires from both `mops check` and `mops migrate
new`.
- [x] `with-next` fixture updated to use a shared `types/State.mo` —
exercises the imports-resolve-correctly behavior end-to-end.
- [x] `npm run check` and `npm run lint` pass.

Author: Kamirus

.agents/skills/mops-cli/SKILL.md

@@ -144,6 +144,8 @@ mops migrate freeze backend       # specify canister explicitly
 
 When `[canisters.<name>.migrations]` is configured, `mops check`, `mops build`, and `mops check-stable` automatically inject `--enhanced-migration`. Do not add `--enhanced-migration` to `[canisters.<name>].args` when using managed migrations — mops will error.
 
+`chain` and `next` must live in the same parent directory. Migration files can import from sibling folders via relative paths (e.g. shared types in `src/backend/types/`); mops stages the active chain into `<parent-of-chain>/.migrations-<canister>/`, preserving depth so relative imports resolve identically. The staged dir self-stamps a `.gitignore`; `mops init` also adds `.migrations-*/` to the project `.gitignore`.
+
 Typical workflow: make a breaking change → `mops check` fails with a hint → `mops migrate new Name` → edit migration → `mops check` passes → `mops build` → deploy → `mops migrate freeze`.
 
 ### `mops remove <package>`

.gitignore

@@ -3,6 +3,7 @@ target/
 dist/
 .dfx/
 .mops/
+.migrations-*/
 mops.lock
 
 .DS_Store

cli/CHANGELOG.md

@@ -1,6 +1,8 @@
 # Mops CLI Changelog
 
 ## Next
+- Migration staging directory moved from `.mops/.migrations/<canister>/` to `<parent-of-chain>/.migrations-<canister>/`, so migration files can import shared modules from sibling folders (e.g. a `types/` folder next to `migrations/`) — relative imports now resolve to the same target whether moc reads the original chain dir or the staged one. The staged dir self-stamps a `.gitignore` so it doesn't pollute `git status`; `mops init` now also adds `.migrations-*/` to the project `.gitignore`
+- `[canisters.<name>.migrations]` now requires `chain` and `next` to share the same parent directory (any layout where the parents differed is rejected with a clear error). The default layout `chain = "migrations"` + `next = "next-migration"` already satisfies this. For per-canister setups, use sibling subdirectories, e.g. `chain = "src/backend/migrations"` + `next = "src/backend/next-migration"`
 
 ## 2.11.0
 - Add `mops migrate new <Name>` and `mops migrate freeze` commands for managing enhanced migration chains

cli/commands/init.ts

@@ -282,16 +282,29 @@ async function applyInit({
     await template("github-workflow:mops-test");
   }
 
-  // add .mops to .gitignore
+  // add mops-managed paths to .gitignore
   {
     let gitignore = path.join(process.cwd(), ".gitignore");
     let gitignoreData = existsSync(gitignore)
       ? readFileSync(gitignore).toString()
       : "";
-    let lf = gitignoreData.endsWith("\n") ? "\n" : "";
+    const additions: string[] = [];
     if (!gitignoreData.includes(".mops")) {
-      writeFileSync(gitignore, `${gitignoreData}\n.mops${lf}`.trimStart());
-      console.log(chalk.green("Added"), ".mops to .gitignore");
+      additions.push(".mops");
+    }
+    if (!gitignoreData.includes(".migrations-")) {
+      additions.push(".migrations-*/");
+    }
+    if (additions.length > 0) {
+      let lf = gitignoreData.endsWith("\n") ? "\n" : "";
+      writeFileSync(
+        gitignore,
+        `${gitignoreData}\n${additions.join("\n")}${lf}`.trimStart(),
+      );
+      console.log(
+        chalk.green("Added"),
+        `${additions.join(", ")} to .gitignore`,
+      );
     }
   }
 

cli/helpers/migrations.ts

@@ -1,12 +1,20 @@
-import { existsSync, mkdirSync, readdirSync, symlinkSync } from "node:fs";
-import { join, resolve } from "node:path";
+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 { resolveConfigPath } from "../mops.js";
+import { getRootDir, resolveConfigPath } from "../mops.js";
 import { MigrationsConfig } from "../types.js";
 
-const MIGRATIONS_TEMP_DIR = ".mops/.migrations";
+function stagedMigrationsDir(chainDir: string, canisterName: string): string {
+  return join(dirname(chainDir), `.migrations-${canisterName}`);
+}
 
 export interface MigrationArgsResult {
   migrationArgs: string[];
@@ -70,6 +78,21 @@ export function validateMigrationsConfig(
       );
     }
   }
+  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(
@@ -130,9 +153,10 @@ export async function prepareMigrationArgs(
     };
   }
 
-  const tempDir = join(MIGRATIONS_TEMP_DIR, canisterName);
+  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)

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

@@ -33,12 +33,12 @@ actor  {
 
 exports[`migrate build build-limit counts next migration as part of the chain 1`] = `
 "// Version: 4.0.0
+type V2__933402648 = {a : Nat; name : Text};
+type V3__40989327 = {a : Nat; email : Text; name : Text};
+type V4__364034734 = {email : Text; id : Nat; name : Text};
 {
-  "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}
+  "20250301_000000_AddEmail" : (old : V2__933402648) -> V3__40989327;
+  "20250401_000000_RenameId" : (old : V3__40989327) -> V4__364034734
 }
 actor  {
   stable email : Text;
@@ -75,10 +75,10 @@ exports[`migrate check check with trimming shows reduced chain 1`] = `
   "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"]
+<CACHE>moc-wrapper ["src/main.mo","--check","--all-libs","--default-persistent-actors","--enhanced-migration=.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"]
+<CACHE>moc-wrapper ["--stable-types","-o",".mops/.check-stable/new.wasm","src/main.mo","--default-persistent-actors","--enhanced-migration=.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'",

cli/tests/migrate.test.ts

@@ -207,6 +207,33 @@ describe("migrate", () => {
     });
   });
 
+  describe("sibling validation", () => {
+    async function patchNextDir(cwd: string, nextValue: string): Promise<void> {
+      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");

cli/tests/migrate/with-next/migrations/20250101_000000_Init.mo

@@ -1,5 +1,7 @@
+import State "../types/State";
+
 module {
-  public func migration(_ : {}) : { a : Nat } {
+  public func migration(_ : State.V0) : State.V1 {
     { a = 0 };
   };
 };

cli/tests/migrate/with-next/migrations/20250201_000000_AddName.mo

@@ -1,5 +1,7 @@
+import State "../types/State";
+
 module {
-  public func migration(old : { a : Nat }) : { a : Nat; name : Text } {
+  public func migration(old : State.V1) : State.V2 {
     { old with name = "" };
   };
 };

cli/tests/migrate/with-next/migrations/20250301_000000_AddEmail.mo

@@ -1,9 +1,7 @@
+import State "../types/State";
+
 module {
-  public func migration(old : { a : Nat; name : Text }) : {
-    a : Nat;
-    name : Text;
-    email : Text;
-  } {
+  public func migration(old : State.V2) : State.V3 {
     { old with email = "" };
   };
 };