feat(cli): require --allow-non-empty to scaffold into a non-empty dir

Anthony's call on the open behavioral question: bare iii project init
should error (not warn) when the target dir contains anything other
than hidden dotfiles or iii-managed paths, and require --allow-non-empty
to override.

- New flag: --allow-non-empty on InitArgs.
- New helper: check_directory_state() runs after create_dir_all and
  before scaffolder-core's copy_template (which uses fs::write and
  would otherwise silently overwrite the user's config.yaml/.gitignore).
- Re-init is always allowed: if .iii/project.ini exists, the directory
  is treated as a known iii project and the guard is skipped.
- "Empty enough" rule: hidden dotfiles (.git/, .env.example, etc.) and
  the data/ runtime directory don't count as user content.
- Error message includes a sample of the offending names plus a clear
  fix line ("pass --allow-non-empty …").

Also DRYs the .iii/project.ini parsing per Anthony's review:
read_existing_project_id and resolve_device_id_for_docker now share
read_project_ini_field(root, key).

Tests: 3 new e2e tests
- project_init_errors_on_non_empty_dir_without_override (README.md present)
- project_init_with_allow_non_empty_succeeds (override works, files preserved)
- project_init_into_dir_with_only_hidden_files_succeeds (.git/ alone is fine)

Replaces project_init_does_not_clobber_existing_config which tested the
old (now incorrect) "silent skip-existing" behavior.

Author: guibeira

engine/src/cli/project/mod.rs

@@ -68,6 +68,14 @@ pub struct InitArgs {
     /// Auto-confirm all prompts (non-interactive mode).
     #[arg(short, long)]
     pub yes: bool,
+
+    /// Allow scaffolding into a non-empty directory. Without this flag, init
+    /// errors out if the target dir contains anything other than hidden
+    /// dotfiles (e.g. `.git/`) or iii-managed paths (`.iii/`, `data/`).
+    /// Re-running init in a directory with `.iii/project.ini` is always
+    /// allowed (idempotent re-init).
+    #[arg(long = "allow-non-empty")]
+    pub allow_non_empty: bool,
 }
 
 impl InitArgs {
@@ -131,6 +139,15 @@ async fn run_init(args: InitArgs) -> i32 {
         );
     }
 
+    if let Err(e) = check_directory_state(&root, args.allow_non_empty) {
+        crate::cli::telemetry::send_project_init_failed("non_empty_dir", &e);
+        return print_err(
+            "target directory is not empty",
+            &e,
+            "pass --allow-non-empty to scaffold into an existing project, or pick a different directory",
+        );
+    }
+
     let device_id = iii::workers::telemetry::environment::get_or_create_device_id();
     let project_name = root
         .file_name()
