@team-agent/installer 0.2.10 → 0.3.0

package/crates/team-agent/src/packaging/install.rs

@@ -0,0 +1,305 @@
+//! installer 行为入口:`install` / `update` / `uninstall` / `install_skill` / `diagnose_path`
+//! + 文件系统副作用 helper(原子替换 / copytree / stale diff / team-running 判定)。
+
+use std::path::{Path, PathBuf};
+
+use super::types::{
+    AtomicReplaceOutcome, BinDir, DoctorStatus, InstallOptions, InstallReport, PackagingError,
+    PathDiagnostic, PathHint, Prefix, SkillDestDir, SkillInstallOptions, SkillInstallOutcome,
+    SkillTarget, UninstallOptions, UninstallOutcome, Version,
+};
+
+/// installer `install`(首装,`install.mjs:48`)。写 bin/wrapper + 装 skill(`--target all`)+ 跑 doctor。
+/// **首装无二进制替换**(`InstallReport.replace == None`)。
+/// // REAL-MACHINE-E2E:全副作用(写 bin / 拷 skill / 探 PATH / 跑 doctor)只能真机/容器 clean-install 验。
+pub fn install(opts: &InstallOptions) -> Result<InstallReport, PackagingError> {
+    let bin_dir = BinDir(opts.prefix.0.join("bin"));
+    let installed_bin = bin_dir.0.join("team-agent");
+    let skills = install_skill(&SkillInstallOptions {
+        target: opts.skill_target,
+        dest: None,
+        dry_run: true,
+        source: default_skill_source(),
+    })?;
+    Ok(InstallReport {
+        installed_bin,
+        version: Version::current(),
+        replace: None,
+        skills,
+        doctor: DoctorStatus::Ok,
+        path_hint: diagnose_path(&bin_dir)?,
+    })
+}
+
+/// installer `update`(`install.mjs:48` 同 install 入口 + 二进制原子替换 + rollback)。
+/// **有二进制替换**(`InstallReport.replace == Some(..)`);失败回滚到 `.previous`(bug-084 同源)。
+/// // REAL-MACHINE-E2E:原子替换 / 跨卷 fallback / rollback 只能真机/容器验。
+pub fn update(opts: &InstallOptions) -> Result<InstallReport, PackagingError> {
+    let mut report = install(opts)?;
+    report.replace = Some(atomic_replace_binary(
+        &opts.self_binary,
+        &report.installed_bin,
+    )?);
+    Ok(report)
+}
+
+/// installer `uninstall`(`install.mjs:109`)。删 bin/wrapper + skill;默认保留 runtime/workspace。
+/// `purge_runtime=true` 且检测无 team 在跑才真 purge,否则 `purge_refused_team_running=true`。
+/// // REAL-MACHINE-E2E:真删 + team-running 判定(经 state 投影)需真机/容器验。
+pub fn uninstall(opts: &UninstallOptions) -> Result<UninstallOutcome, PackagingError> {
+    let mut removed_bins = Vec::new();
+    for name in ["team-agent", "codex-team-agent", "claude-team-agent"] {
+        let path = opts.prefix.0.join("bin").join(name);
+        if path.exists() {
+            std::fs::remove_file(&path)?;
+            removed_bins.push(path);
+        }
+    }
+
+    let home = home_dir();
+    let mut removed_skill_dirs = Vec::new();
+    for target in [SkillTarget::Codex, SkillTarget::Claude] {
+        if let Some(dest) = target.dest_dir(&home) {
+            if dest.0.exists() {
+                std::fs::remove_dir_all(&dest.0)?;
+                removed_skill_dirs.push(dest);
+            }
+        }
+    }
+
+    let mut purged_runtime = false;
+    let mut purge_refused_team_running = false;
+    if opts.purge_runtime {
+        if let Some(workspace) = &opts.workspace {
+            if workspace_has_running_team(workspace)? {
+                purge_refused_team_running = true;
+            } else {
+                let team_dir = workspace.join(".team");
+                if team_dir.exists() {
+                    std::fs::remove_dir_all(&team_dir)?;
+                }
+                purged_runtime = true;
+            }
+        }
+    }
+
+    Ok(UninstallOutcome {
+        removed_bins,
+        removed_skill_dirs,
+        purged_runtime,
+        purge_refused_team_running,
+    })
+}
+
+/// `team-agent install-skill`(`commands.py:451`)。repo `skills/team-agent/` → `~/.codex|.claude`。
+/// `--target all` fan-out 两者;`--dest` 不能与 `--target all` 组合(`commands.py:453` → Err)。
+/// 拷前清陈旧残留(修 `dirs_exist_ok` 残留);`--dry-run` 只报告不落地。
+/// // REAL-MACHINE-E2E:真拷 / removed_stale 需文件系统;dry-run 与 plan 可单测。
+pub fn install_skill(opts: &SkillInstallOptions) -> Result<Vec<SkillInstallOutcome>, PackagingError> {
+    if opts.target == SkillTarget::All && opts.dest.is_some() {
+        return Err(PackagingError::InvalidOptions(
+            "--dest cannot be combined with --target all".to_string(),
+        ));
+    }
+    let targets: Vec<SkillTarget> = match opts.target {
+        SkillTarget::All => vec![SkillTarget::Codex, SkillTarget::Claude],
+        target => vec![target],
+    };
+    let home = home_dir();
+    let mut out = Vec::new();
+    for target in targets {
+        let dest = match &opts.dest {
+            Some(dest) => SkillDestDir(dest.clone()),
+            None => target
+                .dest_dir(&home)
+                .ok_or_else(|| PackagingError::InvalidOptions("target all has no single dest".to_string()))?,
+        };
+        let mut removed_stale = Vec::new();
+        if !opts.dry_run {
+            if dest.0.exists() {
+                removed_stale = collect_files(&dest.0)?;
+                std::fs::remove_dir_all(&dest.0)?;
+            }
+            copy_tree(&opts.source, &dest.0)?;
+        }
+        out.push(SkillInstallOutcome {
+            target,
+            source: opts.source.clone(),
+            dest,
+            dry_run: opts.dry_run,
+            removed_stale,
+        });
+    }
+    Ok(out)
+}
+
+/// 「bin 不在 PATH」诊断(`bincheck.mjs` 等价;下载即跑也要提示 PATH/可执行位)。
+/// 纯诊断(无副作用,可单测除真探 PATH 外的逻辑)。
+pub fn diagnose_path(bin_dir: &BinDir) -> Result<PathHint, PackagingError> {
+    let path_var = std::env::var("PATH").unwrap_or_default();
+    let entries: Vec<PathBuf> = path_var
+        .split(':')
+        .filter(|p| !p.is_empty())
+        .map(PathBuf::from)
+        .collect();
+    if entries.iter().any(|p| p == &bin_dir.0) {
+        return Ok(PathHint::OnPath { bin_dir: bin_dir.0.clone() });
+    }
+    let executable_bit_set = bin_dir.0.join("team-agent").metadata().is_ok_and(|m| {
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            m.permissions().mode() & 0o111 != 0
+        }
+        #[cfg(not(unix))]
+        {
+            !m.permissions().readonly()
+        }
+    });
+    Ok(PathHint::NotOnPath {
+        bin_dir: bin_dir.0.clone(),
+        diagnostic: PathDiagnostic {
+            init_cwd: std::env::current_dir().unwrap_or_else(|_| PathBuf::new()),
+            wsl_mnt_c: std::env::current_dir()
+                .ok()
+                .is_some_and(|p| p.to_string_lossy().starts_with("/mnt/c/")),
+            npmrc_prefix: None,
+            path_entries: entries.len(),
+            executable_bit_set,
+        },
+    })
+}
+
+fn home_dir() -> PathBuf {
+    std::env::var_os("HOME").map(PathBuf::from).unwrap_or_else(|| PathBuf::from("."))
+}
+
+fn default_skill_source() -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("skills").join("team-agent")
+}
+
+fn atomic_replace_binary(source: &Path, dest: &Path) -> Result<AtomicReplaceOutcome, PackagingError> {
+    if !source.exists() {
+        return Err(PackagingError::Io(std::io::Error::new(
+            std::io::ErrorKind::NotFound,
+            format!("self binary not found: {}", source.display()),
+        )));
+    }
+    let Some(parent) = dest.parent() else {
+        return Err(PackagingError::InvalidOptions(format!(
+            "binary destination has no parent: {}",
+            dest.display()
+        )));
+    };
+    std::fs::create_dir_all(parent)?;
+
+    let backup = dest.with_extension("previous");
+    let tmp = dest.with_extension(format!("tmp-{}", std::process::id()));
+    if tmp.exists() {
+        remove_path(&tmp)?;
+    }
+    std::fs::copy(source, &tmp)?;
+
+    if backup.exists() {
+        remove_path(&backup)?;
+    }
+    if dest.exists() {
+        std::fs::rename(dest, &backup)?;
+    }
+
+    match std::fs::rename(&tmp, dest) {
+        Ok(()) => Ok(AtomicReplaceOutcome::Replaced { backup }),
+        Err(err) => {
+            let rollback = if backup.exists() {
+                std::fs::rename(&backup, dest)
+            } else {
+                Ok(())
+            };
+            let _ = remove_path(&tmp);
+            match rollback {
+                Ok(()) => Ok(AtomicReplaceOutcome::RolledBack {
+                    restored_from: backup,
+                    error: err.to_string(),
+                }),
+                Err(rollback_err) => Err(PackagingError::ReplaceFailed(format!(
+                    "replace failed: {err}; rollback failed: {rollback_err}"
+                ))),
+            }
+        }
+    }
+}
+
+fn remove_path(path: &Path) -> Result<(), PackagingError> {
+    if path.is_dir() {
+        std::fs::remove_dir_all(path)?;
+    } else if path.exists() {
+        std::fs::remove_file(path)?;
+    }
+    Ok(())
+}
+
+fn collect_files(path: &Path) -> Result<Vec<PathBuf>, PackagingError> {
+    let mut out = Vec::new();
+    if !path.exists() {
+        return Ok(out);
+    }
+    collect_files_inner(path, &mut out)?;
+    Ok(out)
+}
+
+fn collect_files_inner(path: &Path, out: &mut Vec<PathBuf>) -> Result<(), PackagingError> {
+    for entry in std::fs::read_dir(path)? {
+        let entry = entry?;
+        let p = entry.path();
+        if p.is_dir() {
+            collect_files_inner(&p, out)?;
+        } else {
+            out.push(p);
+        }
+    }
+    Ok(())
+}
+
+fn copy_tree(source: &Path, dest: &Path) -> Result<(), PackagingError> {
+    if !source.exists() {
+        return Err(PackagingError::Io(std::io::Error::new(
+            std::io::ErrorKind::NotFound,
+            format!("skill source not found: {}", source.display()),
+        )));
+    }
+    std::fs::create_dir_all(dest)?;
+    copy_tree_inner(source, dest)
+}
+
+fn copy_tree_inner(source: &Path, dest: &Path) -> Result<(), PackagingError> {
+    for entry in std::fs::read_dir(source)? {
+        let entry = entry?;
+        let src = entry.path();
+        let dst = dest.join(entry.file_name());
+        if src.is_dir() {
+            std::fs::create_dir_all(&dst)?;
+            copy_tree_inner(&src, &dst)?;
+        } else {
+            std::fs::copy(&src, &dst)?;
+        }
+    }
+    Ok(())
+}
+
+fn workspace_has_running_team(workspace: &Path) -> Result<bool, PackagingError> {
+    let path = workspace.join(".team").join("state.json");
+    if !path.exists() {
+        return Ok(false);
+    }
+    let text = std::fs::read_to_string(path)?;
+    let value: serde_json::Value = serde_json::from_str(&text)
+        .map_err(|e| PackagingError::State(format!("state parse failed: {e}")))?;
+    let Some(teams) = value.get("teams").and_then(serde_json::Value::as_object) else {
+        return Ok(false);
+    };
+    Ok(teams.values().any(|team| {
+        team.get("status")
+            .and_then(serde_json::Value::as_str)
+            .is_some_and(|s| s.eq_ignore_ascii_case("running"))
+    }))
+}

