feat: auto-create mops.lock on first install (#457)

## Summary

- `mops.lock` is now created automatically on the first run of any
dependency command — no manual opt-in required
- On first creation, a one-time hint is printed recommending that
**applications** commit the file and **library authors** add it to
`.gitignore` (same convention as Cargo)
- Subsequent runs are idempotent — the hint does not repeat and no
unnecessary writes occur

## Motivation

Previously users had to run `mops i --lock update` once to bootstrap the
lock file. This is inconsistent with every major package manager (npm,
yarn, pnpm, Cargo, Bundler, Poetry) and meant most projects silently
missed the reproducibility and integrity benefits of `mops.lock`.

## Changes

- **`cli/integrity.ts`**: Collapse two-branch guard in `checkIntegrity`
to a single ternary — non-CI now always defaults to `"update"`; add
first-creation message in `updateLockFile`
- **`cli/tests/cli.test.ts`**: Integration tests for auto-creation,
idempotency, and `--lock ignore` opt-out; unset `CI` env to simulate
local behavior
- **`cli/tests/helpers.ts`**: Add `env` override field to `CliOptions`
to allow unsetting env vars in tests
- **`cli/tests/install/success/mops.toml`**: Dedicated fixture — avoids
race condition with `build.test.ts` which uses `build/success` in
parallel
- **`docs/docs/10-mops.lock.md`**: Rewrote — removed "disabled by
default" notice, added Libraries vs Applications guidance (Cargo-style),
added CI section, fixed "Opting out" to list only commands that accept
`--lock`
- **`cli/CHANGELOG.md`**: Entry under `## Next`

## Behavior preserved

- `--lock ignore` still fully bypasses creation on any command
- CI (`CI=1`) still defaults to `"check"` and silently skips if no lock
file exists
- All internal `silent: true` / `lock: "ignore"` call sites are
unaffected

## How to test

```bash
# First install creates the lock file
rm -f mops.lock && mops install
# Prints: "mops.lock created.  Applications: commit this file.  Libraries: add mops.lock to .gitignore."

# Second install is silent — no duplicate hint
mops install

# Opt-out works
rm -f mops.lock && mops install --lock ignore
# mops.lock does NOT exist
```

Author: Kamirus

cli/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Next
 
+- `mops.lock` is now created automatically the first time dependencies are installed — no need to run `mops i --lock update` once to opt in. Triggered by `mops install`, `mops add`, `mops remove`, `mops update`, `mops sync`, and `mops init` (when it installs dependencies). Applications should commit `mops.lock`; library authors should add it to `.gitignore`.
+
 ## 2.7.0
 
 - `mops publish` no longer requires a `repository` field — it is now optional metadata (used by the registry UI for source links)

cli/integrity.ts

@@ -36,16 +36,8 @@ type LockFile = LockFileV1 | LockFileV2 | LockFileV3;
 export async function checkIntegrity(lock?: "check" | "update" | "ignore") {
   let force = !!lock;
 
-  if (
-    !lock &&
-    !process.env["CI"] &&
-    fs.existsSync(path.join(getRootDir(), "mops.lock"))
-  ) {
-    lock = "update";
-  }
-
   if (!lock) {
-    lock = process.env["CI"] ? "check" : "ignore";
+    lock = process.env["CI"] ? "check" : "update";
   }
 
   if (lock === "update") {
@@ -197,7 +189,13 @@ export async function updateLockFile() {
 
   let rootDir = getRootDir();
   let lockFile = path.join(rootDir, "mops.lock");
+  let isNew = !fs.existsSync(lockFile);
   fs.writeFileSync(lockFile, JSON.stringify(lockFileJson, null, 2));
+  if (isNew) {
+    console.log("mops.lock created.");
+    console.log("  Applications: commit this file.");
+    console.log("  Libraries: add mops.lock to .gitignore.");
+  }
 }
 
 // compare hashes of local files with hashes from the lock file

cli/tests/cli.test.ts

@@ -1,4 +1,6 @@
-import { describe, expect, test } from "@jest/globals";
+import { describe, expect, jest, test } from "@jest/globals";
+import { existsSync, rmSync } from "node:fs";
+import path from "path";
 import { cli } from "./helpers";
 
 describe("cli", () => {
@@ -10,3 +12,63 @@ describe("cli", () => {
     expect((await cli(["--help"])).stdout).toMatch(/^Usage: mops/m);
   });
 });
+
+describe("install", () => {
+  jest.setTimeout(120_000);
+
+  test("creates mops.lock automatically on first install", async () => {
+    const cwd = path.join(import.meta.dirname, "install/success");
+    const lockFile = path.join(cwd, "mops.lock");
+    rmSync(lockFile, { force: true });
+    try {
+      // Unset CI so checkIntegrity uses the local default ("update")
+      const result = await cli(["install"], { cwd, env: { CI: undefined } });
+      expect(result.exitCode).toBe(0);
+      expect(existsSync(lockFile)).toBe(true);
+      expect(result.stdout).toMatch(/mops\.lock created/);
+    } finally {
+      rmSync(lockFile, { force: true });
+      rmSync(path.join(cwd, ".mops"), { recursive: true, force: true });
+    }
+  });
+
+  test("does not print 'mops.lock created' on subsequent installs", async () => {
+    const cwd = path.join(import.meta.dirname, "install/success");
+    const lockFile = path.join(cwd, "mops.lock");
+    rmSync(lockFile, { force: true });
+    try {
+      // Unset CI so checkIntegrity uses the local default ("update")
+      const first = await cli(["install"], { cwd, env: { CI: undefined } });
+      expect(first.exitCode).toBe(0);
+      expect(first.stdout).toMatch(/mops\.lock created/);
+      const result = await cli(["install"], { cwd, env: { CI: undefined } });
+      expect(result.exitCode).toBe(0);
+      expect(existsSync(lockFile)).toBe(true);
+      expect(result.stdout).not.toMatch(/mops\.lock created/);
+    } finally {
+      rmSync(lockFile, { force: true });
+      rmSync(path.join(cwd, ".mops"), { recursive: true, force: true });
+    }
+  });
+
+  test("does not create mops.lock when --lock ignore is passed", async () => {
+    const cwd = path.join(import.meta.dirname, "install/success");
+    const lockFile = path.join(cwd, "mops.lock");
+    rmSync(lockFile, { force: true });
+    try {
+      // Unset CI for consistency; --lock ignore bypasses auto-detection regardless
+      const result = await cli(["install", "--lock", "ignore"], {
+        cwd,
+        env: { CI: undefined },
+      });
+      expect(result.exitCode).toBe(0);
+      expect(existsSync(lockFile)).toBe(false);
+    } finally {
+      rmSync(lockFile, { force: true });
+      rmSync(path.join(cwd, ".mops"), { recursive: true, force: true });
+    }
+  });
+
+  // mops add/remove/update/sync are not separately tested here because they
+  // all route through the same checkIntegrity code path tested above.
+});

cli/tests/helpers.ts

@@ -5,19 +5,20 @@ import { fileURLToPath } from "url";
 
 export interface CliOptions {
   cwd?: string;
+  env?: Record<string, string | undefined>;
 }
 
 // When MOPS_TEST_GLOBAL is set, invoke the globally-installed `mops` binary
 // directly rather than the npm script. This exercises the real global-install
 // code path where the binary lives outside the project tree.
 const useGlobalBinary = Boolean(process.env.MOPS_TEST_GLOBAL);
 
-export const cli = async (args: string[], { cwd }: CliOptions = {}) => {
+export const cli = async (args: string[], { cwd, env }: CliOptions = {}) => {
   const [cmd, cmdArgs] = useGlobalBinary
     ? ["mops", args]
     : ["npm", ["run", "--silent", "mops", "--", ...args]];
   return await execa(cmd, cmdArgs, {
-    env: { ...process.env, ...(cwd != null && { MOPS_CWD: cwd }) },
+    env: { ...process.env, ...(cwd != null && { MOPS_CWD: cwd }), ...env },
     ...(cwd != null && { cwd }),
     stdio: "pipe",
     reject: false,

cli/tests/install/success/mops.toml

@@ -0,0 +1,2 @@
+[dependencies]
+core = "1.0.0"

docs/docs/10-mops.lock.md

@@ -5,30 +5,54 @@ sidebar_label: mops.lock
 
 # `mops.lock` file
 
-:::info
-Currently lockfile is disabled by default. You can enable it by running `mops i --lock update` once.
+`mops.lock` is used to ensure integrity of dependencies, so that you can be sure that all dependencies have exactly the same source code as they had when the package author published them to the Mops Registry.
 
-When `mops.lock` file exists, no need to specify `--lock` flag.
-:::
+`mops.lock` is created automatically the first time dependencies are installed, and kept up to date on every subsequent run. It is triggered by:
+- `mops install`
+- `mops add`
+- `mops remove`
+- `mops update`
+- `mops sync`
+- `mops init` (when it installs dependencies)
 
-`mops.lock` is used to ensure integrity of dependencies, so that you can be sure that all dependencies have exactly the same source code as they had when the package author published them to the Mops Registry.
+`mops.lock` is maintained by Mops and should not be manually edited.
+
+## Should you commit `mops.lock`?
+
+The answer depends on whether your project is an **application** or a **library**.
+
+**Applications** (canisters, scripts, frontends) — commit `mops.lock`. It guarantees that every developer and CI environment installs the exact same dependency versions.
+
+**Libraries** (packages published to the Mops registry) — add `mops.lock` to `.gitignore`. Your library will be used as a dependency inside other projects, and those projects will resolve their own dependency graph. Committing your lock file could mislead contributors into thinking the locked versions are significant.
 
-A valid `mops.lock` speeds up `mops install` command because it avoids downloading intermediate versions of dependencies.
+```bash
+# .gitignore entry for library authors
+mops.lock
+```
 
-_It's only faster when there are no global cached packages. For example you are running `mops install` inside a fresh Docker container. Or when you call `mops install` for the first time in a project._
+This is the same convention used by [Cargo](https://doc.rust-lang.org/cargo/faq.html#why-do-binaries-have-cargolock-in-version-control-but-not-libraries).
 
-`mops.lock` contains the following information:
-- Hash of `[dependencies]` and `[dev-dependencies]` section of `mops.toml` file
+## Performance
+
+A valid `mops.lock` speeds up `mops install` because it avoids resolving intermediate dependency versions.
+
+_It's only faster when there are no globally cached packages — for example when running `mops install` inside a fresh Docker container or for the first time in a project._
+
+## What `mops.lock` contains
+
+- Hash of the `[dependencies]` and `[dev-dependencies]` sections of `mops.toml`
 - All transitive dependencies with the final resolved versions
-- Hash of each file of each dependency
+- Hash of each file of each dependency (retrieved from the Mops registry canister)
 
-File hashes are retrieved from the mops registry canister.
+## CI environments
 
-When `mops.lock` exists, it is updated(and checked) automatically when you run any of the following commands:
-- `mops add`
-- `mops remove`
-- `mops install`
-- `mops update`
-- `mops sync`
+In CI, if `mops.lock` does not exist, integrity checking is skipped and no lock file is created. To enforce the lock in CI, commit `mops.lock` to your repository before running CI.
+
+## Opting out
+
+To skip lock file creation and checks for a single run, pass `--lock ignore` to `mops install`, `mops add`, `mops remove`, `mops update`, or `mops sync`:
 
-`mops.lock` maintained by Mops and should not be manually edited.
+```bash
+mops install --lock ignore
+mops add <package> --lock ignore
+```