ic-mops 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Mops CLI Changelog
 
 ## Next
+
+## 2.1.0
+- Add `mops check --fix` subcommand (for Motoko files) with autofix logic
+- Add `mops check` subcommand for type-checking Motoko files
+- Warn for `dfx` projects instead of requiring `mops toolchain init`
+- Allow specifying toolchain file paths in `mops.toml`
+- Add `mops lint` subcommand and `lintoko` toolchain management
+- Improve bench-canister Bench type to be less restrictive (by @timohanke)
+
+## 2.0.1
+- Patch vulnerability in `tar` dependency
+
+# 2.0.0
 - `mops publish` add support for subheadings in changelog (by @f0i)
 - `mops toolchain` now downloads `moc.js` in addition to `moc` binary
 - New `mops build` subcommand (alternative to `dfx build`)

package/RELEASE.md

@@ -0,0 +1,179 @@
+# Mops CLI Release
+
+## Prerequisites
+
+### macOS: GNU tar
+
+```bash
+brew install gnu-tar
+```
+
+Add to `~/.zshrc` or `~/.bashrc`:
+```bash
+export PATH="$HOMEBREW_PREFIX/opt/gnu-tar/libexec/gnubin:$PATH"
+```
+
+### Docker
+
+Docker (or OrbStack) must be installed and running. The CLI build happens inside a Docker container (`zenvoich/mops-builder:1.1.0`) for reproducibility.
+
+### dfx
+
+`dfx` must be installed with the `mops` identity configured (see [Adding the `mops` identity to dfx](#adding-the-mops-identity-to-dfx)).
+
+## Release Steps
+
+### 1. Install dependencies
+
+```bash
+cd cli && bun install
+```
+
+### 2. Update changelog
+
+Move items from the `## Next` section in `CHANGELOG.md` into a new version heading:
+
+```markdown
+## Next
+
+## X.Y.Z
+- Change 1
+- Change 2
+```
+
+The heading must contain the exact version string — `release-cli.ts` parses it to extract release notes.
+
+### 3. Create a release branch and PR
+
+Direct pushes to `main` are not allowed. Create a branch and PR:
+
+```bash
+git checkout -b <username>/release-X.Y.Z
+```
+
+### 4. Bump version
+
+Use `--no-git-tag-version` since the version bump will be committed as part of the PR (not directly on `main`):
+
+```bash
+cd cli
+npm version minor --no-git-tag-version  # or: patch / major
+```
+
+### 5. Commit, push, and open PR
+
+```bash
+git add cli/CHANGELOG.md cli/package.json cli/package-lock.json
+git commit -m "release: CLI vX.Y.Z"
+git push -u origin <username>/release-X.Y.Z
+gh pr create --title "release: CLI vX.Y.Z" --body "..."
+```
+
+Wait for CI to pass, then merge the PR.
+
+### 6. Check reproducibility of the build
+
+After the PR is merged to `main`, check the SHA256 hash from the latest [build-hash workflow](https://github.com/caffeinelabs/mops/actions/workflows/build-hash.yml) run.
+
+**Important**: The CI hash is written to the GitHub Actions **Step Summary** — it is only visible on the **Summary tab** of the workflow run page. It does **not** appear in the downloadable logs (`gh run view --log` will not find it). You must open the run URL in a browser to see it.
+
+Build the same version locally:
+```bash
+cd cli
+MOPS_VERSION=0.0.0 ./build.sh
+```
+
+`build.sh` does the following:
+1. Reads `COMMIT_HASH` (defaults to `git rev-parse HEAD`) and `MOPS_VERSION`
+2. Runs `docker build` using `cli/Dockerfile` with those as build args
+3. The Dockerfile clones the repo at that commit, runs `bun install`, sets the version, and runs `npm run build`
+4. Prints the SHA256 hash of `cli.tgz`
+5. Copies `cli.tgz` out of the container into `cli/bundle/cli.tgz`
+
+Compare the locally printed hash with the one from the CI Step Summary. If they don't match, do not proceed.
+
+**Notes on the local build output:**
+- The "Verification failed" message at the end is **expected** — it happens because no `SHASUM` env var is passed for comparison. The important output is the `Actual shasum: <hash>` line.
+
+### 7. Publish to npm
+
+After the PR is merged and the build hash is verified:
+
+```bash
+git checkout main && git pull
+cd cli
+npm publish
+```
+
+### 8. Prepare on-chain release
+
+Run from the **repo root** (not `cli/`), with Docker running:
+
+```bash
+npm run release-cli
+```
+
+This runs `cli/release-cli.ts`, which:
+1. Calls `./build.sh` — full Docker build with the real version from `cli/package.json`
+2. Extracts release notes from `CHANGELOG.md` for that version
+3. Computes SHA256 of `bundle/cli.tgz`
+4. Copies the tarball to `cli-releases/versions/<version>.tgz`
+5. Creates tag copies: `latest.tgz` and `<major>.tgz`
+6. Updates `cli-releases/tags/latest` to the new version
+7. Updates `cli-releases/releases.json` with metadata (timestamp, size, hash, commit hash, download URL, release notes)
+
+### 9. Deploy the canister
+
+```bash
+dfx deploy --network ic --no-wallet cli --identity mops
+```
+
+This deploys the `cli-releases` canister (serving `cli.mops.one`) to the Internet Computer mainnet.
+
+## Verify build
+
+Anyone can verify a released version by rebuilding from source:
+
+```bash
+cd cli
+docker build . --build-arg COMMIT_HASH=<commit_hash> --build-arg MOPS_VERSION=<mops_version> -t mops
+docker run --rm --env SHASUM=<build_hash> mops
+```
+
+## Adding the `mops` identity to dfx
+
+Check if the identity already exists:
+```bash
+dfx identity list
+```
+
+If `mops` appears, verify it's the correct one:
+```bash
+dfx identity get-principal --identity mops
+```
+
+If it doesn't exist, import it from the PEM file stored in Bitwarden (`Mops identity (canisters and packages)`):
+
+1. Save the PEM key to a temporary file:
+```bash
+cat > /tmp/mops-identity.pem << 'EOF'
+-----BEGIN EC PRIVATE KEY-----
+<paste key from Bitwarden>
+-----END EC PRIVATE KEY-----
+EOF
+```
+
+2. Import into dfx:
+```bash
+dfx identity import mops /tmp/mops-identity.pem
+```
+
+3. Delete the temporary file:
+```bash
+rm /tmp/mops-identity.pem
+```
+
+4. Verify:
+```bash
+dfx identity get-principal --identity mops
+```

package/check-requirements.ts

@@ -4,19 +4,14 @@ import chalk from "chalk";
 
 import { getDependencyType, getRootDir, readConfig } from "./mops.js";
 import { resolvePackages } from "./resolve-packages.js";
-import { getMocVersion } from "./helpers/get-moc-version.js";
+import { getMocSemVer } from "./helpers/get-moc-version.js";
 import { getPackageId } from "./helpers/get-package-id.js";
 
 export async function checkRequirements({ verbose = false } = {}) {
-  let config = readConfig();
-  let mocVersion = config.toolchain?.moc;
-  if (!mocVersion) {
-    mocVersion = getMocVersion(false);
-  }
-  if (!mocVersion) {
+  let installedMoc = getMocSemVer();
+  if (!installedMoc) {
     return;
   }
-  let installedMoc = new SemVer(mocVersion);
   let highestRequiredMoc = new SemVer("0.0.0");
   let highestRequiredMocPkgId = "";
   let rootDir = getRootDir();

package/cli.ts

@@ -10,11 +10,13 @@ import { add } from "./commands/add.js";
 import { bench } from "./commands/bench.js";
 import { build, DEFAULT_BUILD_OUTPUT_DIR } from "./commands/build.js";
 import { bump } from "./commands/bump.js";
+import { check } from "./commands/check.js";
 import { checkCandid } from "./commands/check-candid.js";
 import { docsCoverage } from "./commands/docs-coverage.js";
 import { docs } from "./commands/docs.js";
 import { format } from "./commands/format.js";
 import { init } from "./commands/init.js";
+import { lint } from "./commands/lint.js";
 import { installAll } from "./commands/install/install-all.js";
 import {
   addMaintainer,
@@ -50,6 +52,7 @@ import {
 } from "./mops.js";
 import { resolvePackages } from "./resolve-packages.js";
 import { Tool } from "./types.js";
+import { TOOLCHAINS } from "./commands/toolchain/toolchain-utils.js";
 
 declare global {
   // eslint-disable-next-line no-var
@@ -73,6 +76,22 @@ if (fs.existsSync(networkFile)) {
 
 let program = new Command();
 
+function parseExtraArgs(variadicArgs?: string[]): {
+  extraArgs: string[];
+  args: string[];
+} {
+  const rawArgs = process.argv.slice(2);
+  const dashDashIndex = rawArgs.indexOf("--");
+  const extraArgs =
+    dashDashIndex !== -1 ? rawArgs.slice(dashDashIndex + 1) : [];
+  const args = variadicArgs
+    ? extraArgs.length > 0
+      ? variadicArgs.slice(0, variadicArgs.length - extraArgs.length)
+      : variadicArgs
+    : [];
+  return { extraArgs, args };
+}
+
 program.name("mops");
 
 // --version
@@ -152,7 +171,7 @@ program
     }
 
     if (options.toolchain) {
-      await toolchain.ensureToolchainInited({ strict: false });
+      await toolchain.checkToolchainInited({ strict: false });
     }
 
     let ok = await installAll(options);
@@ -231,7 +250,7 @@ program
         installFromLockFile: true,
       });
     }
-    await toolchain.ensureToolchainInited({ strict: false });
+    await toolchain.checkToolchainInited({ strict: false });
     let sourcesArr = await sources(options);
     console.log(sourcesArr.join("\n"));
   });
@@ -272,18 +291,45 @@ program
     ),
   )
   .allowUnknownOption(true) // TODO: restrict unknown before "--"