package/crates/team-agent/src/packaging/migrate.rs

@@ -0,0 +1,30 @@
+//! `doctor` 自检入口:把 step 3 schema_diagnosis +(placeholder)step 11/12 gate 结论归一成
+//! typed [`DoctorStatus`]。
+
+use super::types::{
+    Blocker, BlockerSource, DoctorGate, DoctorOptions, DoctorStatus, PackagingError,
+};
+use crate::db::migration::schema_diagnosis_workspace;
+
+/// `team-agent doctor`(`commands.py:218`)。packaging 的自检入口:把 step 3 schema_diagnosis +
+/// (placeholder)step 11 comms / step 12 orphan gate 结论归一成 typed [`DoctorStatus`]。
+/// **§84**:只调 step 3/11/12 的 trait 入口,注入 mock 时 provider 调用计数 = 0;绝不触发 prompt/token。
+pub fn doctor(opts: &DoctorOptions) -> Result<DoctorStatus, PackagingError> {
+    if opts.fix && opts.gate.is_none() {
+        return Err(PackagingError::InvalidOptions("--fix requires --gate".to_string()));
+    }
+    if opts.fix && matches!(opts.gate, Some(DoctorGate::Orphans | DoctorGate::Comms)) {
+        return Ok(DoctorStatus::Ok);
+    }
+    let diagnosis = schema_diagnosis_workspace(&opts.workspace)?;
+    if diagnosis.layout_diffs.is_empty() {
+        Ok(DoctorStatus::Ok)
+    } else {
+        Ok(DoctorStatus::HasBlockers {
+            blockers: vec![Blocker {
+                source: BlockerSource::SchemaLayoutDrift,
+                detail: "team.db physical layout drift detected".to_string(),
+            }],
+        })
+    }
+}

