agpm_cli/lib.rs
1//! AGPM - Claude Code Package Manager
2//!
3//! A Git-based package manager for Claude Code resources (agents, snippets, commands,
4//! scripts, hooks, and MCP servers) that enables reproducible installations using
5//! lockfile-based dependency management, similar to Cargo.
6//!
7//! # Architecture Overview
8//!
9//! AGPM follows a manifest/lockfile model where:
10//! - `agpm.toml` defines desired dependencies and their version constraints
11//! - `agpm.lock` records exact resolved versions for reproducible builds
12//! - Resources are fetched directly from Git repositories (no central registry)
13//! - Pattern-based dependencies enable bulk installation of related resources
14//!
15//! ## Key Features
16//!
17//! - **Decentralized**: No central registry - resources come from Git repositories
18//! - **Reproducible**: Lockfile ensures identical installations across environments
19//! - **Cross-platform**: Works on Windows, macOS, and Linux with proper path handling
20//! - **Pattern Matching**: Install multiple resources using glob patterns (e.g., `agents/*.md`)
21//! - **MCP Integration**: Native support for Model Context Protocol servers
22//! - **Hook System**: Automated Claude Code event handlers
23//! - **Security**: Input validation, path traversal prevention, credential isolation
24//!
25//! # Core Modules
26//!
27//! ## Core Functionality
28//! - [`cache`] - Git repository caching and management for performance
29//! - [`cli`] - Command-line interface with comprehensive subcommands
30//! - [`config`] - Global (~/.agpm/config.toml) and project configuration
31//! - [`core`] - Core types, error handling, and resource abstractions
32//! - [`resolver`] - Dependency resolution, conflict detection, and version matching
33//!
34//! ## Git Integration
35//! - [`git`] - Git operations wrapper using system git command (like Cargo)
36//! - [`source`] - Source repository operations and management
37//!
38//! ## Resource Management
39//! - [`lockfile`] - Lockfile generation, parsing, and validation (agpm.lock)
40//! - [`manifest`] - Manifest parsing and validation (agpm.toml)
41//! - [`markdown`] - Markdown file operations and frontmatter extraction
42//! - [`metadata`] - Extraction of transitive dependencies from resource files
43//! - [`pattern`] - Pattern-based dependency resolution using glob patterns
44//!
45//! ## Resource Types
46//! - [`hooks`] - Claude Code hook configuration and settings.local.json management
47//! - [`mcp`] - Model Context Protocol server configuration and .mcp.json management
48//!
49//! ## Supporting Modules
50//! - [`models`] - Shared data models for dependency specifications
51//! - [`utils`] - Cross-platform utilities, file operations, and path validation
52//! - [`version`] - Version constraint parsing, comparison, and resolution
53//!
54//! # Manifest Format (agpm.toml)
55//!
56//! ## Basic Example
57//! ```toml
58//! # Define source repositories
59//! [sources]
60//! community = "https://github.com/aig787/agpm-community.git"
61//! official = "https://github.com/example-org/agpm-official.git"
62//!
63//! # Install individual resources
64//! [agents]
65//! code-reviewer = { source = "official", path = "agents/reviewer.md", version = "v1.0.0" }
66//! local-helper = "../local-agents/helper.md" # Local file
67//!
68//! # Pattern-based dependencies (new feature)
69//! ai-agents = { source = "community", path = "agents/ai/*.md", version = "v1.0.0" }
70//! all-tools = { source = "community", path = "**/tools/*.md", version = "latest" }
71//!
72//! [snippets]
73//! utils = { source = "community", path = "snippets/utils.md", version = "v2.1.0" }
74//!
75//! [commands]
76//! deploy = { source = "official", path = "commands/deploy.md", version = "v1.0.0" }
77//!
78//! # MCP servers and hooks
79//! [mcp-servers]
80//! filesystem = { source = "official", path = "mcp-servers/filesystem.json", version = "v1.0.0" }
81//!
82//! [hooks]
83//! pre-commit = { source = "community", path = "hooks/pre-commit.json", version = "v1.0.0" }
84//! ```
85//!
86//! # Command-Line Usage
87//!
88//! ## Installation and Management
89//! ```bash
90//! # Initialize new AGPM project
91//! agpm init
92//!
93//! # Install all dependencies from agpm.toml
94//! agpm install
95//!
96//! # Install with frozen lockfile (CI/production)
97//! agpm install --frozen
98//!
99//! # Update dependencies within version constraints
100//! agpm update
101//!
102//! # Update specific dependencies only
103//! agpm update code-reviewer utils
104//! ```
105//!
106//! ## Resource Discovery
107//! ```bash
108//! # List installed resources
109//! agpm list
110//!
111//! # List with details and source information
112//! agpm list --details
113//!
114//! # List specific resource types
115//! agpm list --agents --format json
116//! ```
117//!
118//! ## Project Management
119//! ```bash
120//! # Validate project configuration
121//! agpm validate --resolve --sources
122//!
123//! # Add new dependencies
124//! agpm add dep agent official:agents/helper.md@v1.0.0
125//!
126//! # Manage cache
127//! agpm cache clean
128//! ```
129
130// Core functionality modules
131pub mod cache;
132pub mod cli;
133pub mod config;
134pub mod constants;
135pub mod core;
136pub mod resolver;
137
138// Git integration
139pub mod git;
140pub mod source;
141
142// Resource management
143pub mod lockfile;
144pub mod manifest;
145pub mod markdown;
146pub mod metadata;
147pub mod pattern;
148pub mod templating;
149
150// Resource types
151pub mod hooks;
152pub mod mcp;
153pub mod skills;
154
155// Supporting modules
156pub mod installer;
157pub mod models;
158pub mod tokens;
159pub mod upgrade;
160pub mod utils;
161pub mod version;
162
163// test_utils module is available for both unit tests and integration tests
164#[cfg(any(test, feature = "test-utils"))]
165pub mod test_utils;