chore(cli): extend dfx replica deprecation to test + watch; track removal in NEXT-MAJOR

- Extract the warning into a shared `helpers/deprecate-dfx-replica.ts`
  and wire it through `mops bench`, `mops test --mode replica`, and
  `mops watch` (one-shot per watch session).
- Recommend `mops toolchain use pocket-ic` in the warning text and docs,
  matching the existing wasmtime hint pattern in `test.ts`.
- Annotate `mops test --replica`'s `--help` with the deprecation note,
  mirroring what `mops bench --replica` already says.
- Add a NEXT-MAJOR.md item under "Drop dfx coupling" to remove the dfx
  replica paths entirely and flip the default to a mops-pinned
  PocketIC version. Calls out the bench-baseline drift for release notes.

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

Author: Kamirus

NEXT-MAJOR.md

@@ -39,6 +39,7 @@ Close the gap between update path and resolve path.
 
 ### Drop `dfx` coupling
 - Remove `dfx`-bundled `moc` fallback in `toolchain bin --fallback`, `test`, `bench`, `bench-replica`, `docs`. (`cli/helpers/get-dfx-version.ts`, `cli/commands/toolchain/index.ts:359,387`, `cli/commands/docs.ts:44-54`)
+- Remove the `dfx` and `dfx-pocket-ic` replica paths from `mops bench`, `mops test --mode replica`, and `mops watch`. Drop the `dfx` choice from `--replica`; drop the implicit `dfx`/`dfx-pocket-ic` fallback when `[toolchain.pocket-ic]` is unset. Flip the default so an unpinned `pocket-ic` auto-resolves to a mops-controlled `DEFAULT_POCKET_IC_VERSION` (download-on-demand via `toolchain.download("pocket-ic", ...)`), so users never need to know dfx exists. Document the version bump policy. Deprecated with warnings in 2.x via `cli/helpers/deprecate-dfx-replica.ts` (PR #555). **User-visible break**: implicit-dfx benchmark baselines drift on first run because PocketIC and dfx-replica report different instruction/heap counts; call out in release notes and recommend re-recording with `--save`.
 - `mops init` stops fetching "default packages for dfx" — mops manages its own toolchain. (LIN: Doctor overhaul)
 - Drop `mops toolchain init` requirement; env-var setup becomes a hint when `dfx.json` is present. (LIN)
 - Reject `dfx` field in `[package]` (deprecated since 2.7).

cli/CHANGELOG.md

@@ -1,7 +1,7 @@
 # Mops CLI Changelog
 
 ## Next
-- Deprecate the `dfx` replica in `mops bench`. Behavior is unchanged for now — `--replica dfx` still works, and `mops bench` still falls back to `dfx` (or dfx-bundled PocketIC) when no `pocket-ic` version is set in `[toolchain]` — but a warning is printed in those paths, and the `dfx` replica will be removed in a future release. To silence the warning, pin a `pocket-ic` version in `[toolchain]` (e.g. `pocket-ic = "12.0.0"`); `mops bench` already prefers it over `dfx` when both are available. Motivation: `dfx` itself is being deprecated, and PocketIC is the better fit for benchmarks anyway — deterministic, in-process, and no separate background daemon to manage.
+- Deprecate the `dfx` replica in `mops bench`, `mops test --mode replica`, and `mops watch`. Behavior is unchanged for now — `--replica dfx` still works, and the implicit fallback to `dfx` (or dfx-bundled PocketIC) when no `pocket-ic` version is set in `[toolchain]` still works — but a warning is printed in those paths. To silence the warning, run `mops toolchain use pocket-ic` to pin a PocketIC version; the replica resolver already prefers it over `dfx` when both are available. The `dfx` replica (and the `dfx-pocket-ic` fallback) will be removed and the default flipped to PocketIC in mops v3. Motivation: `dfx` itself is being deprecated upstream, and PocketIC is the better fit for benchmarks and replica tests anyway — deterministic, in-process, and no separate background daemon to manage.
 
 - Add `--patch` to `mops update` and `mops outdated` to restrict updates to patch versions only (e.g. `1.2.3 -> 1.2.4`, never `1.2.3 -> 1.3.0`). Mutually exclusive with `--major`. For pre-1.0 packages this matches the default — caret already restricts `0.x.y` to patch updates. Useful for risk-averse upgrades on packages that have hit 1.0+.
 

cli/cli.ts

@@ -413,7 +413,7 @@ program
   .addOption(
     new Option(
       "--replica <replica>",
-      "Which replica to use to run tests in replica mode",
+      "Which replica to use to run tests in replica mode (`dfx` is deprecated; prefer `pocket-ic`)",
     ).choices(["dfx", "pocket-ic"]),
   )
   .option("-w, --watch", "Enable watch mode")

cli/commands/bench.ts

@@ -22,6 +22,7 @@ import { parallel } from "../parallel.js";
 import { absToRel } from "./test/utils.js";
 import { getMocVersion } from "../helpers/get-moc-version.js";
 import { getDfxVersion } from "../helpers/get-dfx-version.js";
+import { warnIfDfxReplica } from "../helpers/deprecate-dfx-replica.js";
 import { getMocPath } from "../helpers/get-moc-path.js";
 import { sources } from "./sources.js";
 import { MOTOKO_GLOB_CONFIG } from "../constants.js";
@@ -98,20 +99,7 @@ export async function bench(
     options.replicaVersion = config.toolchain?.["pocket-ic"] || "";
   }
 
-  if (replicaType === "dfx" || replicaType === "dfx-pocket-ic") {
-    let explicitDfx = optionsArg.replica === "dfx";
-    let usedFallback = replicaType === "dfx-pocket-ic";
-    let lead = explicitDfx
-      ? "`--replica dfx` is deprecated and will be removed in a future release."
-      : usedFallback
-        ? "Falling back to dfx-bundled PocketIC because no `pocket-ic` version is set in `[toolchain]`. This fallback is deprecated and will be removed in a future release."
-        : "`mops bench` is using `dfx` because no `pocket-ic` version is set in `[toolchain]`. The `dfx` replica is deprecated and will be removed in a future release.";
-    console.log(
-      chalk.yellow(
-        `${lead}\nAdd a \`pocket-ic\` version to \`[toolchain]\` in mops.toml (e.g. \`pocket-ic = "12.0.0"\`) to silence this warning.`,
-      ),
-    );
-  }
+  warnIfDfxReplica(replicaType, optionsArg.replica === "dfx");
 
   options.verbose && console.log(options);
 

cli/commands/test/test.ts

@@ -32,6 +32,7 @@ import { toolchain } from "../toolchain/index.js";
 import { Replica } from "../replica.js";
 import { TestMode } from "../../types.js";
 import { getDfxVersion } from "../../helpers/get-dfx-version.js";
+import { warnIfDfxReplica } from "../../helpers/deprecate-dfx-replica.js";
 import { MOTOKO_GLOB_CONFIG, MOTOKO_IGNORE_PATTERNS } from "../../constants.js";
 
 type ReporterName = "verbose" | "files" | "compact" | "silent";
@@ -79,6 +80,8 @@ export async function test(filter = "", options: Partial<TestOptions> = {}) {
     }
   }
 
