ctxinit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ctxinit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,484 @@
+# ctxinit
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
+[![npm version](https://img.shields.io/npm/v/ctxinit.svg)](https://www.npmjs.com/package/ctxinit)
+
+A CLI tool for managing AI context files across multiple IDE targets. Compile your project context and rules into optimized formats for Claude Code, Cursor, and general AI agents.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Project Structure](#project-structure)
+- [Configuration](#configuration)
+- [Writing Rules](#writing-rules)
+- [Commands](#commands)
+- [Output Formats](#output-formats)
+- [Self-Healing Features](#self-healing-features)
+- [Programmatic API](#programmatic-api)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- **Multi-Target Compilation**: Generate context files for Claude (`CLAUDE.md`), Cursor (`.cursor/rules/*.mdc`), and general agents (`AGENTS.md`)
+- **Token Budget Management**: Intelligent rule selection to fit within configurable token limits
+- **Rule Priority System**: Control which rules get included when space is limited
+- **Glob-Based Filtering**: Apply rules conditionally based on file patterns
+- **Incremental Builds**: Only rebuild when source files change
+- **Self-Healing Verification**: Detect tampering with SHA-256 checksums
+- **Watch Mode (planned)**: Automatically rebuild on file changes
+
+## Installation
+
+```bash
+npm install -g ctxinit
+```
+
+Or use with npx:
+
+```bash
+npx ctxinit init
+```
+
+## Quick Start
+
+```bash
+# Initialize a new context project
+ctx init
+
+# Build context files for all targets
+ctx build
+
+# Verify output integrity
+ctx verify
+
+# Check whether outputs are up to date (no writes)
+ctx build --check
+```
+
+## Project Structure
+
+After initialization, your project will have:
+
+```text
+.context/
+  config.yaml       # Main configuration file
+  project.md        # Project description (required)
+  architecture.md   # Architecture overview (optional)
+  rules/            # Rule files
+    *.md            # Individual rule files
+```
+
+## Configuration
+
+The `.context/config.yaml` file controls compilation:
+
+```yaml
+version: '1.0'
+project:
+  name: my-project
+  description: Project description
+
+compile:
+  claude:
+    max_tokens: 4000
+    strategy: priority
+    always_include:
+      - core-rules
+
+  cursor:
+    strategy: all
+
+  agents:
+    max_tokens: 8000
+```
+
+### Compilation Strategies
+
+- **all**: Include all rules (default for Cursor)
+- **priority**: Include rules by priority until token budget is reached
+- **directory**: Include rules from specific directories
+- **glob**: Include rules whose globs match current context files
+- **tag**: Filter rules by tags
+
+## Writing Rules
+
+Rules are markdown files with YAML frontmatter:
+
+```markdown
+---
+id: coding-standards
+description: Project coding standards
+priority: 10
+always_apply: true
+globs:
+  - "**/*.ts"
+  - "**/*.js"
+tags:
+  - code-quality
+domain: backend
+---
+
+# Coding Standards
+
+Your rule content here...
+```
+
+### Frontmatter Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique rule identifier (required) |
+| `description` | string | Brief description |
+| `priority` | number | Higher = more important (0-100) |
+| `always_apply` | boolean | Always include regardless of globs |
+| `globs` | string[] | File patterns for conditional application |
+| `tags` | string[] | Categorization tags |
+| `domain` | string | Domain category |
+
+## Commands
+
+### `ctx init`
+
+Initialize a new context project in the current directory. By default, this also runs the enhanced LLM bootstrap and then builds compiled outputs.
+
+```bash
+ctx init [options]
+```
+
+Options:
+- `--force`: Overwrite existing .context directory (creates backup)
+- `--bootstrap, -b`: Run LLM bootstrap after init (default)
+- `--no-bootstrap`: Skip LLM bootstrap (only create templates)
+- `--no-interactive`: Run without prompts (use defaults)
+- `--wizard`: Launch guided migration wizard
+- `--dry-run`: Show what would happen without making changes
+
+### `ctx build`
+
+Compile rules to target formats.
+
+```bash
+ctx build [targets...] [options]
+```
+
+Options:
+- `-i, --incremental`: Only rebuild changed files
+- `--force`: Force full rebuild
+- `--skip-validation`: Skip rule validation
+- `--check`: Check whether outputs are up to date (no writes)
+- `-t, --target <targets...>`: Specific targets to build (claude, cursor, agents)
+- `-v, --verbose`: Verbose output
+- `-q, --quiet`: Suppress output except errors
+
+Examples:
+```bash
+ctx build                    # Build all targets
+ctx build claude cursor      # Build specific targets
+ctx build --target claude    # Build specific targets (flag)
+ctx build --check            # Check outputs match sources
+```
+
+### `ctx verify`
+
+Verify compiled output integrity using checksums.
+
+```bash
+ctx verify [options]
+```
+
+Options:
+- `--json`: Output in JSON format
+- `-v, --verbose`: Show detailed information
+
+Examples:
+```bash
+ctx verify                   # Verify all outputs
+ctx verify --json            # JSON output
+ctx verify --verbose         # Detailed output
+```
+
+### `ctx lint`
+
+Validate rules without building. Alias: `ctx validate`.
+
+```bash
+ctx lint [files...] [options]
+```
+
+Options:
+- `--json`: Output in JSON format
+- `-v, --verbose`: Show detailed output
+- `-q, --quiet`: Suppress output except errors
+
+Examples:
+```bash
+ctx lint                      # Lint all rules
+ctx lint .context/rules/foo.md # Lint specific files
+ctx validate --json           # Alias
+```
+
+Additional commands: `ctx diff`, `ctx migrate`, `ctx hooks`, `ctx bootstrap` (see `ctx --help`).
+
+## Output Formats
+
+### Claude (CLAUDE.md)
+
+Single markdown file optimized for Claude Code:
+- Project context and architecture
+- Rule directory index
+- Selected rules based on token budget
+- Context hygiene meta-rule
+
+### Cursor (.cursor/rules/*.mdc)
+
+Individual `.mdc` files with Cursor-compatible frontmatter:
+- One file per rule
+- YAML frontmatter with description, globs, alwaysApply
+- Full rule content
+
+### Agents (AGENTS.md)
+
+Comprehensive file for general AI agents:
+- Full project overview
+- Complete architecture documentation
+- Rule summaries with metadata
+- Navigation-friendly structure
+
+## Self-Healing Features
+
+ctxinit embeds metadata in compiled outputs for integrity verification:
+
+```html
+<!-- ctx build metadata -->
+<!-- timestamp: 2024-01-15T10:30:00.000Z -->
+<!-- checksum: sha256:abc123... -->
+```
+
+Use `ctx verify` to detect tampering or accidental modifications.
+
+## Programmatic API
+
+```typescript
+import { ConfigLoader, RuleParser, ClaudeCompiler } from 'ctxinit';
+
+// Load configuration
+const configLoader = new ConfigLoader(projectRoot);
+const config = configLoader.loadConfig();
+
+// Parse rules
+const parser = new RuleParser(projectRoot);
+const rules = parser.discoverAndParse();
+
+// Compile
+const compiler = new ClaudeCompiler({
+  projectRoot,
+  config,
+  rules
+});
+const result = await compiler.compile();
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 18.0.0
+- npm or yarn
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/stone16/ctxinit.git
+cd ctxinit
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+```
+
+### Local Testing with npm pack
+
+To test your changes as an end user would experience them, use `npm pack` to create a tarball and install it in a separate directory:
+
+```bash
+# 1. Build and pack the project
+npm run build
+npm pack
+# Creates ctxinit-x.x.x.tgz
+
+# 2. In a separate test directory, install from the tarball
+mkdir ~/test-project && cd ~/test-project
+npm install /path/to/ctxinit/ctxinit-x.x.x.tgz
+
+# 3. Test the CLI commands
+npx ctx init
+npx ctx build
+npx ctx verify
+```
+
+For global installation testing:
+
+```bash
+npm install -g /path/to/ctxinit/ctxinit-x.x.x.tgz
+ctx init
+ctx build
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests in watch mode
+npm test -- --watch
+
+# Run a specific test file
+npm test -- tests/compiler/claude-compiler.test.ts
+
+# Run tests matching a pattern
+npm test -- --testNamePattern="should compile"
+```
+
+### Code Quality
+
+```bash
+# Run linting
+npm run lint
+
+# Fix linting issues automatically
+npm run lint:fix
+
+# Check code formatting
+npm run format:check
+
+# Format code
+npm run format
+```
+
+### Development Workflow
+
+```bash
+# Watch mode for TypeScript compilation
+npm run dev
+
+# In another terminal, test your changes
+ctx build --verbose
+```
+
+### Project Structure
+
+```text
+ctxinit/
+├── bin/                  # CLI entry point
+│   └── ctx.js
+├── src/                  # Source code
+│   ├── cli/              # CLI commands
+│   ├── compiler/         # Target compilers
+│   ├── config/           # Configuration loading
+│   ├── parser/           # Rule parsing
+│   ├── build/            # Build orchestration
+│   ├── schemas/          # Zod schemas
+│   └── index.ts          # Public API exports
+├── tests/                # Test files
+│   ├── cli/              # CLI command tests
+│   ├── compiler/         # Compiler tests
+│   ├── config/           # Config tests
+│   ├── parser/           # Parser tests
+│   ├── build/            # Build tests
+│   ├── integration/      # Integration tests
+│   ├── performance/      # Performance benchmarks
+│   └── __mocks__/        # Test mocks
+├── templates/            # Template files for ctx init
+├── docs/                 # Documentation
+└── examples/             # Example projects
+```
+
+### Writing Tests
+
+Tests use Jest and follow this structure:
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+
+describe('MyFeature', () => {
+  beforeEach(() => {
+    // Setup
+  });
+
+  afterEach(() => {
+    // Cleanup
+  });
+
+  it('should do something', () => {
+    // Test
+    expect(result).toBe(expected);
+  });
+});
+```
+
+### Debugging
+
+```bash
+# Run with Node.js inspector
+node --inspect-brk bin/ctx.js build
+
+# Debug tests
+node --inspect-brk node_modules/.bin/jest --runInBand
+```
+
+## Contributing
+
+We welcome contributions! Here's how you can help:
+
+### Reporting Issues
+
+- Search [existing issues](https://github.com/stone16/ctxinit/issues) first
+- Include reproduction steps, expected vs actual behavior
+- Provide your environment details (Node.js version, OS, etc.)
+
+### Pull Requests
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make your changes
+4. Add or update tests as needed
+5. Ensure all tests pass: `npm test`
+6. Ensure linting passes: `npm run lint`
+7. Commit with a clear message
+8. Push and open a Pull Request
+
+### Development Guidelines
+
+- Follow existing code style
+- Write tests for new features
+- Update documentation as needed
+- Keep commits focused and atomic
+- Use conventional commit messages when possible
+
+### Areas for Contribution
+
+- Bug fixes and improvements
+- New compilation targets
+- Documentation improvements
+- Performance optimizations
+- Test coverage improvements
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+**Questions?** Open an issue or start a discussion on GitHub.

package/bin/ctx.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../dist/cli').run();

package/dist/analysis/index.d.ts

@@ -0,0 +1,2 @@
+export * from './static-analysis';
+//# sourceMappingURL=index.d.ts.map

package/dist/analysis/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analysis/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/dist/analysis/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./static-analysis"), exports);
+//# sourceMappingURL=index.js.map

package/dist/analysis/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/analysis/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC"}

package/dist/analysis/static-analysis.d.ts

@@ -0,0 +1,79 @@
+import { ParsedRule, RuleValidationError, RuleValidationWarning, RuleValidationResult } from '../schemas/rule';
+import { Config } from '../schemas/config';
+/**
+ * Analysis result for a complete validation run
+ */
+export interface AnalysisResult {
+    /** Whether validation passed (no blocking errors) */
+    valid: boolean;
+    /** Blocking errors that prevent compilation */
+    errors: RuleValidationError[];
+    /** Non-blocking warnings */
+    warnings: RuleValidationWarning[];
+    /** Total rules analyzed */
+    rulesAnalyzed: number;
+}
+/**
+ * Options for static analysis
+ */
+export interface AnalysisOptions {
+    /** Project root directory */
+    projectRoot: string;
+    /** Configuration for token limits */
+    config?: Config;
+}
+/**
+ * Analyze rules for duplicate IDs
+ *
+ * @param rules - Parsed rules to analyze
+ * @returns Array of duplicate ID errors
+ */
+export declare function findDuplicateIds(rules: ParsedRule[]): RuleValidationError[];
+/**
+ * Find dead links in markdown content
+ *
+ * @param rule - Parsed rule to analyze
+ * @param projectRoot - Project root for resolving relative links
+ * @returns Array of dead link errors
+ */
+export declare function findDeadLinks(rule: ParsedRule, projectRoot: string): RuleValidationError[];
+/**
+ * Find ghost rules (globs that match no files)
+ *
+ * @param rule - Parsed rule to analyze
+ * @param projectRoot - Project root for glob matching
+ * @returns Array of ghost rule warnings
+ */
+export declare function findGhostRules(rule: ParsedRule, projectRoot: string): RuleValidationWarning[];
+/**
+ * Check for potential token limit issues
+ *
+ * @param rules - Parsed rules to analyze
+ * @param config - Configuration with token limits
+ * @returns Array of token limit warnings
+ */
+export declare function checkTokenLimits(rules: ParsedRule[], config?: Config): RuleValidationWarning[];
+/**
+ * Detect circular references in rule imports
+ *
+ * @param rules - Parsed rules to analyze
+ * @returns Array of circular reference errors
+ */
+export declare function findCircularReferences(rules: ParsedRule[]): RuleValidationError[];
+/**
+ * Validate a single rule
+ *
+ * @param rule - Parsed rule to validate
+ * @param options - Analysis options
+ * @returns Validation result for the rule
+ */
+export declare function validateRule(rule: ParsedRule, options: AnalysisOptions): RuleValidationResult;
+/**
+ * Run complete static analysis on all rules
+ *
+ * @param rules - Parsed rules to analyze
+ * @param options - Analysis options
+ * @returns Complete analysis result
+ */
+export declare function analyzeRules(rules: ParsedRule[], options: AnalysisOptions): AnalysisResult;
+//# sourceMappingURL=static-analysis.d.ts.map

package/dist/analysis/static-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-analysis.d.ts","sourceRoot":"","sources":["../../src/analysis/static-analysis.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC/G,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,KAAK,EAAE,OAAO,CAAC;IACf,+CAA+C;IAC/C,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC9B,4BAA4B;IAC5B,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,2BAA2B;IAC3B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,mBAAmB,EAAE,CAwB3E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAuC1F;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,qBAAqB,EAAE,CA6B7F;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAyB9F;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,mBAAmB,EAAE,CA6CjF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,GAAG,oBAAoB,CAe7F;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc,CA0B1F"}