-  .action(async (canisters, options, command) => {
+  .action(async (canisters, options) => {
+    checkConfigFile(true);
+    const { extraArgs, args } = parseExtraArgs(canisters);
+    await installAll({
+      silent: true,
+      lock: "ignore",
+      installFromLockFile: true,
+    });
+    await build(args.length ? args : undefined, {
+      ...options,
+      extraArgs,
+    });
+  });
+
+// check
+program
+  .command("check <files...>")
+  .description(
+    "Check Motoko entrypoint files for syntax errors and type issues (including transitively imported files)",
+  )
+  .option("--verbose", "Verbose console output")
+  .addOption(
+    new Option(
+      "--fix",
+      "Apply autofixes to all files, including transitively imported ones",
+    ),
+  )
+  .allowUnknownOption(true)
+  .action(async (files, options) => {
     checkConfigFile(true);
-    const extraArgsIndex = command.args.indexOf("--");
+    const { extraArgs, args: fileList } = parseExtraArgs(files);
     await installAll({
       silent: true,
       lock: "ignore",
       installFromLockFile: true,
     });
-    await build(canisters.length ? canisters : undefined, {
+    await check(fileList, {
       ...options,
-      extraArgs:
-        extraArgsIndex !== -1 ? command.args.slice(extraArgsIndex + 1) : [],
+      extraArgs,
     });
   });
 
@@ -575,7 +621,7 @@ toolchainCommand
 toolchainCommand
   .command("use")
   .description("Install specified tool version and update mops.toml")
-  .addArgument(new Argument("<tool>").choices(["moc", "wasmtime", "pocket-ic"]))
+  .addArgument(new Argument("<tool>").choices(TOOLCHAINS))
   .addArgument(new Argument("[version]"))
   .action(async (tool, version) => {
     if (!checkConfigFile()) {
@@ -589,7 +635,7 @@ toolchainCommand
   .description(
     "Update specified tool or all tools to the latest version and update mops.toml",
   )
-  .addArgument(new Argument("[tool]").choices(["moc", "wasmtime", "pocket-ic"]))
+  .addArgument(new Argument("[tool]").choices(TOOLCHAINS))
   .action(async (tool?: Tool) => {
     if (!checkConfigFile()) {
       process.exit(1);
@@ -600,9 +646,9 @@ toolchainCommand
 toolchainCommand
   .command("bin")
   .description(
-    'Get path to the tool binary\n<tool> can be one of "moc", "wasmtime", "pocket-ic"',
+    `Get path to the tool binary\n<tool> can be one of ${TOOLCHAINS.map((s) => `"${s}"`).join(", ")}`,
   )
-  .addArgument(new Argument("<tool>").choices(["moc", "wasmtime", "pocket-ic"]))
+  .addArgument(new Argument("<tool>").choices(TOOLCHAINS))
   .addOption(
     new Option(
       "--fallback",
@@ -671,6 +717,28 @@ program
     }
   });
 
+// lint
+program
+  .command("lint [filter]")
+  .description("Lint Motoko code")
+  .addOption(new Option("--verbose", "Verbose output"))
+  .addOption(new Option("--fix", "Apply fixes"))
+  .addOption(
+    new Option(
+      "-r, --rules <directory...>",
+      "Directories containing rules (can be used multiple times)",
+    ),
+  )
+  .allowUnknownOption(true)
+  .action(async (filter, options) => {
+    checkConfigFile(true);
+    const { extraArgs } = parseExtraArgs();
+    await lint(filter, {
+      ...options,
+      extraArgs,
+    });
+  });
+
 // docs
 const docsCommand = new Command("docs").description("Documentation management");
 

package/commands/bench/bench-canister.mo

@@ -2,14 +2,25 @@ import Nat64 "mo:core/Nat64";
 import Nat "mo:core/Nat";
 import Runtime "mo:core/Runtime";
 import InternetComputer "mo:core/InternetComputer";
-import Int64 "mo:core/Int64";
 import Region "mo:core/Region";
 import Prim "mo:prim";
-import Bench "mo:bench";
 
 import UserBench "./user-bench"; // file path will be replaced with the *.bench.mo file path
 
 persistent actor class () {
+  type BenchSchema = {
+    name : Text;
+    description : Text;
+    rows : [Text];
+    cols : [Text];
+  };
+
+  type Bench = {
+    getVersion : () -> Nat;
+    getSchema : () -> BenchSchema;
+    runCell : (Nat, Nat) -> ();
+  };
+
   type BenchResult = {
     instructions : Int;
     rts_mutator_instructions : Int;
@@ -23,16 +34,16 @@ persistent actor class () {
     rts_reclaimed : Int;
   };
 
-  transient var benchOpt : ?Bench.Bench = null;
+  transient var benchOpt : ?Bench = null;
 
-  public func init() : async Bench.BenchSchema {
+  public func init() : async BenchSchema {
     let bench = UserBench.init();
     benchOpt := ?bench;
     ignore Region.grow(Region.new(), 1);
     bench.getSchema();
   };
 
-  public query func getSchema() : async Bench.BenchSchema {
+  public query func getSchema() : async BenchSchema {
     let ?bench = benchOpt else Runtime.trap("bench not initialized");
     bench.getSchema();
   };
@@ -41,7 +52,7 @@ persistent actor class () {
     {
       instructions = 0;
       rts_heap_size = Prim.rts_heap_size();
-      stable_memory_size = Int64.toInt(Int64.fromNat64(Prim.stableMemorySize())) * 65536;
+      stable_memory_size = Prim.rts_stable_memory_size() * 65536;
       rts_stable_memory_size = Prim.rts_stable_memory_size();
       rts_logical_stable_memory_size = Prim.rts_logical_stable_memory_size();
       rts_memory_size = Prim.rts_memory_size();

package/commands/bench.ts

@@ -19,6 +19,7 @@ import { getMocVersion } from "../helpers/get-moc-version.js";
 import { getDfxVersion } from "../helpers/get-dfx-version.js";
 import { getMocPath } from "../helpers/get-moc-path.js";
 import { sources } from "./sources.js";
+import { MOTOKO_GLOB_CONFIG } from "../constants.js";
 
 import { Benchmark, Benchmarks } from "../declarations/main/main.did.js";
 import { BenchResult, _SERVICE } from "../declarations/bench/bench.did.js";
@@ -26,18 +27,6 @@ import { BenchReplica } from "./bench-replica.js";
 
 type ReplicaName = "dfx" | "pocket-ic" | "dfx-pocket-ic";
 
-let ignore = [
-  "**/node_modules/**",
-  "**/.mops/**",
-  "**/.vessel/**",
-  "**/.git/**",
-];
-
-let globConfig = {
-  nocase: true,
-  ignore: ignore,
-};
-
 type BenchOptions = {
   replica: ReplicaName;
   replicaVersion: string;
@@ -113,7 +102,7 @@ export async function bench(
   if (filter) {
     globStr = `**/bench?(mark)/**/*${filter}*.mo`;
   }
-  let files = globSync(path.join(rootDir, globStr), globConfig);
+  let files = globSync(path.join(rootDir, globStr), MOTOKO_GLOB_CONFIG);
   if (!files.length) {
     if (filter) {
       options.silent ||

package/commands/build.ts

@@ -1,14 +1,15 @@
 import chalk from "chalk";
 import { execa } from "execa";
 import { exists } from "fs-extra";
-import { mkdir } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { getMocPath } from "../helpers/get-moc-path.js";
+import { cliError } from "../error.js";
+import { isCandidCompatible } from "../helpers/is-candid-compatible.js";
+import { CustomSection, getWasmBindings } from "../wasm.js";
 import { readConfig } from "../mops.js";
 import { CanisterConfig } from "../types.js";
 import { sourcesArgs } from "./sources.js";
-import { isCandidCompatible } from "../helpers/is-candid-compatible.js";
-import { cliError } from "../error.js";
+import { toolchain } from "./toolchain/index.js";
 
 export interface BuildOptions {
   outputDir: string;
@@ -27,7 +28,7 @@ export async function build(
   }
 
   let outputDir = options.outputDir ?? DEFAULT_BUILD_OUTPUT_DIR;
-  let mocPath = getMocPath();
+  let mocPath = await toolchain.bin("moc", { fallback: true });
   let canisters: Record<string, CanisterConfig> = {};
   let config = readConfig();
   if (config.canisters) {
@@ -69,17 +70,17 @@ export async function build(
     : canisters;
 
   for (let [canisterName, canister] of Object.entries(filteredCanisters)) {
-    options.verbose && console.time(`build canister ${canisterName}`);
     console.log(chalk.blue("build canister"), chalk.bold(canisterName));
     let motokoPath = canister.main;
     if (!motokoPath) {
       cliError(`No main file is specified for canister ${canisterName}`);
     }
+    const wasmPath = join(outputDir, `${canisterName}.wasm`);
     let args = [
       "-c",
       "--idl",
       "-o",
-      join(outputDir, `${canisterName}.wasm`),
+      wasmPath,
       motokoPath,
       ...(options.extraArgs ?? []),
       ...(await sourcesArgs()).flat(),
@@ -100,6 +101,12 @@ export async function build(
       }
       args.push(...canister.args);
     }
+    const isPublicCandid = true; // always true for now to reduce corner cases
+    const candidVisibility = isPublicCandid ? "icp:public" : "icp:private";
+    if (isPublicCandid) {
+      args.push("--public-metadata", "candid:service");
+      args.push("--public-metadata", "candid:args");
+    }
     try {
       if (options.verbose) {
         console.log(chalk.gray(mocPath, JSON.stringify(args)));
@@ -128,8 +135,8 @@ export async function build(
         console.log(result.stdout);
       }
 
+      const generatedDidPath = join(outputDir, `${canisterName}.did`);
       if (canister.candid) {
-        const generatedDidPath = join(outputDir, `${canisterName}.did`);
         const originalCandidPath = canister.candid;
 
         try {
@@ -146,27 +153,45 @@ export async function build(
 
           if (options.verbose) {
             console.log(
-              chalk.green(
+              chalk.gray(
                 `Candid compatibility check passed for canister ${canisterName}`,
               ),
             );
           }
-        } catch (candidError: any) {
+        } catch (err: any) {
           cliError(
-            `Error during Candid compatibility check for canister ${canisterName}`,
-            candidError,
+            `Error during Candid compatibility check for canister ${canisterName}${err?.message ? `\n${err.message}` : ""}`,
           );
         }
       }
-    } catch (cliError: any) {
-      if (cliError.message?.includes("Build failed for canister")) {
-        throw cliError;
+
+      options.verbose &&
+        console.log(chalk.gray(`Adding metadata to ${wasmPath}`));
+      const candidPath = canister.candid ?? generatedDidPath;
+      const candidText = await readFile(candidPath, "utf-8");
+      const customSections: CustomSection[] = [
+        { name: `${candidVisibility} candid:service`, data: candidText },
+      ];
+      if (canister.initArg) {
+        customSections.push({
+          name: `${candidVisibility} candid:args`,
+          data: canister.initArg,
+        });
+      }
+      const wasmBytes = await readFile(wasmPath);
+      const newWasm = getWasmBindings().add_custom_sections(
+        wasmBytes,
+        customSections,
+      );
+      await writeFile(wasmPath, newWasm);
+    } catch (err: any) {
+      if (err.message?.includes("Build failed for canister")) {
+        throw err;
       }
       cliError(
-        `Error while compiling canister ${canisterName}${cliError?.message ? `\n${cliError.message}` : ""}`,
+        `Error while compiling canister ${canisterName}${err?.message ? `\n${err.message}` : ""}`,
       );
     }
-    options.verbose && console.timeEnd(`build canister ${canisterName}`);
   }
 
   console.log(