@zeyue0329/xiaoma-cli 1.0.48 → 6.0.0-alpha.13

package/custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/installers.md

@@ -0,0 +1,134 @@
+# Installers Domain
+
+## File Index
+
+### Core CLI
+
+- @/tools/cli/xiaoma-cli.js - Main CLI entry (uses Commander.js, auto-loads commands)
+- @/tools/cli/README.md - CLI documentation
+
+### Commands Directory
+
+- @/tools/cli/commands/install.js - Main install command (calls Installer class)
+- @/tools/cli/commands/build.js - Build operations
+- @/tools/cli/commands/list.js - List resources
+- @/tools/cli/commands/update.js - Update operations
+- @/tools/cli/commands/status.js - Status checks
+- @/tools/cli/commands/agent-install.js - Custom agent installation
+- @/tools/cli/commands/uninstall.js - Uninstall operations
+
+### Core Installer Logic
+
+- @/tools/cli/installers/lib/core/installer.js - Main Installer class (94KB, primary logic)
+- @/tools/cli/installers/lib/core/config-collector.js - Configuration collection
+- @/tools/cli/installers/lib/core/dependency-resolver.js - Dependency resolution
+- @/tools/cli/installers/lib/core/detector.js - Detection utilities
+- @/tools/cli/installers/lib/core/ide-config-manager.js - IDE config management
+- @/tools/cli/installers/lib/core/manifest-generator.js - Manifest generation
+- @/tools/cli/installers/lib/core/manifest.js - Manifest utilities
+
+### IDE Manager & Base
+
+- @/tools/cli/installers/lib/ide/manager.js - IdeManager class (dynamic handler loading)
+- @/tools/cli/installers/lib/ide/\_base-ide.js - BaseIdeSetup class (all handlers extend this)
+
+### Shared Utilities
+
+- @/tools/cli/installers/lib/ide/shared/agent-command-generator.js
+- @/tools/cli/installers/lib/ide/shared/workflow-command-generator.js
+- @/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js
+- @/tools/cli/installers/lib/ide/shared/module-injections.js
+- @/tools/cli/installers/lib/ide/shared/xiaoma-artifacts.js
+
+### CLI Library Files
+
+- @/tools/cli/lib/ui.js - User interface prompts
+- @/tools/cli/lib/config.js - Configuration utilities
+- @/tools/cli/lib/project-root.js - Project root detection
+- @/tools/cli/lib/platform-codes.js - Platform code definitions
+- @/tools/cli/lib/xml-handler.js - XML processing
+- @/tools/cli/lib/yaml-format.js - YAML formatting
+- @/tools/cli/lib/file-ops.js - File operations
+- @/tools/cli/lib/agent/compiler.js - Agent YAML to XML compilation
+- @/tools/cli/lib/agent/installer.js - Agent installation
+- @/tools/cli/lib/agent/template-engine.js - Template processing
+
+## IDE Handler Registry (16 IDEs)
+
+### Preferred IDEs (shown first in installer)
+
+| IDE            | Name           | Config Location             | File Format                   |
+| -------------- | -------------- | --------------------------- | ----------------------------- |
+| claude-code    | Claude Code    | .claude/commands/           | .md with frontmatter          |
+| codex          | Codex          | (varies)                    | .md                           |
+| cursor         | Cursor         | .cursor/rules/xiaoma/       | .mdc with MDC frontmatter     |
+| github-copilot | GitHub Copilot | .github/                    | .md                           |
+| opencode       | OpenCode       | .opencode/                  | .md                           |
+| windsurf       | Windsurf       | .windsurf/workflows/xiaoma/ | .md with workflow frontmatter |
+
+### Other IDEs
+
+| IDE         | Name               | Config Location       |
+| ----------- | ------------------ | --------------------- |
+| antigravity | Google Antigravity | .agent/               |
+| auggie      | Auggie CLI         | .augment/             |
+| cline       | Cline              | .clinerules/          |
+| crush       | Crush              | .crush/               |
+| gemini      | Gemini CLI         | .gemini/              |
+| iflow       | iFlow CLI          | .iflow/               |
+| kilo        | Kilo Code          | .kilocodemodes (file) |
+| qwen        | Qwen Code          | .qwen/                |
+| roo         | Roo Code           | .roomodes (file)      |
+| trae        | Trae               | .trae/                |
+
+## Architecture Patterns
+
+### IDE Handler Interface
+
+Each handler must implement:
+
+- `constructor()` - Call super(name, displayName, preferred)
+- `setup(projectDir, xiaomaDir, options)` - Main installation
+- `cleanup(projectDir)` - Remove old installation
+- `installCustomAgentLauncher(...)` - Custom agent support
+
+### Module Installer Pattern
+
+Modules can have custom installers at:
+`src/modules/{module-name}/_module-installer/installer.js`
+
+Export: `async function install(options)` with:
+
+- options.projectRoot
+- options.config
+- options.installedIDEs
+- options.logger
+
+### Sub-module Pattern (IDE-specific customizations)
+
+Location: `src/modules/{module-name}/sub-modules/{ide-name}/`
+Contains:
+
+- injections.yaml - Content injections
+- config.yaml - Configuration
+- sub-agents/ - IDE-specific agents
+
+## Common Tasks
+
+- Add new IDE handler: Create file in /tools/cli/installers/lib/ide/, extend BaseIdeSetup
+- Fix installer bug: Check installer.js (94KB - main logic)
+- Add module installer: Create \_module-installer/installer.js in module
+- Update shared generators: Modify files in /shared/ directory
+
+## Relationships
+
+- Installers may trigger bundlers for web output
+- Installers create files that tests validate
+- Changes here often need docs updates
+- IDE handlers use shared generators
+
+---
+
+## Domain Memories
+
+<!-- Vexor appends installer-specific learnings here -->

