feat: rewrite crux as a harness manager (v2.0)

[kaushalpaneri]

Summary

Rewrite crux from a per-MCP/per-skill manager (v1.x) into a harness manager (v2.0). A harness is a versioned bundle of agent configuration — CLAUDE.md, skills, MCPs, plugins, hooks — addressed by name@version. Activate one with crux use and Crux deploys symlinks under ~/.claude/ (or <cwd>/.claude/) into the registry.

Design doc: /Users/kaushal/Downloads/crux-v2-design.md (Part 1 — design, Part 2 — spec).
Plan: docs/superpowers/plans/2026-05-10-crux-v2-harness-manager.md.

What's in

• Registry tree under ~/.crux/registry/{mcps,skills,plugins,harnesses}/.
• Pointer file resolution: walk-up crux.toml → fallback ~/.crux/active.toml.
• Symlink-based activation with conflict detection (refuses to clobber non-Crux files).
• .mcp.json generation that wraps keychain MCPs with keychain-auth.sh and HTTP MCPs with http-bridge-auth.sh.
• Versioning (crux new, crux bump) with append-only history log capped at 100 rows.
• crux use - rolls back to the previous activation; crux use --none deactivates and removes managed symlinks.
• crux migrate converts a v1 crux.json to harness@v1 + crux.toml pointer.

Architecture

src/crux_cli/
├── paths.py          v2 path helpers (registry_root, harnesses_root, …)
├── tomlio.py         minimal TOML reader/writer
├── pointer.py        parse_ref, resolve_active (cwd walk-up)
├── history.py        bounded TSV activation log
├── bundle.py         bundle.toml reader/writer
├── store.py          enumeration + lookup of primitives
├── harness_ops.py    new / bump
├── registry_ops.py   add MCP/skill/plugin; remove (with reference guard)
├── activation.py     plan_symlinks → apply_plan → emit_mcp_json
├── mcp_emit.py       .mcp.json builder with keychain/http launcher wiring
├── migrate_v1.py     v1 crux.json → v2 harness + pointer
├── setup.py          create registry tree, install skill + launchers
└── cli/commands/     setup_cmd, doctor_cmd, migrate_cmd, registry_cmd,
                      secret_cmd, harness_cmd, use_cmd

Removed modules: manifest.py, sync.py, projects.py, sandbox.py, setup_crux.py, auth.py, preflight.py, health.py, and the old cli/commands/{mcp,skill,project,task,version,doctor}.py.

Tests

• 218 unit tests across the new modules.
• 12 integration tests in tests/integration/test_cli_v2.py that drive python -m crux_cli in a subprocess and walk through realistic user workflows: fresh setup, versioning, directory vs user scope, use - rollback, --none deactivation, building a bundle from scratch, reference-guarded removal, migration, doctor, and refusal to clobber existing files.
• Smoke-tested end-to-end (setup → new → use → active) outside the test suite to confirm real CLI behavior.

Test plan

• All unit tests pass (pytest tests/unit/)
• All integration tests pass (pytest tests/integration/)
• Smoke test: setup, new, use, active end-to-end in /tmp works as expected
• Ruff clean across src/ and tests/
• CI passes on this PR

🤖 Generated with Claude Code