Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 14 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 工具链、无需编译等待);
Expand Down Expand Up @@ -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
Expand All @@ -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).

Expand Down
183 changes: 166 additions & 17 deletions crates/codegraph-cli/src/installer/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -313,12 +313,15 @@ fn uninstall_targets(
}

/// Options for `codegraph skill <action>`. 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<String>,
pub location: Option<String>,
pub yes: bool,
pub force: bool,
pub show_diff: bool,
pub dry_run: bool,
}

fn resolve_skill_targets(
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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() {
Expand All @@ -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
Expand Down Expand Up @@ -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
// "<name>: <label>"; an unsupported report yields "not supported".
let supported = |status| SkillStatusReport {
// Given a supported target reporting each status, Then the line carries
// the installed/embedded version context; unsupported stays concise.
let supported = |status, installed_version: Option<&str>| SkillStatusReport {
display_name: "Claude Code",
location: Location::Global,
status: Some(status),
installed_version: installed_version.map(str::to_string),
};
assert_eq!(
skill_status_line(&supported(skill::SkillStatus::UpToDate)),
"Claude Code: up to date"
skill_status_line(&supported(skill::SkillStatus::UpToDate, None)),
format!("Claude Code: up to date ({})", skill::EMBEDDED_VERSION)
);
assert_eq!(
skill_status_line(&supported(skill::SkillStatus::LocallyModified)),
"Claude Code: locally modified"
skill_status_line(&supported(
skill::SkillStatus::LocallyModified,
Some("0.40.1")
)),
format!(
"Claude Code: locally modified (base 0.40.1; embedded {})",
skill::EMBEDDED_VERSION
)
);
assert_eq!(
skill_status_line(&supported(skill::SkillStatus::Outdated)),
"Claude Code: outdated"
skill_status_line(&supported(skill::SkillStatus::Outdated, Some("0.40.1"))),
format!(
"Claude Code: outdated (0.40.1 -> {})",
skill::EMBEDDED_VERSION
)
);
assert_eq!(
skill_status_line(&supported(skill::SkillStatus::NotInstalled)),
"Claude Code: not installed"
skill_status_line(&supported(skill::SkillStatus::NotInstalled, None)),
format!(
"Claude Code: not installed (embedded {})",
skill::EMBEDDED_VERSION
)
);
assert_eq!(
skill_status_line(&SkillStatusReport {
display_name: "Hermes Agent",
location: Location::Local,
status: None,
installed_version: None,
}),
"Hermes Agent: not supported"
);
Expand Down Expand Up @@ -796,20 +939,26 @@ mod tests {
location: Some("global".to_string()),
yes: true,
force: false,
show_diff: false,
dry_run: false,
})
.unwrap();
run_skill_status(SkillArgs {
target: Some("claude".to_string()),
location: Some("global".to_string()),
yes: false,
force: false,
show_diff: false,
dry_run: false,
})
.unwrap();
run_skill_uninstall(SkillArgs {
target: Some("claude".to_string()),
location: Some("global".to_string()),
yes: true,
force: false,
show_diff: false,
dry_run: false,
})
.unwrap();

Expand Down
Loading
Loading