@zebralabs/context-cli 0.1.3 → 0.1.5

package/README.md

@@ -0,0 +1,472 @@
+# @zebralabs/context-cli
+
+> Install engineering standards into your repository. AI remembers forever.
+
+[![npm version](https://img.shields.io/npm/v/@zebralabs/context-cli.svg)](https://www.npmjs.com/package/@zebralabs/context-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Context CLI** is the command-line tool for installing and managing [Context Packs](https://www.zebralabs.io/context-packs) — professional engineering standards that teach your AI tools (Cursor, Claude) how to generate consistent, standards-compliant output.
+
+## What is Context CLI?
+
+AI coding assistants are fast, but they generate inconsistent output. Without standards, you spend time fixing AI mistakes instead of building features.
+
+**Context Packs** solve this by injecting professional standards directly into your repository. Once installed, AI automatically follows your rules — no re-explaining, no drift, consistent output every time.
+
+### Key Benefits
+
+- ✅ **Standards live in your repo** — Version-controlled, reviewable, evolvable
+- ✅ **Automatic enforcement** — AI reads standards automatically, no activation needed
+- ✅ **Modular knowledge** — Install only what you need, add more over time
+- ✅ **Built for AI tools** — Designed for how Cursor and Claude actually work
+
+> **Learn more:** Visit [zebralabs.io/context-packs](https://www.zebralabs.io/context-packs) for product overview, available packs, and purchasing.
+
+## Quick Start
+
+### 1. Install the CLI
+
+```bash
+npm install -g @zebralabs/context-cli
+```
+
+### 2. Install Your First Pack
+
+After purchasing a pack, you'll receive a download link and authentication token. Install it:
+
+```bash
+ctx pack install pack-01-documentation-management \
+  --registry https://www.zebralabs.io/api \
+  --token YOUR_TOKEN_HERE
+```
+
+### 3. Verify Installation
+
+```bash
+ctx list
+```
+
+You should see your installed pack listed. The pack is now part of your repository and works automatically with Cursor and Claude.
+
+### 4. Start Using
+
+Ask Cursor or Claude to generate documentation following your standards:
+
+```
+Generate a component specification following our documentation standards
+```
+
+AI will automatically use your installed standards — no re-explaining needed.
+
+> **Need a pack?** Browse available packs at [zebralabs.io/context-packs](https://www.zebralabs.io/context-packs)
+
+## Commands
+
+### `ctx help`
+
+Show help information and command usage.
+
+```bash
+ctx help
+```
+
+### `ctx pack install <packId>`
+
+Install a context pack into your repository.
+
+**Options:**
+- `--repo-root <path>` — Repository root directory (default: auto-detect)
+- `--mode <SkipExisting|Overwrite>` — File merge mode (default: SkipExisting)
+- `--zip <path>` — Install from local ZIP file
+- `--registry <url>` — Registry URL for downloading packs
+- `--token <token>` — Authentication token for registry
+- `--version <x.y.z>` — Specific pack version (default: latest)
+
+**Examples:**
+
+Install from registry (requires token):
+```bash
+ctx pack install pack-01-documentation-management \
+  --registry https://www.zebralabs.io/api \
+  --token YOUR_TOKEN
+```
+
+Install specific version:
+```bash
+ctx pack install pack-01-documentation-management \
+  --registry https://www.zebralabs.io/api \
+  --token YOUR_TOKEN \
+  --version 0.4.0
+```
+
+Install from local ZIP (for testing):
+```bash
+ctx pack install pack-01-documentation-management \
+  --zip ./pack-01-documentation-management-v0.4.0.zip
+```
+
+**What happens:**
+- Pack files are extracted and merged into `docs/practices-and-standards/`
+- Cursor rules (`.cursor/rules/`) are copied to repository root
+- Cursor skills (`.cursor/skills/`) are copied to repository root
+- `CLAUDE.md` is copied to repository root
+- `context.yaml` is created/updated with pack information
+
+### `ctx list`
+
+List all installed context packs and their contributions.
+
+```bash
+ctx list
+```
+
+**Output:**
+```
+Installed Context Packs
+-----------------------
+
+- pack-01-documentation-management @ 0.4.0
+  Contributes:
+    - docs/practices-and-standards/01-engineering-practices/01-documentation-methodology
+    - docs/practices-and-standards/01-engineering-practices/00-methodologies
+```
+
+**Options:**
+- `--context-yaml <path>` — Path to `context.yaml` file (default: auto-detect)
+
+### `ctx compile`
+
+Compile standards from installed packs into consolidated outputs.
+
+**Options:**
+- `--pack <packId>` — Compile a specific pack only
+- `--context-yaml <path>` — Path to `context.yaml` file (default: auto-detect)
+
+**Examples:**
+
+Compile all installed packs:
+```bash
+ctx compile
+```
+
+Compile a specific pack:
+```bash
+ctx compile --pack pack-01-documentation-management
+```
+
+**Output:**
+- `docs/practices-and-standards/.compiled/system-prompt.md` — Consolidated standards
+- `docs/practices-and-standards/.compiled/sources.md` — Source file list
+- `docs/practices-and-standards/.compiled/report.md` — Compilation report
+
+**Pack-specific compilation:**
+When using `--pack`, outputs are generated in the pack directory:
+- `docs/practices-and-standards/packs/<pack-id>/.cursor/rules/` — Cursor rules
+- `docs/practices-and-standards/packs/<pack-id>/.cursor/skills/` — Cursor skills
+- `docs/practices-and-standards/packs/<pack-id>/CLAUDE.md` — Claude instructions
+- `docs/practices-and-standards/packs/<pack-id>/CONSOLIDATED-STANDARDS.md` — Human-readable standards
+
+### `ctx validate`
+
+Validate your `context.yaml` configuration and installed packs.
+
+```bash
+ctx validate
+```
+
+**Checks:**
+- Schema version compatibility
+- Installed pack manifests exist
+- Precedence list references valid packs
+- Pack file structure integrity
+
+**Options:**
+- `--context-yaml <path>` — Path to `context.yaml` file (default: auto-detect)
+
+### `ctx version`
+
+Show the CLI version.
+
+```bash
+ctx version
+# or
+ctx -v
+# or
+ctx --version
+```
+
+## How It Works
+
+### Repository Structure
+
+After installing a pack, your repository structure looks like:
+
+```
+your-repo/
+├── .cursor/
+│   ├── rules/              # Cursor rules (auto-loaded)
+│   │   ├── index.md
+│   │   └── doc-process.md
+│   └── skills/             # Cursor skills (on-demand)
+│       └── Domain Discovery Process/
+│           └── SKILL.md
+├── CLAUDE.md               # Claude instructions
+├── docs/
+│   └── practices-and-standards/
+│       ├── context.yaml    # Pack registry and configuration
+│       ├── 01-engineering-practices/
+│       │   ├── 00-methodologies/
+│       │   └── 01-documentation-methodology/
+│       └── packs/
+│           └── pack-01-documentation-management/
+│               ├── pack.yaml
+│               └── ...
+└── ...
+```
+
+### Context Configuration
+
+The `context.yaml` file tracks installed packs and their precedence:
+
+```yaml
+schema: context-install/v1
+registry: https://www.zebralabs.io/api
+
+installed_packs:
+  - id: pack-01-documentation-management
+    version: 0.4.0
+    manifest: docs/practices-and-standards/packs/pack-01-documentation-management/pack.yaml
+
+precedence:
+  - pack-01-documentation-management
+```
+
+**Precedence:** When multiple packs define conflicting rules, packs listed earlier in `precedence` take priority.
+
+### Integration with AI Tools
+
+**Cursor:**
+- Rules in `.cursor/rules/` are automatically loaded — AI follows them in every conversation
+- Skills in `.cursor/skills/` are available on-demand — invoke by name when needed
+- Methodology files in `docs/practices-and-standards/` are indexed automatically
+
+**Claude:**
+- `CLAUDE.md` provides consolidated standards at repository root
+- Methodology files can be referenced in conversations
+- Standards are version-controlled with your code
+
+## Examples & Workflows
+
+### Workflow 1: First-Time Installation
+
+```bash
+# 1. Install CLI
+npm install -g @zebralabs/context-cli
+
+# 2. Install pack (after purchase)
+ctx pack install pack-01-documentation-management \
+  --registry https://www.zebralabs.io/api \
+  --token YOUR_TOKEN
+
+# 3. Verify
+ctx list
+
+# 4. Start using with Cursor/Claude
+# AI now automatically follows your standards
+```
+
+### Workflow 2: Updating a Pack
+
+```bash
+# Install newer version
+ctx pack install pack-01-documentation-management \
+  --registry https://www.zebralabs.io/api \
+  --token YOUR_TOKEN \
+  --version 0.5.0 \
+  --mode Overwrite
+
+# Recompile to regenerate assets
+ctx compile --pack pack-01-documentation-management
+```
+
+### Workflow 3: Local Development
+
+```bash
+# Install from local ZIP (for pack development/testing)
+ctx pack install pack-01-documentation-management \
+  --zip ./my-pack-v0.1.0.zip \
+  --mode Overwrite
+
+# Compile to test asset generation
+ctx compile --pack pack-01-documentation-management
+```
+
+### Workflow 4: Multiple Packs
+
+```bash
+# Install first pack
+ctx pack install pack-01-documentation-management \
+  --registry https://www.zebralabs.io/api \
+  --token YOUR_TOKEN
+
+# Install second pack (when available)
+ctx pack install pack-02-pr-review \
+  --registry https://www.zebralabs.io/api \
+  --token YOUR_TOKEN
+
+# Set precedence (edit context.yaml manually or via future command)
+# Then compile all packs
+ctx compile
+```
+
+## Troubleshooting
+
+### "Could not find context.yaml"
+
+**Problem:** CLI can't locate `context.yaml` in your repository.
+
+**Solutions:**
+- Ensure you're running commands from your repository root
+- Use `--context-yaml <path>` to specify the path explicitly
+- Check that `context.yaml` exists in `docs/practices-and-standards/` or `practices-and-standards/`
+
+### "Pack manifest not found"
+
+**Problem:** Installed pack's `pack.yaml` file is missing.
+
+**Solutions:**
+- Reinstall the pack: `ctx pack install <pack-id> --mode Overwrite`
+- Check that the pack directory exists in `docs/practices-and-standards/packs/`
+
+### "Missing required --token for registry install"
+
+**Problem:** Registry installation requires authentication token.
+
+**Solutions:**
+- Ensure you have a valid token from your pack purchase
+- Use `--token YOUR_TOKEN` flag
+- For local testing, use `--zip <path>` instead
+
+### Installation Files Skipped
+
+**Problem:** Files weren't copied during installation.
+
+**Solutions:**
+- Check installation mode: `--mode SkipExisting` skips existing files
+- Use `--mode Overwrite` to replace existing files
+- Check merge report in `docs/practices-and-standards/.install/`
+
+### Compilation Errors
+
+**Problem:** `ctx compile` fails with module errors.
+
+**Solutions:**
+- Ensure you're running from the repository root
+- Check Node.js version (requires Node.js 18+)
+- Verify all pack files are intact: `ctx validate`
+- Try compiling a specific pack: `ctx compile --pack <pack-id>`
+
+## Advanced Usage
+
+### Custom Pack Development
+
+To develop your own packs:
+
+1. Create pack structure following the standard format
+2. Include `pack.yaml` manifest with `contributes.roots`
+3. Include `install.ps1` installer script
+4. Test installation: `ctx pack install <pack-id> --zip <path>`
+5. Test compilation: `ctx compile --pack <pack-id>`
+
+### Precedence Configuration
+
+Edit `docs/practices-and-standards/context.yaml` to set pack precedence:
+
+```yaml
+precedence:
+  - pack-01-documentation-management  # Highest priority
+  - pack-02-pr-review                 # Lower priority
+```
+
+Packs listed earlier take precedence when rules conflict.
+
+### Custom Registry
+
+Use a custom registry for private or internal packs:
+
+```bash
+ctx pack install my-pack \
+  --registry https://my-company.com/api \
+  --token INTERNAL_TOKEN
+```
+
+Or set default registry in `context.yaml`:
+```yaml
+registry: https://my-company.com/api
+```
+
+## What's to Come
+
+We're actively developing new features to make Context CLI even more powerful. Here's what's coming:
+
+### Enhanced Compilation Engine
+
+- **Rule Extraction** — Automatic extraction of structured rules from markdown documents using `@context.rules` markers
+- **Conflict Detection** — Intelligent detection of conflicting rules across multiple packs
+- **Semantic Conflict Resolution** — Beyond ID-based conflicts, detect when rules semantically conflict
+- **Custom Documentation Support** — Include your own custom standards alongside installed packs
+- **Change Tracking** — Only recompile what's changed since last compilation
+
+### Multi-Pack Improvements
+
+- **Interactive Conflict Resolution** — Guided workflow for resolving conflicts between packs
+- **Granular Precedence** — Set precedence at rule level, not just pack level
+- **Conflict Reports** — Detailed reports showing all conflicts and resolutions
+- **Pack Dependencies** — Declare dependencies between packs
+
+### Developer Experience
+
+- **Precedence Management** — CLI commands to manage pack precedence without editing YAML
+- **Pack Updates** — `ctx pack update` command to update all packs to latest versions
+- **Pack Removal** — `ctx pack uninstall` to cleanly remove packs
+- **Better Error Messages** — More helpful error messages with suggested fixes
+- **Progress Indicators** — Visual feedback during long operations
+
+### Integration Enhancements
+
+- **GitHub Copilot Support** — Generate `.github/copilot-instructions.md` from compiled standards
+- **VS Code Integration** — VS Code extension for managing packs and standards
+- **CI/CD Integration** — Validate standards in CI pipelines
+- **Diff Viewing** — See what changed when updating packs
+
+### Performance & Reliability
+
+- **Incremental Compilation** — Faster compilations by only processing changed files
+- **Parallel Processing** — Process multiple packs in parallel
+- **Caching** — Cache compilation results for faster subsequent runs
+- **Validation Improvements** — More comprehensive validation with better error reporting
+
+### Documentation & Learning
+
+- **Interactive Tutorial** — Guided walkthrough for first-time users
+- **Pack Marketplace** — Browse and discover packs from the CLI
+- **Examples Library** — Curated examples of custom packs and configurations
+
+---
+
+**Have ideas or feedback?** We'd love to hear from you! Visit [zebralabs.io/context-packs](https://www.zebralabs.io/context-packs) to share your thoughts.
+
+## Links & Resources
+
+- **Product Website:** [zebralabs.io/context-packs](https://www.zebralabs.io/context-packs)
+- **Available Packs:** Browse packs and purchase at [zebralabs.io/context-packs](https://www.zebralabs.io/context-packs)
+- **Support:** Contact support through the website
+
+## License
+
+MIT License — see [LICENSE](LICENSE) file for details.
+
+---
+
+**Ready to get started?** Install the CLI and visit [zebralabs.io/context-packs](https://www.zebralabs.io/context-packs) to browse available packs.
+

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zebralabs/context-cli",
-    "version": "0.1.3",
+    "version": "0.1.5",
     "description": "Context-as-Code CLI (help/list/compile/validate)",
     "license": "MIT",
     "type": "module",

package/src/application/compile/compile-context.js

@@ -0,0 +1,119 @@
+import { Stage1Discovery } from "./stage1-discovery.js";
+import { Stage2Extraction } from "./stage2-extraction.js";
+import { Stage4Consolidation } from "./stage4-consolidation.js";
+import { Stage5Assets } from "./stage5-assets.js";
+import { Stage6Validation } from "./stage6-validation.js";
+import YAML from "yaml";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Main compilation orchestrator
+ * Coordinates all compilation stages
+ */
+export class CompileContext {
+  constructor() {
+    this.stage1 = new Stage1Discovery();
+    this.stage2 = new Stage2Extraction();
+    this.stage4 = new Stage4Consolidation();
+    this.stage5 = new Stage5Assets();
+    this.stage6 = new Stage6Validation();
+  }
+
+  /**
+   * Compile context for a specific pack
+   * @param {string} repoRoot - Repository root
+   * @param {string} packId - Pack ID to compile
+   * @param {string} outputPath - Output path (defaults to pack directory)
+   * @returns {Object} Compilation result
+   */
+  async compilePack(repoRoot, packId, outputPath = null) {
+    // Try both locations for context.yaml
+    const installedPath = path.join(repoRoot, "docs", "practices-and-standards", "context.yaml");
+    const sourcePath = path.join(repoRoot, "practices-and-standards", "context.yaml");
+    
+    let contextPath;
+    if (fs.existsSync(installedPath)) {
+      contextPath = installedPath;
+    } else if (fs.existsSync(sourcePath)) {
+      contextPath = sourcePath;
+    } else {
+      throw new Error(`context.yaml not found. Checked:\n  - ${installedPath}\n  - ${sourcePath}`);
+    }
+
+    const contextYaml = YAML.parse(fs.readFileSync(contextPath, "utf8"));
+
+    // Find the pack in installed packs
+    const pack = (contextYaml.installed_packs || []).find(p => p.id === packId);
+    if (!pack) {
+      throw new Error(`Pack ${packId} not found in context.yaml`);
+    }
+
+    // Determine output path
+    if (!outputPath) {
+      // Output to pack directory
+      const packDir = path.dirname(path.join(repoRoot, pack.manifest));
+      outputPath = packDir;
+    }
+
+    const stageReports = {};
+
+    // Stage 1: Discovery
+    console.log("Stage 1: Discovery & Collection...");
+    const discovery = this.stage1.execute(repoRoot, contextYaml);
+    
+    // Filter to only files from the specified pack
+    const packSourceFiles = discovery.sourceFiles.filter(f => f.packId === packId);
+    
+    console.log(`  Found ${packSourceFiles.length} source files`);
+    stageReports.stage1 = discovery;
+
+    // Stage 2: Extraction
+    console.log("Stage 2: Rule Extraction & Parsing...");
+    const extraction = this.stage2.execute(packSourceFiles);
+    
+    console.log(`  Extracted ${extraction.report.rulesExtracted} rules`);
+    console.log(`  Extracted ${extraction.report.preferencesExtracted} preferences`);
+    console.log(`  Extracted ${extraction.report.scopesExtracted} scopes`);
+
+    if (extraction.report.errors.length > 0) {
+      console.warn(`  Errors: ${extraction.report.errors.length}`);
+      extraction.report.errors.forEach(e => {
+        console.warn(`    - ${e.file}: ${e.error}`);
+      });
+    }
+    stageReports.stage2 = extraction.report;
+
+    // Stage 4: Consolidation
+    console.log("Stage 4: Consolidation & Standard Generation...");
+    const consolidation = this.stage4.execute(extraction.compilation, outputPath);
+    console.log(`  Generated ${consolidation.filesGenerated.length} consolidated files`);
+
+    // Stage 5: Asset Generation
+    console.log("Stage 5: Integration Asset Generation...");
+    const assets = await this.stage5.execute(extraction.compilation, packSourceFiles, outputPath);
+    console.log(`  Generated Cursor rules: ${assets.results.cursorRules.filesGenerated.length} files`);
+    if (assets.skillsExtracted > 0) {
+      console.log(`  Generated Cursor skills: ${assets.results.cursorSkills.filesGenerated.length} files`);
+    }
+    console.log(`  Generated Claude.md`);
+
+    // Stage 6: Validation & Reporting
+    console.log("Stage 6: Validation & Reporting...");
+    const validation = this.stage6.execute(extraction.compilation, stageReports, outputPath);
+    console.log(`  Validation: ${validation.validation.rulesValid ? "✅ Passed" : "❌ Failed"}`);
+    console.log(`  Generated ${validation.reportsGenerated.length} reports`);
+
+    return {
+      compilation: extraction.compilation,
+      outputPath,
+      stageReports: {
+        ...stageReports,
+        stage4: consolidation,
+        stage5: assets,
+        stage6: validation
+      }
+    };
+  }
+}
+