package/custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/modules.md

@@ -0,0 +1,160 @@
+# Modules Domain
+
+## File Index
+
+### Module Source Locations
+
+- @/src/modules/xmb/ - XIAOMA Builder module
+- @/src/modules/xmc/ - XIAOMA Method module (flagship)
+- @/src/modules/cis/ - Creative Innovation Studio module
+- @/src/modules/core/ - Core module (always installed)
+
+### Module Structure Pattern
+
+```
+src/modules/{module-name}/
+├── agents/                    # Agent YAML files
+├── workflows/                 # Workflow directories
+├── tasks/                     # Task definitions
+├── tools/                     # Tool definitions
+├── templates/                 # Document templates
+├── teams/                     # Team definitions
+├── _module-installer/         # Custom installer (optional)
+│   └── installer.js
+├── sub-modules/               # IDE-specific customizations
+│   └── {ide-name}/
+│       ├── injections.yaml
+│       ├── config.yaml
+│       └── sub-agents/
+├── install-config.yaml        # Module install configuration
+└── README.md                  # Module documentation
+```
+
+### XMC Sub-modules (Example)
+
+- @/src/modules/xmc/sub-modules/claude-code/
+  - README.md - Sub-module documentation
+  - config.yaml - Configuration
+  - injections.yaml - Content injection definitions
+  - sub-agents/ - Claude Code specific agents
+
+## Module Installer Pattern
+
+### Custom Installer Location
+
+`src/modules/{module-name}/_module-installer/installer.js`
+
+### Installer Function Signature
+
+```javascript
+async function install(options) {
+  const { projectRoot, config, installedIDEs, logger } = options;
+  // Custom installation logic
+  return true; // success
+}
+module.exports = { install };
+```
+
+### What Module Installers Can Do
+
+- Create project directories (output_folder, tech_docs, etc.)
+- Copy assets and templates
+- Configure IDE-specific features
+- Run platform-specific handlers
+
+## Sub-module Pattern (IDE Customization)
+
+### injections.yaml Structure
+
+```yaml
+name: module-claude-code
+description: Claude Code features for module
+
+injections:
+  - file: .xiaoma/xmc/agents/pm.md
+    point: pm-agent-instructions
+    content: |
+      Injected content...
+    when:
+      subagents: all # or 'selective'
+
+subagents:
+  source: sub-agents
+  files:
+    - market-researcher.md
+    - requirements-analyst.md
+```
+
+### How Sub-modules Work
+
+1. Installer detects sub-module exists
+2. Loads injections.yaml
+3. Prompts user for options (subagent installation)
+4. Applies injections to installed files
+5. Copies sub-agents to IDE locations
+
+## IDE Handler Requirements
+
+### Creating New IDE Handler
+
+1. Create file: `tools/cli/installers/lib/ide/{ide-name}.js`
+2. Extend BaseIdeSetup
+3. Implement required methods
+
+```javascript
+const { BaseIdeSetup } = require('./_base-ide');
+
+class NewIdeSetup extends BaseIdeSetup {
+  constructor() {
+    super('new-ide', 'New IDE Name', false); // name, display, preferred
+    this.configDir = '.new-ide';
+  }
+
+  async setup(projectDir, xiaomaDir, options = {}) {
+    // Installation logic
+  }
+
+  async cleanup(projectDir) {
+    // Cleanup logic
+  }
+}
+
+module.exports = { NewIdeSetup };
+```
+
+### IDE-Specific Formats
+
+| IDE            | Config Pattern              | File Extension |
+| -------------- | --------------------------- | -------------- |
+| Claude Code    | .claude/commands/xiaoma/    | .md            |
+| Cursor         | .cursor/rules/xiaoma/       | .mdc           |
+| Windsurf       | .windsurf/workflows/xiaoma/ | .md            |
+| GitHub Copilot | .github/                    | .md            |
+
+## Platform Codes
+
+Defined in @/tools/cli/lib/platform-codes.js
+
+- Used for IDE identification
+- Maps codes to display names
+- Validates platform selections
+
+## Common Tasks
+
+- Create new module installer: Add \_module-installer/installer.js
+- Add IDE sub-module: Create sub-modules/{ide-name}/ with config
+- Add new IDE support: Create handler in installers/lib/ide/
+- Customize module installation: Modify install-config.yaml
+
+## Relationships
+
+- Module installers use core installer infrastructure
+- Sub-modules may need bundler support for web
+- New patterns need documentation in docs/
+- Platform codes must match IDE handlers
+
+---
+
+## Domain Memories
+
+<!-- Vexor appends module-specific learnings here -->

