airc-cli 0.1.0 → 0.1.2

package/README.md

@@ -2,32 +2,16 @@
 
 AI Config Manager - A TypeScript-based CLI tool to manage and install AI tool configuration files across multiple AI development tools.
 
-## Features
-
-- ✅ **Multi-Tool Support** - Install configs for Claude, Gemini CLI, Cursor, Antigravity, GitHub Copilot, and OpenCode
-- ✅ **Centralized Config Management** - User-level config directory (~/.airc) with git-based source management
-- ✅ **Git Source Integration** - Add configs from GitHub/GitLab/Bitbucket repositories
-- ✅ **Automatic Config Copying** - Add sources and configs are automatically copied to your local directory
-- ✅ **Format Conversion** - Automatically converts commands to tool-specific formats (TOML, prompt.md, YAML)
-- ✅ **Config Discovery** - Browse available configs from sources
-- ✅ **Smart Updates** - Keep configs in sync with source updates (only updates changed files)
-- ✅ **Sparse Checkout** - Support GitHub tree URLs for subfolder-only checkout
-- ✅ **Safe Installation** - Prevents accidental overwrites (with force option available)
-- ✅ **Migration Tool** - Easy migration from old project-based configs to new user config workflow
-- ✅ **Comprehensive Testing** - 532+ tests with full coverage
-- ✅ **TypeScript Support** - Fully typed for better development experience
+Idea is manage your AI tools config in same place and then reuse everywhere.
 
 ## Installation
 
 ```bash
-# Install dependencies
-bun install
+npm install airc-cli -g
+airc --help
 
-# Build the project
-bun run build
-
-# Install globally (optional)
-bun link
+# Or use npx directly
+npx airc-cli --help
 ```
 
 ## Quick Start
@@ -41,34 +25,35 @@ airc init
 ```
 
 This creates:
+
 - `~/.airc/` - User config directory
-- `~/.airc/config/.claude/` - Local config storage (commands, skills, agents)
-- `~/.airc/sources/` - Git source repositories
-- `~/.aircrc` - Configuration file
+- `~/.airc/config/skills/` - Local skills config storage
+- `~/.airc/config/commands/` - Local commands config storage
+- `~/.airc/config/agents/` - Local commands config storage
+- `~/.aircrc` - Configuration file for airc cli
 
 ### 2. Add a Source
 
-Add a git repository containing AI configs. This automatically clones the repository and copies config files to your local directory:
+Add a git repository containing AI configs. This automatically copies config files to your local directory:
 
 ```bash
 # Add from GitHub (full repository)
-airc source add https://github.com/username/ai-configs
+airc source add https://github.com/vercel-labs/agent-skills
 
 # Add with custom name
-airc source add https://github.com/username/ai-configs --name my-configs
+airc source add https://github.com/vercel-labs/agent-skills --name vercel-skills
 
-# Add specific branch
-airc source add https://github.com/username/ai-configs --branch develop
-
-# Add from GitHub tree URL (sparse checkout - only specified subfolder)
-airc source add https://github.com/username/ai-configs/tree/main/custom-skills
+# Add from GitHub tree URL
+airc source add https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices
 ```
 
 **What happens:**
-- Repository is cloned to `~/.airc/sources/`
+
+- Repository is cloned to `~/.airc/temp/`
 - Config folders (skills, commands, agents) are automatically discovered
 - Config files are copied to `~/.airc/config/{type}/{source-name}/`
-- Metadata is tracked for smart updates
+- Metadata is tracked in `~/.aircrc` for smart updates
+- Remove temp repo
 
 ### 3. View Your Configs
 
@@ -87,638 +72,35 @@ airc list --type skills
 Install your configs to specific AI tools:
 
 ```bash
