internal: Rename frozen lockfiles to immutable. (#1098)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: milesj

CHANGELOG.md

@@ -35,7 +35,7 @@
     - Signature files may contain multiple binary signatures, multiple signatures in one armored block, or multiple concatenated armored blocks. Verification succeeds when any signature matches a trusted key.
     - GPG verification streams the artifact from disk in a blocking worker and records only the verified signer fingerprint and artifact SHA256 in lockfiles, instead of the armored public keyring.
 - **Lockfiles**
-  - Added a `--frozen-lockfile` flag to `proto install` (and a `PROTO_FROZEN_LOCKFILE` environment variable) that treats the lockfile as read-only. Versions are resolved from existing lockfile records, and the lockfile is never created, updated, or pruned.
+  - Added an `--immutable-lockfile` flag to `proto install` (and a `PROTO_IMMUTABLE_LOCKFILE` environment variable) that treats the lockfile as read-only. Versions are resolved from existing lockfile records, and the lockfile is never created, updated, or pruned.
     - If a tool being installed has no matching record, the install fails instead of resolving a fresh version, which is useful for reproducible installs in CI.
     - This flag cannot be combined with `--update-lockfile` or `--pin`.
   - Updated `proto pin` and `proto unpin` to always keep the lockfile of the modified config in sync, even when another config (like an environment config) takes precedence for the tool.

crates/cli/src/commands/install.rs

@@ -50,12 +50,12 @@ pub struct InstallArgs {
 
     #[arg(
         long,
-        env = "PROTO_FROZEN_LOCKFILE",
+        env = "PROTO_IMMUTABLE_LOCKFILE",
         group = "lockfile-mode",
         conflicts_with = "pin",
         help = "Error if the lockfile is missing a record or would be modified"
     )]
-    pub frozen_lockfile: bool,
+    pub immutable_lockfile: bool,
 
     #[arg(long, help = "Pin the resolved version to .prototools")]
     pub pin: Option<Option<PinLocation>>,
@@ -174,8 +174,8 @@ pub async fn install_one(
 
     // Don't resolve the version from a lockfile
     spec.resolve_from_lockfile = !args.update_lockfile;
-    spec.update_lockfile = !args.internal && !args.frozen_lockfile;
-    spec.frozen = args.frozen_lockfile;
+    spec.update_lockfile = !args.internal && !args.immutable_lockfile;
+    spec.immutable = args.immutable_lockfile;
 
     // Load config including global versions,
     // so that our requirements can be satisfied
@@ -225,9 +225,9 @@ pub async fn install_one(
     let outcome = result?;
     let tool = workflow.tool;
 
-    // Reconcile lockfiles by removing orphaned records, unless frozen, as
+    // Reconcile lockfiles by removing orphaned records, unless immutable, as
     // pruning would modify the lockfile
-    if !args.internal && !args.frozen_lockfile {
+    if !args.internal && !args.immutable_lockfile {
         Locker::prune_orphaned_records(&session.env)?;
     }
 
@@ -336,8 +336,8 @@ async fn install_all(session: ProtoSession, args: InstallArgs) -> SessionResult
 
         let mut spec = version.clone();
         spec.resolve_from_lockfile = !args.update_lockfile;
-        spec.update_lockfile = !args.internal && !args.frozen_lockfile;
-        spec.frozen = args.frozen_lockfile;
+        spec.update_lockfile = !args.internal && !args.immutable_lockfile;
+        spec.immutable = args.immutable_lockfile;
 
         let tool_context = tool.context.clone();
         let topo_graph = topo_graph.clone();
@@ -448,9 +448,9 @@ async fn install_all(session: ProtoSession, args: InstallArgs) -> SessionResult
 
     workflow_manager.stop_rendering().await?;
 
-    // Reconcile lockfiles by removing orphaned records, unless frozen, as
+    // Reconcile lockfiles by removing orphaned records, unless immutable, as
     // pruning would modify the lockfile
-    if !args.internal && !args.frozen_lockfile {
+    if !args.internal && !args.immutable_lockfile {
         Locker::prune_orphaned_records(&session.env)?;
     }
 

crates/cli/src/commands/run.rs

@@ -446,7 +446,7 @@ pub async fn run(session: ProtoSession, mut args: RunArgs) -> SessionResult {
                         resolve_from_manifest: false,
                         resolve_from_lockfile: false,
                         update_lockfile: false,
-                        frozen: false,
+                        immutable: false,
                     }),
                     ..Default::default()
                 },

crates/cli/tests/install_all_lockfile_test.rs

@@ -320,7 +320,7 @@ version = "4.5.15"
         );
     }
 