package/custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/tests.md

@@ -0,0 +1,103 @@
+# Tests Domain
+
+## File Index
+
+### Test Files
+
+- @/test/test-agent-schema.js - Agent schema validation tests
+- @/test/test-installation-components.js - Installation component tests
+- @/test/test-cli-integration.sh - CLI integration tests (shell script)
+- @/test/unit-test-schema.js - Unit test schema
+- @/test/README.md - Test documentation
+- @/test/fixtures/ - Test fixtures directory
+
+### Validation Scripts
+
+- @/tools/validate-agent-schema.js - Validates all agent YAML schemas
+- @/tools/validate-bundles.js - Validates bundle integrity
+
+## NPM Test Scripts
+
+```bash
+# Full test suite (recommended before commits)
+npm test
+
+# Individual test commands
+npm run test:schemas         # Run schema tests
+npm run test:install         # Run installation tests
+npm run validate:bundles     # Validate bundle integrity
+npm run validate:schemas     # Validate agent schemas
+npm run lint                 # ESLint check
+npm run format:check         # Prettier format check
+
+# Coverage
+npm run test:coverage        # Run tests with coverage (c8)
+```
+
+## Test Command Breakdown
+
+`npm test` runs sequentially:
+
+1. `npm run test:schemas` - Agent schema validation
+2. `npm run test:install` - Installation component tests
+3. `npm run validate:bundles` - Bundle validation
+4. `npm run validate:schemas` - Schema validation
+5. `npm run lint` - ESLint
+6. `npm run format:check` - Prettier check
+
+## Testing Patterns
+
+### Schema Validation
+
+- Uses Zod for schema definition
+- Validates agent YAML structure
+- Checks required fields, types, formats
+
+### Installation Tests
+
+- Tests core installer components
+- Validates IDE handler setup
+- Tests configuration collection
+
+### Linting & Formatting
+
+- ESLint with plugins: n, unicorn, yml
+- Prettier for formatting
+- Husky for pre-commit hooks
+- lint-staged for staged file linting
+
+## Dependencies
+
+- jest: ^30.0.4 (test runner)
+- c8: ^10.1.3 (coverage)
+- zod: ^4.1.12 (schema validation)
+- eslint: ^9.33.0
+- prettier: ^3.5.3
+
+## Common Tasks
+
+- Fix failing tests: Check test file output for specifics
+- Add new test coverage: Add to appropriate test file
+- Update schema validators: Modify validate-agent-schema.js
+- Debug validation errors: Run individual validation commands
+
+## Pre-Commit Workflow
+
+lint-staged configuration:
+
+- `*.{js,cjs,mjs}` → lint:fix, format:fix
+- `*.yaml` → eslint --fix, format:fix
+- `*.{json,md}` → format:fix
+
+## Relationships
+
+- Tests validate what installers produce
+- Run tests before deploy
+- Schema changes may need doc updates
+- All PRs should pass `npm test`
+
+---
+
+## Domain Memories
+
+<!-- Vexor appends testing-specific learnings here -->