@@ -429,26 +446,28 @@ async fn persist_project_ini(
 }
 
 fn read_existing_project_id(root: &Path) -> Option<String> {
+    read_project_ini_field(root, "project_id")
+}
+
+/// Read a single key from `.iii/project.ini` (flat or `[project]`-prefixed
+/// format), returning `None` when the file is absent, unreadable, or the key
+/// is missing/empty. The format-tolerant parser is shared between
+/// `read_existing_project_id` (used by re-init) and
+/// `resolve_device_id_for_docker` (used by the docker generator).
+fn read_project_ini_field(root: &Path, key: &str) -> Option<String> {
     let path = root.join(".iii").join("project.ini");
     let contents = std::fs::read_to_string(path).ok()?;
+    let prefix = format!("{key}=");
     contents
         .lines()
-        .find_map(|l| l.trim().strip_prefix("project_id="))
+        .find_map(|l| l.trim().strip_prefix(&prefix))
         .map(|v| v.trim().to_string())
         .filter(|v| !v.is_empty())
 }
 
 fn resolve_device_id_for_docker(root: &Path) -> String {
-    let path = root.join(".iii").join("project.ini");
-    let ini_exists = path.exists();
-    let contents = std::fs::read_to_string(&path).ok();
-    let device_id = contents.as_ref().and_then(|s| {
-        s.lines()
-            .find_map(|l| l.trim().strip_prefix("device_id="))
-            .map(|v| v.trim().to_string())
-            .filter(|v| !v.is_empty())
-    });
-    match device_id {
+    let ini_exists = root.join(".iii").join("project.ini").exists();
+    match read_project_ini_field(root, "device_id") {
         Some(id) => id,
         None => {
             if ini_exists {
@@ -488,6 +507,59 @@ fn resolve_root(dir: Option<&str>) -> Result<PathBuf, String> {
     }
 }
 
+/// Reject scaffolding into a non-empty directory unless the user opted in via
+/// `--allow-non-empty`, OR the directory is already an iii project (has
+/// `.iii/project.ini`). Hidden dotfiles (`.git/`, `.gitignore`, etc.) and
+/// the `data/` runtime directory are not considered "non-empty content" —
+/// they're either dev tooling or iii-managed state.
+fn check_directory_state(root: &Path, allow_non_empty: bool) -> Result<(), String> {
+    if !root.exists() {
+        return Ok(());
+    }
+    if !root.is_dir() {
+        return Err(format!("{} exists but is not a directory", root.display()));
+    }
+    // Idempotent re-init: an existing project.ini means we're scaffolding
+    // into a directory we previously initialized. Always allowed.
+    if root.join(".iii").join("project.ini").exists() {
+        return Ok(());
+    }
+    if allow_non_empty {
+        return Ok(());
+    }
+    let entries: Vec<String> = match std::fs::read_dir(root) {
+        Ok(rd) => rd
+            .filter_map(|e| e.ok())
+            .map(|e| e.file_name().to_string_lossy().into_owned())
+            .filter(|name| {
+                // Hidden files/dirs (.git, .env.example, etc.) and iii's
+                // own runtime data directory are not "user content" for
+                // the purpose of this check.
+                !name.starts_with('.') && name != "data"
+            })
+            .collect(),
+        Err(e) => return Err(format!("read {}: {e}", root.display())),
+    };
+    if entries.is_empty() {
+        Ok(())
+    } else {
+        let mut sample = entries.clone();
+        sample.sort();
+        let preview: Vec<String> = sample.iter().take(5).cloned().collect();
+        let suffix = if sample.len() > 5 {
+            format!(", and {} more", sample.len() - 5)
+        } else {
+            String::new()
+        };
+        Err(format!(
+            "{} contains {}{}",
+            root.display(),
+            preview.join(", "),
+            suffix
+        ))
+    }
+}
+
 fn print_err(problem: &str, cause: &str, fix: &str) -> i32 {
     eprintln!("{} {}", "error:".red().bold(), problem);
     eprintln!("  {} {}", "cause:".dimmed(), cause);

engine/tests/project_init_e2e.rs

@@ -206,22 +206,77 @@ fn project_generate_docker_uses_existing_project_ini_device_id() {
 }
 
 #[test]
-fn project_init_does_not_clobber_existing_config() {
+fn project_init_errors_on_non_empty_dir_without_override() {
+    // A pre-existing user file in the target directory should make init
+    // refuse to scaffold (we'd otherwise silently overwrite it via
+    // scaffolder-core's copy_template).
     let dir = tempdir().unwrap();
-    std::fs::write(dir.path().join("config.yaml"), "existing: yes\n").unwrap();
+    std::fs::write(dir.path().join("README.md"), "# my project\n").unwrap();
     let out = iii_bin()
         .args(["project", "init", "--template-dir"])
         .arg(fixtures())
         .arg("--directory")
         .arg(dir.path())
         .output()
         .expect("failed to run iii");
-    assert!(out.status.success());
-    // copy_template uses fs::write which overwrites, so a stale fixture
-    // would clobber. We assert the file is non-empty (the bare template
-    // should always produce something).
-    let cfg = std::fs::read_to_string(dir.path().join("config.yaml")).unwrap();
-    assert!(!cfg.is_empty());
+    assert!(
+        !out.status.success(),
+        "init should refuse a non-empty directory without --allow-non-empty"
+    );
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        stderr.contains("not empty"),
+        "expected non-empty error message:\n{stderr}"
+    );
+    assert!(
+        stderr.contains("--allow-non-empty"),
+        "error should suggest --allow-non-empty:\n{stderr}"
+    );
+    let readme = std::fs::read_to_string(dir.path().join("README.md")).unwrap();
+    assert_eq!(readme, "# my project\n", "user file must be untouched");
+}
+
+#[test]
+fn project_init_with_allow_non_empty_succeeds() {
+    let dir = tempdir().unwrap();
+    std::fs::write(dir.path().join("README.md"), "# my project\n").unwrap();
+    let out = iii_bin()
+        .args(["project", "init", "--allow-non-empty", "--template-dir"])
+        .arg(fixtures())
+        .arg("--directory")
+        .arg(dir.path())
+        .output()
+        .expect("failed to run iii");
+    assert!(
+        out.status.success(),
+        "init --allow-non-empty failed: {}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+    assert!(dir.path().join(".iii").join("project.ini").exists());
+    assert!(dir.path().join("config.yaml").exists());
+    // README.md isn't in the bare template's file list, so the user's copy
+    // is left in place.
+    assert!(dir.path().join("README.md").exists());
+}
+
+#[test]
+fn project_init_into_dir_with_only_hidden_files_succeeds() {
+    // A directory that only contains hidden dotfiles (e.g. a freshly
+    // `git init`'d project) should not trigger the non-empty guard.
+    let dir = tempdir().unwrap();
+    std::fs::create_dir_all(dir.path().join(".git")).unwrap();
+    let out = iii_bin()
+        .args(["project", "init", "--template-dir"])
+        .arg(fixtures())
+        .arg("--directory")
+        .arg(dir.path())
+        .output()
+        .expect("failed to run iii");
+    assert!(
+        out.status.success(),
+        "init in a dir with only .git/ should succeed: {}",
+        String::from_utf8_lossy(&out.stderr)
+    );
 }
 
 #[test]