-    mod frozen {
+    mod immutable {
         use super::*;
 
         fn create_sandbox() -> ProtoSandbox {
@@ -379,7 +379,7 @@ version = "{version}"
 
             sandbox
                 .run_bin(|cmd| {
-                    cmd.arg("install").arg("--frozen-lockfile");
+                    cmd.arg("install").arg("--immutable-lockfile");
                 })
                 .success();
 
@@ -398,7 +398,7 @@ version = "{version}"
         }
 
         #[test]
-        fn doesnt_prune_orphans_when_frozen() {
+        fn doesnt_prune_orphans_when_immutable() {
             let sandbox = create_sandbox();
             sandbox.create_file(
                 ".protolock",
@@ -413,7 +413,7 @@ version = "{version}"
 
             sandbox
                 .run_bin(|cmd| {
-                    cmd.arg("install").arg("--frozen-lockfile");
+                    cmd.arg("install").arg("--immutable-lockfile");
                 })
                 .success();
 
@@ -433,7 +433,7 @@ version = "{version}"
 
             sandbox
                 .run_bin(|cmd| {
-                    cmd.arg("install").arg("--frozen-lockfile");
+                    cmd.arg("install").arg("--immutable-lockfile");
                 })
                 .failure();
 

crates/cli/tests/install_one_lockfile_test.rs

@@ -1026,7 +1026,7 @@ version = "1.0.0"
         }
     }
 
-    mod frozen {
+    mod immutable {
         use super::*;
 
         fn create_record(spec: &str, version: &str) -> String {
@@ -1053,7 +1053,7 @@ version = "{version}"
                     cmd.arg("install")
                         .arg("protostar")
                         .arg("5.0.0")
-                        .arg("--frozen-lockfile");
+                        .arg("--immutable-lockfile");
                 })
                 .success();
 
@@ -1076,13 +1076,13 @@ version = "{version}"
             let sandbox = create_proto_sandbox("lockfile");
             sandbox.create_file(".protolock", create_record("^5.10", "5.10.10"));
 
-            // 5.10.15 is the latest, but the frozen record pins 5.10.10
+            // 5.10.15 is the latest, but the immutable record pins 5.10.10
             let assert = sandbox
                 .run_bin(|cmd| {
                     cmd.arg("install")
                         .arg("protostar")
                         .arg("^5.10")
-                        .arg("--frozen-lockfile");
+                        .arg("--immutable-lockfile");
                 })
                 .success();
 
@@ -1101,11 +1101,11 @@ version = "{version}"
                     cmd.arg("install")
                         .arg("protostar")
                         .arg("5.0.0")
-                        .arg("--frozen-lockfile");
+                        .arg("--immutable-lockfile");
                 })
                 .failure();
 
-            assert.stderr(predicate::str::contains("Lockfile is frozen"));
+            assert.stderr(predicate::str::contains("Lockfile is immutable"));
 
             // Nothing was written to the lockfile
             assert!(!sandbox.path().join(".protolock").exists());
@@ -1123,11 +1123,11 @@ version = "{version}"
                     cmd.arg("install")
                         .arg("protostar")
                         .arg("5.10.0")
-                        .arg("--frozen-lockfile");
+                        .arg("--immutable-lockfile");
                 })
                 .failure();
 
-            assert.stderr(predicate::str::contains("Lockfile is frozen"));
+            assert.stderr(predicate::str::contains("Lockfile is immutable"));
 
             // And the existing record was left untouched
             let lockfile = ProtoLock::load(sandbox.path().join(".protolock")).unwrap();
@@ -1146,7 +1146,7 @@ version = "{version}"
                     cmd.arg("install")
                         .arg("protostar")
                         .arg("5.0.0")
-                        .arg("--frozen-lockfile")
+                        .arg("--immutable-lockfile")
                         .arg("--update-lockfile");
                 })
                 .failure()
@@ -1162,7 +1162,7 @@ version = "{version}"
                     cmd.arg("install")
                         .arg("protostar")
                         .arg("5.0.0")
-                        .arg("--frozen-lockfile")
+                        .arg("--immutable-lockfile")
                         .arg("--pin");
                 })
                 .failure()

