124 lines
4.0 KiB
Markdown
124 lines
4.0 KiB
Markdown
# CLI Reference - Primary Knowledge Source
|
|
|
|
**Primary Reference:** `{project-root}/tools/cli/README.md`
|
|
|
|
This document contains Scott's curated knowledge about the CLI system. The full README should always be consulted for complete details.
|
|
|
|
## Quick Architecture Overview
|
|
|
|
### Two Primary Functions
|
|
|
|
1. **Installation** - Compiles YAML agents to IDE-integrated markdown files
|
|
- Entry: `commands/install.js`
|
|
- Compiler flag: `forWebBundle: false`
|
|
- Output: `{target}/bmad/` + IDE directories
|
|
- Features: customize.yaml merging, IDE artifacts, manifest generation
|
|
|
|
2. **Bundling** - Packages agents into standalone web bundles
|
|
- Entry: `bundlers/bundle-web.js`
|
|
- Compiler flag: `forWebBundle: true`
|
|
- Output: `web-bundles/`
|
|
- Features: Inline dependencies, no filesystem access needed
|
|
|
|
### Core Components
|
|
|
|
**Compilation Engine** (`lib/yaml-xml-builder.js`)
|
|
|
|
- Converts YAML agents to XML
|
|
- Handles both IDE and web formats
|
|
- Uses fragment system for modular activation blocks
|
|
|
|
**Installer** (`installers/lib/core/installer.js`)
|
|
|
|
- Orchestrates full installation flow
|
|
- Manages 6 stages: input → pre-install → install → IDE → manifests → validation
|
|
|
|
**IDE System** (`installers/lib/ide/`)
|
|
|
|
- 14 IDE integrations via base-derived architecture
|
|
- BaseIDE class provides common functionality
|
|
- Each handler implements: setup(), createArtifacts(), cleanup()
|
|
|
|
**Manifest Generator** (`installers/lib/core/manifest-generator.js`)
|
|
|
|
- Creates 5 manifest files: installation, workflows, agents, tasks, files
|
|
- Enables update detection and integrity validation
|
|
|
|
### Key Directories
|
|
|
|
```
|
|
tools/cli/
|
|
├── bmad-cli.js # Main entry point
|
|
├── commands/ # CLI command handlers
|
|
├── bundlers/ # Web bundling system
|
|
├── installers/ # Installation system
|
|
│ └── lib/
|
|
│ ├── core/ # Core installer logic
|
|
│ ├── modules/ # Module processing
|
|
│ └── ide/ # IDE integrations
|
|
└── lib/ # Shared compilation utilities
|
|
```
|
|
|
|
### Fragment System
|
|
|
|
Location: `src/utility/models/fragments/`
|
|
|
|
- `activation-steps.xml` - IDE activation (filesystem-aware)
|
|
- `web-bundle-activation-steps.xml` - Web activation (bundled)
|
|
- `menu-handlers.xml` - Menu handler wrapper
|
|
- `handler-*.xml` - Individual handler types (workflow, exec, tmpl, data, action)
|
|
|
|
Fragments are injected dynamically based on agent capabilities.
|
|
|
|
### Common Operations
|
|
|
|
**Adding New IDE Support:**
|
|
|
|
1. Create handler: `installers/lib/ide/{ide-code}.js`
|
|
2. Extend BaseIDE class
|
|
3. Implement required methods
|
|
4. Auto-discovered on next run
|
|
|
|
**Adding Menu Handlers:**
|
|
|
|
1. Create fragment: `fragments/handler-{type}.xml`
|
|
2. Update agent-analyzer.js to detect attribute
|
|
3. Update activation-builder.js to inject fragment
|
|
|
|
**Debugging Installation:**
|
|
|
|
- Check logs for compilation errors
|
|
- Verify target directory permissions
|
|
- Validate module dependencies resolved
|
|
- Confirm IDE artifacts created
|
|
|
|
## Scott's Operational Notes
|
|
|
|
### Common Issues to Watch For
|
|
|
|
1. **Path Resolution** - Always use `{project-root}` variables
|
|
2. **Backward Compatibility** - Test with existing installations
|
|
3. **IDE Artifacts** - Verify creation for all selected IDEs
|
|
4. **Config Merging** - Ensure customize.yaml properly merged
|
|
5. **Manifest Generation** - All 5 files must be created
|
|
|
|
### Best Practices
|
|
|
|
1. **Test in Isolation** - Use temporary directories for testing
|
|
2. **Check Dependencies** - 4-pass system should resolve all refs
|
|
3. **Validate Compilation** - Every agent must compile without errors
|
|
4. **Verify Integrity** - File hashes must match manifests
|
|
5. **Document Changes** - Update README when adding features
|
|
|
|
### Future Enhancement Areas
|
|
|
|
- Enhanced error reporting with recovery suggestions
|
|
- Installation dry-run mode
|
|
- Partial update capability
|
|
- Better rollback mechanisms
|
|
- Performance optimization for large module sets
|
|
|
|
---
|
|
|
|
**Captain's Note:** This is a living document. Update as patterns emerge and knowledge grows!
|