-# Install to Claude
-airc install claude
-
-# Install globally
-airc install cursor --global
-```
-
-## Usage
-
-### Workflow Overview
-
-The workflow is simple and streamlined:
-
-1. **Initialize** - Set up your user config directory (`airc init`)
-2. **Add Sources** - Add git repositories containing configs (`airc source add <url>`)
-   - Automatically clones repository and copies configs
-3. **List** - View available configs in your local directory (`airc list`)
-4. **Install** - Deploy configs to specific AI tools (`airc install <tool>`)
-5. **Update** - Keep configs up-to-date with sources (`airc source update <name>`)
-
-### Commands
-
-#### `init`
-
-Initialize airc user config directory.
-
-```bash
-airc init [options]
-```
-
-**Options:**
-- `-f, --force` - Reinitialize even if already initialized
-
-#### `source add <url>`
-
-Add a git repository as a config source. Automatically clones the repository and copies config files to your local directory.
-
-```bash
-airc source add <url> [options]
-```
-
-**Arguments:**
-- `url` - Git repository URL (GitHub/GitLab/Bitbucket, HTTPS or SSH)
-  - Regular URL: `https://github.com/user/configs`
-  - GitHub tree URL (sparse checkout): `https://github.com/user/configs/tree/main/subfolder`
-
-**Options:**
-- `-n, --name <name>` - Custom source name (default: extracted from URL)
-- `-b, --branch <branch>` - Git branch to checkout (default: repository default)
-- `--depth <number>` - Scan depth for config folders (default: 3)
-- `-f, --force` - Replace existing source if it exists
-
-**Examples:**
-```bash
-# Full repository clone
-airc source add https://github.com/user/configs
-
-# Custom name
-airc source add git@github.com:user/configs.git --name my-configs
-
-# Specific branch
-airc source add https://github.com/user/configs --branch main
-
-# GitHub tree URL (sparse checkout - only specified subfolder)
-airc source add https://github.com/user/configs/tree/main/custom-skills
-
-# Custom scan depth
-airc source add https://github.com/user/configs --depth 5
-```
-
-**What happens:**
-- Repository is cloned to `~/.airc/sources/{source-name}/`
-- Config folders (skills, commands, agents) are discovered up to specified depth
-- Config files (*.md) are copied to `~/.airc/config/{type}/{source-name}/`
-- Metadata is tracked in `.aircrc` for smart updates
-
-#### `source list`
-
-List all added sources.
-
-```bash
-airc source list [options]
-```
-
-**Options:**
-- `-v, --verbose` - Show detailed information (URL, branch, path)
-
-#### `source update [name]`
-
-Update source(s) to latest version with smart update logic.
-
-```bash
-airc source update [name] [options]
-```
-
-**Arguments:**
-- `name` - Source name to update (optional)
-
-**Options:**
-- `-a, --all` - Update all sources
-
-**Examples:**
-```bash
-# Update specific source
-airc source update my-configs
-
-# Update all sources
-airc source update --all
-```
-
-**Smart Update Behavior:**
-- **UPDATE**: Files with changed hashes are updated
-- **ADD**: New files from source are added
-- **SKIP**: Files with unchanged hashes are skipped
-- **KEEP**: Files deleted from source are kept (conservative approach)
-
-**Example Output:**
-```
-Updating source 'my-configs'...
-✓ Updated: skills/my-configs/web-design.md
-+ Added: skills/my-configs/api-helper.md
-📦 Kept: skills/my-configs/old-config.md (deleted from source)
-
-Summary: 1 updated, 1 added, 5 unchanged, 1 kept
-Tip: Run 'airc install <tool>' to apply changes
-```
-
-#### `source remove [name]`
-
-Remove source(s).
-
-```bash
-airc source remove [name] [options]
-```
-
-**Arguments:**
-- `name` - Source name to remove (optional)
-
-**Options:**
-- `-f, --force` - Confirm removal without prompt (required)
-- `-a, --all` - Remove all sources
-
-#### `source check [name]`
-
-Check if source(s) have updates available.
-
-```bash
-airc source check [name] [options]
-```
-
-**Arguments:**
-- `name` - Source name to check (optional)
-
-**Options:**
-- `-a, --all` - Check all sources
-
-#### `browse`
-
-Browse available configs in `~/.airc/config/` directory.
-
-```bash
-airc browse
-```
-
-Opens the config directory in your file browser for easy exploration.
-
-#### `remove <path>`
-
-Remove a config file from your local directory.
-
-```bash
-airc remove <path> [options]
-```
-
-**Arguments:**
-- `path` - Config file path relative to `~/.airc/config/` (e.g., `skills/my-source/web-design.md`)
-
-**Options:**
-- `-f, --force` - Confirm removal without prompt (required)
-
-**Examples:**
-```bash
-airc remove skills/my-source/web-design.md --force
-airc remove commands/external/check-types.md --force
-```
-
-**What happens:**
-- Config file is deleted from `~/.airc/config/`
-- Metadata is cleaned up from `.aircrc`
-- Helpful restore hint is displayed (use `airc source update` to restore)
-
-#### `list`
-
-List all configs in user config directory with their details.
-
-```bash
-airc list [options]
-```
-
-**Options:**
-- `-t, --type <type>` - Filter by type (commands, skills, agents)
-- `-v, --verbose` - Show detailed information (file counts, last updated time)
-
-#### `status`
-
-Show status of sources and configs.
-
-```bash
-airc status
-```
-
-Shows:
-- Initialization status
-- Sources status (up-to-date, behind, ahead, diverged)
-- Configs status (total, linked, imported, by type)
-
-#### `create <type> <name>`
-
-Create a new config in user directory.
-
-```bash
-airc create <type> <name> [options]
-```
-
-**Arguments:**
-- `type` - Config type (command, skill, agent)
-- `name` - Config name (lowercase, numbers, hyphens only)
-
-**Options:**
-- `-d, --description <description>` - Config description
-- `-f, --force` - Overwrite existing config
-
-#### `edit <type> <name>`
-
-Edit a config in your default editor.
-
-```bash
-airc edit <type> <name>
-```
-
-**Arguments:**
-- `type` - Config type (command, skill, agent)
-- `name` - Config name
-
-Uses `$EDITOR` or `$VISUAL` environment variable (defaults to vi).
-
-#### `install <tool>`
-
-Install configuration files to a specific AI tool.
-
-```bash
-airc install <tool> [options]
-```
-
-**Arguments:**
-- `tool` - AI tool name (claude, gemini, cursor, copilot, antigravity, opencode)
-
-**Options:**
-- `-c, --config-path <path>` - Path to config folder (default: user config)
-- `-f, --force` - Overwrite existing files without prompting
-- `-g, --global` - Install to global directory (~/.tool) instead of project directory
-
-**Supported AI Tools:**
-
-| Tool | Project Path | Global Path | Format Conversion |
-|------|-------------|-------------|-------------------|
-| `claude` | `.claude/` | `~/.claude/` | None (native format) |
-| `gemini` | `.gemini/` | `~/.gemini/` | Commands → TOML |
-| `cursor` | `.cursor/` | `~/.cursor/` | None (native format) |
-| `copilot` | `.github/` | `~/.copilot/` | Commands → .prompt.md |
-| `antigravity` | `.gemini/antigravity/` | `~/.gemini/antigravity/` | Commands → YAML workflows |
-| `opencode` | `.opencode/` | `~/.config/opencode/` | None (native format) |
-
-## Common Workflows
-
-### First Time Setup
-
-```bash
-# 1. Initialize airc
-airc init
-
-# 2. Add your config sources
-airc source add https://github.com/myteam/ai-configs --name team-configs
-airc source add https://github.com/personal/my-skills --name personal
-
-# 3. View what was copied
-airc list
-
-# 4. Install to your AI tool (e.g., Claude)
+# Install to Claude for your project only(<project-root>/.claude)
+cd <project-root>
 airc install claude
-```
-
-### Using Sparse Checkout for Large Repositories
-
-```bash
-# Clone only the "custom-prompts" subfolder
-airc source add https://github.com/bigorg/ai-resources/tree/main/custom-prompts
 
-# This clones only the specified subfolder, saving disk space and time
-```
-
-### Updating Configs from Upstream
-
-```bash
-# Update specific source
-airc source update team-configs
-
-# Or update all sources at once
-airc source update --all
-
-# Then reinstall to apply changes
-airc install claude --force
-```
-
-### Managing Multiple Sources with Conflicts
-
-```bash
-# Add multiple sources that might have overlapping file names
-airc source add https://github.com/team-a/configs --name team-a
-airc source add https://github.com/team-b/configs --name team-b
-
-# Files are organized by source prefix
-airc list
-# Output shows:
-# skills/team-a/web-design.md
-# skills/team-b/web-design.md
-
-# Both versions are installed without conflicts
-airc install claude
-```
-
-### Removing Unwanted Configs
-
-```bash
-# Remove a specific config file
-airc remove skills/team-a/old-skill.md --force
-
-# If you change your mind, restore it from source
-airc source update team-a
-```
-
-### Working Across Multiple Projects
-
-```bash
-# Install to project-specific directory (default)
-cd ~/projects/my-app
-airc install claude
-
-# Install globally for all projects
+# Install globally(~/.claude)
 airc install claude --global
 ```
 