+  warnIfDfxReplica(replicaType, options.replica === "dfx");
+
   replica.type = replicaType;
   replica.verbose = !!options.verbose;
 

cli/commands/watch/tester.ts

@@ -3,6 +3,10 @@ import { readConfig } from "../../mops.js";
 import { ErrorChecker } from "./error-checker.js";
 import { testWithReporter } from "../test/test.js";
 import { SilentReporter } from "../test/reporters/silent-reporter.js";
+import {
+  warnIfDfxReplica,
+  type ReplicaName,
+} from "../../helpers/deprecate-dfx-replica.js";
 
 export class Tester {
   verbose = false;
@@ -13,6 +17,7 @@ export class Tester {
   aborted = false;
   controller = new AbortController();
   currentRun: Promise<any> | undefined;
+  warnedDfx = false;
 
   constructor({
     verbose,
@@ -53,12 +58,20 @@ export class Tester {
     this.controller = new AbortController();
 
     let config = readConfig();
+    let replicaType: ReplicaName = config.toolchain?.["pocket-ic"]
+      ? "pocket-ic"
+      : "dfx";
+
+    if (!this.warnedDfx) {
+      warnIfDfxReplica(replicaType, false);
+      this.warnedDfx = true;
+    }
 
     this.currentRun = testWithReporter(
       this.reporter,
       "",
       "interpreter",
-      config.toolchain?.["pocket-ic"] ? "pocket-ic" : "dfx",
+      replicaType,
       true,
       this.controller.signal,
     );

cli/helpers/deprecate-dfx-replica.ts

@@ -0,0 +1,26 @@
+import chalk from "chalk";
+
+export type ReplicaName = "dfx" | "pocket-ic" | "dfx-pocket-ic";
+
+// Prints a deprecation warning when `mops bench`/`mops test`/`mops watch`
+// resolves to a dfx-backed replica. Removal is tracked in NEXT-MAJOR.md
+// under "Drop dfx coupling".
+export function warnIfDfxReplica(
+  replicaType: ReplicaName,
+  explicit: boolean,
+): void {
+  if (replicaType !== "dfx" && replicaType !== "dfx-pocket-ic") {
+    return;
+  }
+  let lead =
+    explicit && replicaType === "dfx"
+      ? "`--replica dfx` is deprecated and will be removed in a future release."
+      : replicaType === "dfx-pocket-ic"
+        ? "Falling back to dfx-bundled PocketIC because no `pocket-ic` version is set in `[toolchain]`. This fallback is deprecated and will be removed in a future release."
+        : "Using `dfx` replica because no `pocket-ic` version is set in `[toolchain]`. The `dfx` replica is deprecated and will be removed in a future release.";
+  console.log(
+    chalk.yellow(
+      `${lead}\nRun \`mops toolchain use pocket-ic\` to pin a PocketIC version and silence this warning.`,
+    ),
+  );
+}

docs/docs/cli/4-dev/01-mops-test.md

@@ -71,14 +71,14 @@ You can also specify `wasi` mode for a specific test file by adding the line bel
 
 Which replica to use to run actor tests.
 
-Default `pocket-ic` if `pocket-ic` is specified in `mops.toml` in `[toolchain]` section, otherwise `dfx`.
+Default `pocket-ic` if `pocket-ic` is specified in `mops.toml` in `[toolchain]` section, otherwise `dfx` (deprecated, see below).
 
 Possible values:
-- `dfx` - use `dfx` local replica
-- `pocket-ic` - use [PocketIC](https://pypi.org/project/pocket-ic/) light replica via [pic.js](https://www.npmjs.com/package/@hadronous/pic) wrapper
+- `pocket-ic` - use [PocketIC](https://github.com/dfinity/pocketic) light replica via [pic.js](https://github.com/dfinity/pic-js). Recommended.
+- `dfx` - **deprecated**. Uses `dfx` local replica. Will be removed in a future release. Run `mops toolchain use pocket-ic` to pin a PocketIC version and `mops test` will use it directly.
 
 :::info
-If you run `mops test --replica pocket-ic` AND `pocket-ic` is not specified in `mops.toml` in `[toolchain]` section, Mops will use pocket-ic replica that comes with dfx (`dfx start --pocketic`).
+If you run `mops test --replica pocket-ic` AND `pocket-ic` is not specified in `mops.toml` in `[toolchain]` section, Mops will use pocket-ic replica that comes with dfx (`dfx start --pocketic`). This fallback path is also deprecated.
 :::
 
 ### `--verbose`

docs/docs/cli/4-dev/02-mops-bench.md

@@ -36,7 +36,7 @@ Default `pocket-ic` if `pocket-ic` is specified in `mops.toml` in `[toolchain]`
 
 Possible values:
 - `pocket-ic` - use [PocketIC](https://github.com/dfinity/pocketic) light replica via [pic.js](https://github.com/dfinity/pic-js). Recommended.
-- `dfx` - **deprecated**. Uses `dfx` local replica. Will be removed in a future release. Pin a `pocket-ic` version in `[toolchain]` (e.g. `pocket-ic = "12.0.0"`) and `mops bench` will use it directly.
+- `dfx` - **deprecated**. Uses `dfx` local replica. Will be removed in a future release. Run `mops toolchain use pocket-ic` to pin a PocketIC version and `mops bench` will use it directly.
 
 ### `--gc`