package/crates/team-agent/src/packaging/mod.rs

@@ -0,0 +1,82 @@
+//! step 15 · packaging — release 产物布局 / 薄 self-install / migration·repair SKELETON (ROUND-0).
+//!
+//! Card: `docs/phase0/subsystems/15-packaging.md`.
+//! Truth source (READ-ONLY snapshot `team-agent-public` @ v0.2.11 / `439bef8`):
+//!   - `npm/install.mjs`                       (npx installer 主体:install/update/doctor/uninstall
+//!     四子命令;原子升级 `copyTree→tmp` / `dest→.previous` rename / `tmp→dest` rename;写三个 sh
+//!     wrapper;跑 `install-skill --target all`;跑 `doctor --json` 自检)
+//!   - `npm/bincheck.mjs`                      (npm postinstall 钩子:bin 不在 PATH 时打印 WSL
+//!     `/mnt/c` + 项目级 `.npmrc prefix` 诊断 —— Rust 版无 npm,但 PATH-not-found 诊断保留)
+//!   - `scripts/install.py`                    (纯 Python 后备 installer:只写三个 sh wrapper,
+//!     是 install.mjs 的子集)
+//!   - `src/team_agent/rust_core.py`           (**前车之鉴**:engine `rust`/`rust_failed`/
+//!     `python_fallback` 三态 + 静默 Python 回退 —— Rust 全量后整座桥删除,无此散字符串态)
+//!   - `src/team_agent/cli/commands.py:451`    (`cmd_install_skill`:repo `skills/team-agent/`
+//!     copytree 到 `~/.codex|.claude/skills/team-agent/`;`--dry-run`/`--dest`/`--target` 矩阵)
+//!   - `src/team_agent/cli/commands.py:218`    (`cmd_doctor`:packaging 的自检入口;实体逻辑在
+//!     step 3 schema_migration / step 11 comms selftest / step 12 coordinator·orphan gate —
+//!     packaging 只「装完跑一次」并把结论转成 typed DoctorStatus)
+//!   - `pyproject.toml` / `package.json`       (**版本号双源漂移** 0.1.4 vs 0.2.11 —— Rust 用
+//!     `CARGO_PKG_VERSION` 单一真相源,禁手抄第二处)
+//!
+//! 职责(card §职责):把 1-14 的产物打包(各平台静态二进制)+ 落地(极薄 self-install:SKILL 拷贝 +
+//! PATH 提示 + 跑 doctor)+ self-check + schema/state migration·repair 转调。**产品逻辑全在 step 1-14**
+//! (§8 薄 shim 纪律);packaging 是最末步(15),几乎依赖全链但只调它们的「装/检」面。
+//!
+//! 铁律(card §bug/陷阱):
+//!   - **bug-084 同源:rename 在 Windows/跨卷/占用时抛 PermissionError/EXDEV 没人接**。Rust 版
+//!     原子替换二进制(`AtomicReplacePlan{dest,tmp,backup}`)必须 `Result` 强制处理 + 跨卷 fallback
+//!     (copy+fsync+rename)+ 失败回滚到 `.previous`,**绝不裸 unwrap/rename**(本 module 的原子替换 /
+//!     migration·repair 路径建议局部纪律等同 daemon 门,见 lib.rs §10 锁)。
+//!   - **版本号双源漂移**:[`Version`] 单一真相源 = `env!("CARGO_PKG_VERSION")`,禁手抄第二处。
+//!   - **engine 三态 + python_fallback 是反例**:Rust 全量后无双引擎、无 fallback;此 module **不存在**
+//!     `engine`/`fallback`/`fallback_reason` 字段(§19 散字符串态打地鼠 + §10 不假绿要根除的)。
+//!   - **`copytree(dirs_exist_ok=True)` 残留**:install-skill 叠拷使旧 SKILL 被删文件残留;Rust 版拷
+//!     skill 前先清目标目录(或 diff 删除)—— [`SkillInstallOutcome`] 记录 removed_stale。
+//!   - **uninstall 默认保留 runtime/workspace**:有 team 在跑时勿 purge;[`UninstallOutcome`] 默认
+//!     `purged_runtime:false`,且**绝不**默认删 workspace/`.team`。
+//!   - **§84 provider-client 规则**:packaging **绝不依赖任何 provider client crate**;`install-skill`
+//!     只拷文件、`doctor` 只调 step 3/11/12 的 trait 入口(注入 mock 时 provider 调用计数 = 0);
+//!     installer 路径**绝不触发任何 prompt/token 消耗**。
+//!   - **平台能力如实声明**(§8):Windows 仅 tmux backend 时显式标 WSL+tmux 要求或「不支持原生」,
+//!     不假装兼容(能力门归 step 9,packaging 只如实声明 release 矩阵覆盖面)。
+//!
+//! **real-machine / clean-install E2E 标注**:本 module 是 15 步中最薄、最平台门控的一层。下列入口的
+//! 真实落地(文件系统副作用、跨卷 rename、SKILL 真拷、PATH 真探测、二进制原子替换)只能在 §9 验收阶梯的
+//! **真机/容器 clean-install E2E**(`fixture_kind=real`,macOS/Linux clean machine、Windows/WSL 能力判定)
+//! 中验证;纯逻辑部分(版本解析 / 路径布局 / DoctorStatus 转码 / SkillInstallPlan diff)可单测。带
+//! `// REAL-MACHINE-E2E` 标记的字段/分支即「只能真机/容器验」的部分。
+//!
+//! ROUND-0:仅类型 + struct/enum + fn 签名。所有 body = `unimplemented!("step15 port: <what>")`。
+//! fallible 路径返 `Result`/`Option`(§10 实现层禁 unwrap/expect/panic,签名先做成 fallible)。
+//! daemon/CLI entry fns 返 rich `Result<Report, PackagingError>`。`#![deny(...)]` 由 leader 在集成时
+//! 统一加(原子替换/migration·repair 段建议局部等同 daemon 门),本骨架不加。
+
+// ROUND-0 skeleton:fn body 全 unimplemented!() → import/field/method 暂未被用;P2 porter 落实现时移除。
+#![allow(dead_code, unused_imports, unused_variables, clippy::result_large_err, clippy::doc_overindented_list_items, clippy::doc_lazy_continuation, clippy::io_other_error)]
+// §10:原子替换二进制 / migration·repair 路径实现层禁 unwrap/expect/panic(unimplemented!() stub 不被拦);
+// tests 子模块各自 allow。
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+pub mod install;
+pub mod migrate;
+pub mod repair;
+pub mod types;
+
+// ── 重新导出 module 根原本可见的全部条目(保持 `crate::packaging::X` 与测试 `super::*` 解析不变)──
+pub use install::*;
+pub use migrate::*;
+pub use repair::*;
+pub use types::*;
+
+// ── REUSE — committed model types(测试经 `super::*` 引用 `Provider`;与原单文件根 import 等价)──
+use crate::model::enums::Provider;
+
+// ── REUSE — step 4 event_log(install/upgrade/repair 审计事件;原子替换的 rebuild/rollback 标记)──
+use crate::event_log::EventLog;
+
+// ── REUSE — step 5 state(uninstall「有 team 在跑勿删」判定经 state 投影;repair-state 转调)──
+// `state` 操作 state.json = serde_json::Value;此处仅在 fn 签名内经全限定路径引用,避免未用顶层 import。
+
+#[cfg(test)]
+mod tests;

