release: v0.2.4 里程碑快照（孤儿提交，无父；树 = dev 68362e5）

本批内容见 CHANGELOG.md 的 0.2.4 段。按 D41 用孤儿快照推 main，保留「公开史只有里程碑」的模型。

crates/cli/tests/adopt_test/cli_surface.rs

@@ -0,0 +1,156 @@
+//! 命令面：help 文案、用法错误、错误码——不碰数据或者只碰「拒绝」那条路。
+//!
+//! 从 `tests/adopt_test.rs` 拆出来只为守 400 行硬线；搬动是纯搬，断言未变。
+
+use crate::support::{parse_json, run_cli, TempDir};
+
+use crate::fixture::foreign_data_root;
+
+/// 运行目录选项的用法错误：一律退出码 1 + `code=usage`（不是内部错误）。
+///
+/// 抓得住：`--isolation custom` 少 `--game-dir` 被默默当成缺省、`shared` 同时给 `--game-dir`
+/// 被静默忽略、未知词被当缺省。
+/// 抓不住：提示文案的措辞（只断言 code 与关键字）。
+#[test]
+fn isolation_option_misuse_is_a_usage_error() {
+    let dir = TempDir::new("adopt-usage");
+    foreign_data_root(dir.path());
+    let cases: Vec<Vec<&str>> = vec![
+        vec!["--isolation", "custom"],
+        vec!["--isolation", "shared", "--game-dir", "C:/tmp/x"],
+        vec!["--isolation", "nope"],
+        vec!["--game-dir", "relative/dir"],
+    ];
+    for extra in cases {
+        let mut args = vec!["instances", "adopt", "1.20.1", "--json", "--data-dir"];
+        let dir_arg = dir.arg();
+        args.push(&dir_arg);
+        args.extend(extra.iter().copied());
+        let (code, stdout, stderr) = run_cli(&args);
+        assert_eq!(code, 1, "args={args:?}\nstdout={stdout}\nstderr={stderr}");
+        let value = parse_json(&stdout);
+        assert_eq!(
+            value["error"]["code"], "usage",
+            "args={args:?} 应是用法错误：{stdout}"
+        );
+    }
+}
+
+/// 不存在的版本 ⇒ `adopt_version_not_found`（不联网、不偷偷装一个）。
+///
+/// 抓得住：不存在的 id 被登记成功。
+/// 抓不住：`versions/` 整个不存在时 `scan` 的空结果（core 侧用例覆盖）。
+#[test]
+fn unknown_version_reports_not_found() {
+    let dir = TempDir::new("adopt-unknown");
+    foreign_data_root(dir.path());
+    let (code, stdout, _) = run_cli(&[
+        "instances",
+        "adopt",
+        "9.9.9",
+        "--json",
+        "--data-dir",
+        &dir.arg(),
+    ]);
+    assert_eq!(code, 1, "{stdout}");
+    assert_eq!(
+        parse_json(&stdout)["error"]["code"],
+        "adopt_version_not_found"
+    );
+}
+
+/// help 里必须有这两条命令（新命令不留「有实现没文档」的状态），且旧命令仍在。
+///
+/// 抓得住：help 漏列 `instances scan` / `instances adopt`（子串断言），或把旧的
+/// `instances launch-args` / `pack import` 弄丢。
+/// 抓不住：帮助文案与真实行为是否一致（那要靠上面的行为用例 + 人读）。
+#[test]
+fn help_lists_the_new_subcommands_next_to_the_old_ones() {
+    let general = unlucky_cli::cli::help::general();
+    for needle in [
+        "instances scan",
+        "instances adopt",
+        "instances list",
+        "install <version>",
+    ] {
+        assert!(general.contains(needle), "总帮助缺 `{needle}`：\n{general}");
+    }
+    let topic = unlucky_cli::cli::help::topic("instances").expect("help instances 存在");
+    for needle in [
+        "instances scan",
+        "instances adopt",
+        "缺省不沿用全局 isolated",
+        "一个字节都不写",
+    ] {
+        assert!(topic.contains(needle), "help instances 缺 `{needle}`");
+    }
+    // 旧的 `per_version` 字面量只在 core 的 `Isolation::parse` 里被兼容，CLI 词表不接受它。
+    let bogus = std::env::temp_dir().join("ull-adopt-help-nonexistent");
+    let bogus = bogus.display().to_string();
+    let args = [
+        "instances",
+        "adopt",
+        "1.20.1",
+        "--isolation",
+        "per_version",
+        "--json",
+        "--data-dir",
+        bogus.as_str(),
+    ];
+    let (code, stdout, _) = run_cli(&args);
+    assert_eq!(code, 1, "`per_version` 不是 CLI 词表：{stdout}");
+}
+
+/// **更高祖先断链**（r2 R2.3 的 CLI 面）：`--data-dir` 指到迁移联接下面的 nested 目录，
+/// 联接目标被搬走后 `instances scan` 必须非零 + 结构化错误，不能 `ok:true / total:0`。
+///
+/// 抓得住：只判 `versions`/游戏根两层（更高层断链会漏，这里会看到 exit0 与 total 0）。
+///
+/// 抓不住：真正的权限不足（EACCES）那一支。
+#[cfg(windows)]
+#[test]
+fn a_dangling_ancestor_is_a_structured_scan_error() {
+    let dir = TempDir::new("scan-ancestor-dangling");
+    let outer = TempDir::new("scan-ancestor-target");
+    let real = outer.path();
+    let game = real.join("nested").join(".minecraft");
+    std::fs::create_dir_all(game.join("versions").join("1.20.1")).expect("建完整版本树");
+    std::fs::write(
+        game.join("versions/1.20.1/1.20.1.json"),
+        br#"{"id":"1.20.1","type":"release","mainClass":"x","libraries":[]}"#,
+    )
+    .expect("写清单");
+    let link = dir.path().join("game-parent-link");
+    let ok = std::process::Command::new("cmd")
+        .args(["/c", "mklink", "/J"])
+        .arg(&link)
+        .arg(real)
+        .output()
+        .is_ok_and(|out| out.status.success());
+    if !ok {
+        eprintln!("[link-guard] 建不出目录联接，跳过祖先断链 CLI 用例");
+        return;
+    }
+    let data_arg = link.join("nested").display().to_string();
+
+    // 断开之前：能扫到 1 个候选。
+    let (code, stdout, stderr) = run_cli(&["instances", "scan", "--json", "--data-dir", &data_arg]);
+    assert_eq!(code, 0, "stdout={stdout} stderr={stderr}");
+    assert_eq!(parse_json(&stdout)["data"]["counts"]["total"], 1);
+
+    // 断开：联接目标改名（入口还在，versions 与游戏根都 NotFound）。
+    let moved = dir.path().join("moved-target");
+    std::fs::rename(real, &moved).expect("移走联接目标");
+
+    let (code, stdout, stderr) = run_cli(&["instances", "scan", "--json", "--data-dir", &data_arg]);
+    assert_eq!(
+        code, 1,
+        "祖先断链必须非零退出：stdout={stdout} stderr={stderr}"
+    );
+    let value = parse_json(&stdout);
+    assert_eq!(value["ok"], false, "{stdout}");
+    assert_eq!(
+        value["error"]["code"], "adopt_versions_unreadable",
+        "{stdout}"
+    );
+}

