@prmichaelsen/acp-visualizer 0.1.0

package/agent/commands/acp.package-remove.md

@@ -0,0 +1,293 @@
+# Command: package-remove
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp.package-remove` has been invoked. Follow the steps below to execute this command.
+
+**Namespace**: acp
+**Version**: 2.0.0
+**Created**: 2026-02-18
+**Last Updated**: 2026-02-22
+**Status**: Active
+**Scripts**: acp.package-remove.sh, acp.common.sh, acp.yaml-parser.sh
+
+---
+
+**Purpose**: Remove installed ACP packages and clean up manifest
+**Category**: Maintenance
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+
+This command removes installed ACP packages by deleting their files from `agent/` directories and removing their entries from `agent/manifest.yaml`. It can optionally preserve locally modified files to prevent accidental loss of customizations.
+
+Use this command when you no longer need a package, want to clean up unused dependencies, or need to reinstall a package from scratch.
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project
+- [ ] `agent/manifest.yaml` exists with installed packages
+- [ ] `agent/scripts/acp.package-remove.sh` exists
+- [ ] Package to remove is actually installed
+
+---
+
+## Steps
+
+### 1. Run Package Remove Script
+
+Execute the remove script with the package name.
+
+**Actions**:
+- Run `./agent/scripts/acp.package-remove.sh` with package name:
+  ```bash
+  # Interactive mode (asks for confirmation)
+  ./agent/scripts/acp.package-remove.sh <package-name>
+  
+  # Auto-confirm mode (skips prompts)
+  ./agent/scripts/acp.package-remove.sh -y <package-name>
+  
+  # Keep modified files
+  ./agent/scripts/acp.package-remove.sh --keep-modified <package-name>
+  ```
+- The script will:
+  - Verify package is installed
+  - List files that will be removed
+  - Detect locally modified files via checksums
+  - Ask for confirmation (unless -y flag used)
+  - Remove files (or keep modified ones if --keep-modified)
+  - Remove package entry from manifest
+  - Update manifest timestamp
+  - Report removal summary
+
+**Expected Outcome**: Package removed successfully
+
+### 2. Verify Removal
+
+Check that files were removed correctly.
+
+**Actions**:
+- Verify files deleted from `agent/` directories
+- Check `agent/manifest.yaml` no longer has package entry
+- If `--keep-modified` used, verify modified files were kept
+- Confirm no orphaned files remain
+
+**Expected Outcome**: Package completely removed (or modified files kept)
+
+### 3. Document Removal
+
+Update progress tracking with removal notes.
+
+**Actions**:
+- Add note to `agent/progress.yaml` about package removal
+- Document which package was removed
+- Note removal date
+- List any kept files (if --keep-modified used)
+
+**Expected Outcome**: Removal tracked in progress
+
+---
+
+## Verification
+
+- [ ] Script executed successfully
+- [ ] Package files removed from agent/ directories
+- [ ] Package entry removed from manifest
+- [ ] Modified files kept if --keep-modified used
+- [ ] Manifest timestamp updated
+- [ ] Removal summary displayed
+- [ ] No errors during removal
+
+---
+
+## Expected Output
+
+### Files Modified
+- `agent/manifest.yaml` - Package entry removed, timestamp updated
+- `agent/patterns/*.md` - Pattern files deleted
+- `agent/commands/*.md` - Command files deleted
+- `agent/design/*.md` - Design files deleted
+
+### Console Output
+
+**Standard Removal**:
+```
+📦 ACP Package Remover
+========================================
+
+Package: firebase (1.2.0)
+
+⚠️  This will remove:
+  - 3 pattern(s)
+  - 2 command(s)
+  - 1 design(s)
+
+Total: 6 file(s)
+
+Remove package 'firebase'? (y/N) y
+
+Removing files...
+  ✓ Removed patterns/user-scoped-collections.md
+  ✓ Removed patterns/firebase-security-rules.md
+  ✓ Removed patterns/firestore-queries.md
+  ✓ Removed commands/firebase.init.md
+  ✓ Removed commands/firebase.migrate.md
+  ✓ Removed design/firebase-architecture.md
+
+Updating manifest...
+✓ Manifest updated
+
+✅ Removal complete!
+
+Removed: 6 file(s)
+```
+
+**With Modified Files** (`--keep-modified`):
+```
+📦 ACP Package Remover
+========================================
+
+Package: firebase (1.2.0)
+
+⚠️  This will remove:
+  - 3 pattern(s)
+  - 2 command(s)
+  - 1 design(s)
+
+Total: 6 file(s)
+
+⚠️  Modified files detected:
+  - patterns/firebase-security-rules.md
+
+Modified files will be kept (--keep-modified)
+
+Remove package 'firebase'? (y/N) y
+
+Removing files...
+  ✓ Removed patterns/user-scoped-collections.md
+  ⊙ Kept patterns/firebase-security-rules.md (modified)
+  ✓ Removed patterns/firestore-queries.md
+  ✓ Removed commands/firebase.init.md
+  ✓ Removed commands/firebase.migrate.md
+  ✓ Removed design/firebase-architecture.md
+
+Updating manifest...
+✓ Manifest updated
+
+✅ Removal complete!
+
+Removed: 5 file(s)
+Kept: 1 file(s) (modified)
+```
+
+---
+
+## Examples
+
+### Example 1: Remove Package
+
+**Context**: No longer need firebase package
+
+**Invocation**: `@acp.package-remove firebase`
+
+**Result**: Prompts for confirmation, removes all 6 files, updates manifest
+
+### Example 2: Remove with Auto-Confirm
+
+**Context**: Want to remove without prompts
+
+**Invocation**: `@acp.package-remove -y firebase`
+
+**Result**: Removes package immediately without confirmation
+
+### Example 3: Keep Modified Files
+
+**Context**: Want to remove package but keep customized files
+
+**Invocation**: `@acp.package-remove --keep-modified firebase`
+
+**Result**: Removes 5 unmodified files, keeps 1 modified file, updates manifest
+
+### Example 4: Package Not Installed
+
+**Context**: Try to remove non-existent package
+
+**Invocation**: `@acp.package-remove nonexistent`
+
+**Result**: Error message "Package not installed: nonexistent", exits without changes
+
+---
+
+## Related Commands
+
+- [`@acp.package-install`](acp.package-install.md) - Install packages
+- [`@acp.package-list`](acp.package-list.md) - List installed packages
+- [`@acp.package-info`](acp.package-info.md) - Show package details
+- [`@acp.package-update`](acp.package-update.md) - Update packages
+
+---
+
+## Troubleshooting
+
+### Issue 1: Package not found
+
+**Symptom**: Error "Package not installed"
+
+**Cause**: Package name incorrect or not installed
+
+**Solution**: Run `@acp.package-list` to see installed packages, check spelling
+
+### Issue 2: Files not removed
+
+**Symptom**: Files still exist after removal
+
+**Cause**: Files were modified and --keep-modified was used
+
+**Solution**: This is intentional. Remove manually or run without --keep-modified
+
+### Issue 3: Manifest corrupted after removal
+
+**Symptom**: Manifest has syntax errors
+
+**Cause**: Rare edge case in awk processing
+
+**Solution**: Restore from git backup, reinstall packages
+
+---
+
+## Security Considerations
+
+### File Deletion
+- **Deletes**: All files installed by the package
+- **Preserves**: Modified files if --keep-modified used
+- **Irreversible**: Deleted files cannot be recovered (unless in git)
+
+### Best Practices
+- **Use git**: Commit before removing packages
+- **Review first**: Use `@acp.package-info` to see what will be removed
+- **Keep modified**: Use --keep-modified if you've customized files
+- **Backup**: Consider git commit or manual backup before removal
+
+---
+
+## Notes
+
+- Removal is permanent (unless files are in git)
+- Modified files detected via checksum comparison
+- Manifest entry completely removed
+- --keep-modified preserves customizations
+- Safe to remove and reinstall packages
+- Use `@acp.package-list --modified` to see which files would be kept
+
+---
+
+**Namespace**: acp
+**Command**: package-remove
+**Version**: 1.0.0
+**Created**: 2026-02-18
+**Last Updated**: 2026-02-18
+**Status**: Active
+**Compatibility**: ACP 2.0.0+
+**Author**: ACP Project

package/agent/commands/acp.package-search.md

@@ -0,0 +1,307 @@
+# Command: package-search
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp.package-search` has been invoked. Follow the steps below to execute this command.
+
+**Namespace**: acp
+**Version**: 1.0.0
+**Created**: 2026-02-18
+**Last Updated**: 2026-02-18
+**Status**: Active
+**Scripts**: acp.package-search.sh, acp.common.sh
+
+---
+
+**Purpose**: Discover ACP packages on GitHub using the GitHub API
+**Category**: Package Discovery
+**Frequency**: As Needed
+
+---
+
+## What This Command Does
+
+This command searches GitHub for ACP packages using the GitHub API. **By default, it only searches repositories with the `acp-package` topic**, ensuring you only see actual ACP packages and not unrelated repositories.
+
+It fetches `package.yaml` metadata from each result and displays comprehensive information including version, description, tags, stars, and installation commands.
+
+Use this command when you want to discover available ACP packages, find packages for specific technologies (via tags), or browse community-created patterns and commands.
+
+---
+
+## Prerequisites
+
+- [ ] Internet connection available
+- [ ] `curl` command available
+- [ ] `agent/scripts/acp.package-search.sh` exists
+- [ ] Optional: `GITHUB_TOKEN` environment variable for higher rate limits
+
+---
+
+## Steps
+
+### 1. Run Package Search Script
+
+Execute the search script with your query.
+
+**Actions**:
+- Run `./agent/scripts/acp.package-search.sh` with search terms:
+  ```bash
+  # Search by keyword
+  ./agent/scripts/acp.package-search.sh firebase
+  
+  # Filter by tag
+  ./agent/scripts/acp.package-search.sh oauth --tag authentication
+  
+  # Search specific user's packages
+  ./agent/scripts/acp.package-search.sh --user prmichaelsen
+  
+  # Sort by recently updated
+  ./agent/scripts/acp.package-search.sh --sort updated --limit 5
+  ```
+
+**Expected Outcome**: Search results displayed
+
+### 2. Review Search Results
+
+Analyze the displayed packages.
+
+**Actions**:
+- Review package names and versions
+- Read descriptions
+- Check star counts (popularity indicator)
+- Note tags (technology indicators)
+- Identify relevant packages for your project
+
+**Expected Outcome**: Suitable packages identified
+
+### 3. Install Selected Package
+
+Use the provided installation command.
+
+**Actions**:
+- Copy installation command from search results
+- Run `@acp.package-install <url>` with the package URL
+- Follow installation prompts
+
+**Expected Outcome**: Package installed successfully
+
+---
+
+## Syntax
+
+```bash
+./agent/scripts/acp.package-search.sh [query] [options]
+
+Options:
+  --tag <tag>              Filter by additional tag
+  --user <username>        Search specific user's repos
+  --org <org>              Search specific organization
+  --sort <field>           Sort by: stars, updated, name (default: stars)
+  --limit <n>              Limit results (default: 10, max: 100)
+```
+
+---
+
+## Verification
+
+- [ ] Script executed successfully
+- [ ] GitHub API queried successfully
+- [ ] Results displayed with all metadata
+- [ ] Package versions shown
+- [ ] Tags displayed
+- [ ] Star counts shown
+- [ ] Installation commands provided
+- [ ] Filters work correctly
+- [ ] Handles no results gracefully
+- [ ] Handles API errors gracefully
+
+---
+
+## Expected Output
+
+### Files Modified
+None - this is a read-only command
+
+### Console Output
+```
+🔍 ACP Package Search
+========================================
+
+ℹ Searching GitHub for: firebase+topic:acp-package
+ℹ Sort by: stars
+ℹ Limit: 10
+
+📦 Found 3 package(s)
+
+1. firebase (1.2.0) ⭐ 45
+   https://github.com/prmichaelsen/acp-firebase
+   Firebase patterns and utilities for ACP projects
+   Tags: firebase, firestore, database, backend
+   Install: ./agent/scripts/acp.package-install.sh https://github.com/prmichaelsen/acp-firebase.git
+
+2. firebase-v11 (1.0.0) ⭐ 12
+   https://github.com/otheruser/acp-firebase-v11
+   Firebase patterns for v11 Admin SDK
+   Tags: firebase, firebase-v11, legacy
+   Install: ./agent/scripts/acp.package-install.sh https://github.com/otheruser/acp-firebase-v11.git
+
+3. fullstack (2.0.0) ⭐ 89
+   https://github.com/community/acp-fullstack
+   Complete fullstack patterns including Firebase
+   Tags: firebase, cloudflare, tanstack, fullstack
+   Install: ./agent/scripts/acp.package-install.sh https://github.com/community/acp-fullstack.git
+
+Showing 3 of 3 result(s)
+
+To install a package:
+  ./agent/scripts/acp.package-install.sh <repository-url>
+```
+
+---
+
+## Examples
+
+### Example 1: Search by Keyword
+
+**Context**: Looking for Firebase-related packages
+
+**Invocation**: `@acp.package-search firebase`
+
+**Result**: Shows 3 packages with firebase in name/description/tags, sorted by stars
+
+### Example 2: Filter by Tag
+
+**Context**: Need OAuth authentication patterns
+
+**Invocation**: `@acp.package-search oauth --tag authentication`
+
+**Result**: Shows packages tagged with both "oauth" and "authentication"
+
+### Example 3: Browse User's Packages
+
+**Context**: Want to see all packages from specific author
+
+**Invocation**: `@acp.package-search --user prmichaelsen`
+
+**Result**: Shows all acp-package repos from prmichaelsen
+
+### Example 4: Find Recent Packages
+
+**Context**: Want to see recently updated packages
+
+**Invocation**: `@acp.package-search --sort updated --limit 5`
+
+**Result**: Shows 5 most recently updated packages
+
+### Example 5: No Results
+
+**Context**: Search for non-existent package
+
+**Invocation**: `@acp.package-search nonexistent123`
+
+**Result**: "No packages found matching your search", suggests trying broader terms
+
+---
+
+## Related Commands
+
+- [`@acp.package-install`](acp.package-install.md) - Install discovered packages
+- [`@acp.package-list`](acp.package-list.md) - List installed packages
+- [`@acp.package-info`](acp.package-info.md) - Show package details
+
+---
+
+## GitHub API Details
+
+### Rate Limits
+- **Without token**: 60 requests/hour
+- **With token**: 5,000 requests/hour
+
+### Setting GitHub Token
+```bash
+export GITHUB_TOKEN="your_github_token"
+```
+
+### API Endpoints Used
+- `GET /search/repositories` - Search repos by topic
+- `GET /repos/{owner}/{repo}/contents/package.yaml` - Fetch metadata
+
+---
+
+## Package Discovery Requirements
+
+For packages to be discoverable via `@acp.package-search`:
+
+1. **GitHub Topic** (REQUIRED): Add `acp-package` topic to repository
+   - This is the canonical way to identify ACP packages
+   - Without this topic, packages will NOT appear in search results
+2. **package.yaml**: Include in repository root with:
+   ```yaml
+   name: package-name
+   version: 1.0.0
+   description: Clear description
+   tags:
+     - tag1
+     - tag2
+   ```
+3. **Clear Description**: Add description to GitHub repository
+4. **ACP Structure**: Follow standard `agent/` directory structure
+
+**Note**: The `topic:acp-package` filter is always applied to ensure search results contain only actual ACP packages, not unrelated repositories with "acp" in the name.
+
+---
+
+## Troubleshooting
+
+### Issue 1: No results found
+
+**Symptom**: "No packages found"
+
+**Cause**: No packages match search criteria
+
+**Solution**: Try broader search terms, remove filters, check spelling
+
+### Issue 2: API rate limit exceeded
+
+**Symptom**: "API rate limit exceeded" error
+
+**Cause**: Made too many requests (60/hour without token)
+
+**Solution**: Wait for rate limit reset, or set GITHUB_TOKEN for higher limits
+
+### Issue 3: Package.yaml not found
+
+**Symptom**: Version shows "unknown"
+
+**Cause**: Package doesn't have package.yaml in root
+
+**Solution**: This is informational only, package can still be installed
+
+### Issue 4: Slow response
+
+**Symptom**: Search takes long time
+
+**Cause**: Fetching package.yaml for each result
+
+**Solution**: This is normal, reduce --limit for faster results
+
+---
+
+## Notes
+
+- Requires internet connection
+- Uses GitHub API (no authentication required for basic use)
+- Fetches package.yaml for each result (adds latency)
+- Results cached by GitHub (may not show very recent packages)
+- Set GITHUB_TOKEN for higher rate limits
+- Packages must have `acp-package` topic to be discoverable
+
+---
+
+**Namespace**: acp
+**Command**: package-search
+**Version**: 1.0.0
+**Created**: 2026-02-18
+**Last Updated**: 2026-02-18
+**Status**: Active
+**Compatibility**: ACP 2.0.0+
+**Author**: ACP Project