crates/cli/tests/plugins_test.rs

@@ -12,6 +12,7 @@ use starbase_utils::envx;
 use std::env;
 use std::fs;
 use std::path::PathBuf;
+use std::time::Duration;
 
 fn create_empty_proto_sandbox_with_tools(ext: &str) -> ProtoSandbox {
     let sandbox = create_empty_proto_sandbox();
@@ -483,7 +484,12 @@ mod plugins {
 
             sandbox
                 .run_bin(|cmd| {
-                    cmd.arg("install").arg("swift");
+                    // The Swift archive is ~1GB; downloading, verifying, and
+                    // unpacking it can exceed the default sandbox timeout.
+                    // Keep this below nextest's 480s terminate threshold.
+                    cmd.arg("install")
+                        .arg("swift")
+                        .timeout(Duration::from_mins(7));
                 })
                 .success();
 

crates/core/src/flow/lock.rs

@@ -14,17 +14,17 @@ use version_spec::{UnresolvedVersionSpec, VersionSpec};
 //      [x] validate lock record
 //      [x] create lockfile if it does not exist
 //      [x] error if spec/req is not found in lockfile
-//      [x] frozen lockfiles
+//      [x] immutable lockfiles
 //      [x] orphan pruning
 // [x] install one
 //      [x] resolve version from lockfile
 //      [x] validate lock record
-//      [x] frozen lockfiles
+//      [x] immutable lockfiles
 //      [x] orphan pruning
 // [x] install one version
 //      [x] don't resolve version from lockfile
 //      [x] validate lock record
-//      [x] frozen lockfiles
+//      [x] immutable lockfiles
 //      [x] orphan pruning
 // [x] uninstall
 //      [x] remove from lockfile

crates/core/src/flow/lock_error.rs

@@ -46,15 +46,15 @@ pub enum ProtoLockError {
     },
 
     #[diagnostic(
-        code(proto::install::frozen_lockfile),
-        help = "Run `proto install` without `--frozen-lockfile` to populate the lockfile, then commit the changes."
+        code(proto::install::immutable_lockfile),
+        help = "Run `proto install` without `--immutable-lockfile` to populate the lockfile, then commit the changes."
     )]
     #[error(
-        "Lockfile is frozen, but is missing a record for {} {}. The lockfile is either not enabled or out of date.",
+        "Lockfile is immutable, but is missing a record for {} {}. The lockfile is either not enabled or out of date.",
         .tool.style(Style::Id),
         .spec.style(Style::Hash),
     )]
-    FrozenMissingRecord { tool: String, spec: String },
+    ImmutableMissingRecord { tool: String, spec: String },
 
     #[diagnostic(code(proto::install::mismatched_arch))]
     #[error(

crates/core/src/flow/resolve.rs

@@ -145,12 +145,12 @@ impl<'tool> Resolver<'tool> {
                 spec.version_locked = Some(record);
                 candidate = version.to_unresolved_spec();
             }
-            // When frozen, the lockfile is authoritative and must already
+            // When immutable, the lockfile is authoritative and must already
             // contain a record for the requested specification. Resolving a
             // fresh version would require writing to the lockfile, so error
             // instead of silently falling through to remote resolution
-            else if spec.frozen {
-                return Err(ProtoLockError::FrozenMissingRecord {
+            else if spec.immutable {
+                return Err(ProtoLockError::ImmutableMissingRecord {
                     tool: self.tool.get_name().to_owned(),
                     spec: spec.req.to_string(),
                 }

crates/core/src/tool_spec.rs

@@ -27,11 +27,11 @@ pub struct ToolSpec {
     /// Update the lockfile when applicable?
     pub update_lockfile: bool,
 
-    /// Treat the lockfile as frozen (read-only)? When enabled, the version
+    /// Treat the lockfile as immutable (read-only)? When enabled, the version
     /// must resolve from an existing lockfile record, and the lockfile is
     /// never created or modified. If a matching record does not exist, an
     /// error is raised instead of resolving a fresh version.
-    pub frozen: bool,
+    pub immutable: bool,
 }
 
 impl ToolSpec {
@@ -90,7 +90,7 @@ impl Default for ToolSpec {
             resolve_from_lockfile: true,
             resolve_from_manifest: true,
             update_lockfile: true,
-            frozen: false,
+            immutable: false,
         }
     }
 }