crates/cli/tests/adopt_test/collision_cases.rs

@@ -0,0 +1,195 @@
+//! 运行目录**碰撞**的 CLI 面：slug 同名 / 大小写不敏感不许让两个实例共用一个目录（复审 r1 的 R1）。
+//!
+//! 从 `tests/adopt_test.rs` 拆出来只为守 400 行硬线；用例体未改。
+
+use std::path::Path;
+
+use crate::support::{parse_json, run_cli, TempDir};
+
+use crate::fixture::foreign_data_root;
+
+/// **slug 碰撞的两个展示名不能绑定同一个物理运行目录**（R1 的 CLI 面）。
+///
+/// 复审 r1 的实跑：`Better MC` 与 `Better-MC` 都成功、两个 UUID、却指向同一个目录，
+/// 随后 `launch --dry-run` 的 `--gameDir` 也是同一个。这条把它钉住。
+///
+/// 抓得住：
+/// - 登记侧不查已有实例占用的目录（两个 `run_dir` 相同，第一条断言红）；
+/// - `launch` 的 `game_dir` 与登记的目录不一致（第三条断言红）。
+///
+/// 抓不住：`pack_dir` 的 slug 规则本身（既有行为，本 mission 不改）。
+#[test]
+fn colliding_slug_names_get_separate_run_dirs() {
+    let dir = TempDir::new("adopt-slug");
+    let root = dir.path();
+    foreign_data_root(root);
+    let dir_arg = dir.arg();
+
+    let first = run_cli(&[
+        "instances",
+        "adopt",
+        "1.20.1",
+        "--name",
+        "Better MC",
+        "--json",
+        "--data-dir",
+        dir_arg.as_str(),
+    ]);
+    assert_eq!(
+        first.0, 0,
+        "第一次登记应成功：stdout={} stderr={}",
+        first.1, first.2
+    );
+    let first = parse_json(&first.1);
+    let second = run_cli(&[
+        "instances",
+        "adopt",
+        "1.20.1",
+        "--name",
+        "Better-MC",
+        "--json",
+        "--data-dir",
+        dir_arg.as_str(),
+    ]);
+    assert_eq!(
+        second.0, 0,
+        "第二次登记应成功：stdout={} stderr={}",
+        second.1, second.2
+    );
+    let second = parse_json(&second.1);
+
+    let first_dir = first["data"]["instance"]["run_dir"]
+        .as_str()
+        .expect("run_dir A")
+        .to_string();
+    let second_dir = second["data"]["instance"]["run_dir"]
+        .as_str()
+        .expect("run_dir B")
+        .to_string();
+    assert_ne!(first_dir, second_dir, "两个实例不许共用运行目录");
+    assert!(
+        Path::new(&first_dir).is_dir() && Path::new(&second_dir).is_dir(),
+        "两个运行目录都要真实存在"
+    );
+
+    // 真启动计划（dry-run）也要分开：两条实例各自的 game_dir 不同。
+    for (value, expect) in [(&first, &first_dir), (&second, &second_dir)] {
+        let id = value["data"]["instance"]["id"]
+            .as_str()
+            .expect("instance id");
+        let args = [
+            "launch",
+            id,
+            "--dry-run",
+            "--json",
+            "--data-dir",
+            dir_arg.as_str(),
+        ];
+        let (code, stdout, stderr) = run_cli(&args);
+        assert_eq!(
+            code, 0,
+            "stdout={stdout}
+stderr={stderr}"
+        );
+        assert_eq!(
+            parse_json(&stdout)["data"]["game_dir"]
+                .as_str()
+                .expect("game_dir"),
+            expect.as_str()
+        );
+    }
+}
+
+/// **Win32 尾点/尾空格**（r2 R2.1 的 CLI 面）：两次登记 + 两条 `launch --dry-run` 不许落到同一物理目录。
+///
+/// 抓得住：认领目录的尾点/尾空格不归一（第二次默认登记仍拿到 `Foo`，`run_dir` 相同断言红）。
+///
+/// 抓不住：`\?\` verbatim 写法（那本来就不折叠，是另一个目录）。
+#[cfg(windows)]
+#[test]
+fn win32_trailing_dot_or_space_claims_do_not_share_a_run_dir() {
+    for suffix in [".", " "] {
+        let dir = TempDir::new("adopt-win32-alias");
+        let root = dir.path();
+        foreign_data_root(root);
+        let dir_arg = dir.arg();
+        let claimed = root
+            .join(".ULL/data/instances")
+            .join(format!("Foo{suffix}"));
+        let claimed_arg = claimed.display().to_string();
+
+        let first = run_cli(&[
+            "instances",
+            "adopt",
+            "1.20.1",
+            "--name",
+            "First",
+            "--isolation",
+            "custom",
+            "--game-dir",
+            claimed_arg.as_str(),
+            "--json",
+            "--data-dir",
+            dir_arg.as_str(),
+        ]);
+        assert_eq!(
+            first.0, 0,
+            "custom 登记应成功：stdout={} stderr={}",
+            first.1, first.2
+        );
+        let first = parse_json(&first.1);
+
+        let second = run_cli(&[
+            "instances",
+            "adopt",
+            "1.20.1",
+            "--name",
+            "Foo",
+            "--json",
+            "--data-dir",
+            dir_arg.as_str(),
+        ]);
+        assert_eq!(
+            second.0, 0,
+            "默认登记应成功：stdout={} stderr={}",
+            second.1, second.2
+        );
+        let second = parse_json(&second.1);
+
+        let first_dir = first["data"]["instance"]["run_dir"]
+            .as_str()
+            .expect("run_dir A")
+            .to_string();
+        let second_dir = second["data"]["instance"]["run_dir"]
+            .as_str()
+            .expect("run_dir B")
+            .to_string();
+        assert_ne!(
+            first_dir, second_dir,
+            "尾点/尾空格别名不许共用运行目录（suffix={suffix:?}）"
+        );
+
+        // 两条启动计划的 --gameDir 也必须分开（argv 已脱敏，比尾段）。
+        for (value, expect) in [(&first, &first_dir), (&second, &second_dir)] {
+            let id = value["data"]["instance"]["id"]
+                .as_str()
+                .expect("instance id");
+            let args = [
+                "launch",
+                id,
+                "--dry-run",
+                "--json",
+                "--data-dir",
+                dir_arg.as_str(),
+            ];
+            let (code, stdout, stderr) = run_cli(&args);
+            assert_eq!(code, 0, "stdout={stdout} stderr={stderr}");
+            let plan = parse_json(&stdout);
+            assert_eq!(
+                plan["data"]["game_dir"].as_str().expect("game_dir"),
+                expect.as_str(),
+                "启动计划必须落在自己的运行目录（suffix={suffix:?}）"
+            );
+        }
+    }
+}

