chore: merge main into v3 (2.24.0 release, MOPS_POCKET_IC_URL) - #768
Open
Kamirus wants to merge 8 commits into
Open
chore: merge main into v3 (2.24.0 release, MOPS_POCKET_IC_URL)#768Kamirus wants to merge 8 commits into
Kamirus wants to merge 8 commits into
Conversation
…e` fold (#757) 2.23.0 scoped the moc 1.12.0+ folded upgrade check to canisters with `[migrations]` and a **committed `.most`** baseline. The changelog, [`mops check-stable`'s docs](https://docs.mops.one/cli/dev/mops-check-stable) and [#624](#624) all say `.mo` baselines are unaffected. They are not: `runStableCheck` compiles a `.mo` baseline to a scratch `.most`, then folds anyway. The folded check is stricter — a field the initial actor requires that no migration produces fails as `M0267` instead of warning `M0254` — so anyone with `[migrations]`, a `.mo` baseline and moc 1.12.0+ can find a green `mops check` red after upgrading to 2.23.0, with nothing in the changelog to explain it. ## Before / After An enhanced-migration canister whose chain never produces `d`, `[check-stable] path = "deployed.mo"`, moc 1.12.0: ```console $ # before src/main.mo:9.7-9.8: type error [M0267], initial actor requires field `d` of type Int; not found in the previous version — write a migration that produces it ✗ Stable compatibility check failed for canister 'backend' $ echo $? 1 ``` ```console $ # after ✓ Stable compatibility check passed for canister 'backend' $ echo $? 0 ``` ## Why it evaded the tests Every moc 1.12.0 fixture pairs the fold's two preconditions the way the feature intended. `check-stable/migrations-chain` has `[migrations]` and a `.most` baseline; `check/deployed-compatible` has a `.mo` baseline but no `[migrations]`, so `canUseStableBaselineCheck` is false and it never reaches the second fold. Nothing pinned the one corner where the two cross. `check-stable/mo-baseline-em` does now, and fails with `M0267` on `main` without this change. Worth noting the second fold could not have been fixed with a guard: `if (isOldMostFile && canUseStableBaselineCheck(...))` is the exact condition the earlier fast path already returns on, so the block is unreachable once corrected. It is deleted rather than guarded, and `runFoldedStableCheck` loses its `baselineIsMostFile` parameter — "folded implies committed `.most`" now holds by construction instead of by argument. ## What is unchanged - Committed `.most` baselines keep the fold, the source locations and the stricter `M0267`. That part of 2.23.0 was intended and stays. - `mops check` already gated its own fold on `configuredMost.endsWith(".most")`, so only the `runStableCheck` path it delegates to was wrong. - No docs change: the shipped prose describes this behavior correctly — it is the code that drifted. Also going onto `v3` as part of [#756](#756), which is where the bug was found, so the branches do not diverge. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
`mops build --check-deploy`, replica tests, and benches can talk to an already-running PocketIC server instead of spawning the `[toolchain] pocket-ic` binary. Platforms that keep PocketIC outside the sandbox (gVisor memory) can set one env var; independent mops users are unchanged. Previously the only cleanup for a PocketIC run was killing the process mops had spawned, which took every instance with it. That does not work against a shared server, so mops now always `DELETE`s the instance it created — including on SIGINT — and never stops the remote process. ## Before ```bash mops build --check-deploy # downloads and spawns [toolchain] pocket-ic, then kills that process ``` `--check-deploy` without a pin: ```text PocketIC deployment check requires `pocket-ic` in `[toolchain]`. Run `mops toolchain use pocket-ic 15.0.0` to pin it. ``` ## After ```bash export MOPS_POCKET_IC_URL="http://127.0.0.1:8001" mops build --check-deploy # POST /instances on that server, install Wasm, DELETE the instance; server stays up ``` A pin is no longer required when the env var is set. If both are set, the pin is ignored and mops warns once: ```text `MOPS_POCKET_IC_URL` is set; the `pocket-ic` pin (15.0.0) in `[toolchain]` is ignored for this run. Unset `MOPS_POCKET_IC_URL` to use the pinned binary. ``` Applies to every mops-managed PocketIC path (`build --check-deploy`, `test --mode replica`, `bench`, `watch`). `--replica dfx` is unchanged. The URL must be `http`/`https` and must speak the PocketIC control API, not the IC HTTP gateway. ## What is unchanged Auth, isolation, and spawning PocketIC itself stay with the caller (e.g. a Caffeine proxy). Mops does not health-check or lazily start the server; the first `POST /instances` is the request the proxy can key off. Made with [Cursor](https://cursor.com) --------- Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Readers of the 2.x docs at the docs.mops.one site root never saw the features shipped in CLI 2.21.0–2.23.0: `grep -rn "check-deploy" docs/versioned_docs/version-2.x/` had zero hits even though `mops build --check-deploy` shipped in 2.21.0. The versioned tree was treated as a frozen snapshot while every feature doc landed only in `docs/docs/` — per the amended "Keep docs in sync" rule, features shipping in a 2.x release belong in both trees. This replays the `docs/docs/` diffs of each 2.21.0–2.23.0 feature into `docs/versioned_docs/version-2.x/`, wording identical: - [#696](#696) — `mops self update` major-version confirmation and `--major` - [#644](#644) — `mops build --check-wasm` / `--check-deploy`, `[build].check-wasm` / `check-deploy`, and `wasmMemoryLimit` in the config reference - [#713](#713) / [#714](#714) — `mops.lock` `graph` section and hash carry-over - [#624](#624) — check/check-stable/migrate diagnostics on moc 1.12.0+ - [#754](#754) — `pocket-ic 15.0.0` recommendation (6 pages) After the replay, `diff -r docs/docs docs/versioned_docs/version-2.x` is empty, so the sync state is trivially checkable. `docusaurus build` passes (links and anchors resolve in both trees). ## What is unchanged - `MOPS_POCKET_IC_URL` on the environment-variables page — already mirrored by [#761](#761). - 2.21.0–2.23.0 changelog entries with no `docs/docs/` counterpart (the unzipper security fix, atomic lock writes, the ENOENT cache-state fixes, the executable-bit and moc-wrapper fixes) — nothing to port; if any deserve docs, that's a change to make in `docs/docs/` first. ## Follow-up worth flagging The docs site deploys from the `v3` branch only, so this has no effect on the live site until it is synced there. `v3`'s `docs/versioned_docs/version-2.x/` is currently identical to pre-backfill `main`, so the sync is exactly this patch — follow-up PR to `v3` incoming. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Release CLI v2.24.0. Prepared by the [Prepare CLI release](https://github.com/caffeinelabs/mops/actions/workflows/prepare-cli-release.yml) workflow. Approve this PR when CI is green — auto-merge is enabled. Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Release artifacts generated by CI for CLI v2.24.0. Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
The 2.x CLI docs contradicted actual CLI behavior in nine places —
missing test/bench discovery rules, an undocumented test mode,
undocumented flags and environment variables, and stale toolchain
versions. Each defect was found by the v3 docs audit (branch
`kamil-claude/v3-sync-2x-docs`) and re-verified here against the 2.x
source (`cli/cli.ts`, `cli/commands/**`) before porting, since 2.x
behavior sometimes differs from v3.
## What was wrong
- **mops test**: the mode list omitted `replica` (the CLI accepts
`interpreter|wasi|replica`); the `// @testmode` block showed only `wasi`
and claimed the marker must be the first line — it is an exact full-line
match anywhere in the file (`lines.includes(...)` in `test/test.ts`);
"Make sure your actor doesn't have a name" contradicts the detection
regex `/^(persistent )?actor( class)?/`, which matches named actors too;
discovery was described as "test/*.test.mo" but is
`**/test?(s)/**/*.test.mo` with a `test/lib.mo` short-circuit and a
`[filter]` that widens the glob to `*<filter>*.mo`.
- **mops bench**: discovery is `**/bench?(mark)/**/*.bench.mo` with the
same filter widening — the page said only "bench/*.bench.mo".
- **mops owner / maintainer**: `--yes` undocumented.
- **mops user import**: `--no-encrypt` undocumented.
- **Environment variables**: `MOPS_ENV` (expands `{MOPS_ENV}` in path
dependencies, defaults to `local`) and `MOPS_CWD` (chdir before the
command runs, for npm scripts) undocumented.
- **mops docs generate**: the `-o` short alias undocumented.
- **mops toolchain info / update**: both accept `wasm-opt` (it is in
`TOOLCHAINS`), and `update <tool>` errors when the tool is not pinned in
`[toolchain]` — verified in `commands/toolchain/index.ts`. The pages
implied a four-tool list and unconditional updates.
- **mops build**: the "Each canister configuration supports" list
omitted `wasmMemoryLimit` (used in an example on the same page) and the
`migrations`/`check-stable` subtables.
- **Toolchain overview / use**: stale example versions `moc 0.10.3` /
`wasmtime 16.0.0` (and `pocket-ic 1.0.0` in `use`) → `1.0.0` / `41.0.0`
/ `15.0.0`, matching `09-mops.toml.md`.
## Deviations from the v3 wording
- The `replica` mode bullet is worded replica-neutrally — 2.x still has
the deprecated dfx path selected via `--replica`, so the v3 "PocketIC
replica" phrasing would be wrong here.
- The v3 `MOPS_ENV` note about lockfile staleness is not ported — it
describes v3-only lockfile behavior and links a v3-only anchor.
- The v3 missing-blank-line fix in mops-build does not apply — 2.x has
no `--locked` section on that page and the blank line is already
present.
## Tree sync
`docs/docs/` and `docs/versioned_docs/version-2.x/` must be
byte-identical (AGENTS.md). Besides applying every fix to both trees,
this also carries
[#761](#761
`MOPS_POCKET_IC_URL` wording into `versioned_docs` (`09-mops.toml.md`,
`cli/4-dev/03-mops-build.md`), where it had only landed in `docs/docs/`.
`diff -r docs/docs docs/versioned_docs/version-2.x` is now empty, and
`cd docs && npm run build` passes (Docusaurus validates links and
anchors).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
Cursor AI review👍 APPROVE — looks safe to merge
VerdictDecision: APPROVE Generated for commit 0834cb6 |
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
automation-sa-sre
approved these changes
Aug 15, 2026
automation-sa-sre
left a comment
automation-sa-sre
left a comment
There was a problem hiding this comment.
Automated approval: the AI review verdict for 0834cb6 is APPROVE. See the "Cursor AI review" comment for details.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Brings
mainup to 2.24.0 into the v3 line: theMOPS_POCKET_IC_URLattach mode, the 2.21.0–2.23.0 docs backfill, the 2.x port of the v3 docs audit, and the 2.24.0 release/cli-releasesartifacts.Merge this with a merge commit, not squash — it is a
main→v3sync and must keep both parents.MOPS_POCKET_IC_URL on v3
Every mops-managed PocketIC path (
build --check-deploy, replica tests,mops bench,mops watch, the tests/benchesmops publishruns) can now attach to an already-running PocketIC server instead of spawning the[toolchain] pocket-icbinary. The port is rewritten for v3 semantics — v3 has no dfx replica and no legacypic-icclient, so the feature lands as: pin required as before,MOPS_POCKET_IC_URLis the one alternative source, and a pin is ignored with a warning when the URL is set.Resolution choices a reviewer should check:
startPocketIckeeps v3's single-client shape (noclient: "dfinity"overloads, noAnyPocketIcunions) and gains main's thunked options — in attached modetoolchain.bin("pocket-ic")is never resolved, so no binary is downloaded and no pin is needed.assertMinimumVersionat download,toolchain.binerroring on a missing pin), so main's early-validation block inbuild.tsstays deleted; the attached-mode gate makes it moot there anyway. The--check-deploy requires a PocketIC pintest still asserts v3's error text.mops testkeeps no--replicaflag; main's SIGINT bounded-teardown and settled-start error surfacing are ported (viacliErrorFrom), the dfx branches are not.mops benchrecords noreplicaVersionin attached mode (ported at the options default, since v3 has no replica-type dispatch).--check-deploy warns when MOPS_POCKET_IC_URL ignores a pintest moved intobuild-check-deploy.test.ts, which owns thebuild/check-deployfixture on v3 (it does not exist on main); the twobuild/success-based URL tests stayed inbuild.test.ts.What was deliberately not taken
.mo-baseline fast-path fix (9de549d2) and itsmo-baseline-emfixture: v3 rejects.mocheck-stable baselines outright (#758), so there is no 3-step path to keep them on. The 2.24.0 changelog entry is kept as the historical record.--replica,dfx-pocket-ic, deprecation warnings) — gone on v3, stays gone.Docs, per the AGENTS.md merge rules
docs/versioned_docs/version-2.x/is byte-identical tomain(verified withgit diff origin/main -- docs/versioned_docs/→ empty).docs/docs/keeps v3's pages; the only delta vs v3 is the new-feature copy rewritten in v3 terms (pin required unlessMOPS_POCKET_IC_URLis set, no dfx mentions — main's "--replica dfxis unaffected" line is dropped from the env-vars page).docs/docusaurus.config.jskeepslastVersion: '2.x';release.ymlkeeps the docs deploy step.Verified
tsc --noEmitclean, ESLint clean, and the merge-adjacent Jest suites pass locally (109 tests acrosspocket-ic-client,pocket-ic,check-stable,bench,build,build-check-deploy,cli,vendor-pic,test-reporter,publish-dry-run). CI runs the full matrix.🤖 Generated with Claude Code