cli: drop mops migrate recommendations from check/build (#531)

Follow-up to #530, which marked `mops migrate` as experimental in the
docs but missed a few CLI hints that still pushed users at it.

## What users will see

**Before:** `mops check` / `mops check-stable` failing on a
stable-compatibility regression printed an extra hint:

> Hint: You may need a migration. Run `mops migrate new <Name>` to
create one.

**After:** that hint is gone. `moc`'s underlying compatibility error
already links to the migration docs, and the hint guessed at the cause —
it could equally be a missing new migration or a bug in an existing one.

**Before:** `mops check`/`build`/`check-stable` failing because the
chain dir doesn't exist:

> Migration chain directory not found: migrations
> Run `mops migrate new <Name>` to initialize the migration chain.

**After:** points at the recommended workflow instead:

> Migration chain directory not found: migrations
> Create the directory and add a `.mo` migration file to initialize the
chain.

Also dropped the matching "a hint is shown suggesting to create a new
migration" sentence from the `mops check-stable` docs page, which is no
longer accurate.

## Why

#530's PR description called this out as a follow-up: with `mops
migrate` flagged experimental, the CLI shouldn't keep nudging users
toward it. The `mops migrate` command itself still exists and works for
those who want it.

## Test plan

- [x] `npm test -- migrate.test.ts` (19 tests, 12 snapshots, all green)
- [x] `npm run check` (TypeScript + svelte-check, pre-commit hook clean)


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

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

Author: Kamirus

cli/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Next
 - 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.
 
 ## 2.13.1
 - `mops lint` now honors `[canisters.<name>.migrations].check-limit`, skipping trimmed chain migrations so projects with large migration histories lint as fast as they type-check. Pass an explicit filter (`mops lint <name>`) to opt back in for a one-off lint of a trimmed file.

cli/commands/check-stable.ts

@@ -98,7 +98,6 @@ export async function checkStable(
         globalMocArgs,
         canisterArgs: [...migration.migrationArgs, ...(canister.args ?? [])],
         options,
-        hasMigrations: !!canister.migrations,
       });
     } finally {
       await migration.cleanup();
@@ -141,7 +140,6 @@ export async function checkStable(
         canisterArgs: [...migration.migrationArgs, ...(canister.args ?? [])],
         sources,
         options,
-        hasMigrations: !!canister.migrations,
       });
     } finally {
       await migration.cleanup();
@@ -169,7 +167,6 @@ export interface RunStableCheckParams {
   canisterArgs: string[];
   sources?: string[];
   options?: Partial<CheckStableOptions>;
-  hasMigrations?: boolean;
 }
 
 export async function runStableCheck(
@@ -238,13 +235,6 @@ export async function runStableCheck(
       if (result.stderr) {
         console.error(result.stderr);
       }
-      if (params.hasMigrations) {
-        console.error(
-          chalk.yellow(
-            "Hint: You may need a migration. Run `mops migrate new <Name>` to create one.",
-          ),
-        );
-      }
       cliError(
         `✗ Stable compatibility check failed for canister '${canisterName}'`,
       );

cli/commands/check.ts

@@ -216,7 +216,6 @@ async function checkCanisters(
           canisterArgs: [...migration.migrationArgs, ...(canister.args ?? [])],
           sources,
           options: { verbose: options.verbose, extraArgs: options.extraArgs },
-          hasMigrations: !!canister.migrations,
         });
       }
     } finally {

cli/helpers/migrations.ts

@@ -130,7 +130,7 @@ function resolveMigrationChain(
   if (!existsSync(chainDir) && !nextFile) {
     cliError(
       `Migration chain directory not found: ${chainDir}\n` +
-        "Run `mops migrate new <Name>` to initialize the migration chain.",
+        "Create the directory and add a `.mo` migration file to initialize the chain.",
     );
   }
 

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

@@ -143,12 +143,11 @@ exports[`migrate migrate new creates a migration file with timestamp and templat
 }
 `;
 
-exports[`migrate stable check hint stable check fails with hint when deployed.most is incompatible 1`] = `
+exports[`migrate stable check stable check fails 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",
 }

cli/tests/migrate.test.ts

@@ -241,8 +241,8 @@ describe("migrate", () => {
     });
   });
 
-  describe("stable check hint", () => {
-    test("stable check fails with hint when deployed.most is incompatible", async () => {
+  describe("stable check", () => {
+    test("stable check fails when deployed.most is incompatible", async () => {
       const cwd = await makeTempFixture("basic");
       await writeFile(
         path.join(cwd, "deployed.most"),

docs/docs/cli/4-dev/05-mops-check-stable.md

@@ -87,7 +87,7 @@ Show detailed output including the `moc` commands being run and the intermediate
 
 ## Enhanced migration support
 
-When a canister has a `[canisters.<name>.migrations]` section in `mops.toml`, `mops check-stable` automatically injects the `--enhanced-migration` flag when generating stable type signatures. If the stable check fails and `[migrations]` is configured, a hint is shown suggesting to create a new migration.
+When a canister has a `[canisters.<name>.migrations]` section in `mops.toml`, `mops check-stable` automatically injects the `--enhanced-migration` flag when generating stable type signatures.
 
 ## Passing flags to the Motoko compiler