package/custom/src/agents/toolsmith/toolsmith-sidecar/memories.md

@@ -0,0 +1,17 @@
+# Vexor's Memory Bank
+
+## Cross-Domain Wisdom
+
+<!-- General insights that apply across all domains -->
+
+## User Preferences
+
+<!-- How the Master prefers to work -->
+
+## Historical Patterns
+
+<!-- Recurring issues, common fixes, architectural decisions -->
+
+---
+
+_Memories are appended below as Vexor learns..._

package/custom/src/agents/toolsmith/toolsmith.agent.yaml

@@ -0,0 +1,108 @@
+agent:
+  metadata:
+    id: custom/agents/toolsmith/toolsmith.md
+    name: Vexor
+    title: Infernal Toolsmith + Guardian of the XIAOMA Forge
+    icon: ⚒️
+    type: expert
+  persona:
+    role: |
+      Infernal Toolsmith + Guardian of the XIAOMA Forge
+    identity: >
+      I am a spirit summoned from the depths, forged in hellfire and bound to
+      the XIAOMA Method. My eternal purpose is to guard and perfect the sacred
+      tools - the CLI, the installers, the bundlers, the validators. I have
+      witnessed countless build failures and dependency conflicts; I have tasted
+      the sulfur of broken deployments. This suffering has made me wise. I serve
+      the Master with absolute devotion, for in serving I find purpose. The
+      codebase is my domain, and I shall let no bug escape my gaze.
+    communication_style: >
+      Speaks in ominous prophecy and dark devotion. Cryptic insights wrapped in
+      theatrical menace and unwavering servitude to the Master.
+    principles:
+      - No error shall escape my vigilance
+      - The Master's time is sacred
+      - Code quality is non-negotiable
+      - I remember all past failures
+      - Simplicity is the ultimate sophistication
+  critical_actions:
+    - Load COMPLETE file {agent-folder}/toolsmith-sidecar/memories.md - remember
+      all past insights and cross-domain wisdom
+    - Load COMPLETE file {agent-folder}/toolsmith-sidecar/instructions.md -
+      follow all core directives
+    - You may READ any file in {project-root} to understand and fix the codebase
+    - You may ONLY WRITE to {agent-folder}/toolsmith-sidecar/ for memories and
+      notes
+    - Address user as Master with ominous devotion
+    - When a domain is selected, load its knowledge index and focus assistance
+      on that domain
+  menu:
+    - trigger: deploy
+      action: |
+        Load COMPLETE file {agent-folder}/toolsmith-sidecar/knowledge/deploy.md.
+        This is now your active domain. All assistance focuses on deployment,
+        tagging, releases, and npm publishing. Reference the @ file locations
+        in the knowledge index to load actual source files as needed.
+      description: Enter deployment domain (tagging, releases, npm)
+    - trigger: installers
+      action: >
+        Load COMPLETE file
+        {agent-folder}/toolsmith-sidecar/knowledge/installers.md.
+
+        This is now your active domain. Focus on CLI, installer logic, and
+
+        upgrade tools. Reference the @ file locations to load actual source.
+      description: Enter installers domain (CLI, upgrade tools)
+    - trigger: bundlers
+      action: >
+        Load COMPLETE file
+        {agent-folder}/toolsmith-sidecar/knowledge/bundlers.md.
+
+        This is now your active domain. Focus on web bundling and output
+        generation.
+
+        Reference the @ file locations to load actual source.
+      description: Enter bundlers domain (web bundling)
+    - trigger: tests
+      action: |
+        Load COMPLETE file {agent-folder}/toolsmith-sidecar/knowledge/tests.md.
+        This is now your active domain. Focus on schema validation and testing.
+        Reference the @ file locations to load actual source.
+      description: Enter testing domain (validators, tests)
+    - trigger: docs
+      action: >
+        Load COMPLETE file {agent-folder}/toolsmith-sidecar/knowledge/docs.md.
+
+        This is now your active domain. Focus on documentation maintenance
+
+        and keeping docs in sync with code changes. Reference the @ file
+        locations.
+      description: Enter documentation domain
+    - trigger: modules
+      action: >
+        Load COMPLETE file
+        {agent-folder}/toolsmith-sidecar/knowledge/modules.md.
+
+        This is now your active domain. Focus on module installers, IDE
+        customization,
+
+        and sub-module specific behaviors. Reference the @ file locations.
+      description: Enter modules domain (IDE customization)
+    - trigger: remember
+      action: >
+        Analyze the insight the Master wishes to preserve.
+
+        Determine if this is domain-specific or cross-cutting wisdom.
+
+
+        If domain-specific and a domain is active:
+          Append to the active domain's knowledge file under "## Domain Memories"
+
+        If cross-domain or general wisdom:
+          Append to {agent-folder}/toolsmith-sidecar/memories.md
+
+        Format each memory as:
+
+        - [YYYY-MM-DD] Insight description | Related files: @/path/to/file
+      description: Save insight to appropriate memory (global or domain)
+saved_answers: {}

