feat(build): generate .most file via --stable-types (#456)

## Summary

- `mops build` now always passes `--stable-types` to `moc`, generating a
`<canister>.most` (Motoko stable types) file alongside `.wasm` and
`.did` for every canister
- `--stable-types` is registered in `managedFlags` so users get a clear
warning if they try to pass it manually via `[build].args` or `--` extra
args

## Test plan

- `custom output path via config outputDir` — asserts `main.most` is
produced in the configured output dir
- `--output CLI option` — asserts `foo.most` is produced alongside
`foo.wasm` and `foo.did`
- `warns when args contain managed flags` — now also passes
`--stable-types` to cover the duplicate-flag warning; snapshot updated
- Verbose-mode snapshots (`build ok 1`, `build error 1`) updated to
reflect `--stable-types` in the logged moc args

## Notable decisions

- No changes to how the `.most` file is consumed — it is left in the
output directory for tooling (e.g. upgrade compatibility checks) to pick
up
- Flag placement mirrors `--idl`: immediately after `-c`, before `-o`

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

---------

Co-authored-by: Ryan Vandersmith <ryanvandersmith@gmail.com>

Author: Kamirus

cli/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Next
 
+- `mops build` now generates a `.most` (Motoko stable types) file alongside `.wasm` and `.did` for each canister; the `.most` file can be passed directly to `mops check-stable` to verify upgrade compatibility
 - `mops.lock` is now created automatically the first time dependencies are installed — no need to run `mops i --lock update` once to opt in. Triggered by `mops install`, `mops add`, `mops remove`, `mops update`, `mops sync`, and `mops init` (when it installs dependencies). Applications should commit `mops.lock`; library authors should add it to `.gitignore`.
 
 ## 2.7.0

cli/commands/build.ts

@@ -69,9 +69,11 @@ export async function build(
     }
     motokoPath = resolveConfigPath(motokoPath);
     const wasmPath = join(outputDir, `${canisterName}.wasm`);
+    const mostPath = join(outputDir, `${canisterName}.most`);
     let args = [
       "-c",
       "--idl",
+      "--stable-types",
       "-o",
       wasmPath,
       motokoPath,
@@ -116,6 +118,9 @@ export async function build(
         console.log(result.stdout);
       }
 
+      options.verbose &&
+        console.log(chalk.gray(`Stable types written to ${mostPath}`));
+
       const generatedDidPath = join(outputDir, `${canisterName}.did`);
       const resolvedCandidPath = canister.candid
         ? resolveConfigPath(canister.candid)
@@ -188,6 +193,7 @@ const managedFlags: Record<string, string> = {
   "-o": "use [build].outputDir in mops.toml or --output flag instead",
   "-c": "this flag is always set by mops build",
   "--idl": "this flag is always set by mops build",
+  "--stable-types": "this flag is always set by mops build",
   "--public-metadata": "this flag is managed by mops build",
 };
 

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

@@ -5,7 +5,8 @@ exports[`build error 1`] = `
   "exitCode": 0,
   "stderr": "",
   "stdout": "build canister foo
-moc-wrapper ["-c","--idl","-o",".mops/.build/foo.wasm","src/Foo.mo","--package","core",".mops/core@1.0.0/src","--release","--public-metadata","candid:service","--public-metadata","candid:args"]
+moc-wrapper ["-c","--idl","--stable-types","-o",".mops/.build/foo.wasm","src/Foo.mo","--package","core",".mops/core@1.0.0/src","--release","--public-metadata","candid:service","--public-metadata","candid:args"]
+Stable types written to .mops/.build/foo.most
 Adding metadata to .mops/.build/foo.wasm
 
 ✓ Built 1 canister successfully",
@@ -34,10 +35,12 @@ exports[`build ok 1`] = `
   "exitCode": 0,
   "stderr": "",
   "stdout": "build canister foo
-moc-wrapper ["-c","--idl","-o",".mops/.build/foo.wasm","src/Foo.mo","--package","core",".mops/core@1.0.0/src","--release","--public-metadata","candid:service","--public-metadata","candid:args"]
+moc-wrapper ["-c","--idl","--stable-types","-o",".mops/.build/foo.wasm","src/Foo.mo","--package","core",".mops/core@1.0.0/src","--release","--public-metadata","candid:service","--public-metadata","candid:args"]
+Stable types written to .mops/.build/foo.most
 Adding metadata to .mops/.build/foo.wasm
 build canister bar
-moc-wrapper ["-c","--idl","-o",".mops/.build/bar.wasm","src/Bar.mo","--package","core",".mops/core@1.0.0/src","--release","--incremental-gc","--public-metadata","candid:service","--public-metadata","candid:args"]
+moc-wrapper ["-c","--idl","--stable-types","-o",".mops/.build/bar.wasm","src/Bar.mo","--package","core",".mops/core@1.0.0/src","--release","--incremental-gc","--public-metadata","candid:service","--public-metadata","candid:args"]
+Stable types written to .mops/.build/bar.most
 Candid compatibility check passed for canister bar
 Adding metadata to .mops/.build/bar.wasm
 
@@ -82,6 +85,7 @@ exports[`build warns when args contain managed flags 1`] = `
   "stderr": "Warning: '-o' in args for canister foo may conflict with mops build — use [build].outputDir in mops.toml or --output flag instead
 Warning: '-c' in args for canister foo may conflict with mops build — this flag is always set by mops build
 Warning: '--idl' in args for canister foo may conflict with mops build — this flag is always set by mops build
+Warning: '--stable-types' in args for canister foo may conflict with mops build — this flag is always set by mops build
 Error while compiling canister foo
 ENOENT: no such file or directory, open '.mops/.build/foo.did'",
   "stdout": "build canister foo",

cli/tests/build.test.ts

@@ -50,13 +50,15 @@ describe("build", () => {
     const customOut = path.join(cwd, "custom-out");
     const customWasm = path.join(customOut, "main.wasm");
     const customDid = path.join(customOut, "main.did");
+    const customMost = path.join(customOut, "main.most");
     const defaultDid = path.join(cwd, ".mops/.build/main.did");
 
     try {
       const result = await cli(["build"], { cwd });
       expect(result.exitCode).toBe(0);
       expect(existsSync(customWasm)).toBe(true);
       expect(existsSync(customDid)).toBe(true);
+      expect(existsSync(customMost)).toBe(true);
       expect(existsSync(defaultDid)).toBe(false);
     } finally {
       cleanFixture(cwd, customOut);
@@ -76,6 +78,7 @@ describe("build", () => {
       expect(result.exitCode).toBe(0);
       expect(existsSync(path.join(outputDir, "foo.wasm"))).toBe(true);
       expect(existsSync(path.join(outputDir, "foo.did"))).toBe(true);
+      expect(existsSync(path.join(outputDir, "foo.most"))).toBe(true);
     } finally {
       cleanFixture(cwd, outputDir);
     }
@@ -88,7 +91,7 @@ describe("build", () => {
 
     try {
       await cliSnapshot(
-        ["build", "foo", "--", "-o", "x", "-c", "--idl"],
+        ["build", "foo", "--", "-o", "x", "-c", "--idl", "--stable-types"],
         { cwd },
         1,
       );

docs/docs/cli/4-dev/03-mops-build.md

@@ -11,12 +11,13 @@ Build Motoko canisters defined in `mops.toml`
 mops build
 ```
 
-Compiles Motoko canisters to WebAssembly (Wasm) modules and generates Candid interface files.
+Compiles Motoko canisters to WebAssembly (Wasm) modules and generates Candid interface and Motoko stable types files.
 
 Canisters must be defined in the `[canisters]` section of your `mops.toml` file.
 
 The build command will automatically:
 - Add Candid metadata to the Wasm modules
+- Generate a Motoko stable types file (`.most`) for each canister
 - Validate Candid compatibility (if a candid file is specified in canister config)
 
 ### Examples
@@ -54,7 +55,7 @@ Show detailed build information including compiler commands and build times.
 
 ### `--output`, `-o`
 
-Specify the output directory for compiled Wasm and Candid files. Overrides `[build].outputDir` from `mops.toml`.
+Specify the output directory for compiled Wasm, Candid, and stable types files. Overrides `[build].outputDir` from `mops.toml`.
 
 Default `.mops/.build`
 
@@ -87,7 +88,7 @@ args = ["--release", "--ai-errors"]
 
 ### `[build].outputDir`
 
-Custom output directory for compiled Wasm and Candid files. The path is relative to the `mops.toml` location.
+Custom output directory for compiled Wasm, Candid, and stable types files. The path is relative to the `mops.toml` location.
 
 Default `.mops/.build`
 
@@ -100,3 +101,18 @@ If a `candid` field is specified in the canister configuration, the build comman
 If the compatibility check fails, the build will fail with an error message.
 
 For manual compatibility checking, see [`mops check-candid`](/cli/mops-check-candid).
+
+## Stable Types
+
+Each build produces a `<canister>.most` file in the output directory alongside the `.wasm` and `.did` files. This file captures the stable variable type signatures of the current canister version.
+
+To use it for upgrade safety checking, save the `.most` file before deploying a new version (e.g. copy it to a committed path), then point `mops check` to it via `mops.toml`:
+
+```toml
+[canisters.backend.check-stable]
+path = ".deployed/backend.most"
+```
+
+With this in place, `mops check` automatically verifies upgrade compatibility on every run.
+
+See [`mops check`](/cli/mops-check#stable-compatibility-checking) for full configuration details.

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

@@ -46,6 +46,10 @@ Path to the old (deployed) version of the actor. Accepts two formats:
 - **`.mo` file** — the old Motoko source file. The command generates the `.most` stable type signature automatically.
 - **`.most` file** — a pre-generated stable type signature. Used directly without compilation.
 
+:::tip
+`mops build` generates a `.most` file for each canister alongside `.wasm` and `.did`. Save it before deploying an upgrade, then configure `[canisters.<name>.check-stable]` in `mops.toml` so `mops check` verifies upgrade safety automatically on every run.
+:::
+
 ### `[canister]`
 
 Name of the canister to check against (as defined in `mops.toml`). The current entrypoint is resolved from `[canisters.<name>].main`.