diff --git a/README.md b/README.md index e910d853..623bda19 100644 --- a/README.md +++ b/README.md @@ -109,8 +109,8 @@ codegraph serve --mcp --path /path/to/project # optional: pin to a specific pro ``` Auto-register it into your agent's config (Claude Code, Cursor, Codex CLI, -opencode, Hermes, Gemini CLI, Antigravity, Kiro, Trae, Qoder, Zed, VS Code, -Copilot CLI, JetBrains): +opencode, Hermes, Gemini CLI, Antigravity, Kiro, Trae, Qoder, Zed, Zuno, +VS Code, Copilot CLI, JetBrains): ```bash codegraph install --yes # detects installed agents and wires them up @@ -204,8 +204,8 @@ directory or `rootUri`/`workspaceFolders`/`roots`. When it can't resolve one, See [`docs/mcp.md`](docs/mcp.md#project-resolution) for the full three-case breakdown. Supported agents: Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, -Gemini CLI, Antigravity IDE, Kiro, Trae, Qoder, Zed, VS Code (GitHub Copilot), -GitHub Copilot CLI, JetBrains IDEs (GitHub Copilot). +Gemini CLI, Antigravity IDE, Kiro, Trae, Qoder, Zed, Zuno, VS Code +(GitHub Copilot), GitHub Copilot CLI, JetBrains IDEs (GitHub Copilot). ```bash codegraph install --yes # auto-detect installed agents @@ -238,9 +238,11 @@ codegraph skill uninstall --target=claude --yes # remove from one agent codegraph skill status # show state for all detected agents ``` -Ten of the eleven install targets have a skill directory (Claude Code, Cursor, -Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, Trae, -Qoder; `zed` is MCP-only and has no skill directory). +Eleven of the fifteen install targets have a skill directory (Claude Code, +Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, +Trae, Qoder, and Zuno). Zuno reuses the standard `~/.agents/skills` / +`.agents/skills` path, so selecting both Codex and Zuno is idempotent. Zed and +the three GitHub Copilot surfaces are MCP-only and have no skill directory. Default location is `--global`; pass `--local` to write into the project tree. Hermes supports global only. @@ -254,6 +256,13 @@ 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)`. +For agents whose installer owns a marker-fenced instructions block, `skill +update` also refreshes that block while preserving all user text outside +`` / ``. This includes Zuno's +global `$XDG_CONFIG_HOME/zuno/AGENTS.md` (normally +`~/.config/zuno/AGENTS.md`) and project-root `AGENTS.md`. `--dry-run` previews +the instructions change without writing it. + Full reference including per-agent skill paths: [`docs/cli.md`](docs/cli.md). --- @@ -267,7 +276,8 @@ stays live depends on whether the IDE expands `${workspaceFolder}`: - **Cursor / Trae** — global config uses `--path ${workspaceFolder}`, so one entry auto-follows every project window. Live watch enabled. - **Kiro / Qoder** — global entry without `--path`; tools work read-only off the existing index. Run `codegraph init --target=kiro` (or `--target=qoder`) inside each project for live watch. - **Zed** — global `settings.json` entry without `--path`. Run `codegraph init --target=zed` inside each project to write a `.zed/settings.json` with an absolute `--path` — the only way to give Zed a per-project path. The installer also writes `//`-commented HTTP and SSH alternatives for remote-development use. -- **Other agents** (Claude Code, Codex CLI, opencode, Hermes, Gemini CLI, Antigravity) — standard `mcpServers` entry; live watch where the daemon can reach the project. +- **Zuno** — global config is `$XDG_CONFIG_HOME/zuno/zuno.json[c]` (normally `~/.config/zuno/zuno.json[c]`); project config is `.zuno/zuno.json[c]`. The installer writes `mcp.codegraph` and migrates the older `mcp.codegraph-mcp-server` key without disturbing siblings or JSONC comments. +- **Other agents** (Claude Code, Codex CLI, opencode, Hermes, Gemini CLI, Antigravity) — their native MCP entry shape; live watch where the daemon can reach the project. > **Zed Remote (SSH).** Zed runs MCP `context_servers` on the local client, not on > the remote host. If codegraph tools return empty in a remote SSH session, use the diff --git a/crates/codegraph-cli/src/installer/mod.rs b/crates/codegraph-cli/src/installer/mod.rs index 0ecf5604..e17bf28b 100644 --- a/crates/codegraph-cli/src/installer/mod.rs +++ b/crates/codegraph-cli/src/installer/mod.rs @@ -381,8 +381,10 @@ pub fn run_skill_install(args: SkillArgs) -> Result<()> { } /// `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. +/// refresh safe/outdated skill content and each target's marker-managed +/// instructions block. `--diff` adds a unified skill diff, `--dry-run` +/// suppresses every write, and `--force` overwrites locally modified skill +/// content. User text outside the managed instructions markers is untouched. pub fn run_skill_update(args: SkillArgs) -> Result<()> { let ctx = context_from_env()?; let (location, targets) = resolve_skill_targets(&ctx, &args)?; @@ -391,7 +393,8 @@ pub fn run_skill_update(args: SkillArgs) -> Result<()> { return Ok(()); } - let mut changed_names: Vec<&str> = Vec::new(); + let mut skill_changed_names: Vec<&str> = Vec::new(); + let mut instructions_changed_names: Vec<&str> = Vec::new(); for target in &targets { let Some(skill_dir) = target.resolved_skill_dir(&ctx, location) else { println!( @@ -412,9 +415,22 @@ pub fn run_skill_update(args: SkillArgs) -> Result<()> { print!("{diff}"); } + let instructions_preview = target.preview_managed_instructions(&ctx, location); + if let Some(file) = &instructions_preview { + println!( + "{}", + managed_instructions_preview_line(target.display_name(), &ctx, file, args.dry_run) + ); + } + if args.dry_run { if preview.decision == skill::SkillUpdateDecision::Update { - changed_names.push(target.display_name()); + skill_changed_names.push(target.display_name()); + } + if instructions_preview.as_ref().is_some_and(|file| { + matches!(file.action, FileAction::Created | FileAction::Updated) + }) { + instructions_changed_names.push(target.display_name()); } continue; } @@ -425,33 +441,119 @@ pub fn run_skill_update(args: SkillArgs) -> Result<()> { .iter() .any(|file| matches!(file.action, FileAction::Created | FileAction::Updated)) { - changed_names.push(target.display_name()); + skill_changed_names.push(target.display_name()); } report_write_result(target.display_name(), &ctx, &result); + + if let Some(file) = target.refresh_managed_instructions(&ctx, location) { + if matches!(file.action, FileAction::Created | FileAction::Updated) { + instructions_changed_names.push(target.display_name()); + } + report_write_result( + target.display_name(), + &ctx, + &WriteResult { + files: vec![file], + notes: Vec::new(), + }, + ); + } } if args.dry_run { - if changed_names.is_empty() { - println!("\nDry run: no skill files would change."); - } else { + if skill_changed_names.is_empty() && instructions_changed_names.is_empty() { + println!("\nDry run: no CodeGraph skill assets would change."); + } + if !skill_changed_names.is_empty() { println!( "\nDry run: would update the CodeGraph skill for {} agent{}: {}.", - changed_names.len(), - if changed_names.len() > 1 { "s" } else { "" }, - changed_names.join(", ") + skill_changed_names.len(), + if skill_changed_names.len() > 1 { + "s" + } else { + "" + }, + skill_changed_names.join(", ") + ); + } + if !instructions_changed_names.is_empty() { + println!( + "\nDry run: would refresh managed CodeGraph instructions for {} agent{}: {}.", + instructions_changed_names.len(), + if instructions_changed_names.len() > 1 { + "s" + } else { + "" + }, + instructions_changed_names.join(", ") + ); + } + } else { + if !skill_changed_names.is_empty() { + println!( + "\nUpdated the CodeGraph skill for {} agent{}: {}.", + skill_changed_names.len(), + if skill_changed_names.len() > 1 { + "s" + } else { + "" + }, + skill_changed_names.join(", ") + ); + } + if !instructions_changed_names.is_empty() { + println!( + "\nRefreshed managed CodeGraph instructions for {} agent{}: {}.", + instructions_changed_names.len(), + if instructions_changed_names.len() > 1 { + "s" + } else { + "" + }, + instructions_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(()) } +fn managed_instructions_preview_line( + display_name: &str, + ctx: &InstallContext, + file: &types::FileWrite, + dry_run: bool, +) -> String { + let path = tildify(ctx, &file.path); + match (file.action, dry_run) { + (FileAction::Created, true) => { + format!("{display_name}: would create managed instructions {path}") + } + (FileAction::Updated, true) => { + format!("{display_name}: would refresh managed instructions {path}") + } + (FileAction::Unchanged, true) => { + format!("{display_name}: managed instructions up to date {path}") + } + (FileAction::Created, false) => { + format!("{display_name}: creating managed instructions {path}") + } + (FileAction::Updated, false) => { + format!("{display_name}: refreshing managed instructions {path}") + } + (FileAction::Unchanged, false) => { + format!("{display_name}: managed instructions up to date {path}") + } + (action, _) => format!( + "{display_name}: {} managed instructions {path}", + action.verb() + ), + } +} + +// Keep the summary logic separate for skills and instructions: a target may +// have an up-to-date or locally modified SKILL.md while its marker-managed +// AGENTS/CLAUDE/GEMINI block still needs a safe refresh. + /// `codegraph skill uninstall`. Removes the installed skill from each resolved /// target; an absent skill is reported as "not configured" (success exit). pub fn run_skill_uninstall(args: SkillArgs) -> Result<()> { diff --git a/crates/codegraph-cli/src/installer/registry.rs b/crates/codegraph-cli/src/installer/registry.rs index e2b17172..1fefaf89 100644 --- a/crates/codegraph-cli/src/installer/registry.rs +++ b/crates/codegraph-cli/src/installer/registry.rs @@ -4,8 +4,8 @@ //! Order is load-bearing: it is the order in `--target=all`, in detection, and //! in `--print-config`'s help listing. Matches `ALL_TARGETS` (registry.ts:20): //! claude, cursor, codex, opencode, hermes, gemini, antigravity, kiro, trae, -//! qoder, zed, plus the three Copilot surfaces appended by this port: vscode, -//! copilot-cli, jetbrains. +//! qoder, zed, zuno, plus the three Copilot surfaces appended by this port: +//! vscode, copilot-cli, jetbrains. use anyhow::{Result, bail}; @@ -22,6 +22,7 @@ use super::targets::{ qoder::QODER_TARGET, trae::TRAE_TARGET, zed::ZED_TARGET, + zuno::ZUNO_TARGET, }; use super::types::{AgentTarget, DetectionResult, InstallContext, Location}; @@ -38,6 +39,7 @@ pub fn all_targets() -> Vec<&'static dyn AgentTarget> { &TRAE_TARGET, &QODER_TARGET, &ZED_TARGET, + &ZUNO_TARGET, &VSCODE_TARGET, &COPILOT_CLI_TARGET, &JETBRAINS_TARGET, @@ -143,6 +145,7 @@ mod tests { "trae", "qoder", "zed", + "zuno", "vscode", "copilot-cli", "jetbrains", diff --git a/crates/codegraph-cli/src/installer/shared.rs b/crates/codegraph-cli/src/installer/shared.rs index 259bfe63..440c315b 100644 --- a/crates/codegraph-cli/src/installer/shared.rs +++ b/crates/codegraph-cli/src/installer/shared.rs @@ -19,17 +19,30 @@ use super::types::{FileAction, FileWrite}; pub const CODEGRAPH_SECTION_START: &str = ""; pub const CODEGRAPH_SECTION_END: &str = ""; -/// The marker-fenced agent-instructions block, byte-identical to -/// `instructions-template.ts:42-51` (`CODEGRAPH_INSTRUCTIONS_BLOCK`). +/// The marker-fenced agent-instructions block. +/// +/// Kept agent-neutral because the same body is written to Codex/OpenCode +/// `AGENTS.md`, Claude `CLAUDE.md`, Gemini `GEMINI.md`, and Zuno `AGENTS.md`. pub const CODEGRAPH_INSTRUCTIONS_BLOCK: &str = " ## CodeGraph -In repositories indexed by CodeGraph (a `.codegraph/` directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code: +When a repository contains a `.codegraph/` directory, use CodeGraph before grep/find or reading source files when you need to understand or locate code. + +Before the first query in a repository, verify that the index is usable: + +- **MCP:** `codegraph_status` +- **Shell:** `codegraph status . --json` + +Do not infer index readiness from the directory alone. Follow the recovery guidance reported by `status`; do not initialize or rebuild an index unless the user requests it or `status` explicitly requires it. -- **MCP tools** (when available): `codegraph_explore` answers most code questions in one call — the relevant symbols' verbatim source plus the call paths between them. `codegraph_node` returns one symbol's source + callers, or reads a whole file with line numbers. If the tools are listed but deferred, load them by name via tool search. -- **Shell** (always works): `codegraph explore \"\"` and `codegraph node ` print the same output. +For code research: -If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is the user's decision. +- Start with `codegraph_explore` for an area, feature, or call flow. +- Use `codegraph_search` to locate a known symbol. +- Use `codegraph_node` for a symbol's source and caller/callee trail, or for a line-numbered whole file. +- If MCP tools are unavailable, use `codegraph explore`, `codegraph search`, and `codegraph node`. + +If there is no `.codegraph/` directory, do not create one unless the user asks. "; /// The MCP-server config block codegraph injects. Ports `getMcpServerConfig` @@ -561,6 +574,24 @@ pub fn replace_or_append_marked_section( FileAction::Updated } +/// Preview what [`upsert_instructions_entry`] would do without writing. +pub fn instructions_entry_action(path: &Path) -> FileAction { + let Ok(content) = fs::read_to_string(path) else { + return FileAction::Created; + }; + if let (Some(start_idx), Some(end_idx)) = ( + content.find(CODEGRAPH_SECTION_START), + content.find(CODEGRAPH_SECTION_END), + ) && end_idx > start_idx + { + let block_end = end_idx + CODEGRAPH_SECTION_END.len(); + if &content[start_idx..block_end] == CODEGRAPH_INSTRUCTIONS_BLOCK { + return FileAction::Unchanged; + } + } + FileAction::Updated +} + /// Upsert the CodeGraph instructions block. Ports `upsertInstructionsEntry` /// (shared.ts:185) — the `appended` action is folded into `Updated` there too. pub fn upsert_instructions_entry(path: &Path) -> FileWrite { @@ -1038,6 +1069,37 @@ mod tests { let _ = fs::remove_dir_all(p.parent().unwrap()); } + #[test] + fn managed_instructions_are_status_first_and_agent_neutral() { + let text = CODEGRAPH_INSTRUCTIONS_BLOCK; + assert!(text.contains("`codegraph_status`")); + assert!(text.contains("`codegraph status . --json`")); + assert!(text.contains("`codegraph_search`")); + assert!(text.contains("caller/callee trail")); + assert!(text.contains("do not create one unless the user asks")); + assert!(!text.contains("deferred")); + assert!(!text.contains("tool search")); + } + + #[test] + fn instructions_entry_action_previews_without_writing() { + let p = tmp_path("AGENTS-preview.md"); + assert_eq!(instructions_entry_action(&p), FileAction::Created); + assert!(!p.exists()); + + fs::write( + &p, + format!("user content\n\n{CODEGRAPH_SECTION_START}\nold\n{CODEGRAPH_SECTION_END}\n"), + ) + .unwrap(); + assert_eq!(instructions_entry_action(&p), FileAction::Updated); + assert!(fs::read_to_string(&p).unwrap().contains("\nold\n")); + + upsert_instructions_entry(&p); + assert_eq!(instructions_entry_action(&p), FileAction::Unchanged); + let _ = fs::remove_dir_all(p.parent().unwrap()); + } + #[test] fn marked_section_appends_to_existing_body() { let p = tmp_path("doc.md"); diff --git a/crates/codegraph-cli/src/installer/targets/claude.rs b/crates/codegraph-cli/src/installer/targets/claude.rs index 66e0ecc4..e85b1c7c 100644 --- a/crates/codegraph-cli/src/installer/targets/claude.rs +++ b/crates/codegraph-cli/src/installer/targets/claude.rs @@ -133,6 +133,10 @@ impl AgentTarget for ClaudeCodeTarget { format!("# Add to {}\n\n{snippet}\n", target.display()) } + fn managed_instructions_path(&self, ctx: &InstallContext, loc: Location) -> Option { + Some(instructions_path(ctx, loc)) + } + fn supports_skills(&self, _loc: Location) -> bool { true } diff --git a/crates/codegraph-cli/src/installer/targets/codex.rs b/crates/codegraph-cli/src/installer/targets/codex.rs index 5c804d34..4b280e53 100644 --- a/crates/codegraph-cli/src/installer/targets/codex.rs +++ b/crates/codegraph-cli/src/installer/targets/codex.rs @@ -155,6 +155,10 @@ impl AgentTarget for CodexTarget { ) } + fn managed_instructions_path(&self, ctx: &InstallContext, loc: Location) -> Option { + (loc == Location::Global).then(|| instructions_path(ctx)) + } + // Skill support is INTENTIONALLY decoupled from `supports_location`: Codex // MCP config is global-only, yet Codex DOES scan project-local skills, so // skills are gated on `supports_skills` (true for BOTH locations), never on diff --git a/crates/codegraph-cli/src/installer/targets/gemini.rs b/crates/codegraph-cli/src/installer/targets/gemini.rs index afd9afe5..f4636f1e 100644 --- a/crates/codegraph-cli/src/installer/targets/gemini.rs +++ b/crates/codegraph-cli/src/installer/targets/gemini.rs @@ -107,6 +107,10 @@ impl AgentTarget for GeminiTarget { format!("# Add to {}\n\n{snippet}\n", target.display()) } + fn managed_instructions_path(&self, ctx: &InstallContext, loc: Location) -> Option { + Some(instructions_path(ctx, loc)) + } + fn supports_skills(&self, _loc: Location) -> bool { true } diff --git a/crates/codegraph-cli/src/installer/targets/mod.rs b/crates/codegraph-cli/src/installer/targets/mod.rs index 0194a1d7..0a4cc21d 100644 --- a/crates/codegraph-cli/src/installer/targets/mod.rs +++ b/crates/codegraph-cli/src/installer/targets/mod.rs @@ -12,3 +12,4 @@ pub mod opencode; pub mod qoder; pub mod trae; pub mod zed; +pub mod zuno; diff --git a/crates/codegraph-cli/src/installer/targets/opencode.rs b/crates/codegraph-cli/src/installer/targets/opencode.rs index 79d5b0ba..3f4146af 100644 --- a/crates/codegraph-cli/src/installer/targets/opencode.rs +++ b/crates/codegraph-cli/src/installer/targets/opencode.rs @@ -158,6 +158,10 @@ impl AgentTarget for OpencodeTarget { format!("# Add to {}\n\n{snippet}\n", target.display()) } + fn managed_instructions_path(&self, ctx: &InstallContext, loc: Location) -> Option { + Some(instructions_path(ctx, loc)) + } + fn supports_skills(&self, _loc: Location) -> bool { true } diff --git a/crates/codegraph-cli/src/installer/targets/zuno.rs b/crates/codegraph-cli/src/installer/targets/zuno.rs new file mode 100644 index 00000000..3da32fd2 --- /dev/null +++ b/crates/codegraph-cli/src/installer/targets/zuno.rs @@ -0,0 +1,417 @@ +//! Zuno target. +//! +//! Writes the MCP entry to `$XDG_CONFIG_HOME/zuno/zuno.json[c]` (global) or +//! `./.zuno/zuno.json[c]` (local), under `mcp.codegraph`. Instructions go to +//! `$XDG_CONFIG_HOME/zuno/AGENTS.md` globally and the project-root `AGENTS.md` +//! locally. Zuno scans the standard `.agents/skills` directories, so this +//! target deliberately reuses them instead of creating a duplicate +//! `zuno/skills/codegraph` discovery path. + +use std::fs; +use std::path::{Path, PathBuf}; + +use serde_json::{Map, Value, json}; + +use super::super::shared::{ + self, CODEGRAPH_SECTION_END, CODEGRAPH_SECTION_START, ConfigRead, parse_json_object, + read_config_file, remove_nested_key_jsonc, to_upstream_json, upsert_instructions_entry, + upsert_nested_key_jsonc, write_json_file, +}; +use super::super::types::{ + AgentTarget, DetectionResult, FileAction, FileWrite, InstallContext, InstallOptions, Location, + TargetId, WriteResult, +}; + +pub struct ZunoTarget; + +const ENTRY_KEY: &str = "codegraph"; +const LEGACY_ENTRY_KEY: &str = "codegraph-mcp-server"; + +fn global_config_dir(ctx: &InstallContext) -> PathBuf { + ctx.xdg_config_home + .as_ref() + .filter(|path| !path.as_os_str().is_empty()) + .cloned() + .unwrap_or_else(|| ctx.home.join(".config")) + .join("zuno") +} + +fn config_dir(ctx: &InstallContext, loc: Location) -> PathBuf { + match loc { + Location::Global => global_config_dir(ctx), + Location::Local => ctx.cwd.join(".zuno"), + } +} + +fn config_path(ctx: &InstallContext, loc: Location) -> PathBuf { + let dir = config_dir(ctx, loc); + let jsonc = dir.join("zuno.jsonc"); + let json = dir.join("zuno.json"); + if jsonc.exists() { + return jsonc; + } + if json.exists() { + return json; + } + json +} + +fn instructions_path(ctx: &InstallContext, loc: Location) -> PathBuf { + match loc { + Location::Global => global_config_dir(ctx).join("AGENTS.md"), + Location::Local => ctx.cwd.join("AGENTS.md"), + } +} + +fn server_entry() -> Value { + json!({ + "type": "local", + "command": ["codegraph", "serve", "--mcp"], + "enabled": true, + }) +} + +fn has_codegraph_entry(config: &Map) -> bool { + config + .get("mcp") + .is_some_and(|mcp| mcp.get(ENTRY_KEY).is_some() || mcp.get(LEGACY_ENTRY_KEY).is_some()) +} + +impl AgentTarget for ZunoTarget { + fn id(&self) -> TargetId { + TargetId::Zuno + } + + fn display_name(&self) -> &'static str { + "Zuno" + } + + fn supports_location(&self, _loc: Location) -> bool { + true + } + + fn detect(&self, ctx: &InstallContext, loc: Location) -> DetectionResult { + let file = config_path(ctx, loc); + let config = + parse_json_object(&fs::read_to_string(&file).unwrap_or_default()).unwrap_or_default(); + DetectionResult { + installed: config_dir(ctx, loc).exists() || file.exists(), + already_configured: has_codegraph_entry(&config), + } + } + + fn install(&self, ctx: &InstallContext, loc: Location, _opts: InstallOptions) -> WriteResult { + WriteResult { + files: vec![ + write_mcp_entry(ctx, loc), + upsert_instructions_entry(&instructions_path(ctx, loc)), + ], + notes: Vec::new(), + } + } + + fn uninstall(&self, ctx: &InstallContext, loc: Location) -> WriteResult { + WriteResult { + files: vec![ + remove_mcp_entry(&config_path(ctx, loc)), + remove_instructions_entry(ctx, loc), + ], + notes: Vec::new(), + } + } + + fn print_config(&self, ctx: &InstallContext, loc: Location) -> String { + let target = config_path(ctx, loc); + let snippet = to_upstream_json(&json!({ + "mcp": { "codegraph": server_entry() }, + })); + format!("# Add to {}\n\n{snippet}\n", target.display()) + } + + fn managed_instructions_path(&self, ctx: &InstallContext, loc: Location) -> Option { + Some(instructions_path(ctx, loc)) + } + + fn supports_skills(&self, _loc: Location) -> bool { + true + } + + fn skill_dir(&self, ctx: &InstallContext, loc: Location) -> Option { + Some(match loc { + Location::Global => ctx.home.join(".agents").join("skills"), + Location::Local => ctx.cwd.join(".agents").join("skills"), + }) + } +} + +fn write_mcp_entry(ctx: &InstallContext, loc: Location) -> FileWrite { + let file = config_path(ctx, loc); + let entry = server_entry(); + match read_config_file(&file) { + ConfigRead::Unparseable => FileWrite { + path: file, + action: FileAction::Skipped, + }, + ConfigRead::Missing => { + let mut mcp = Map::new(); + mcp.insert(ENTRY_KEY.to_string(), entry); + let mut config = Map::new(); + config.insert("mcp".to_string(), Value::Object(mcp)); + let _ = write_json_file(&file, &config); + FileWrite { + path: file, + action: FileAction::Created, + } + } + ConfigRead::Parsed(config) => { + let had_legacy = config + .get("mcp") + .and_then(|mcp| mcp.get(LEGACY_ENTRY_KEY)) + .is_some(); + let mut action = upsert_nested_key_jsonc(&file, "mcp", ENTRY_KEY, &entry, None) + .unwrap_or(FileAction::Skipped); + if action != FileAction::Skipped + && had_legacy + && remove_nested_key_jsonc(&file, "mcp", LEGACY_ENTRY_KEY) + .is_ok_and(|removed| removed == FileAction::Removed) + { + action = FileAction::Updated; + } + FileWrite { path: file, action } + } + } +} + +fn remove_mcp_entry(file: &Path) -> FileWrite { + let canonical = remove_nested_key_jsonc(file, "mcp", ENTRY_KEY).unwrap_or(FileAction::NotFound); + let legacy = + remove_nested_key_jsonc(file, "mcp", LEGACY_ENTRY_KEY).unwrap_or(FileAction::NotFound); + FileWrite { + path: file.to_path_buf(), + action: if canonical == FileAction::Removed || legacy == FileAction::Removed { + FileAction::Removed + } else { + FileAction::NotFound + }, + } +} + +fn remove_instructions_entry(ctx: &InstallContext, loc: Location) -> FileWrite { + let file = instructions_path(ctx, loc); + let action = + shared::remove_marked_section(&file, CODEGRAPH_SECTION_START, CODEGRAPH_SECTION_END); + FileWrite { path: file, action } +} + +pub static ZUNO_TARGET: ZunoTarget = ZunoTarget; + +#[cfg(test)] +mod tests { + use super::*; + + struct Fixture { + base: PathBuf, + ctx: InstallContext, + } + + impl Fixture { + fn new(label: &str) -> Self { + let base = std::env::temp_dir().join(format!( + "cg-zuno-{label}-{}-{}", + std::process::id(), + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .unwrap() + .as_nanos() + )); + let ctx = InstallContext { + home: base.join("home"), + cwd: base.join("project"), + app_data: None, + xdg_config_home: Some(base.join("xdg")), + hermes_home: None, + }; + fs::create_dir_all(&ctx.home).unwrap(); + fs::create_dir_all(&ctx.cwd).unwrap(); + Self { base, ctx } + } + } + + impl Drop for Fixture { + fn drop(&mut self) { + let _ = fs::remove_dir_all(&self.base); + } + } + + fn opts() -> InstallOptions { + InstallOptions { + auto_allow: false, + front_load_hook: false, + } + } + + #[test] + fn paths_and_shared_skill_dirs_match_zuno_discovery() { + let fx = Fixture::new("paths"); + assert_eq!( + config_path(&fx.ctx, Location::Global), + fx.base.join("xdg/zuno/zuno.json") + ); + assert_eq!( + instructions_path(&fx.ctx, Location::Global), + fx.base.join("xdg/zuno/AGENTS.md") + ); + assert_eq!( + config_path(&fx.ctx, Location::Local), + fx.ctx.cwd.join(".zuno/zuno.json") + ); + assert_eq!( + instructions_path(&fx.ctx, Location::Local), + fx.ctx.cwd.join("AGENTS.md") + ); + assert_eq!( + ZunoTarget.skill_dir(&fx.ctx, Location::Global), + Some(fx.ctx.home.join(".agents/skills")) + ); + assert_eq!( + ZunoTarget.skill_dir(&fx.ctx, Location::Local), + Some(fx.ctx.cwd.join(".agents/skills")) + ); + } + + #[test] + fn existing_jsonc_is_preferred_over_json() { + let fx = Fixture::new("jsonc"); + let dir = config_dir(&fx.ctx, Location::Global); + fs::create_dir_all(&dir).unwrap(); + fs::write(dir.join("zuno.json"), "{}\n").unwrap(); + fs::write(dir.join("zuno.jsonc"), "{ // preferred\n}\n").unwrap(); + assert!(config_path(&fx.ctx, Location::Global).ends_with("zuno.jsonc")); + } + + #[test] + fn global_install_preserves_jsonc_siblings_and_user_instructions() { + let fx = Fixture::new("global"); + let config = config_path(&fx.ctx, Location::Global); + let instructions = instructions_path(&fx.ctx, Location::Global); + fs::create_dir_all(config.parent().unwrap()).unwrap(); + fs::write( + &config, + "{\n // keep this comment\n \"mcp\": {\n \"other\": { \"command\": [\"other\"] }\n }\n}\n", + ) + .unwrap(); + fs::write( + &instructions, + format!( + "user before\n\n{CODEGRAPH_SECTION_START}\nold\n{CODEGRAPH_SECTION_END}\n\nuser after\n" + ), + ) + .unwrap(); + + let first = ZunoTarget.install(&fx.ctx, Location::Global, opts()); + assert!( + first + .files + .iter() + .all(|file| { matches!(file.action, FileAction::Created | FileAction::Updated) }) + ); + let written = fs::read_to_string(&config).unwrap(); + assert!(written.contains("// keep this comment")); + let parsed = parse_json_object(&written).unwrap(); + assert_eq!( + parsed["mcp"][ENTRY_KEY]["command"], + json!(["codegraph", "serve", "--mcp"]) + ); + assert_eq!(parsed["mcp"][ENTRY_KEY]["type"], "local"); + assert_eq!(parsed["mcp"][ENTRY_KEY]["enabled"], true); + assert!(parsed["mcp"]["other"].is_object()); + + let managed = fs::read_to_string(&instructions).unwrap(); + assert!(managed.contains("user before")); + assert!(managed.contains("user after")); + assert!(managed.contains("`codegraph_status`")); + assert!(!managed.contains("\nold\n")); + + let before = fs::read_to_string(&config).unwrap(); + let second = ZunoTarget.install(&fx.ctx, Location::Global, opts()); + assert!( + second + .files + .iter() + .all(|file| file.action == FileAction::Unchanged) + ); + assert_eq!(fs::read_to_string(&config).unwrap(), before); + } + + #[test] + fn local_install_and_uninstall_use_project_paths() { + let fx = Fixture::new("local"); + let config = config_path(&fx.ctx, Location::Local); + let instructions = instructions_path(&fx.ctx, Location::Local); + fs::write(&instructions, "project rules\n").unwrap(); + + ZunoTarget.install(&fx.ctx, Location::Local, opts()); + assert!(config.exists()); + assert!(instructions.starts_with(&fx.ctx.cwd)); + assert!( + parse_json_object(&fs::read_to_string(&config).unwrap()).unwrap()["mcp"][ENTRY_KEY] + .is_object() + ); + + ZunoTarget.uninstall(&fx.ctx, Location::Local); + let parsed = parse_json_object(&fs::read_to_string(&config).unwrap()).unwrap(); + assert!(parsed.get("mcp").is_none()); + assert_eq!( + fs::read_to_string(&instructions).unwrap(), + "project rules\n" + ); + } + + #[test] + fn install_migrates_legacy_entry_without_duplication() { + let fx = Fixture::new("legacy"); + let config = config_path(&fx.ctx, Location::Global); + fs::create_dir_all(config.parent().unwrap()).unwrap(); + fs::write( + &config, + format!( + "{{\n \"mcp\": {{\n \"{LEGACY_ENTRY_KEY}\": {{ \"type\": \"local\", \"command\": [\"codegraph\", \"serve\", \"--mcp\"] }}\n }}\n}}\n" + ), + ) + .unwrap(); + assert!( + ZunoTarget + .detect(&fx.ctx, Location::Global) + .already_configured + ); + + let result = ZunoTarget.install(&fx.ctx, Location::Global, opts()); + assert_eq!(result.files[0].action, FileAction::Updated); + let parsed = parse_json_object(&fs::read_to_string(&config).unwrap()).unwrap(); + assert!(parsed["mcp"][ENTRY_KEY].is_object()); + assert!(parsed["mcp"].get(LEGACY_ENTRY_KEY).is_none()); + } + + #[test] + fn unparseable_config_is_backed_up_and_not_clobbered() { + let fx = Fixture::new("unparseable"); + let config = config_path(&fx.ctx, Location::Global); + fs::create_dir_all(config.parent().unwrap()).unwrap(); + fs::write(&config, "{ invalid").unwrap(); + + let result = ZunoTarget.install(&fx.ctx, Location::Global, opts()); + assert_eq!(result.files[0].action, FileAction::Skipped); + assert_eq!(fs::read_to_string(&config).unwrap(), "{ invalid"); + assert!(config.with_extension("backup").exists()); + } + + #[test] + fn print_config_uses_zuno_local_command_shape() { + let fx = Fixture::new("print"); + let output = ZunoTarget.print_config(&fx.ctx, Location::Global); + assert!(output.contains("\"mcp\"")); + assert!(output.contains("\"type\": \"local\"")); + assert!(output.contains("\"command\": [")); + assert!(output.contains("\"codegraph\"")); + } +} diff --git a/crates/codegraph-cli/src/installer/types.rs b/crates/codegraph-cli/src/installer/types.rs index c43b2687..c54e7b9d 100644 --- a/crates/codegraph-cli/src/installer/types.rs +++ b/crates/codegraph-cli/src/installer/types.rs @@ -8,7 +8,7 @@ use std::path::PathBuf; -use super::skill; +use super::{shared, skill}; /// Ports the `Location` union (types.ts:15). #[derive(Debug, Clone, Copy, PartialEq, Eq)] @@ -40,6 +40,7 @@ pub enum TargetId { Trae, Qoder, Zed, + Zuno, VsCode, CopilotCli, JetBrains, @@ -59,6 +60,7 @@ impl TargetId { TargetId::Trae => "trae", TargetId::Qoder => "qoder", TargetId::Zed => "zed", + TargetId::Zuno => "zuno", TargetId::VsCode => "vscode", TargetId::CopilotCli => "copilot-cli", TargetId::JetBrains => "jetbrains", @@ -134,7 +136,7 @@ pub struct InstallContext { pub cwd: PathBuf, /// `%APPDATA%` equivalent, used only by the opencode legacy-Windows sweep. pub app_data: Option, - /// `$XDG_CONFIG_HOME`, used only by the opencode global config dir. + /// `$XDG_CONFIG_HOME`, used by XDG-aware global config dirs. pub xdg_config_home: Option, /// `$HERMES_HOME`, used only by the Hermes target. pub hermes_home: Option, @@ -150,6 +152,39 @@ pub trait AgentTarget { fn uninstall(&self, ctx: &InstallContext, loc: Location) -> WriteResult; fn print_config(&self, ctx: &InstallContext, loc: Location) -> String; + // --- Managed-instructions refresh surface ------------------------------ + + /// Marker-managed instructions file for this target/location, when one is + /// part of the target's install contract. Default: `None`. + fn managed_instructions_path(&self, _ctx: &InstallContext, _loc: Location) -> Option { + None + } + + /// Preview the marker-block refresh without writing. Used by + /// `codegraph skill update --dry-run`. + fn preview_managed_instructions( + &self, + ctx: &InstallContext, + loc: Location, + ) -> Option { + self.managed_instructions_path(ctx, loc) + .map(|path| FileWrite { + action: shared::instructions_entry_action(&path), + path, + }) + } + + /// Refresh only CodeGraph's marker-fenced block, preserving all user-owned + /// text outside it. Used by `codegraph skill update`. + fn refresh_managed_instructions( + &self, + ctx: &InstallContext, + loc: Location, + ) -> Option { + self.managed_instructions_path(ctx, loc) + .map(|path| shared::upsert_instructions_entry(&path)) + } + // --- Skill-capability surface (all default; targets opt in) -------------- // // A target enables skill install/uninstall/status by overriding ONLY @@ -421,6 +456,10 @@ mod tests { (TargetId::Trae, "trae"), (TargetId::Qoder, "qoder"), (TargetId::Zed, "zed"), + (TargetId::Zuno, "zuno"), + (TargetId::VsCode, "vscode"), + (TargetId::CopilotCli, "copilot-cli"), + (TargetId::JetBrains, "jetbrains"), ]; for (id, expected) in target_pairs { assert_eq!(id.as_str(), expected); @@ -450,6 +489,21 @@ mod tests { // writing no files and never panicking. assert!(!target.supports_skills(Location::Global)); assert!(target.skill_dir(&ctx, Location::Global).is_none()); + assert!( + target + .managed_instructions_path(&ctx, Location::Global) + .is_none() + ); + assert!( + target + .preview_managed_instructions(&ctx, Location::Global) + .is_none() + ); + assert!( + target + .refresh_managed_instructions(&ctx, Location::Global) + .is_none() + ); let install = target.install_skill(&ctx, Location::Global, false); assert!(install.files.is_empty()); diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs index 815cf38e..dee1371a 100644 --- a/crates/codegraph-cli/src/main.rs +++ b/crates/codegraph-cli/src/main.rs @@ -559,7 +559,10 @@ enum SkillAction { #[arg(short, long)] yes: bool, }, - /// Refresh an installed skill to the embedded version (use --force to overwrite local edits). + /// Refresh the installed skill and marker-managed agent instructions. + /// + /// Use --force to overwrite local edits to SKILL.md; user text outside the + /// managed instructions markers is always preserved. Update { #[arg(short, long)] target: Option, @@ -574,7 +577,7 @@ enum SkillAction { /// Show a unified installed-versus-embedded diff before writing. #[arg(long)] diff: bool, - /// Preview version and content changes without writing files. + /// Preview skill and managed-instructions changes without writing files. #[arg(long)] dry_run: bool, }, diff --git a/crates/codegraph-cli/tests/installer.rs b/crates/codegraph-cli/tests/installer.rs index 7a1cc490..9c1de89e 100644 --- a/crates/codegraph-cli/tests/installer.rs +++ b/crates/codegraph-cli/tests/installer.rs @@ -272,6 +272,70 @@ fn opencode_local_uses_mcp_wrapper() { assert!(read_json(&cfg)["mcp"].get("codegraph").is_none()); } +#[test] +fn zuno_global_migrates_legacy_entry_and_preserves_user_content() { + let fx = Fixture::new("zuno-global"); + let config = fx.root.join("xdg/zuno/zuno.json"); + let agents = fx.root.join("xdg/zuno/AGENTS.md"); + fs::create_dir_all(config.parent().unwrap()).unwrap(); + fs::write( + &config, + concat!( + "{\n", + " // user comment\n", + " \"mcp\": {\n", + " \"other\": { \"type\": \"local\", \"command\": [\"other\"] },\n", + " \"codegraph-mcp-server\": { \"type\": \"local\", \"command\": [\"codegraph\", \"serve\", \"--mcp\"] }\n", + " }\n", + "}\n", + ), + ) + .unwrap(); + fs::write( + &agents, + "user before\n\n\nold\n\n\nuser after\n", + ) + .unwrap(); + + fx.run(&["install", "--target=zuno", "--global", "--yes"]); + let raw = fs::read_to_string(&config).unwrap(); + assert!(raw.contains("// user comment")); + let parsed = crate_jsonc(&raw); + let mcp = parsed["mcp"].as_object().unwrap(); + assert!(mcp.get("other").is_some()); + assert!(mcp.get("codegraph-mcp-server").is_none()); + assert_eq!( + mcp["codegraph"]["command"], + serde_json::json!(["codegraph", "serve", "--mcp"]) + ); + assert_eq!(mcp["codegraph"]["type"], "local"); + assert_eq!(mcp["codegraph"]["enabled"], true); + + let instructions = fs::read_to_string(&agents).unwrap(); + assert!(instructions.contains("user before")); + assert!(instructions.contains("user after")); + assert!(instructions.contains("`codegraph_status`")); + assert!(!instructions.contains("\nold\n")); + + fx.run(&["uninstall", "--target=zuno", "--global"]); + let parsed = crate_jsonc(&fs::read_to_string(&config).unwrap()); + assert!(parsed["mcp"].get("codegraph").is_none()); + assert!(parsed["mcp"].get("other").is_some()); + assert_eq!( + fs::read_to_string(&agents).unwrap(), + "user before\n\nuser after\n" + ); +} + +fn crate_jsonc(text: &str) -> Value { + let without_comments = text + .lines() + .filter(|line| !line.trim_start().starts_with("//")) + .collect::>() + .join("\n"); + serde_json::from_str(&without_comments).unwrap() +} + #[test] fn print_config_does_not_write() { let fx = Fixture::new("print"); diff --git a/crates/codegraph-cli/tests/skill_install.rs b/crates/codegraph-cli/tests/skill_install.rs index 81c3c29a..520932db 100644 --- a/crates/codegraph-cli/tests/skill_install.rs +++ b/crates/codegraph-cli/tests/skill_install.rs @@ -178,6 +178,46 @@ fn skill_install_codex_local_writes_into_project() { assert!(body.contains("name: codegraph")); } +#[test] +fn skill_update_zuno_refreshes_managed_agents_without_touching_user_text() { + let fx = Fixture::new("zuno-update"); + let skill_md = fx.home.join(".agents/skills/codegraph/SKILL.md"); + let agents = fx.root.join("xdg/zuno/AGENTS.md"); + + fx.run(&["skill", "install", "--target=zuno", "--global", "-y"]); + assert!( + skill_md.exists(), + "Zuno reuses the standard global skill dir" + ); + + fs::create_dir_all(agents.parent().unwrap()).unwrap(); + let stale = concat!( + "user before\n\n", + "\n", + "old managed instructions\n", + "\n\n", + "user after\n", + ); + fs::write(&agents, stale).unwrap(); + + let dry_run = fx.run(&["skill", "update", "--target=zuno", "--global", "--dry-run"]); + assert!(dry_run.contains("would refresh managed instructions")); + assert_eq!( + fs::read_to_string(&agents).unwrap(), + stale, + "dry-run must not write AGENTS.md" + ); + + let applied = fx.run(&["skill", "update", "--target=zuno", "--global"]); + assert!(applied.contains("Refreshed managed CodeGraph instructions")); + let updated = fs::read_to_string(&agents).unwrap(); + assert!(updated.contains("user before")); + assert!(updated.contains("user after")); + assert!(updated.contains("`codegraph_status`")); + assert!(updated.contains("`codegraph_search`")); + assert!(!updated.contains("old managed instructions")); +} + // --- Scenario 4: update with no change reports Unchanged ------------------- #[test] diff --git a/docs/cli.md b/docs/cli.md index 71116853..9c8b894b 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -20,7 +20,7 @@ | `uninstall` | Remove codegraph from agent configs (inverse of `install`) | `-t/--target`, `-l/--location`, `--global`, `--local`, `-y/--yes` | | `skill` | Install / update / uninstall / check the embedded agent skill | `` (install, update, uninstall, status) | | `skill install` | Write the embedded SKILL.md into each agent's skill directory | `-t/--target`, `--global`, `--local`, `-y/--yes` | -| `skill update` | Preview versions/line counts and refresh the installed skill | `-t/--target`, `--global`, `--local`, `--force`, `--diff`, `--dry-run` | +| `skill update` | Refresh the installed skill and marker-managed agent instructions | `-t/--target`, `--global`, `--local`, `--force`, `--diff`, `--dry-run` | | `skill uninstall` | Remove the skill from agent skill directories | `-t/--target`, `--global`, `--local`, `-y/--yes` | | `skill status` | Report install state per agent (up to date / locally modified / outdated / not installed) | `-t/--target`, `--global`, `--local` | | `init` | Initialize `.codegraph/` and run the first full index | `[path]`, `-t/--target` (also write project-level MCP config; default `none`) | @@ -75,7 +75,7 @@ config file; `uninstall` reverses it. No hand-editing of JSON/TOML required. Supported agents (`ALL_TARGETS` order): **Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, Trae, Qoder, Zed, -VS Code (`vscode`), GitHub Copilot CLI (`copilot-cli`), JetBrains +Zuno, VS Code (`vscode`), GitHub Copilot CLI (`copilot-cli`), JetBrains (`jetbrains`).** The written MCP command launches the Rust binary: `command: "codegraph"`, `args: ["serve", "--mcp"]` (Cursor injects `--path`; Kiro injects `--path` only on a project-local @@ -121,6 +121,15 @@ Behavior is idempotent (upsert by the `codegraph` key). `uninstall` removes only codegraph's own entry and leaves other MCP servers intact. Instruction files are delimited by ``/`` markers. +**Zuno.** `--target=zuno` supports both locations. Global files are +`$XDG_CONFIG_HOME/zuno/zuno.json[c]` and +`$XDG_CONFIG_HOME/zuno/AGENTS.md` (normally under `~/.config/zuno/`); +project files are `.zuno/zuno.json[c]` and the project-root `AGENTS.md`. The MCP +entry uses Zuno's `mcp.` wrapper with +`"command": ["codegraph", "serve", "--mcp"]`. Install migrates the older +`mcp.codegraph-mcp-server` key to `mcp.codegraph` while preserving JSONC +comments and sibling entries. + **`--prompt-hook` (opt-in, Claude Code only).** Passing `--prompt-hook` writes an additional `UserPromptSubmit` hook into Claude Code's config. Before each prompt the hook calls `codegraph prompt-hook`, which runs `codegraph_explore` against the @@ -189,11 +198,12 @@ codegraph skill status # report state for all d codegraph skill status --target=all # report state for every agent ``` -Ten of the eleven install targets have a skill directory. `--target` accepts -those ten agent ids (`claude`, `cursor`, `codex`, `opencode`, `hermes`, -`gemini`, `antigravity`, `kiro`, `trae`, `qoder`) plus `auto`, `all`, and -`none`. Note: `zed` is a valid install target but has **no skill directory** -(MCP config only) — passing `--target=zed` to `codegraph skill` is a no-op. +Eleven of the fifteen install targets have a skill directory. `--target` +accepts those eleven agent ids (`claude`, `cursor`, `codex`, `opencode`, +`hermes`, `gemini`, `antigravity`, `kiro`, `trae`, `qoder`, `zuno`) plus +`auto`, `all`, and `none`. Zed and the three GitHub Copilot targets are valid +install targets but have **no skill directory** (MCP config only), so passing +them to `codegraph skill` is a no-op. Default location is `--global`; pass `--local` to write into the project tree. Hermes supports global only (no automatic project-scope for skills). @@ -211,10 +221,14 @@ Hermes supports global only (no automatic project-scope for skills). | kiro | `~/.kiro/skills/codegraph/` | `.kiro/skills/codegraph/` | | trae | `Trae/User/skills/codegraph/` | `.trae/skills/codegraph/` | | qoder | `~/.agents/skills/codegraph/` | `.qoder/skills/codegraph/` | +| zuno | `~/.agents/skills/codegraph/` | `.agents/skills/codegraph/` | Note: opencode uses the singular `skill/` directory name (not `skills/`). -Codex and Antigravity share `.agents/skills/` for local installs — writing both -targets locally is idempotent (same content and hash). +Codex, Antigravity, and Zuno may share `.agents/skills/` — writing more than one +of those targets to the same scope is idempotent (same content and hash). Zuno +uses the standard path intentionally because it already discovers that path; +installing a second copy under `zuno/skills` would make same-name lookup +ambiguous. ### Update semantics @@ -243,6 +257,22 @@ Codex CLI: outdated (0.40.1 -> 0.47.0) opencode: locally modified (base 0.40.1; embedded 0.47.0) ``` +The same `skill update` command also refreshes CodeGraph's marker-fenced +instructions for targets that install them: Claude Code, Codex CLI, opencode, +Gemini CLI, and Zuno. Only the bytes between `` and +`` are replaced; surrounding user instructions are +preserved. For example: + +```bash +codegraph skill update --target=zuno --global +# refreshes ~/.config/zuno/AGENTS.md by default +``` + +`--dry-run` previews this instructions action as well as the Skill change and +writes neither file. `--force` applies only to locally modified `SKILL.md` +content; the instructions block is already explicitly installer-managed by its +markers. + --- ## `codegraph self-update` — upgrade in place from GitHub Releases diff --git a/docs/mcp.md b/docs/mcp.md index 1be0e3a3..4349a435 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -85,8 +85,38 @@ regardless of cwd (e.g. `"args": ["serve", "--mcp", "-p", "/abs/path/to/project"]`). Supported agents: Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, -Gemini CLI, Antigravity IDE, Kiro, Trae, Qoder, Zed, VS Code (GitHub Copilot), -GitHub Copilot CLI, JetBrains IDEs (GitHub Copilot). +Gemini CLI, Antigravity IDE, Kiro, Trae, Qoder, Zed, Zuno, VS Code +(GitHub Copilot), GitHub Copilot CLI, JetBrains IDEs (GitHub Copilot). + +--- + +## Zuno — `mcp` config + +Zuno uses an `mcp.` wrapper and a string-array command: + +```jsonc +{ + "mcp": { + "codegraph": { + "type": "local", + "command": ["codegraph", "serve", "--mcp"], + "enabled": true, + }, + }, +} +``` + +Run `codegraph install --target=zuno --global` for +`$XDG_CONFIG_HOME/zuno/zuno.json[c]` (normally +`~/.config/zuno/zuno.json[c]`), or `--local` for +`.zuno/zuno.json[c]`. Existing JSONC comments and sibling MCP entries are +preserved. A pre-existing `mcp.codegraph-mcp-server` entry is migrated to the +canonical `mcp.codegraph` key. + +The installer also manages only the fenced CodeGraph block in Zuno's +`AGENTS.md`: global `$XDG_CONFIG_HOME/zuno/AGENTS.md`, or the project-root +`AGENTS.md` for a local install. `codegraph skill update --target=zuno` refreshes +that block together with the shared `.agents/skills/codegraph/SKILL.md`. --- diff --git a/docs/readme/README.zh-CN.md b/docs/readme/README.zh-CN.md index a155a7e6..bd97a202 100644 --- a/docs/readme/README.zh-CN.md +++ b/docs/readme/README.zh-CN.md @@ -99,7 +99,8 @@ codegraph serve --mcp --path /path/to/project # 可选:固定到指定项目 ``` 自动注册进你的代理配置(Claude Code / Cursor / Codex CLI / opencode / Hermes / -Gemini CLI / Antigravity / Kiro / Trae / Qoder / Zed): +Gemini CLI / Antigravity / Kiro / Trae / Qoder / Zed / Zuno / VS Code / +Copilot CLI / JetBrains): ```bash codegraph install --yes # 检测已安装的代理并接线 @@ -186,7 +187,8 @@ cargo install --git https://github.com/sunerpy/codegraph-rust codegraph-rs `"args": ["serve", "--mcp", "-p", "/abs/path/to/project"]`)。 支持的代理:Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、 -Gemini CLI、Antigravity IDE、Kiro、Trae、Qoder、Zed。 +Gemini CLI、Antigravity IDE、Kiro、Trae、Qoder、Zed、Zuno、VS Code、 +GitHub Copilot CLI、JetBrains IDE。 ```bash codegraph install --yes # 自动检测已安装代理 @@ -218,9 +220,11 @@ codegraph skill uninstall --target=claude --yes # 从单个代理中移除 codegraph skill status # 查看所有已检测代理的安装状态 ``` -全部 10 个支持的代理均有技能目录(Claude Code、Cursor、Codex CLI、opencode、 -Hermes Agent、Gemini CLI、Antigravity IDE、Kiro、Trae、Qoder)。默认位置为 `--global`;传入 -`--local` 可写入项目树。Hermes 仅支持全局安装。注意:`zed` 是有效的安装目标但**无技能目录**(仅 MCP 配置)。 +15 个安装目标中有 11 个具备技能目录(Claude Code、Cursor、Codex CLI、opencode、 +Hermes Agent、Gemini CLI、Antigravity IDE、Kiro、Trae、Qoder、Zuno)。Zuno 复用标准 +`~/.agents/skills` / `.agents/skills`,因此与 Codex 同时选择时仍然幂等。默认位置为 +`--global`;传入 `--local` 可写入项目树。Hermes 仅支持全局安装。Zed 与三个 GitHub +Copilot 目标仅支持 MCP 配置,无技能目录。 **更新语义。** `skill update` 用 git blob SHA-1 对比已安装文件与内嵌版本的内容哈希。 未被修改的文件会自动刷新;经过手动编辑的文件会被跳过并提示"locally modified"(可传 @@ -230,6 +234,17 @@ Hermes Agent、Gemini CLI、Antigravity IDE、Kiro、Trae、Qoder)。默认位 `--diff` 输出统一差异,`--dry-run` 输出相同预览但不修改文件。`skill status` 也会显示版本来源,例如 `outdated (0.40.1 -> 0.47.0)`。 +对于由安装器维护指令块的代理,`skill update` 还会同步刷新 marker 之间的内容, +并保留 marker 外的全部用户规则。Zuno 的全局路径是 +`$XDG_CONFIG_HOME/zuno/AGENTS.md`(通常为 `~/.config/zuno/AGENTS.md`),项目级路径 +是仓库根 `AGENTS.md`。例如: + +```bash +codegraph skill update --target=zuno --global +``` + +`--dry-run` 同样只预览 AGENTS.md 的变化,不会写入。 + 完整参考(含各代理技能路径):[`../cli.md`](../cli.md)。 --- @@ -242,7 +257,8 @@ Hermes Agent、Gemini CLI、Antigravity IDE、Kiro、Trae、Qoder)。默认位 - **Cursor / Trae** — 全局配置使用 `--path ${workspaceFolder}`,一份配置自动跟随每个项目窗口,保存即更新。 - **Kiro / Qoder** — 全局条目写入裸 `serve --mcp`(无 `--path`),工具对现有索引只读访问。在各项目内运行 `codegraph init --target=kiro` 可获得实时监听。 - **Zed** — 全局 `~/.config/zed/settings.json`(Linux/macOS)或 `%APPDATA%\Zed\settings.json`(Windows)写入裸条目。在项目内运行 `codegraph init --target=zed` 写入带绝对 `--path` 的 `.zed/settings.json`——这是 Zed 获得项目级实时索引的唯一方式。 -- **Claude Code、Cursor、Codex CLI、opencode、Hermes、Gemini CLI、Antigravity** — 标准 `mcpServers` 配置,均通过守护进程获得实时监听。 +- **Zuno** — 全局配置位于 `$XDG_CONFIG_HOME/zuno/zuno.json[c]`(通常是 `~/.config/zuno/`),项目配置位于 `.zuno/zuno.json[c]`。安装器写入 `mcp.codegraph`,并自动迁移旧的 `mcp.codegraph-mcp-server` 键,同时保留 JSONC 注释和其他 MCP 项。 +- **Claude Code、Cursor、Codex CLI、opencode、Hermes、Gemini CLI、Antigravity** — 使用各自原生的 MCP 配置结构,守护进程可到达项目时获得实时监听。 **在 Kiro、Qoder 或 Zed 中获得实时自动更新。** 在每个项目中运行一次: diff --git a/skills/codegraph/SKILL.md b/skills/codegraph/SKILL.md index e762a674..abf7a561 100644 --- a/skills/codegraph/SKILL.md +++ b/skills/codegraph/SKILL.md @@ -84,7 +84,8 @@ is healthy, do not run a manual sync after every edit. Each project still needs one usable index, normally created with `codegraph init`. Auto-register into all detected agents (Claude Code, Cursor, Codex, opencode, -Hermes, Gemini CLI, Antigravity, Kiro): +Hermes, Gemini CLI, Antigravity, Kiro, Trae, Qoder, Zed, Zuno, VS Code, +Copilot CLI, JetBrains): ```bash codegraph install --yes