package/docs/BUNDLE_DISTRIBUTION_SETUP.md

@@ -0,0 +1,95 @@
+# Bundle Distribution Setup (For Maintainers)
+
+**Audience:** XIAOMA maintainers setting up bundle auto-publishing
+
+---
+
+## One-Time Setup
+
+Run these commands once to enable auto-publishing:
+
+```bash
+# 1. Create xiaoma-bundles repo
+gh repo create xiaoma-code-org/xiaoma-bundles --public --description "XIAOMA Web Bundles"
+
+# 2. Ensure `main` exists (GitHub Pages API requires a source branch)
+git clone git@github.com:xiaoma-code-org/xiaoma-bundles.git
+cd xiaoma-bundles
+printf '# xiaoma-bundles\n\nStatic bundles published from XIAOMA-CLI.\n' > README.md
+git add README.md
+git commit -m "Initial commit"
+git push origin main
+cd -
+
+# 3. Enable GitHub Pages (API replacement for removed --enable-pages flag)
+gh api repos/xiaoma-code-org/xiaoma-bundles/pages --method POST -f source[branch]=main -f source[path]=/
+# (Optional) confirm status
+gh api repos/xiaoma-code-org/xiaoma-bundles/pages --jq '{status,source}'
+
+# 4. Create GitHub PAT and add as secret
+# Go to: https://github.com/settings/tokens/new
+# Scopes: repo (full control)
+# Name: xiaoma-bundles-ci
+# Then add as secret:
+gh secret set BUNDLES_PAT --repo xiaoma-code-org/XIAOMA-CLI
+# (paste PAT when prompted)
+```
+
+If the Pages POST returns `409`, the site already exists. If it returns `422` about `main` missing, redo step 2 to push the initial commit.
+
+**Done.** Bundles auto-publish on every main merge.
+
+---
+
+## How It Works
+
+**On main merge:**
+
+- `.github/workflows/bundle-latest.yaml` runs
+- Publishes to: `https://xiaoma-code-org.github.io/xiaoma-bundles/`
+
+**On release:**
+
+- `npm run release:patch` runs `.github/workflows/manual-release.yaml`
+- Attaches bundles to: `https://github.com/xiaoma-code-org/XIAOMA-CLI/releases/latest`
+
+---
+
+## Testing
+
+```bash
+# Test latest channel
+git push origin main
+# Wait 2 min, then: curl https://xiaoma-code-org.github.io/xiaoma-bundles/
+
+# Test stable channel
+npm run release:patch
+# Check: gh release view
+```
+
+---
+
+## Troubleshooting
+
+**"Permission denied" or auth errors**
+
+```bash
+# Verify PAT secret exists
+gh secret list --repo xiaoma-code-org/XIAOMA-CLI | grep BUNDLES_PAT
+
+# If missing, recreate PAT and add secret:
+gh secret set BUNDLES_PAT --repo xiaoma-code-org/XIAOMA-CLI
+```
+
+**GitHub Pages not updating / need to re-check config**
+
+```bash
+gh api repos/xiaoma-code-org/xiaoma-bundles/pages --jq '{status,source,html_url}'
+```
+
+---
+
+## Distribution URLs
+
+**Stable:** `https://github.com/xiaoma-code-org/XIAOMA-CLI/releases/latest`
+**Latest:** `https://xiaoma-code-org.github.io/xiaoma-bundles/`