From a0523efc69e895f1c37cf0c014b7c3fe62f286e7 Mon Sep 17 00:00:00 2001 From: sunerpy Date: Wed, 26 Aug 2026 20:53:07 +0800 Subject: [PATCH] feat(cli): preview agent skill updates --- README.md | 18 +- crates/codegraph-cli/src/installer/mod.rs | 183 +++++++++- crates/codegraph-cli/src/installer/skill.rs | 358 ++++++++++++++++++-- crates/codegraph-cli/src/installer/types.rs | 34 +- crates/codegraph-cli/src/main.rs | 16 + crates/codegraph-cli/tests/skill_install.rs | 53 +++ docs/cli.md | 22 +- docs/mcp.md | 4 +- docs/readme/README.zh-CN.md | 19 +- skills/codegraph/SKILL.md | 45 +-- 10 files changed, 659 insertions(+), 93 deletions(-) diff --git a/README.md b/README.md index 09627189..8ad2cdc3 100644 --- a/README.md +++ b/README.md @@ -121,8 +121,11 @@ irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/instal # Fallback — build from source (only if you have a Rust toolchain) cargo install --git https://github.com/sunerpy/codegraph-rust codegraph-rs # binary: `codegraph` -codegraph init /path/to/project # create the index DB (.codegraph/) -codegraph index /path/to/project # parse + build the graph +codegraph status /path/to/project --json # inspect index health first +codegraph init /path/to/project # create the first usable index +codegraph sync /path/to/project # ordinary added/changed/deleted files +codegraph index /path/to/project # intentional full rebuild +codegraph index --force /path/to/project # only when diagnostics prescribe it ``` > 中文:优先用上面的一键安装脚本(直接下载预编译二进制,无需 Rust 工具链、无需编译等待); @@ -250,13 +253,16 @@ Beyond wiring the MCP server, CodeGraph can install a `SKILL.md` directly into each agent's skill directory. The skill teaches your agent to use CodeGraph for code research and project onboarding — reach for `codegraph_explore` before grep/read, use `codegraph_node` instead of a plain file read on indexed source, -and run `codegraph init` when no `.codegraph/` index is present yet. +inspect `codegraph status`, run `codegraph init` when no usable index exists, +and use `codegraph sync` for ordinary manual catch-up. ```bash codegraph skill install --yes # install into all detected agents (global) codegraph skill install --target=claude,cursor --yes # explicit list codegraph skill install --target=auto --local # project-local skill dirs -codegraph skill update # refresh skill if unchanged by user +codegraph skill update # show version/+/- summary, then refresh +codegraph skill update --diff # also print the unified content diff +codegraph skill update --dry-run --diff # preview without writing files codegraph skill update --force # overwrite even locally-modified files codegraph skill uninstall --target=claude --yes # remove from one agent codegraph skill status # show state for all detected agents @@ -273,6 +279,10 @@ against the embedded version. An unmodified file is refreshed automatically; a hand-edited file is skipped with a "locally modified" note (pass `--force` to overwrite). A small sidecar file (`.codegraph-skill.json`) records the installed hash so the update check can distinguish "outdated" from "locally modified". +Before writing, update prints the installed-to-embedded version transition and +added/removed line counts. `--diff` adds a deterministic unified diff; +`--dry-run` prints the same preview without changing files. `skill status` also +shows version provenance, for example `outdated (0.40.1 -> 0.47.0)`. Full reference including per-agent skill paths: [`docs/cli.md`](docs/cli.md). diff --git a/crates/codegraph-cli/src/installer/mod.rs b/crates/codegraph-cli/src/installer/mod.rs index 5a2570ac..0ecf5604 100644 --- a/crates/codegraph-cli/src/installer/mod.rs +++ b/crates/codegraph-cli/src/installer/mod.rs @@ -313,12 +313,15 @@ fn uninstall_targets( } /// Options for `codegraph skill `. One arg struct serves all four -/// actions; `yes` is consumed by install/uninstall, `force` by update. +/// actions; `yes` is consumed by install/uninstall, while update consumes +/// `force`, `show_diff`, and `dry_run`. pub struct SkillArgs { pub target: Option, pub location: Option, pub yes: bool, pub force: bool, + pub show_diff: bool, + pub dry_run: bool, } fn resolve_skill_targets( @@ -377,10 +380,76 @@ pub fn run_skill_install(args: SkillArgs) -> Result<()> { Ok(()) } -/// `codegraph skill update`: identical to install, but `--force` (plumbed -/// through [`SkillArgs::force`]) overwrites a locally modified skill. +/// `codegraph skill update`: preview the version transition + line counts, then +/// refresh safe/outdated content. `--diff` adds a unified diff, `--dry-run` +/// suppresses writes, and `--force` overwrites locally modified content. pub fn run_skill_update(args: SkillArgs) -> Result<()> { - run_skill_install(args) + let ctx = context_from_env()?; + let (location, targets) = resolve_skill_targets(&ctx, &args)?; + if targets.is_empty() { + println!("No agent targets selected — nothing to do."); + return Ok(()); + } + + let mut changed_names: Vec<&str> = Vec::new(); + for target in &targets { + let Some(skill_dir) = target.resolved_skill_dir(&ctx, location) else { + println!( + "{}: skills not supported for --location={}", + target.display_name(), + location.as_str() + ); + continue; + }; + let preview = skill::preview_update_for_dir(&skill_dir, args.force); + println!( + "{}", + skill_update_preview_line(target.display_name(), &preview, args.dry_run) + ); + if args.show_diff + && let Some(diff) = preview.unified_diff.as_deref() + { + print!("{diff}"); + } + + if args.dry_run { + if preview.decision == skill::SkillUpdateDecision::Update { + changed_names.push(target.display_name()); + } + continue; + } + + let result = target.install_skill(&ctx, location, args.force); + if result + .files + .iter() + .any(|file| matches!(file.action, FileAction::Created | FileAction::Updated)) + { + changed_names.push(target.display_name()); + } + report_write_result(target.display_name(), &ctx, &result); + } + + if args.dry_run { + if changed_names.is_empty() { + println!("\nDry run: no skill files would change."); + } else { + println!( + "\nDry run: would update the CodeGraph skill for {} agent{}: {}.", + changed_names.len(), + if changed_names.len() > 1 { "s" } else { "" }, + changed_names.join(", ") + ); + } + } else if !changed_names.is_empty() { + println!( + "\nUpdated the CodeGraph skill for {} agent{}: {}.", + changed_names.len(), + if changed_names.len() > 1 { "s" } else { "" }, + changed_names.join(", ") + ); + } + Ok(()) } /// `codegraph skill uninstall`. Removes the installed skill from each resolved @@ -443,7 +512,7 @@ pub fn run_skill_uninstall(args: SkillArgs) -> Result<()> { /// `codegraph skill status`. Prints one line per target: "up to date" / /// "locally modified" / "outdated" / "not installed" / "not supported". pub fn run_skill_status(args: SkillArgs) -> Result<()> { - let _ = (args.yes, args.force); + let _ = (args.yes, args.force, args.show_diff, args.dry_run); let ctx = context_from_env()?; let (location, targets) = resolve_skill_targets(&ctx, &args)?; if targets.is_empty() { @@ -461,7 +530,67 @@ pub fn run_skill_status(args: SkillArgs) -> Result<()> { /// Map a [`SkillStatusReport`] to its single printed line. Extracted so the /// label mapping is unit-testable without filesystem state. fn skill_status_line(report: &SkillStatusReport) -> String { - format!("{}: {}", report.display_name, report.label()) + let current = skill::EMBEDDED_VERSION; + match report.status { + None => format!("{}: not supported", report.display_name), + Some(skill::SkillStatus::NotInstalled) => { + format!( + "{}: not installed (embedded {current})", + report.display_name + ) + } + Some(skill::SkillStatus::UpToDate) => { + format!("{}: up to date ({current})", report.display_name) + } + Some(skill::SkillStatus::Outdated) => format!( + "{}: outdated ({} -> {current})", + report.display_name, + report.installed_version.as_deref().unwrap_or("unknown") + ), + Some(skill::SkillStatus::LocallyModified) => format!( + "{}: locally modified (base {}; embedded {current})", + report.display_name, + report.installed_version.as_deref().unwrap_or("unknown") + ), + } +} + +fn skill_update_preview_line( + display_name: &str, + preview: &skill::SkillUpdatePreview, + dry_run: bool, +) -> String { + let current = skill::EMBEDDED_VERSION; + let change = format!("+{} -{}", preview.added_lines, preview.removed_lines); + let action = if dry_run { "would update" } else { "updating" }; + match (preview.decision, preview.status) { + (skill::SkillUpdateDecision::Unchanged, _) => { + format!("{display_name}: up to date ({current})") + } + (skill::SkillUpdateDecision::LocallyModified, _) => format!( + "{display_name}: locally modified (base {}; embedded {current}; {change}) — skipped; use --force to overwrite", + preview.installed_version.as_deref().unwrap_or("unknown") + ), + (skill::SkillUpdateDecision::Update, skill::SkillStatus::NotInstalled) => { + let action = if dry_run { + "would install" + } else { + "installing" + }; + format!("{display_name}: {action} embedded skill {current} ({change})") + } + (skill::SkillUpdateDecision::Update, skill::SkillStatus::LocallyModified) => format!( + "{display_name}: {action} locally modified skill (base {}; embedded {current}; {change})", + preview.installed_version.as_deref().unwrap_or("unknown") + ), + (skill::SkillUpdateDecision::Update, skill::SkillStatus::UpToDate) => { + format!("{display_name}: {action} {current} -> {current} ({change})") + } + (skill::SkillUpdateDecision::Update, skill::SkillStatus::Outdated) => format!( + "{display_name}: {action} {} -> {current} ({change})", + preview.installed_version.as_deref().unwrap_or("unknown") + ), + } } /// Render the per-file log lines for an install result. Ports the loop in @@ -551,34 +680,48 @@ mod tests { #[test] fn skill_status_line_renders_each_state() { - // Given a supported target reporting each status, Then the line is - // ":