feat: add clean command, make init non-destructive

init no longer deletes existing state. It refuses if the home directory
has contents and directs the user to run `clean` first. config.toml is
preserved across clean by default (--all to remove it). Removes --force
flag from init.

Author: rvagg

.github/workflows/ci.yml

@@ -150,14 +150,14 @@ jobs:
     - name: "EXEC: {Initialize with cached Docker}, DEP: {C-docker-images-cache}"
       if: steps.cache-docker-images.outputs.cache-hit == 'true'
       run: |
-        rm -rf ~/.foc-devnet
+        ./foc-devnet clean --all
         ./foc-devnet init --no-docker-build
 
     # If Docker images are not cached, do full init (downloads YugabyteDB and builds all images)
     - name: "EXEC: {Initialize without cache}, independent"
       if: steps.cache-docker-images.outputs.cache-hit != 'true'
       run: |
-        rm -rf ~/.foc-devnet
+        ./foc-devnet clean --all
         ./foc-devnet init
 
     # CACHE-DOCKER: Build Docker images if not cached

README.md

@@ -50,10 +50,11 @@ cargo run -- init \
     --curio local:/home/user/code/curio \
     --filecoin-services local:/home/user/code/filecoin-services \
     --lotus local:/home/user/code/lotus \
-    --synapse-sdk local:/home/user/code/synapse-sdk \
-    --force
+    --synapse-sdk local:/home/user/code/synapse-sdk
 ```
 
+**Re-initializing?** Run `cargo run -- clean` first to remove existing state. Config is preserved by default; use `--all` to reset it too.
+
 ### Step 2: Build
 
 ```bash
@@ -176,7 +177,7 @@ Bundled with Portainer for browser-based Docker management—no terminal wizardr
 ## 🛠️ Need More?
 
 See **[README_ADVANCED.md](README_ADVANCED.md)** for comprehensive documentation on:
-- **All commands reference** (init, build, start, stop, status, version)
+- **All commands reference** (init, build, start, stop, clean, status, version)
 - **Configuration system** (config.toml structure, parameters, editing)
 - **Complete directory structure** (what's stored where and why)
 - **Resetting and cleanup** (manual cleanup, disk management)

README_ADVANCED.md

@@ -6,9 +6,30 @@ This guide covers advanced usage, internal architecture, and operational details
 
 ## Commands Reference
 
+### `clean`
+Removes foc-devnet state. Preserves `config.toml` by default so it can be reused on next `init`.
+
+```bash
+foc-devnet clean [OPTIONS]
+```
+
+**Options:**
+- `--all` - Also remove `config.toml`
+- `--images` - Also remove cached foc-* Docker images
+
+**Examples:**
+```bash
+foc-devnet clean               # Remove state, preserve config.toml
+foc-devnet clean --all         # Remove everything including config
+foc-devnet clean --images      # Remove state + Docker images
+foc-devnet clean --all --images # Full reset
+```
+
 ### `init`
 Initializes foc-devnet by downloading repositories, building Docker images, and preparing the environment.
 
+Requires a clean home directory. If existing state is present, `init` will refuse and ask you to run `clean` first. If a `config.toml` was preserved across `clean`, it is reused (with any CLI overrides applied on top).
+
 ```bash
 foc-devnet init [OPTIONS]
 ```
@@ -21,7 +42,6 @@ foc-devnet init [OPTIONS]
 - `--yugabyte-url <URL>` - Yugabyte download URL
 - `--yugabyte-archive <PATH>` - Local Yugabyte archive file
 - `--proof-params-dir <PATH>` - Local proof params directory
-- `--force` - Force regeneration of config file. Useful when switching between configurations.
 - `--rand` - Use random mnemonic instead of deterministic one. Use this for unique test scenarios.
 
 **Source Format:**
@@ -35,8 +55,7 @@ foc-devnet init [OPTIONS]
 ```bash
 foc-devnet init \
     --lotus local:/home/user/lotus \
-    --curio gitbranch:pdpv0 \
-    --force
+    --curio gitbranch:pdpv0
 ```
 
 ### `build`
@@ -273,8 +292,8 @@ tag = "synapse-sdk-v0.36.1"
 Defaults are defined in code (see [`src/config.rs`](src/config.rs) `Config::default()`) and written to `config.toml` during `init`. This means:
 
 - **First-time setup:** Running `foc-devnet init` creates `config.toml` with current defaults from code
-- **Updating defaults:** When a new version of `foc-devnet` includes updated defaults (e.g., newer Lotus version), run `foc-devnet init --force` to regenerate `config.toml` with the new defaults
-- **Preserving customizations:** After regenerating, you'll need to reapply any custom settings you had modified
+- **Updating defaults:** When a new version of `foc-devnet` includes updated defaults (e.g., newer Lotus version), run `foc-devnet clean --all` then `foc-devnet init` to regenerate `config.toml` with the new defaults
+- **Preserving config across re-init:** Running `foc-devnet clean` (without `--all`) preserves your `config.toml`, so a subsequent `init` reuses your existing settings
 - **Source of truth:** The code defines what defaults are available; `config.toml` stores your specific configuration
 
 ### Editing Config
@@ -283,8 +302,9 @@ Defaults are defined in code (see [`src/config.rs`](src/config.rs) `Config::defa
 # Edit manually
 vim ~/.foc-devnet/config.toml
 
-# Or use init --force to regenerate
-foc-devnet init --force
+# Or regenerate from defaults
+foc-devnet clean --all
+foc-devnet init
 ```
 
 ---
@@ -475,10 +495,9 @@ cd ~/.foc-devnet/docker/volumes/run-specific
 ls | grep --invert-match "$CURRENT_RUN" | xargs rm -rf
 ```
 
-**Complete nuclear reset (delete EVERYTHING including config):**
+**Complete reset (delete EVERYTHING including config):**
 ```bash
-# This deletes all runs, config, repos, binaries, keys - use with caution!
-rm -rf ~/.foc-devnet
+foc-devnet clean --all --images
 ```
 
 ---
@@ -827,17 +846,15 @@ foc-devnet init \
     --lotus local:/home/user/dev/lotus \
     --curio local:/home/user/dev/curio \
     --filecoin-services local:/home/user/dev/filecoin-services \
-    --synapse-sdk local:/home/user/dev/synapse-sdk \
-    --force
+    --synapse-sdk local:/home/user/dev/synapse-sdk
 ```
 
 **Mixed approach:**
 
 ```bash
 foc-devnet init \
     --lotus gitbranch:master \
-    --curio local:/home/user/dev/curio \
-    --force
+    --curio local:/home/user/dev/curio
 ```
 
 ### Sharing Configuration
@@ -1203,7 +1220,8 @@ docker logs foc-<run-id>-lotus
 docker images | grep foc-lotus
 
 # Rebuild if needed
-foc-devnet init --force
+foc-devnet clean
+foc-devnet init
 ```
 
 ### Build failures

src/cli.rs

@@ -21,6 +21,15 @@ pub enum Commands {
     },
     /// Stop the local cluster
     Stop,
+    /// Remove foc-devnet state. Preserves config.toml unless --all is passed.
+    Clean {
+        /// Also remove config.toml
+        #[arg(long)]
+        all: bool,
+        /// Also remove cached foc-* Docker images
+        #[arg(long)]
+        images: bool,
+    },
     /// Initialize foc-devnet by building and caching Docker images
     Init {
         /// Curio source location (e.g., 'gittag:tag', 'gittag:url:tag', 'gitcommit:commit', 'gitcommit:url:commit', 'gitbranch:branch', 'gitbranch:url:branch', 'local:/path/to/curio')
@@ -41,9 +50,6 @@ pub enum Commands {
         /// Path to local filecoin-proof-params directory to use instead of downloading
         #[arg(long)]
         proof_params_dir: Option<String>,
-        /// Force regeneration of config file even if it exists
-        #[arg(long)]
-        force: bool,
         /// Use random mnemonic instead of deterministic one
         #[arg(long)]
         rand: bool,

src/commands/clean.rs

@@ -0,0 +1,124 @@
+use std::io::ErrorKind;
+use std::process::Command;
+use tracing::{info, warn};
+
+use crate::paths::{foc_devnet_config, foc_devnet_home};
+
+/// Remove foc-devnet state from the home directory.
+///
+/// Preserves config.toml by default so `init` can reuse it. Pass `all` to
+/// remove config.toml too. The directory itself is always preserved to avoid
+/// permission errors when the parent is not user-writable (e.g. a mount point).
+pub fn clean(all: bool, remove_images: bool) -> Result<(), Box<dyn std::error::Error>> {
+    let home_dir = foc_devnet_home();
+    let config_path = foc_devnet_config();
+
+    if !home_dir.exists() {
+        info!("Nothing to clean ({})", home_dir.display());
+        return Ok(());
+    }
+
+    info!("Cleaning {}", home_dir.display());
+    let mut kept_config = false;
+
+    for entry in std::fs::read_dir(&home_dir)? {
+        let entry = entry?;
+        let path = entry.path();
+
+        if !all && path == config_path {
+            kept_config = true;
+            continue;
+        }
+
+        if path.is_dir() {
+            std::fs::remove_dir_all(&path)?;
+        } else {
+            std::fs::remove_file(&path)?;
+        }
+    }
+
+    if kept_config {
+        info!("Preserved config.toml (use --all to remove it too)");
+    }
+
+    info!("Cleaned foc-devnet state");
+
+    if remove_images {
+        clean_docker_images()?;
+    }
+
+    Ok(())
+}
+
+/// Check whether the home directory is ready for init.
+///
+/// Returns true if the directory contains no meaningful state. Ignores
+/// config.toml (preserved by clean for reuse) and the state/ and run/
+/// directories which are created as side effects of the logging and poison
+/// infrastructure before any command runs.
+pub fn is_clean_for_init() -> Result<bool, Box<dyn std::error::Error>> {
+    let home_dir = foc_devnet_home();
+    if !home_dir.exists() {
+        return Ok(true);
+    }
+    let config_path = foc_devnet_config();
+    let state_dir = crate::paths::foc_devnet_state();
+    let runs_dir = crate::paths::foc_devnet_runs();
+    for entry in std::fs::read_dir(&home_dir)? {
+        let path = entry?.path();
+        if path == config_path || path == state_dir || path == runs_dir {
+            continue;
+        }
+        return Ok(false);
+    }
+    Ok(true)
+}
+
+fn docker_not_found_error() -> Box<dyn std::error::Error> {
+    "Docker CLI not found. Install Docker and ensure the 'docker' command is on PATH."
+        .to_string()
+        .into()
+}
+
+fn clean_docker_images() -> Result<(), Box<dyn std::error::Error>> {
+    info!("Removing foc-* Docker images");
+    let output = Command::new("docker")
+        .args(["images", "--format", "{{.Repository}}:{{.Tag}}"])
+        .output()
+        .map_err(|err| match err.kind() {
+            ErrorKind::NotFound => docker_not_found_error(),
+            _ => err.into(),
+        })?;
+
+    if !output.status.success() {
+        warn!("Could not list Docker images (Docker may not be running)");
+        return Ok(());
+    }
+
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let mut removed_count = 0;
+
+    for line in stdout.lines() {
+        if line.starts_with("foc-") {
+            let remove_output = Command::new("docker")
+                .args(["rmi", line])
+                .output()
+                .map_err(|err| match err.kind() {
+                    ErrorKind::NotFound => docker_not_found_error(),
+                    _ => err.into(),
+                })?;
+
+            if remove_output.status.success() {
+                removed_count += 1;
+            }
+        }
+    }
+
+    if removed_count > 0 {
+        info!("Removed {} Docker image(s)", removed_count);
+    } else {
+        info!("No foc-* Docker images found");
+    }
+
+    Ok(())
+}