ic-mops 2.14.0 → 2.15.0

package/commands/generate.ts

@@ -0,0 +1,201 @@
+import chalk from "chalk";
+import { execa } from "execa";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { cliError } from "../error.js";
+import {
+  filterCanisters,
+  resolveCanisterConfigs,
+} from "../helpers/resolve-canisters.js";
+import {
+  GENERATE_CANDID_MANAGED_FLAGS,
+  prepareMocArgs,
+} from "../helpers/moc-args.js";
+import {
+  getRootDir,
+  readConfig,
+  resolveConfigPath,
+  writeConfig,
+} from "../mops.js";
+import { CanisterConfig } from "../types.js";
+import { toolchain } from "./toolchain/index.js";
+
+export interface GenerateCandidOptions {
+  output?: string;
+  verbose?: boolean;
+  extraArgs?: string[];
+}
+
+export async function generateCandid(
+  canisterNames: string[] | undefined,
+  options: GenerateCandidOptions,
+): Promise<void> {
+  if (canisterNames?.length === 0) {
+    cliError("No canisters specified");
+  }
+
+  const config = readConfig();
+  const canisters = resolveCanisterConfigs(config);
+  if (!Object.keys(canisters).length) {
+    cliError("No Motoko canisters found in mops.toml configuration");
+  }
+
+  const filtered = filterCanisters(canisters, canisterNames);
+  const filteredEntries = Object.entries(filtered);
+
+  if (options.output && filteredEntries.length > 1) {
+    cliError(
+      "--output / -o is only supported when generating for a single canister",
+    );
+  }
+
+  const mocPath = await toolchain.bin("moc", { fallback: true });
+  const rootDir = getRootDir();
+
+  let configChanged = false;
+
+  for (const [canisterName, canister] of filteredEntries) {
+    const dest = resolveDestination(
+      canisterName,
+      canister,
+      canisters,
+      options.output,
+      rootDir,
+    );
+
+    console.log(
+      chalk.blue("generate candid"),
+      chalk.bold(canisterName),
+      chalk.gray(`→ ${dest.fsPath}`),
+    );
+
+    const prepared = await prepareMocArgs(config, canister, canisterName, {
+      mode: "build",
+      managedFlags: GENERATE_CANDID_MANAGED_FLAGS,
+      commandName: "mops generate candid",
+      verbose: options.verbose,
+      extraArgs: options.extraArgs,
+    });
+
+    try {
+      await mkdir(path.dirname(dest.fsPath), { recursive: true });
+      const args = [
+        "--idl",
+        "-o",
+        dest.fsPath,
+        prepared.motokoPath,
+        ...prepared.args,
+      ];
+      if (options.verbose) {
+        console.log(chalk.gray(mocPath, JSON.stringify(args)));
+      }
+      const result = await execa(mocPath, args, {
+        stdio: options.verbose ? "inherit" : "pipe",
+        reject: false,
+      });
+
+      if (result.exitCode !== 0) {
+        if (!options.verbose) {
+          if (result.stderr) {
+            console.error(chalk.red(result.stderr));
+          }
+          if (result.stdout?.trim()) {
+            console.error(chalk.yellow("Output:"));
+            console.error(result.stdout);
+          }
+        }
+        cliError(
+          `Failed to generate Candid for canister ${canisterName} (exit code: ${result.exitCode})`,
+        );
+      }
+
+      if (dest.configPath !== null) {
+        const c = (config.canisters ??= {});
+        const existing = c[canisterName];
+        const obj: CanisterConfig =
+          typeof existing === "string"
+            ? { main: existing }
+            : { ...(existing ?? {}) };
+        obj.candid = dest.configPath;
+        c[canisterName] = obj;
+        configChanged = true;
+      }
+    } finally {
+      await prepared.cleanup();
+    }
+  }
+
+  if (configChanged) {
+    writeConfig(config);
+  }
+
+  console.log(
+    chalk.green(
+      `\n✓ Generated Candid for ${filteredEntries.length} canister${filteredEntries.length === 1 ? "" : "s"}`,
+    ),
+  );
+}
+
+interface Destination {
+  /** Path used for filesystem operations and passed to moc (cwd-relative or absolute). */
+  fsPath: string;
+  /** Value to write into `[canisters.<name>].candid` (project-root-relative). `null` skips the config update. */
+  configPath: string | null;
+}
+
+function resolveDestination(
+  canisterName: string,
+  canister: CanisterConfig,
+  allCanisters: Record<string, CanisterConfig>,
+  outputFlag: string | undefined,
+  rootDir: string,
+): Destination {
+  if (!canister.main) {
+    cliError(`No main file is specified for canister ${canisterName}`);
+  }
+
+  let fsPath: string;
+  let configPath: string | null;
+
+  if (outputFlag) {
+    fsPath = outputFlag;
+    configPath = null;
+
+    const outAbs = path.resolve(fsPath);
+    for (const [otherName, other] of Object.entries(allCanisters)) {
+      if (otherName === canisterName || !other.candid) {
+        continue;
+      }
+      if (path.resolve(rootDir, other.candid) === outAbs) {
+        console.warn(
+          chalk.yellow(
+            `Warning: --output path collides with [canisters.${otherName}].candid (${other.candid}). Sharing a .did between canisters is almost always a mistake.`,
+          ),
+        );
+      }
+    }
+  } else if (canister.candid) {
+    fsPath = resolveConfigPath(canister.candid);
+    configPath = null;
+  } else {
+    // Default: <dirname(main)>/<canisterName>.did, forward slashes for the toml value
+    const mainDir = path.dirname(canister.main).replace(/\\/g, "/");
+    const projectRel =
+      mainDir === "." || mainDir === ""
+        ? `${canisterName}.did`
+        : `${mainDir}/${canisterName}.did`;
+    fsPath = resolveConfigPath(projectRel);
+    configPath = projectRel;
+  }
+
+  const absPath = path.resolve(fsPath);
+  const dotMopsDir = path.resolve(rootDir, ".mops");
+  if (absPath === dotMopsDir || absPath.startsWith(dotMopsDir + path.sep)) {
+    cliError(
+      `Refusing to write Candid file inside .mops/ (private build cache): ${fsPath}\n` +
+        "Choose a path outside .mops/ — it should be committable and readable by downstream tooling.",
+    );
+  }
+
+  return { fsPath, configPath };
+}