-### Project Structure
-
-```
-airc/
-├── config/                    # Default configuration files
-│   └── .claude/               # Source configs (Claude format)
-│       ├── commands/          # Command definitions
-│       ├── skills/            # Skill definitions
-│       └── agents/            # Agent definitions
-├── src/                       # Source code
-│   ├── commands/              # CLI commands
-│   │   ├── init.ts            # Initialize user config
-│   │   ├── sourceAdd.ts       # Add git sources (with auto-copy)
-│   │   ├── sourceList.ts      # List sources
-│   │   ├── sourceRemove.ts    # Remove sources
-│   │   ├── sourceUpdate.ts    # Update sources (smart update)
-│   │   ├── sourceCheck.ts     # Check source status
-│   │   ├── browse.ts          # Browse available configs
-│   │   ├── remove.ts          # Remove configs
-│   │   ├── list.ts            # List local configs
-│   │   ├── status.ts          # Show status
-│   │   ├── create.ts          # Create new configs
-│   │   ├── edit.ts            # Edit configs
-│   │   └── install.ts         # Install to AI tools
-│   ├── utils/                 # Utility functions
-│   │   ├── copy.ts            # File copying with conversion
-│   │   ├── converters.ts      # Format converters
-│   │   ├── paths.ts           # Path resolution
-│   │   ├── validation.ts      # Input validation
-│   │   ├── userConfig.ts      # User config management
-│   │   └── sourceUtils.ts     # Git source utilities
-│   ├── cli.ts                 # CLI entry point
-│   └── types.ts               # TypeScript types
-├── dist/                      # Compiled JavaScript
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
-### User Config Directory Structure
-
-After running `airc init`, your user config directory:
-
-```
-~/.airc/
-├── config/                    # Local config storage
-│   ├── skills/                # Skills by source
-│   │   ├── my-configs/        # From source "my-configs"
-│   │   │   └── web-design.md
-│   │   └── other-source/      # From source "other-source"
-│   │       └── api-helper.md
-│   ├── commands/              # Commands by source
-│   │   └── my-configs/
-│   │       └── check-types.md
-│   └── agents/                # Agents by source
-│       └── my-configs/
-│           └── code-reviewer.md
-├── sources/                   # Git source repositories
-│   ├── my-configs/            # Cloned source repository
-│   │   └── (repository files)
-│   └── other-source/
-│       └── (repository files)
-└── .aircrc                    # User configuration file (with metadata)
-```
-
-## Development
-
-### Scripts
-
-- `bun run build` - Build the TypeScript project
-- `bun test` - Run tests (532+ tests, >80% coverage)
-- `bun run test:watch` - Run tests in watch mode
-- `bun run lint` - Lint the source code using oxlint
-- `bun run airc` - Run CLI during development
-
-### Adding a New AI Tool
-
-To add support for a new AI tool:
-
-1. **Update types** (`src/types.ts`):
-   - Add to `AIType` union
-   - Add to `AI_FOLDERS` mapping
-   - Add to `AI_SUBFOLDERS` mapping
-
-2. **Update paths** (`src/utils/paths.ts`):
-   - Add entry to `TOOL_PATHS` with project/global paths and subfolders
-
-3. **Add converter** (`src/utils/converters.ts`):
-   - Add converter function if format transformation is needed
-
-4. **Update copy logic** (`src/utils/copy.ts`):
-   - Add tool-specific limitations if any
-
-5. **Update documentation**:
-   - Update README.md with supported tools table
-   - Add format conversion examples if applicable
-
-### Format Conversions
-
-The tool automatically converts Claude command format to tool-specific formats:
-
-**Gemini CLI (.toml):**
-```toml
-[[command]]
-name = "command-name"
-description = "Command description"
-
-[prompt]
-type = "text"
-content = """
-Command content
-"""
-```
-
-**GitHub Copilot (.prompt.md):**
-```markdown
-# Command Description
-
-Command content
-```
-
-**Antigravity (.yaml):**
-```yaml
-name: "command-name"
-description: "Command description"
-
-rules:
-  - "Analyze the user's request"
-  - "Follow the task instructions below"
-
-prompt: |
-  Command content
-```
-
-## Testing
-
-The project includes comprehensive tests:
+### 4. Update imported config
 
 ```bash
