cli: fix concurrent mops invocations clobbering shared scratch dirs (#532)

## Problem

Running two `mops` processes on the same project (e.g. an editor watcher
and `caffeine check --fix`, or two back-to-back invocations from a
script) intermittently failed with misleading errors:

- `.mops/.check-stable/new.most: No such file or directory` from `mops
check-stable`
- `EEXIST: file already exists, symlink ...` from `mops
check`/`build`/`check-stable` when `[canisters.<name>.migrations]` was
configured

Worse, `check-stable` would print a "Hint: You may need a migration"
suggestion (now removed in #531) that pointed users at the wrong cause
entirely.

## Root cause

Two scratch directories were shared across all `mops` processes for the
same project:

1. **`.mops/.check-stable/`** — `runStableCheck` did `rm -rf <dir>` →
`mkdir <dir>` at the start and `rm -rf <dir>` at the end. Two concurrent
runs would: A creates `new.most`, B's startup `rm -rf` deletes it, A's
subsequent `--stable-compatible` read fails.
2. **`<parent>/.migrations-<canister>/`** — `prepareMigrationArgs` (used
when migrations need a trimmed/`next`-merged staging dir) wiped the dir
and re-symlinked. Two concurrent runs raced on `symlinkSync` (EEXIST) or
on each other's wipe.

Both directories existed mostly to give moc a stable path to read from
during the invocation; they weren't actually shared state that needed to
be coordinated.

## Fix

Switch both directories to per-invocation unique paths created with
`fs.mkdtempSync`:

- `.mops/.check-stable/` → `.mops/.check-stable-XXXXXX/`
- `<parent>/.migrations-<canister>/` →
`<parent>/.migrations-<canister>-XXXXXX/`

Each process owns its own dir for its lifetime and removes it on exit.
No shared mutable state → no race possible by construction. Existing
`.gitignore` rules already cover both patterns (`.mops/` and
`.migrations-*/`).

Caller behavior is unchanged: `prepareMigrationArgs` still returns a
`cleanup()` callback that removes the staged dir in `finally`.

## Caveats

- A crashed process leaks its scratch dir (small — symlinks + a couple
of `.most`/`.wasm` files). Both locations are gitignored, so it's
cosmetic.
- Stale `.mops/.check-stable/` or `<parent>/.migrations-<canister>/`
directories from older releases aren't auto-cleaned. They'll stay until
the user removes them; harmless but visible in `git status` for projects
that don't ignore them.

## Test plan

- [x] Added regression test: 10 parallel `mops check-stable` invocations
against a fixture with `check-limit = 3` and 4 chain migrations (forces
both the check-stable scratch path and the migration staging `mkdtemp`
branch).
- [x] Existing migrate / check / build / check-stable suites pass
(103/103, 64 snapshots).
- [x] `npm run lint` + `npm run check` clean.
- [x] Empirical reproduction of both error symptoms before the fix; both
gone after.
- [ ] Reviewer sanity: trigger the original failure with two parallel
`mops check-stable` (or `caffeine check --fix` + an editor watcher) on a
project with `[migrations]` configured; confirm clean output.

Made with [Cursor](https://cursor.com)

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Kamirus

cli/CHANGELOG.md

@@ -1,6 +1,7 @@
 # Mops CLI Changelog
 
 ## Next
+- Fix race conditions when two `mops` processes run on the same project (e.g. an editor watcher and `caffeine check --fix`, or back-to-back invocations). `mops check-stable` used a shared `.mops/.check-stable/` scratch dir and `mops check`/`build`/`check-stable` used a shared `<parent>/.migrations-<canister>/` staging dir; concurrent runs would clobber each other and surface as misleading errors like `.mops/.check-stable/new.most: No such file or directory` or `EEXIST: file already exists, symlink ...`. Both directories are now per-invocation (created via `mkdtemp` and removed when the command finishes).
 - Deprecate `skipIfMissing` in `[canisters.<name>.check-stable]`. Behavior is unchanged for now, but `mops check`/`check-stable` print a warning when it is set. For initial deployments, commit a `.most` file at the configured `path` containing an empty actor (`// Version: 1.0.0\nactor { };`) instead — the stable check then runs against an empty baseline.
 - Drop the "you may need a migration" hint after a failed stable compatibility check in `mops check`/`check-stable`. The hint guessed at whether the user needed a new migration or a fix to an existing one, and `moc`'s underlying compatibility error already links to the migration docs.
 - The missing-chain-directory error from `mops check`/`build`/`check-stable` now points at adding a `.mo` file to the `chain` directory instead of running the experimental `mops migrate new <Name>` command.

cli/commands/check-stable.ts

@@ -1,5 +1,5 @@
-import { basename, join } from "node:path";
-import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { existsSync, mkdirSync, mkdtempSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import chalk from "chalk";
 import { execa } from "execa";
@@ -17,7 +17,10 @@ import {
 import { sourcesArgs } from "./sources.js";
 import { toolchain } from "./toolchain/index.js";
 
-const CHECK_STABLE_DIR = ".mops/.check-stable";
+// Per-invocation scratch dir lives under `.mops/`; `mkdtempSync` makes it unique so
+// concurrent `mops` processes don't clobber each other's `old.most`/`new.most`.
+const CHECK_STABLE_PARENT = ".mops";
+const CHECK_STABLE_PREFIX = ".check-stable-";
 
 export interface CheckStableOptions {
   verbose: boolean;
@@ -189,15 +192,17 @@ export async function runStableCheck(
     cliError(`File not found: ${oldFile}`);
   }
 
-  await rm(CHECK_STABLE_DIR, { recursive: true, force: true });
-  mkdirSync(CHECK_STABLE_DIR, { recursive: true });
+  mkdirSync(CHECK_STABLE_PARENT, { recursive: true });
+  const scratchDir = mkdtempSync(
+    join(CHECK_STABLE_PARENT, CHECK_STABLE_PREFIX),
+  );
   try {
     const oldMostPath = isOldMostFile
       ? oldFile
       : await generateStableTypes(
           mocPath,
           oldFile,
-          join(CHECK_STABLE_DIR, "old.most"),
+          join(scratchDir, "old.most"),
           sources,
           globalMocArgs,
           canisterArgs,
@@ -207,7 +212,7 @@ export async function runStableCheck(
     const newMostPath = await generateStableTypes(
       mocPath,
       canisterMain,
-      join(CHECK_STABLE_DIR, "new.most"),
+      join(scratchDir, "new.most"),
       sources,
       globalMocArgs,
       canisterArgs,
@@ -246,7 +251,7 @@ export async function runStableCheck(
       ),
     );
   } finally {
-    await rm(CHECK_STABLE_DIR, { recursive: true, force: true });
+    await rm(scratchDir, { recursive: true, force: true });
   }
 }
 
@@ -259,8 +264,7 @@ async function generateStableTypes(
   canisterArgs: string[],
   options: Partial<CheckStableOptions>,
 ): Promise<string> {
-  const base = basename(outputPath, ".most");
-  const wasmPath = join(CHECK_STABLE_DIR, base + ".wasm");
+  const wasmPath = outputPath.replace(/\.most$/, ".wasm");
   const args = [
     "--stable-types",
     "-o",

cli/helpers/migrations.ts

@@ -1,6 +1,7 @@
 import {
   existsSync,
   mkdirSync,
+  mkdtempSync,
   readdirSync,
   symlinkSync,
   writeFileSync,
@@ -193,9 +194,11 @@ export async function prepareMigrationArgs(
     return { migrationArgs, cleanup: async () => {} };
   }
 
-  const tempDir = stagedMigrationsDir(chainDir, canisterName);
-  await rm(tempDir, { recursive: true, force: true });
-  mkdirSync(tempDir, { recursive: true });
+  // Per-invocation staging dir; `mkdtempSync` makes it unique so concurrent `mops`
+  // processes don't clobber each other's symlinks. Cleaned up below in `cleanup()`.
+  const baseDir = stagedMigrationsDir(chainDir, canisterName);
+  mkdirSync(dirname(baseDir), { recursive: true });
+  const tempDir = mkdtempSync(`${baseDir}-`);
   writeFileSync(join(tempDir, ".gitignore"), "*\n");
 
   for (const { file, dir } of included) {

cli/tests/check-stable.test.ts

@@ -86,4 +86,24 @@ describe("check-stable", () => {
     expect(result.exitCode).toBe(1);
     expect(result.stderr).toMatch(/File not found/);
   });
+
+  // Regression: two concurrent `mops check-stable` runs on the same project used to clobber
+  // each other's `.mops/.check-stable/new.most` and the staged migration symlinks, surfacing
+  // as a misleading `new.most: No such file or directory` or an `EEXIST: symlink` crash.
+  test("concurrent runs do not clobber each other's scratch state", async () => {
+    const cwd = path.join(import.meta.dirname, "check-stable/migrations-chain");
+    const results = await Promise.all(
+      Array.from({ length: 10 }, () => cli(["check-stable"], { cwd })),
+    );
+    for (const result of results) {
+      expect({
+        exitCode: result.exitCode,
+        stderr: result.stderr,
+      }).toEqual({
+        exitCode: 0,
+        stderr: "",
+      });
+      expect(result.stdout).toMatch(/Stable compatibility check passed/);
+    }
+  }, 60_000);
 });

cli/tests/check-stable/migrations-chain/deployed.most

@@ -0,0 +1,14 @@
+// Version: 4.0.0
+{
+  "20250101_000000_Init" : {} -> {a : Nat; b : Text};
+  "20250201_000000_AddField" : (old : {a : Nat; b : Text}) -> {a : Nat; b : Text; c : Bool};
+  "20250301_000000_AddD" : (old : {a : Nat; b : Text; c : Bool}) -> {a : Nat; b : Text; c : Bool; d : Int};
+  "20250401_000000_AddE" : (old : {a : Nat; b : Text; c : Bool; d : Int}) -> {a : Nat; b : Text; c : Bool; d : Int; e : Text}
+}
+actor  {
+  stable a : Nat;
+  stable b : Text;
+  stable c : Bool;
+  stable d : Int;
+  stable e : Text
+};

cli/tests/check-stable/migrations-chain/migrations/20250101_000000_Init.mo

@@ -0,0 +1,8 @@
+module {
+  public func migration(_ : {}) : { a : Nat; b : Text } {
+    {
+      a = 42;
+      b = "hello";
+    };
+  };
+};

cli/tests/check-stable/migrations-chain/migrations/20250201_000000_AddField.mo

@@ -0,0 +1,9 @@
+module {
+  public func migration(old : { a : Nat; b : Text }) : {
+    a : Nat;
+    b : Text;
+    c : Bool;
+  } {
+    { old with c = true };
+  };
+};

cli/tests/check-stable/migrations-chain/migrations/20250301_000000_AddD.mo

@@ -0,0 +1,10 @@
+module {
+  public func migration(old : { a : Nat; b : Text; c : Bool }) : {
+    a : Nat;
+    b : Text;
+    c : Bool;
+    d : Int;
+  } {
+    { old with d = 0 };
+  };
+};

cli/tests/check-stable/migrations-chain/migrations/20250401_000000_AddE.mo

@@ -0,0 +1,11 @@
+module {
+  public func migration(old : { a : Nat; b : Text; c : Bool; d : Int }) : {
+    a : Nat;
+    b : Text;
+    c : Bool;
+    d : Int;
+    e : Text;
+  } {
+    { old with e = "" };
+  };
+};

cli/tests/check-stable/migrations-chain/mops.toml

@@ -0,0 +1,15 @@
+[toolchain]
+moc = "1.5.0"
+
+[moc]
+args = ["--default-persistent-actors"]
+
+[canisters.backend]
+main = "src/main.mo"
+
+[canisters.backend.migrations]
+chain = "migrations"
+check-limit = 3
+
+[canisters.backend.check-stable]
+path = "deployed.most"