package/commands/lint.ts

@@ -103,6 +103,8 @@ export interface LintOptions {
   rules?: string[];
   files?: string[];
   extraArgs: string[];
+  /** Commander `--no-check-limit`: lint the full migration chain. */
+  noCheckLimit?: boolean;
 }
 
 function buildCommonArgs(
@@ -193,9 +195,10 @@ async function lintImpl(
     : "lintoko";
 
   const isExplicit = !!filter || !!(options.files && options.files.length > 0);
-  const trimmedMigrations = isExplicit
-    ? new Set<string>()
-    : getTrimmedMigrationFiles(config);
+  const trimmedMigrations =
+    isExplicit || options.noCheckLimit
+      ? new Set<string>()
+      : getTrimmedMigrationFiles(config);
 
   let filesToLint: string[];
   if (options.files && options.files.length > 0) {

package/dist/cli.js

@@ -12,9 +12,11 @@ import { bump } from "./commands/bump.js";
 import { check } from "./commands/check.js";
 import { checkCandid } from "./commands/check-candid.js";
 import { checkStable } from "./commands/check-stable.js";
+import { deployed, deployedInit } from "./commands/deployed.js";
 import { docsCoverage } from "./commands/docs-coverage.js";
 import { docs } from "./commands/docs.js";
 import { format } from "./commands/format.js";
+import { generateCandid } from "./commands/generate.js";
 import { info } from "./commands/info.js";
 import { init } from "./commands/init.js";
 import { lint } from "./commands/lint.js";
@@ -60,6 +62,16 @@ function parseExtraArgs(variadicArgs) {
         : [];
     return { extraArgs, args };
 }
+// Shared `--help` section describing the enhanced migration `check-limit`
+// trimming and its override flag, so the limit behaviour is discoverable
+// from `--help`. `withFix` appends the `--fix` hint for commands that support it.
+function enhancedMigrationHelp(withFix) {
+    const example = withFix ? " (e.g. to --fix older migrations)" : "";
+    return ("\nEnhanced migration ([canisters.<name>.migrations]):\n" +
+        "  The canister is checked against its migration chain. [migrations].check-limit\n" +
+        "  trims it to the last N migrations (older ones are skipped). Pass --no-check-limit\n" +
+        `  to use the full chain${example}.`);
+}
 program.name("mops");
 // --version
 program.version(`CLI ${version()}\nAPI ${apiVersion}`, "-v --version");
@@ -76,7 +88,7 @@ program
     .command("add <pkg>")
     .description("Install the package and save it to mops.toml")
     .option("--dev", "Add to [dev-dependencies] section")
-    .option("--verbose")
+    .option("--verbose", "Show more information")
     .addOption(new Option("--lock <action>", "Lockfile action").choices([
     "update",
     "ignore",
@@ -111,7 +123,7 @@ program
     .alias("i")
     .description("Install all dependencies specified in mops.toml")
     .option("--no-toolchain", "Do not install toolchain")
-    .option("--verbose")
+    .option("--verbose", "Show more information")
     .addOption(new Option("--lock <action>", "Lockfile action").choices([
     "check",
     "update",
@@ -145,7 +157,7 @@ program
     .option("--no-docs", "Do not generate docs")
     .option("--no-test", "Do not run tests")
     .option("--no-bench", "Do not run benchmarks")
-    .option("--verbose")
+    .option("--verbose", "Show more information")
     .action(async (options) => {
     if (!checkConfigFile()) {
         process.exit(1);
@@ -247,6 +259,12 @@ program
     .description("Build a canister")
     .addOption(new Option("--verbose", "Verbose console output"))
     .addOption(new Option("--output, -o <output>", "Output directory"))
+    .addHelpText("after", "\nArguments after -- are forwarded directly to moc, e.g.:\n  $ mops build -- -Werror")
+    .addHelpText("after", "\nEnhanced migration ([canisters.<name>.migrations]):\n" +
+    "  The canister is built against its full migration chain (every migration is\n" +
+    "  compiled into the wasm). If mops check passes but mops build fails while\n" +
+    "  [migrations].check-limit is set, re-run with mops check --no-check-limit to\n" +
+    "  surface the issue (check trims the chain; build compiles all of it).")
     .allowUnknownOption(true) // TODO: restrict unknown before "--"
     .action(async (canisters, options) => {
     checkConfigFile(true);
@@ -268,6 +286,9 @@ program
     .description("Check Motoko canisters or files for syntax errors and type issues. Arguments can be canister names or file paths. If no arguments are given, checks all canisters from mops.toml. Also runs stable compatibility checks for canisters with [check-stable] configured, and runs linting if lintoko is configured in [toolchain]")
     .option("--verbose", "Verbose console output")
     .addOption(new Option("--fix", "Apply autofixes to all files, including transitively imported ones"))
+    .addOption(new Option("--no-check-limit", "Check the full migration chain, ignoring [migrations].check-limit"))
+    .addHelpText("after", "\nArguments after -- are forwarded directly to moc, e.g.:\n  $ mops check -- -Werror")
+    .addHelpText("after", enhancedMigrationHelp(true))
     .allowUnknownOption(true)
     .action(async (args, options) => {
     checkConfigFile(true);
@@ -300,6 +321,9 @@ program
     .command("check-stable [args...]")
     .description("Check stable variable compatibility. With no arguments, checks all canisters with [check-stable] configured. Arguments can be canister names or an old file path followed by an optional canister name")
     .option("--verbose", "Verbose console output")
+    .addOption(new Option("--no-check-limit", "Check the full migration chain, ignoring [migrations].check-limit"))
+    .addHelpText("after", "\nArguments after -- are forwarded directly to moc, e.g.:\n  $ mops check-stable -- -Werror")
+    .addHelpText("after", enhancedMigrationHelp(false))
     .allowUnknownOption(true)
     .action(async (args, options) => {
     checkConfigFile(true);
@@ -314,6 +338,25 @@ program
         extraArgs,
     });
 });
+// deployed
+const deployedCommand = new Command("deployed")
+    .description("Post-deploy hook: promote .most stable-types files into the deployed directory so `mops check-stable` compares against the just-deployed version. Pass canister names to scope; with no arguments, all canisters in mops.toml are promoted")
+    .argument("[canisters...]")
+    .addOption(new Option("--build-dir <dir>", "Directory to read built .most files from (default: [build].outputDir or .mops/.build)"))
+    .addOption(new Option("--dir <dir>", "Destination directory (default: [deployed].dir or deployed)"))
+    .action(async (canisters, options) => {
+    checkConfigFile(true);
+    await deployed(canisters.length ? canisters : undefined, options);
+});
+deployedCommand
+    .command("init [canisters...]")
+    .description("Pre-first-deploy bootstrap: create an empty-actor .most baseline in the deployed directory and wire [canisters.<name>.check-stable].path to it. Idempotent")
+    .addOption(new Option("--dir <dir>", "Destination directory (default: [deployed].dir or deployed)"))
+    .action(async (canisters, options) => {
+    checkConfigFile(true);
+    await deployedInit(canisters.length ? canisters : undefined, options);
+});
+program.addCommand(deployedCommand);
 // test
 program
     .command("test [filter]")
@@ -574,6 +617,31 @@ migrateCommand
     await migrateFreeze(canister);
 });
 program.addCommand(migrateCommand);
+// generate
+const generateCommand = new Command("generate")
+    .description("Generate source-derived artifacts (Candid, ...)")
+    .showHelpAfterError();
+generateCommand
+    .command("candid [canisters...]")
+    .description("(Re)generate the curated `.did` file for one or more canisters from current Motoko source. With no canister names, generates for all canisters in mops.toml. When [canisters.<name>].candid is set, overwrites that file; otherwise writes <name>.did next to `main` and sets the field.")
+    .addOption(new Option("--output, -o <output>", "Write the generated .did to <output> (single-canister only; does not touch mops.toml)"))
+    .addOption(new Option("--verbose", "Verbose console output"))
+    .addHelpText("after", "\nArguments after -- are forwarded directly to moc, e.g.:\n  $ mops generate candid -- -Werror")
+    .allowUnknownOption(true)
+    .action(async (canisters, options) => {
+    checkConfigFile(true);
+    const { extraArgs, args } = parseExtraArgs(canisters);
+    await installAll({
+        silent: true,
+        lock: "ignore",
+        installFromLockFile: true,
+    });
+    await generateCandid(args.length ? args : undefined, {
+        ...options,
+        extraArgs,
+    });
+});
+program.addCommand(generateCommand);
 // self
 const selfCommand = new Command("self").description("Mops CLI management");
 selfCommand
@@ -623,6 +691,9 @@ program
     .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)"))
+    .addOption(new Option("--no-check-limit", "Lint the full migration chain, ignoring [migrations].check-limit"))
+    .addHelpText("after", "\nArguments after -- are forwarded directly to lintoko, e.g.:\n  $ mops lint -- --severity warning")
+    .addHelpText("after", enhancedMigrationHelp(true))
     .allowUnknownOption(true)
     .action(async (filter, options) => {
     checkConfigFile(true);
@@ -630,6 +701,7 @@ program
     await lint(filter, {
         ...options,
         extraArgs,
+        noCheckLimit: options.checkLimit === false,
     });
 });
 // docs

package/dist/commands/build.d.ts

@@ -1,7 +1,13 @@
+import { Config } from "../types.js";
 export interface BuildOptions {
     outputDir: string;
     verbose: boolean;
     extraArgs: string[];
 }
 export declare const DEFAULT_BUILD_OUTPUT_DIR = ".mops/.build";
+/**
+ * Resolve the build output directory: CLI override → `[build].outputDir`
+ * (project-root-relative, resolved via `resolveConfigPath`) → default.
+ */
+export declare function resolveBuildOutputDir(config: Config, override?: string): string;
 export declare function build(canisterNames: string[] | undefined, options: Partial<BuildOptions>): Promise<void>;

package/dist/commands/build.js

@@ -6,22 +6,30 @@ import { join } from "node:path";
 import { lock, unlockSync } from "proper-lockfile";
 import { cliError } from "../error.js";
 import { isCandidCompatible } from "../helpers/is-candid-compatible.js";
-import { filterCanisters, resolveCanisterConfigs, validateCanisterArgs, } from "../helpers/resolve-canisters.js";
-import { prepareMigrationArgs } from "../helpers/migrations.js";
+import { filterCanisters, resolveCanisterConfigs, } from "../helpers/resolve-canisters.js";
+import { BUILD_MANAGED_FLAGS, prepareMocArgs } from "../helpers/moc-args.js";
 import { getWasmBindings } from "../wasm.js";
-import { getGlobalMocArgs, readConfig, resolveConfigPath } from "../mops.js";
-import { sourcesArgs } from "./sources.js";
+import { readConfig, resolveConfigPath } from "../mops.js";
 import { toolchain } from "./toolchain/index.js";
 export const DEFAULT_BUILD_OUTPUT_DIR = ".mops/.build";
+/**
+ * Resolve the build output directory: CLI override → `[build].outputDir`
+ * (project-root-relative, resolved via `resolveConfigPath`) → default.
+ */
+export function resolveBuildOutputDir(config, override) {
+    if (override) {
+        return override;
+    }
+    return config.build?.outputDir
+        ? resolveConfigPath(config.build.outputDir)
+        : DEFAULT_BUILD_OUTPUT_DIR;
+}
 export async function build(canisterNames, options) {
     if (canisterNames?.length === 0) {
         cliError("No canisters specified to build");
     }
     let config = readConfig();
-    let configOutputDir = config.build?.outputDir
-        ? resolveConfigPath(config.build.outputDir)
-        : undefined;
-    let outputDir = options.outputDir ?? configOutputDir ?? DEFAULT_BUILD_OUTPUT_DIR;
+    let outputDir = resolveBuildOutputDir(config, options.outputDir);
     let mocPath = await toolchain.bin("moc", { fallback: true });
     let canisters = resolveCanisterConfigs(config);
     if (!Object.keys(canisters).length) {
@@ -33,11 +41,6 @@ export async function build(canisterNames, options) {
     const filteredCanisters = filterCanisters(canisters, canisterNames);
     for (let [canisterName, canister] of Object.entries(filteredCanisters)) {
         console.log(chalk.blue("build canister"), chalk.bold(canisterName));
-        let motokoPath = canister.main;
-        if (!motokoPath) {
-            cliError(`No main file is specified for canister ${canisterName}`);
-        }
-        motokoPath = resolveConfigPath(motokoPath);
         const wasmPath = join(outputDir, `${canisterName}.wasm`);
         const mostPath = join(outputDir, `${canisterName}.most`);
         // per-canister lock to prevent parallel builds of the same canister from clobbering output files
@@ -63,7 +66,13 @@ export async function build(canisterNames, options) {
             catch { }
         };
         process.on("exit", exitCleanup);
-        const migration = await prepareMigrationArgs(canister.migrations, canisterName, "build", options.verbose);
+        const prepared = await prepareMocArgs(config, canister, canisterName, {
+            mode: "build",
+            managedFlags: BUILD_MANAGED_FLAGS,
+            commandName: "mops build",
+            verbose: options.verbose,
+            extraArgs: options.extraArgs,
+        });
         try {
             let args = [
                 "-c",
@@ -71,12 +80,9 @@ export async function build(canisterNames, options) {
                 "--stable-types",
                 "-o",
                 wasmPath,
-                motokoPath,
-                ...(await sourcesArgs()).flat(),
-                ...getGlobalMocArgs(config),
-                ...migration.migrationArgs,
+                prepared.motokoPath,
+                ...prepared.args,
             ];
-            args.push(...collectExtraArgs(config, canister, canisterName, options.extraArgs));
             const isPublicCandid = true; // always true for now to reduce corner cases
             const candidVisibility = isPublicCandid ? "icp:public" : "icp:private";
             if (isPublicCandid) {
@@ -151,7 +157,7 @@ export async function build(canisterNames, options) {
             }
         }
         finally {
-            await migration.cleanup();
+            await prepared.cleanup();
             process.removeListener("exit", exitCleanup);
             try {
                 await release?.();
@@ -161,35 +167,3 @@ export async function build(canisterNames, options) {
     }
     console.log(chalk.green(`\n✓ Built ${Object.keys(filteredCanisters).length} canister${Object.keys(filteredCanisters).length === 1 ? "" : "s"} successfully`));
 }
-const managedFlags = {
-    "-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",
-};
-function collectExtraArgs(config, canister, canisterName, extraArgs) {
-    const args = [];
-    if (config.build?.args) {
-        if (typeof config.build.args === "string") {
-            cliError(`[build] config 'args' should be an array of strings in mops.toml config file`);
-        }
-        args.push(...config.build.args);
-    }
-    if (canister.args) {
-        validateCanisterArgs(canister, canisterName, config);
-        args.push(...canister.args);
-    }
-    if (extraArgs) {
-        args.push(...extraArgs);
-    }
-    const warned = new Set();
-    for (const arg of args) {
-        const hint = managedFlags[arg];
-        if (hint && !warned.has(arg)) {
-            warned.add(arg);
-            console.warn(chalk.yellow(`Warning: '${arg}' in args for canister ${canisterName} may conflict with mops build — ${hint}`));
-        }
-    }
-    return args;
-}

package/dist/commands/check-stable.d.ts

@@ -2,6 +2,8 @@ import { CanisterConfig } from "../types.js";
 export interface CheckStableOptions {
     verbose: boolean;
     extraArgs: string[];
+    /** Commander `--no-check-limit`: false ignores [migrations].check-limit. */
+    checkLimit: boolean;
 }
 export declare function resolveStablePath(canister: CanisterConfig, canisterName: string, options?: {
     required?: boolean;

package/dist/commands/check-stable.js

@@ -52,7 +52,7 @@ export async function checkStable(args, options = {}) {
             cliError(`No main file specified for canister '${name}' in mops.toml`);
         }
         validateCanisterArgs(canister, name, config);
-        const migration = await prepareMigrationArgs(canister.migrations, name, "check", options.verbose);
+        const migration = await prepareMigrationArgs(canister.migrations, name, "check", options.verbose, options.checkLimit === false);
         try {
             await runStableCheck({
                 oldFile,
@@ -85,7 +85,7 @@ export async function checkStable(args, options = {}) {
         if (!stablePath) {
             continue;
         }
-        const migration = await prepareMigrationArgs(canister.migrations, name, "check", options.verbose);
+        const migration = await prepareMigrationArgs(canister.migrations, name, "check", options.verbose, options.checkLimit === false);
         try {
             await runStableCheck({
                 oldFile: stablePath,

package/dist/commands/check.d.ts

@@ -2,5 +2,7 @@ export interface CheckOptions {
     verbose: boolean;
     fix: boolean;
     extraArgs: string[];
+    /** Commander `--no-check-limit`: false ignores [migrations].check-limit. */
+    checkLimit: boolean;
 }
 export declare function check(args: string[], options?: Partial<CheckOptions>): Promise<void>;

package/dist/commands/check.js

@@ -83,6 +83,7 @@ async function checkImpl(args, options = {}) {
             fix: options.fix,
             rules: lintRules,
             files: lintFiles,
+            noCheckLimit: options.checkLimit === false,
         });
     }
 }
@@ -97,7 +98,7 @@ async function checkCanisters(config, canisters, options) {
         }
         validateCanisterArgs(canister, canisterName, config);
         const motokoPath = resolveConfigPath(canister.main);
-        const migration = await prepareMigrationArgs(canister.migrations, canisterName, "check", options.verbose);
+        const migration = await prepareMigrationArgs(canister.migrations, canisterName, "check", options.verbose, options.checkLimit === false);
         try {
             const mocArgs = [
                 "--check",

package/dist/commands/deployed.d.ts

@@ -0,0 +1,10 @@
+export declare const DEFAULT_DEPLOYED_DIR = "deployed";
+export interface DeployedOptions {
+    buildDir?: string;
+    dir?: string;
+}
+export interface DeployedInitOptions {
+    dir?: string;
+}
+export declare function deployed(canisterNames: string[] | undefined, options?: DeployedOptions): Promise<void>;
+export declare function deployedInit(canisterNames: string[] | undefined, options?: DeployedInitOptions): Promise<void>;