crates/cli/tests/adopt_test/fixture.rs

@@ -0,0 +1,81 @@
+//! CLI 侧夹具：一个「别的启动器铺好了 `.minecraft`」的数据根。
+//!
+//! 快照工具**复用 core 测试那一份**（`crates/core/tests/adopt/snapshot.rs`，全节点：目录/文件/链接
+//! 各记形状与 mtime）。以前 CLI 自己抄了一份 walk，两份都漏了目录节点——复审 r1 的 R5 正是这个洞，
+//! 所以这里直接 `#[path]` 引用同一份源码：判据只有一处，不会再漂。
+
+#[path = "../../../core/tests/adopt/snapshot.rs"]
+mod snapshot;
+
+pub use snapshot::{assert_unchanged, snapshot, snapshot_opt, Node};
+
+use std::path::Path;
+
+/// 造一份「别的启动器已经铺好的」数据根（`<root>/.minecraft` + `<root>/.ULL`）：
+///
+/// | 路径 | 用意 |
+/// | --- | --- |
+/// | `versions/1.20.1/` | 正常版本（清单 + jar），可登记、可 `launch --dry-run` |
+/// | `versions/1.20.1-orphan/` | 缺父版本 ⇒ 不可登记 |
+/// | `libraries/` `assets/` | 恒共享层（登记不该碰） |
+/// | `mods/` `saves/` | 玩家数据（登记不该碰） |
+/// | `launcher_profiles.json` | 别的启动器的元数据（连读都不该读，更不该写） |
+pub fn foreign_data_root(root: &Path) {
+    let minecraft = root.join(".minecraft");
+    let versions = minecraft.join("versions");
+    write_version(&versions, "1.20.1", MANIFEST_OK, true);
+    write_version(&versions, "1.20.1-orphan", MANIFEST_ORPHAN, true);
+    write_file(
+        &minecraft.join("libraries/com/mojang/brigadier/1.0.18/brigadier-1.0.18.jar"),
+        b"library-bytes",
+    );
+    write_file(
+        &minecraft.join("assets/indexes/5.json"),
+        b"{\"objects\":{}}",
+    );
+    write_file(&minecraft.join("mods/jei.jar"), b"mod-bytes");
+    write_file(&minecraft.join("saves/World/level.dat"), b"save-bytes");
+    write_file(
+        &minecraft.join("launcher_profiles.json"),
+        br#"{"profiles":{"1.20.1":{"name":"1.20.1","lastVersionId":"1.20.1"}}}"#,
+    );
+}
+
+fn write_version(versions: &Path, id: &str, manifest: &str, jar: bool) {
+    let dir = versions.join(id);
+    std::fs::create_dir_all(&dir).expect("建版本目录");
+    std::fs::write(dir.join(format!("{id}.json")), manifest.as_bytes()).expect("写清单");
+    if jar {
+        std::fs::write(dir.join(format!("{id}.jar")), b"junk").expect("写 jar");
+    }
+}
+
+fn write_file(path: &Path, bytes: &[u8]) {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).expect("建父目录");
+    }
+    std::fs::write(path, bytes).expect("写文件");
+}
+
+const MANIFEST_OK: &str = r#"{
+  "id": "1.20.1",
+  "type": "release",
+  "mainClass": "net.minecraft.client.main.Main",
+  "assets": "5",
+  "assetIndex": { "id": "5" },
+  "arguments": {
+    "game": ["--username", "${auth_player_name}", "--version", "${version_name}",
+             "--gameDir", "${game_directory}"],
+    "jvm": ["-Djava.library.path=${natives_directory}", "-cp", "${classpath}"]
+  },
+  "libraries": [],
+  "downloads": { "client": { "size": 4, "url": "http://example.invalid/client.jar" } }
+}"#;
+
+const MANIFEST_ORPHAN: &str = r#"{
+  "id": "1.20.1-orphan",
+  "type": "release",
+  "inheritsFrom": "1.20.1-not-on-disk",
+  "mainClass": "net.minecraft.client.main.Main",
+  "libraries": []
+}"#;