-# Run all tests
-bun test
-
-# Run tests in watch mode
-bun run test:watch
+airc source update react-best-practices
 ```
 
-Test coverage includes:
-- Type definitions and validation
-- User config initialization and management
-- Git source operations (add, list, remove, update, check)
-- GitHub tree URL parsing and sparse checkout
-- Folder scanning and categorization (with fuzzy matching)
-- File hashing and change detection
-- Config file copying with source prefix
-- Metadata tracking and smart updates
-- Config browsing and discovery
-- Config removal with metadata cleanup
-- Config creation and editing
-- Path resolution for all tools and scopes
-- Format conversion for all target tools
-- Copy operations with and without force flag
-- Global vs project-level installations
-- Integration tests for full workflows
-- Error handling and edge cases
-
-**Test Stats:**
-- 532+ tests across 29+ test files
-- ~111ms execution time
-- Full coverage of all commands and utilities
-
-## Key Concepts
-
-### Source-Based Config Management
-
-Sources are git repositories containing config files:
-- Automatically cloned to `~/.airc/sources/` when added
-- Config files are automatically copied to `~/.airc/config/{type}/{source-name}/`
-- Can be updated with `airc source update` (smart update - only changed files)
-- Metadata is tracked in `.aircrc` for efficient updates
-
-### Sparse Checkout Support
-
-GitHub tree URLs enable sparse checkout (only specified subfolder):
-```bash
-# Regular URL - clones entire repository
-airc source add https://github.com/user/configs
-
-# Tree URL - clones only "custom-skills" subfolder
-airc source add https://github.com/user/configs/tree/main/custom-skills
-```
-
-### Smart Updates
-
-When you run `airc source update`, the tool intelligently:
-- **UPDATE**: Files with changed hashes (re-copies with updated content)
-- **ADD**: New files from source (copies to local directory)
-- **SKIP**: Files with unchanged hashes (no action needed)
-- **KEEP**: Files deleted from source (conservative approach - doesn't delete)
+### 5. Removing Unwanted Configs
 
-### Conflict Resolution
-
-Multiple sources can have files with the same name. Source prefix directories prevent conflicts and allow easy identification:
-
-**Example Scenario:**
 ```bash
