@zebralabs/context-cli 0.1.4 → 0.1.6

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.4",
+    "version": "0.1.6",
     "description": "Context-as-Code CLI (help/list/compile/validate)",
     "license": "MIT",
     "type": "module",

package/src/context.js

@@ -520,6 +520,31 @@ function ensureDir(p) {
   fs.mkdirSync(p, { recursive: true });
 }
 
+/**
+ * After pack install: ensure docs/local/ exists and .gitignore has /docs/local/
+ * (create .gitignore if missing; append entry if present but pattern not found).
+ */
+function ensureDocsLocalAndGitignore(repoRoot) {
+  const docsLocalDir = path.join(repoRoot, "docs", "local");
+  ensureDir(docsLocalDir);
+
+  const gitignorePath = path.join(repoRoot, ".gitignore");
+  const entry = "\n# Local-only documentation (excluded from AI context and version control)\n/docs/local/\n";
+  const pattern = "/docs/local/";
+
+  if (!fs.existsSync(gitignorePath)) {
+    fs.writeFileSync(gitignorePath, entry.trimStart(), "utf8");
+    return;
+  }
+
+  const content = fs.readFileSync(gitignorePath, "utf8");
+  if (content.includes(pattern) || content.includes("docs/local/")) return;
+
+  const trimmed = content.trimEnd();
+  const suffix = trimmed.endsWith("\n") ? entry : "\n" + entry;
+  fs.writeFileSync(gitignorePath, trimmed + suffix, "utf8");
+}
+
 function writeYamlFile(filePath, obj) {
   const text = YAML.stringify(obj, { indent: 2 });
   fs.writeFileSync(filePath, text.endsWith("\n") ? text : (text + "\n"), "utf8");
@@ -717,6 +742,9 @@ async function cmdPackInstall(repoRoot, packId, opts) {
     const installCmd = `& "${installer}" -TargetRoot "${repoRoot}" -PackId "${packId}" -Mode "${mode}"`;
     runPwsh(installCmd, { cwd: extractDir });
 
+    // Ensure docs/local/ exists and .gitignore has /docs/local/
+    ensureDocsLocalAndGitignore(repoRoot);
+
     // Update context.yaml (safe read + repair)
     let ctx2 = readYamlFileSafe(ctxPath);
     if (!ctx2) {
@@ -772,7 +800,7 @@ async function main() {
 
   if (cmd === "--version" || cmd === "-v" || cmd === "version") {
     // Make sure package.json has version (or hardcode a constant)
-    console.log("0.1.4");
+    console.log("0.1.6");
     return;
   }