Spec: mops deployed command

[Kamirus]

Proposal spec for a new mops deployed command group that produces the committed deployed snapshot (.most + .did) for a Motoko canister.

Why

mops build emits <name>.wasm, <name>.did, <name>.most from one compilation. The wasm is deployed; the other two must be committed as the deployed snapshot:

• .most — consumed by mops check-stable to guard upgrades against state loss; must match what's on-chain.
• .did — a committed record of the deployed interface for icp tooling (@icp-sdk/bindgen, icp canister call) and the repo. Not consumed by mops — placed at the icp-cli team's request.

Today this is copied by hand after deploy; forgetting it means the snapshot drifts from on-chain reality. This enables the in-progress icp-cli Motoko recipe to snapshot both files in its post-install sync phase, reusing the exact artifacts that produced the deployed wasm.

Key decisions

• update, not sync — sync is taken (deps reconciliation) and clashes with icp's sync phase; the action is advancing a snapshot forward.
• Copy-or-error, never regenerate — strictly reuses mops build output so the snapshot can't decouple from the deployed wasm.
• A configurable snapshot directory ([deployed].dir, default deployed/, --dir override) is the only thing that determines output paths. Both .most and .did go to <dir>/<name>.*.
• Decoupled from check-stable.path — mops deployed never reads it. init points [check-stable].path at <dir>/<name>.most so the file update writes is the file check-stable reads. If a user points it elsewhere, update/init warn (no hard coupling).
• The .did is a pure output artifact — mops doesn't consume it; no Candid compat check (check-candid deferred). --no-did opts out.
• The existing candid field is ignored — it's a curated ahead-of-code interface that the build embeds; the snapshot is a generated lags-code record (see spec appendix).
• init configures mops.toml — writes the empty-actor .most baseline and sets check-stable.path to coincide; no .did baseline needed. Flags the whole-file TOML rewrite caveat.
• Canister selection follows mops build/mops check (no arg = all; named = strict). update doesn't require check-stable configured. Multi-canister icp deploys work because icp expands the recipe per canister.

Design proposal only — no implementation. Open questions: directory config surface (global vs per-canister), per-environment snapshots, future check-candid, optional deployed manifest.

  

[github-actions]

Cursor AI review

👍 APPROVE — looks safe to merge

Category	Assessment	Details
Summary	✅	Adds two draft design specs: specs/mops-deployed.md (post-deploy .most snapshot via mops deployed / mops deployed init) and specs/mops-candid.md (curated .did maintenance via mops generate candid). No runtime code changes.
Code Quality	✅	Specs are well-scoped with explicit non-goals, copy-or-error semantics, and a DRY requirement to share moc invocation logic with build.ts.
Consistency	✅	Canister selection, --output defaults, empty-actor baseline, and writeConfig/TOML.stringify caveats match existing CLI patterns (build, check, check-stable, sync).
Security	✅	Local file operations only; no chain reads, no regeneration that could decouple artifacts from deployed wasm.
Tests	✅	Spec-only PR; follow-ups (e.g. candid drift in mops check) are explicitly deferred rather than assumed done.
Maintainability	✅	Clear split between deploy-driven .most and interface-driven .did; open questions and init-as-reserved-name edge case documented.

Verdict

Decision: APPROVE
Risk: Very Low
Reason: This is a documentation-only design proposal with no production code paths changed. The two specs are internally consistent, accurately reference existing CLI behavior, and defer implementation details appropriately.

---

Generated for commit 990dce5