feat(cli): dirctl install

[akijakya]

Summary

Implements dirctl install (#1737): pull a record by CID or verifiable name and install its OASF-derived artifacts — an MCP server entry and/or an Agent Skill — directly into the configs of detected AI coding agents (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Cline, Roo, Gemini, OpenCode, Zed, Continue, Codex).

The placement machinery is extracted into a shared cli/internal/agentcfg engine (per-agent paths, JSON/YAML/TOML codec, managed-block merge, atomic writes, detection, summary) so dirctl init (#1705) can reuse it.

Commands

• dirctl install <cid-or-name> (≡ install run) — detect → plan → confirm → install
• dirctl install uninstall <cid-or-name> (top-level dirctl uninstall shorthand) — reverse it
• dirctl install list — show detected agents and target paths

Behavior

• What gets installed is derived from the record's modules, not flags (agentskills → skill, integration/mcp → MCP entry; a2a-only or no installable module → clear error pointing to dirctl export).
• --agents all|<ids> selects agents; detection is always required — undetected agents are skipped, never forced.
• Identity is the record name, so re-installing a newer version replaces the old artifacts cleanly and different records coexist. Writes are surgical, idempotent, and atomic.

Follow-ups tracked in #1705 (dirctl init wizard) and #1742 (batch install).

Closes #1737.

[Copilot]

Pull request overview

Adds a new dirctl install command (plus uninstall/list) that pulls a record and installs its MCP server config and/or Agent Skill into the config files of detected AI coding agents, backed by a new shared cli/internal/agentcfg placement engine (paths, codecs, managed-block merge, atomic writes, reporting).

Changes:

• Introduces cli/internal/agentcfg with per-agent registry, config codecs (JSON/YAML/TOML), atomic file writes, and plan/summary formatting.
• Adds cli/cmd/install command group (install, install run, install uninstall, install list) and a top-level dirctl uninstall shorthand.
• Updates CLI reference docs to document the new install/uninstall/list behavior.

Reviewed changes

Copilot reviewed 47 out of 47 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
docs/content/dir/dir-cli-reference.md	Documents the new install/uninstall/list commands and flags.
cli/internal/agentcfg/types.go	Defines core agent/target types (MCP + skill strategies).
cli/internal/agentcfg/summary.go	Implements post-run summary rendering.
cli/internal/agentcfg/summary_test.go	Tests summary output/tally behavior.
cli/internal/agentcfg/skill_render.go	Renders canonical SKILL.md into tool-specific rule formats.
cli/internal/agentcfg/skill_render_test.go	Tests skill rendering for each supported renderer.
cli/internal/agentcfg/skill_path.go	Implements skill path resolution helpers and ErrNoGlobalPath.
cli/internal/agentcfg/skill_frontmatter.go	Parses YAML frontmatter from canonical SKILL.md.
cli/internal/agentcfg/skill_frontmatter_test.go	Tests frontmatter parsing behavior.
cli/internal/agentcfg/skill_engine.go	Installs/removes skill artifacts (folder/file/managed-block).
cli/internal/agentcfg/skill_engine_test.go	Tests skill install/uninstall idempotency and fallbacks.
cli/internal/agentcfg/skill_block.go	Managed-block upsert/remove helpers for shared instruction files.
cli/internal/agentcfg/skill_block_test.go	Tests managed-block upsert/remove semantics.
cli/internal/agentcfg/result.go	Defines Outcome/Action and helpers for failure reporting.
cli/internal/agentcfg/registry.go	Adds the supported-agent registry (paths, detection markers, targets).
cli/internal/agentcfg/registry_test.go	Tests registry integrity and target path resolvability.
cli/internal/agentcfg/plan.go	Implements pre-run plan formatting.
cli/internal/agentcfg/plan_test.go	Tests plan formatting.
cli/internal/agentcfg/paths.go	Centralizes per-agent config path resolution by OS.
cli/internal/agentcfg/paths_test.go	Tests platform-specific path resolution.
cli/internal/agentcfg/options.go	Agent selection resolution logic (detected-only).
cli/internal/agentcfg/options_test.go	Tests selection behavior for explicit/all choices.
cli/internal/agentcfg/mcp_remove_test.go	Tests MCP removal behavior (only our key removed).
cli/internal/agentcfg/mcp_engine.go	Installs/removes MCP server entries with structured codecs + atomic writes.
cli/internal/agentcfg/mcp_engine_test.go	Tests MCP install/update/idempotency/dry-run behavior.
cli/internal/agentcfg/fsutil/atomic.go	Implements atomic file writes (temp + rename).
cli/internal/agentcfg/fsutil/atomic_test.go	Tests atomic write behavior and temp cleanup.
cli/internal/agentcfg/codec/codec.go	Adds JSON/YAML/TOML decode/encode and nested-map helpers.
cli/internal/agentcfg/codec/codec_test.go	Tests codec round-trips and nested helpers.
cli/cmd/root.go	Registers install commands and skips client setup for install list.
cli/cmd/install/uninstall.go	Implements install uninstall and top-level uninstall shorthand.
cli/cmd/install/testdata/skill.json	Test record fixture: skill-only module.
cli/cmd/install/testdata/multi.json	Test record fixture: skill + MCP modules.
cli/cmd/install/testdata/mcp.json	Test record fixture: MCP-only module.
cli/cmd/install/testdata/bare.json	Test record fixture: no modules.
cli/cmd/install/testdata/a2a.json	Test record fixture: A2A-only module.
cli/cmd/install/run.go	Defines install run subcommand.
cli/cmd/install/options.go	Shared flag struct for install subcommands.
cli/cmd/install/list.go	Implements install list (detect + show target paths).
cli/cmd/install/install.go	Implements main install flow: pull+derive → plan → confirm → apply → summary.
cli/cmd/install/install_test.go	Tests list behavior, subcommand wiring, uninstall shorthand flags.
cli/cmd/install/flags.go	Implements --agents, --dry-run, --yes/-y flag plumbing/validation.
cli/cmd/install/flags_test.go	Tests --agents parsing/validation.
cli/cmd/install/derive.go	Derives installable artifacts (skill + MCP entries) from record modules.
cli/cmd/install/derive_test.go	Tests artifact derivation and slug sanitization.
cli/cmd/install/apply.go	Applies/removes artifacts across selected agents (including skill dedupe).
cli/cmd/install/apply_test.go	Tests end-to-end apply behavior for MCP and skill targets.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 75.09398% with 265 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cli/internal/agentcfg/skill_engine.go	59.9%	33 Missing and 22 partials ⚠️
cli/cmd/install/install.go	37.9%	35 Missing and 1 partial ⚠️
cli/cmd/install/uninstall.go	6.7%	28 Missing ⚠️
cli/internal/agentcfg/mcp_engine.go	68.1%	12 Missing and 11 partials ⚠️
cli/internal/agentcfg/registry.go	89.8%	17 Missing and 1 partial ⚠️
cli/internal/agentcfg/codec/codec.go	85.3%	12 Missing and 3 partials ⚠️
cli/internal/agentcfg/fsutil/atomic.go	31.6%	7 Missing and 6 partials ⚠️
cli/internal/agentcfg/skill_render.go	76.0%	6 Missing and 6 partials ⚠️
cli/cmd/install/derive.go	84.1%	5 Missing and 5 partials ⚠️
cli/internal/agentcfg/skill_block.go	75.6%	5 Missing and 5 partials ⚠️
... and 9 more

📢 Thoughts on this report? Let us know!

[ramizpolic]

LGTM