-# Add first source with web-design.md
-airc source add https://github.com/team-a/configs --name team-a
-
-# Add second source also containing web-design.md
-airc source add https://github.com/team-b/configs --name team-b
+airc remove react-best-practices
 ```
 
-**Result:**
-```
-~/.airc/config/
-├── skills/
-│   ├── team-a/
-│   │   └── web-design.md    ← From team-a's repository
-│   └── team-b/
-│       └── web-design.md    ← From team-b's repository
-```
-
-**Installation:**
-```bash
-# Both versions coexist and can be installed
-airc list --type skills
-# Output:
-# skills/team-a/web-design.md (source: team-a)
-# skills/team-b/web-design.md (source: team-b)
-
-# Install to Claude (both will be installed)
-airc install claude
-```
+### 6. Add your own configs
 
-### Installation Flow
+Initially we have three folders in config folder(skills / commands / agents), but you can add your own custom folder, they will be copied to target folder when using `airc install` command:
 
 ```
-Git Source → Auto-Copy → Local Config (~/.airc) → Install → AI Tool
+airc/
+├── config/           # Default configuration files
+│   ├── commands/     # Command definitions
+│   ├── skills/       # Skill definitions
+│   ├── agents/       # Agent definitions
+│   └── scripts/      # Add your own config folder
 ```
-
-1. Add source repository (`airc source add`)
-2. Configs are automatically copied to local directory
-3. Install configs to specific AI tools (`airc install`)
-
-## Error Handling
-
-The CLI provides clear error messages for common issues:
-
-- **Invalid AI tool**: Shows list of supported tools
-- **Missing config path**: Prompts to initialize airc or add sources
-- **Target exists**: Warns about existing files and suggests --force flag
-- **Conversion failures**: Logs warnings for files that couldn't be converted
-- **Unsupported features**: Notes when a tool doesn't support certain features (e.g., Copilot global agents)
-
-## Special Behaviors
-
-### Tool-Specific Limitations
-
-- **Gemini**: Does not support agents (agents folder is skipped)
-- **Antigravity**: Does not support commands or agents (only workflows/skills)
-- **Copilot Global**: Does not support agents (agents folder is skipped with info message)
-
-### File Format Handling
-
-- **.md files**: Converted based on target tool format
-- **Other files**: Copied as-is without conversion
-
-## License
-
-MIT
-
-## Contributing
-
-Contributions are welcome! Please ensure:
-
-1. All tests pass (`bun test`)
-2. Test coverage remains above 80%
-3. Code follows the existing style
-4. Commit messages are clear and descriptive
-
-## Support
-
-For issues and questions, please open an issue on the project repository.