feat: upgrade subcommand — regenerate-lockfile MVP (PR-5a)

crates/deacon/src/cli.rs

@@ -510,6 +510,34 @@ pub enum Commands {
         command: TemplateCommands,
     },
 
+    /// Regenerate (or refresh) the devcontainer lockfile from the currently
+    /// resolved Feature set. Use `--dry-run` to print the lockfile JSON to
+    /// stdout instead of writing to disk.
+    ///
+    /// See `docs/subcommand-specs/upgrade/SPEC.md` for the authoritative behavior.
+    #[cfg(feature = "full")]
+    Upgrade {
+        /// Print the generated lockfile JSON to stdout instead of writing it
+        /// to disk. Spec §2.
+        #[arg(long)]
+        dry_run: bool,
+        /// Docker CLI path. Default `docker`. Spec §2 surface parity only.
+        #[arg(long, default_value = "docker")]
+        docker_path: String,
+        /// Docker Compose CLI path. Default `docker-compose`. Spec §2 surface parity only.
+        #[arg(long, default_value = "docker-compose")]
+        docker_compose_path: String,
+        /// HIDDEN: pin the version of a specific Feature in `devcontainer.json`
+        /// before regenerating the lockfile. Used by Dependabot.
+        /// Must be used with `--target-version`. **Pinning is deferred to PR-5b.**
+        #[arg(long, short = 'f', hide = true)]
+        feature: Option<String>,
+        /// HIDDEN: target version for `--feature`. Must match
+        /// `^\d+(\.\d+(\.\d+)?)?$`. **Pinning is deferred to PR-5b.**
+        #[arg(long, short = 'v', hide = true)]
+        target_version: Option<String>,
+    },
+
     /// Convert an already-running container into a DevContainer by applying
     /// configuration + image metadata, executing lifecycle hooks, and emitting
     /// a JSON snapshot of the resulting configuration.
@@ -1417,6 +1445,28 @@ impl Cli {
                 execute_templates(args).await
             }
             #[cfg(feature = "full")]
+            Some(Commands::Upgrade {
+                dry_run,
+                docker_path,
+                docker_compose_path,
+                feature,
+                target_version,
+            }) => {
+                use crate::commands::upgrade::{execute_upgrade, UpgradeArgs};
+
+                let args = UpgradeArgs {
+                    workspace_folder: self.workspace_folder,
+                    config_path: self.config,
+                    docker_path,
+                    docker_compose_path,
+                    dry_run,
+                    feature,
+                    target_version,
+                };
+
+                execute_upgrade(args).await
+            }
+            #[cfg(feature = "full")]
             Some(Commands::RunUserCommands {
                 skip_post_create,
                 skip_post_attach,

crates/deacon/src/commands/mod.rs

@@ -19,6 +19,8 @@ pub mod shared;
 #[cfg(feature = "full")]
 pub mod templates;
 pub mod up;
+#[cfg(feature = "full")]
+pub mod upgrade;
 
 /// Re-export the UpResult type to preserve the stdout JSON contract for the up command.
 pub use up::UpResult;