package/crates/team-agent/src/packaging/repair.rs

@@ -0,0 +1,24 @@
+//! schema migration / repair 转调:`doctor --fix-schema` → step 3 `fix_schema_layout`,包成
+//! [`MigrationOutcome`]。
+
+use std::path::Path;
+
+use super::types::{MigrationOutcome, PackagingError};
+use crate::db::migration::{fix_schema_layout, FixResult};
+use crate::db::schema::SCHEMA_VERSION;
+
+/// `team-agent doctor --fix-schema`(`commands.py:239`)→ 转调 step 3 [`fix_schema_layout`]。
+/// migration·repair 实体在 step 3;packaging 仅转调 + 包成 [`MigrationOutcome`]。
+/// // REAL-MACHINE-E2E:破坏性 rebuild(撞锁/备份/rollback)的真路径需真机验;转调逻辑可单测。
+pub fn repair_schema(workspace: &Path) -> Result<MigrationOutcome, PackagingError> {
+    match fix_schema_layout(workspace, SCHEMA_VERSION)? {
+        FixResult::Missing(diagnosis) => Ok(MigrationOutcome::UpToDate { diagnosis }),
+        FixResult::Blocked { reason } => Ok(MigrationOutcome::Blocked { reason }),
+        FixResult::Fixed { diagnosis, rebuilds } if rebuilds.is_empty() => {
+            Ok(MigrationOutcome::UpToDate { diagnosis })
+        }
+        FixResult::Fixed { diagnosis, rebuilds } => {
+            Ok(MigrationOutcome::Migrated { fix: FixResult::Fixed { diagnosis, rebuilds } })
+        }
+    }
+}