crabbuild/compass/plans

struct InstallFixture {
    _directory: TempDir,
    project: PathBuf,
    home: PathBuf,
}
 
impl InstallFixture {
    fn new() -> Result<Self, Box<dyn Error>> {
        let directory = tempfile::tempdir()?;
        let project = directory.path().join("project");
        let home = directory.path().join("home");
        fs::create_dir_all(&project)?;
        fs::create_dir_all(&home)?;
        Ok(Self {
            _directory: directory,
            project,
            home,
        })
    }
 
    fn run(&self, arguments: &[&str]) -> Result<Output, Box<dyn Error>> {
        Ok(Command::new(env!("CARGO_BIN_EXE_compass"))
            .args(arguments)
            .current_dir(&self.project)
            .env("HOME", &self.home)
            .env("USERPROFILE", &self.home)
            .env_remove("CLAUDE_CONFIG_DIR")
            .env_remove("CODEX_HOME")
            .output()?)
    }
}
 
fn directory_tree(root: &Path) -> Result<BTreeMap<PathBuf, Vec<u8>>, Box<dyn Error>> {
    fn visit(
        root: &Path,
        directory: &Path,
        output: &mut BTreeMap<PathBuf, Vec<u8>>,
    ) -> Result<(), Box<dyn Error>> {
        let mut entries = fs::read_dir(directory)?.collect::<Result<Vec<_>, _>>()?;
        entries.sort_by_key(fs::DirEntry::file_name);
        for entry in entries {
            let path = entry.path();
            if path.is_dir() {
                visit(root, &path, output)?;
            } else if path.is_file() {
                output.insert(path.strip_prefix(root)?.to_path_buf(), fs::read(path)?);
            }
        }
        Ok(())
    }
 
    let mut output = BTreeMap::new();
    visit(root, root, &mut output)?;
    Ok(output)
}

#[test]
fn project_codex_install_creates_native_compass_skill() -> Result<(), Box<dyn Error>> {
    let fixture = InstallFixture::new()?;
    let output = fixture.run(&["install", "--platform", "codex", "--project"])?;
    assert!(output.status.success(), "{}", String::from_utf8_lossy(&output.stderr));
 
    let skill = fixture.project.join(".codex/skills/compass/SKILL.md");
    let body = fs::read_to_string(&skill)?;
    assert!(body.starts_with("---\nname: compass\n"));
    assert!(body.contains("compass query"));
    assert!(body.contains("compass-out/"));
    assert_native(&body);
    assert!(skill.with_file_name(".compass_version").is_file());
    Ok(())
}
 
fn assert_native(value: &str) {
    for forbidden in ["graphify", "graphifyy", "GRAPHIFY_", "graphify-out"] {
        assert!(!value.contains(forbidden), "stale token {forbidden}: {value}");
    }
}

#[test]
fn compass_lifecycle_preserves_adjacent_graphify_install() -> Result<(), Box<dyn Error>> {
    let fixture = InstallFixture::new()?;
    let graphify = fixture.project.join(".codex/skills/graphify/SKILL.md");
    fs::create_dir_all(graphify.parent().ok_or("graphify parent")?)?;
    fs::write(&graphify, "---\nname: graphify\n---\n")?;
    fs::create_dir_all(fixture.project.join("graphify-out"))?;
 
    assert!(fixture.run(&["install", "--platform", "codex", "--project"])?.status.success());
    assert!(fixture.run(&["uninstall", "--platform", "codex", "--project"])?.status.success());
 
    assert_eq!(fs::read_to_string(graphify)?, "---\nname: graphify\n---\n");
    assert!(fixture.project.join("graphify-out").is_dir());
    Ok(())
}

cargo test -p compass-cli --test install_cli project_codex_install_creates_native_compass_skill -- --exact

git add crates/compass-cli/tests/install_cli.rs
git commit -m "test: define native Compass skill contracts"

#[test]
fn canonical_compass_skill_package_is_native() {
    let body = asset_text("compass-skill/SKILL.md").expect("canonical Compass skill");
    assert!(body.starts_with("---\nname: compass\n"));
    assert!(body.contains("references/query.md"));
    assert!(body.contains("compass query"));
    assert!(body.contains("compass update"));
    for forbidden in ["graphify", "graphifyy", "GRAPHIFY_", "graphify-out", "python -m"] {
        assert!(!body.contains(forbidden), "stale token {forbidden}");
    }
    assert!(EMBEDDED_ASSETS.iter().any(|asset| {
        asset.path.starts_with("compass-skill/references/")
    }));
}

cargo test -p compass-cli install_commands::tests::canonical_compass_skill_package_is_native -- --exact

---
name: compass
description: Use when answering questions about a codebase, its architecture, dependencies, impact, or project artifacts, especially when compass-out exists or the user invokes /compass.
---
 
# Compass
 
Use Compass as the first navigation layer for codebase and architecture work.
 
## Existing graph
 
When `compass-out/graph.json` exists:
 
1.Run `compass reflect --if-stale`.
2.Read `compass-out/reflections/LESSONS.md` when it exists.
3.Run `compass query "<question>"` for scoped context.
4.Use `compass path "<source>" "<target>"` for dependency paths.
5.Use `compass explain "<concept>"` for one concept and its neighbors.
 
Read `compass-out/GRAPH_REPORT.md` for broad architecture only. Navigate `compass-out/wiki/index.md` when the wiki exists.
 
## Build or refresh
 
Run `compass update INPUT_PATH`. Use `.` when the user gives no path. After code changes, run `compass update .`.
 
Load only the reference needed for the request:
 
-Query and navigation: `references/query.md`
-Incremental refresh: `references/update.md`
-Hooks and assistant setup: `references/hooks.md`
-Watch mode and added sources: `references/add-watch.md`
-Export formats: `references/exports.md`
-Repository cloning and merged graphs: `references/github-and-merge.md`
-Graph schema and provenance: `references/extraction-spec.md`
 
If `compass` is unavailable, report that the Compass CLI must be installed. Do not install Python or another package.

# Query and navigate
 
Load this reference for codebase questions when `compass-out/graph.json` exists.
 
-`compass query "<question>"`: return a relevance-ranked scoped subgraph
-`compass path "<source>" "<target>"`: show the shortest dependency path
-`compass explain "<concept>"`: show one node and its connected context
-`compass affected <path-or-symbol>`: estimate downstream impact
-`compass tree`: render repository structure with graph context
 
Run `compass <command> --help` before using options not shown here.

# Refresh a graph
 
Load this reference when source files changed or the user requests a rebuild.
 
Run `compass update INPUT_PATH`. Use `.` when no path was supplied. Run `compass reflect --if-stale` after the update before answering a codebase question.
 
Run `compass update --help` before adding build options.

# Manage hooks and assistant setup
 
Load this reference when the user asks for automatic refresh or assistant registration.