@esotech/contextuate 2.0.0

package/dist/templates/tools/standards-detector.tool.md

@@ -0,0 +1,301 @@
+# Standards Detector Tool
+
+> **Type:** AI Tool Guide
+> **Purpose:** Analyze project files to detect and document coding standards
+
+---
+
+## When to Use This Tool
+
+Use this tool when:
+- Setting up Contextuate in an existing project
+- User wants coding standards documented
+- Standards need to be inferred from existing code
+- Creating project-specific coding standards
+
+---
+
+## Input
+
+**Required:** Access to project source files
+
+**Optional:**
+- Specific languages to analyze
+- Specific directories to focus on
+- Existing style config files (.eslintrc, .prettierrc, phpcs.xml, etc.)
+
+---
+
+## Process
+
+### Step 1: Detect Languages
+
+Scan project for source files and identify languages:
+
+| Extension | Language |
+|-----------|----------|
+| `.php` | PHP |
+| `.js`, `.jsx` | JavaScript |
+| `.ts`, `.tsx` | TypeScript |
+| `.py` | Python |
+| `.go` | Go |
+| `.rb` | Ruby |
+| `.java` | Java |
+| `.cs` | C# |
+| `.rs` | Rust |
+
+### Step 2: Check for Config Files
+
+Look for existing style configuration:
+
+| File | Tool | Language |
+|------|------|----------|
+| `.eslintrc*` | ESLint | JS/TS |
+| `.prettierrc*` | Prettier | JS/TS/CSS |
+| `phpcs.xml` | PHP_CodeSniffer | PHP |
+| `.php-cs-fixer.php` | PHP CS Fixer | PHP |
+| `pyproject.toml` | Black/Ruff | Python |
+| `.editorconfig` | EditorConfig | All |
+| `tslint.json` | TSLint | TypeScript |
+| `.rubocop.yml` | RuboCop | Ruby |
+
+If config files exist, extract rules from them first.
+
+### Step 3: Analyze Sample Files
+
+For each detected language, read 3-5 representative files:
+- Prefer files in `src/`, `app/`, `lib/` directories
+- Choose files with 50-200 lines (not too short, not too long)
+- Include different file types (classes, utilities, controllers)
+
+### Step 4: Detect Patterns
+
+For each file, analyze:
+
+#### Formatting
+- **Indentation:** Count leading whitespace characters
+  - All tabs → tabs
+  - 2 spaces → 2-space indent
+  - 4 spaces → 4-space indent
+- **Braces:** Check if `{` appears on same line or next line
+- **Spacing:** Check patterns inside parentheses, after keywords
+- **Semicolons (JS):** Present at end of statements?
+- **Quotes (JS):** Single or double quotes predominant?
+
+#### Naming
+- **Classes:** PascalCase, snake_case, etc.
+- **Functions:** camelCase, snake_case, etc.
+- **Variables:** camelCase, snake_case, etc.
+- **Constants:** UPPER_CASE, camelCase, etc.
+
+#### Structure
+- **Import organization:** Grouped? Alphabetized?
+- **File organization:** Class structure patterns
+
+#### Documentation
+- **DocBlocks:** Present? Format?
+- **Comments:** Inline style?
+
+### Step 5: Resolve Conflicts
+
+If patterns vary across files:
+1. Count occurrences of each pattern
+2. Use majority pattern (60%+ agreement)
+3. Note inconsistencies for user review
+4. Flag if no clear majority exists
+
+### Step 6: Generate Standards Document
+
+Use the appropriate template from `templates/standards/`:
+- `php.standards.md` for PHP
+- `javascript.standards.md` for JS/TS
+
+Fill in detected values, replacing `{placeholders}`.
+
+---
+
+## Output
+
+Create files in `docs/ai/standards/` (user-customizable location):
+
+```
+docs/ai/standards/
+├── php.standards.md        # If PHP detected
+├── javascript.standards.md # If JS/TS detected
+└── {language}.standards.md # For other languages
+```
+
+These user standards take priority over framework defaults in `docs/ai/.context/templates/standards/`.
+See [coding-standards.md](../standards/coding-standards.md) for resolution order.
+
+---
+
+## Analysis Checklist
+
+### PHP Analysis
+
+```php
+// Check for:
+// 1. Indentation
+$line = "    code";  // 4 spaces
+$line = "\tcode";    // tab
+
+// 2. Brace style
+class Foo {          // same-line
+class Foo            // next-line
+{
+
+// 3. Parentheses spacing
+function foo( $param )   // spaces inside
+function foo($param)     // no spaces
+
+// 4. Array syntax
+$arr = array();      // long syntax
+$arr = [];           // short syntax
+
+// 5. Visibility
+public $prop;        // explicit
+var $prop;           // implicit (old style)
+
+// 6. Type hints
+function foo( string $a ): int    // yes
+function foo( $a )                 // no
+```
+
+### JavaScript Analysis
+
+```javascript
+// Check for:
+// 1. Semicolons
+const x = 1;    // with semicolon
+const x = 1     // without
+
+// 2. Quotes
+'single quotes'
+"double quotes"
+
+// 3. Variable declaration
+const x = 1;    // const preferred
+let x = 1;      // let used
+var x = 1;      // var used (legacy)
+
+// 4. Arrow functions
+const fn = () => {};     // arrow
+function fn() {}         // declaration
+
+// 5. Trailing commas
+{ a: 1, b: 2, }   // trailing
+{ a: 1, b: 2 }    // no trailing
+
+// 6. Object shorthand
+{ name: name }    // verbose
+{ name }          // shorthand
+```
+
+---
+
+## Example Output
+
+After analyzing a PHP project:
+
+```markdown
+# PHP Coding Standards
+
+> **Language:** PHP
+> **Generated:** 2024-01-15
+> **Detected from:** src/Services/, src/Controllers/
+
+---
+
+## Formatting
+
+### Indentation
+- **Style:** tabs
+- **Size:** 1 tab
+
+### Braces
+- **Classes/Functions:** same-line
+- **Control structures:** same-line
+
+### Spacing
+- **Inside parentheses:** yes - `function( $param )`
+- **After keywords:** yes - `if( $x )`
+- **Array brackets:** no-spaces - `$arr['key']`
+
+---
+
+## Naming Conventions
+
+### Classes
+- **Style:** PascalCase
+- **Example:** `UserService`, `PaymentController`
+
+### Methods
+- **Style:** camelCase
+- **Example:** `getUserById()`, `processPayment()`
+
+### Variables
+- **Style:** snake_case
+- **Example:** `$user_name`, `$is_active`
+
+...
+```
+
+---
+
+## Edge Cases
+
+### Mixed Standards
+If project has inconsistent standards:
+1. Document the majority pattern
+2. Add a note about inconsistencies
+3. Suggest the user choose one
+
+```markdown
+> **Note:** Mixed indentation detected (60% tabs, 40% 2-space).
+> Documenting tabs as primary. Consider standardizing.
+```
+
+### No Clear Pattern
+If no pattern emerges:
+1. Leave placeholder in template
+2. Note that manual input is needed
+
+```markdown
+### Variables
+- **Style:** {inconsistent - needs manual specification}
+```
+
+### Config File Conflicts
+If config files disagree with actual code:
+1. Prefer config file settings (they're intentional)
+2. Note that code may not follow config
+3. Suggest running linter to fix
+
+---
+
+## Reporting
+
+After generating standards, report:
+
+1. Languages detected
+2. Files analyzed
+3. Config files found
+4. Standards documents created
+5. Any inconsistencies or manual input needed
+
+```
+Standards Detection Complete
+============================
+Languages: PHP, JavaScript
+Files analyzed: 12
+Config files: .eslintrc.js, .editorconfig
+
+Created:
+  - docs/ai/standards/php.standards.md
+  - docs/ai/standards/javascript.standards.md
+
+Notes:
+  - PHP: Inconsistent variable naming (70% snake_case)
+  - JS: No semicolons detected, matches .eslintrc
+```

package/dist/templates/version.json

@@ -0,0 +1,8 @@
+{
+	"name": "contextuate",
+	"version": "1.0.0",
+	"description": "AI Context Framework - Standardized documentation for AI coding assistants",
+	"repository": "https://github.com/esotech/contextuate",
+	"installed": null,
+	"updated": null
+}

package/dist/utils/git.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitManager = void 0;
+const child_process_1 = require("child_process");
+const util_1 = __importDefault(require("util"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const execAsync = util_1.default.promisify(child_process_1.exec);
+class GitManager {
+    constructor(cwd) {
+        this.cwd = cwd;
+    }
+    async isGitRepo() {
+        try {
+            await execAsync('git rev-parse --is-inside-work-tree', { cwd: this.cwd });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async getCurrentBranch() {
+        const { stdout } = await execAsync('git rev-parse --abbrev-ref HEAD', { cwd: this.cwd });
+        return stdout.trim();
+    }
+    async createWorktree(agentName, sessionId) {
+        // Worktrees will be stored in .contextuate/worktrees/
+        const worktreeDir = path_1.default.join(this.cwd, '.contextuate/worktrees', `${agentName}-${sessionId}`);
+        const branchName = `agent/${agentName}/${sessionId}`;
+        // Ensure parent dir exists
+        await fs_extra_1.default.ensureDir(path_1.default.dirname(worktreeDir));
+        // Create worktree with a new branch
+        // -b creates the branch
+        await execAsync(`git worktree add -b ${branchName} "${worktreeDir}"`, { cwd: this.cwd });
+        return worktreeDir;
+    }
+    async removeWorktree(worktreePath, deleteBranch = false) {
+        await execAsync(`git worktree remove "${worktreePath}" --force`, { cwd: this.cwd });
+        if (deleteBranch) {
+            // Extract branch name from path? Or pass it in.
+            // For safety, maybe we don't auto-delete the branch by default so work is preserved.
+        }
+    }
+    async commitChanges(worktreePath, message) {
+        try {
+            await execAsync('git add .', { cwd: worktreePath });
+            // check if there are changes
+            await execAsync(`git commit -m "${message}"`, { cwd: worktreePath });
+        }
+        catch (e) {
+            // If nothing to commit, that's fine
+            if (e.stdout && e.stdout.includes('nothing to commit')) {
+                return;
+            }
+            throw e;
+        }
+    }
+}
+exports.GitManager = GitManager;

package/dist/utils/tokens.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateTokens = estimateTokens;
+exports.generateFileTree = generateFileTree;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Estimates the number of tokens in a string.
+ * Uses a simple heuristic: ~4 characters per token for English text/code.
+ */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Generates a compact file tree representation of a directory.
+ * Respects .gitignore via a simple filter (can be enhanced).
+ */
+async function generateFileTree(dir, maxDepth = 5) {
+    const lines = [];
+    // Load gitignore if present
+    const gitignorePath = path_1.default.join(dir, '.gitignore');
+    let ignorePatterns = ['.git', 'node_modules', 'dist', 'coverage', '.DS_Store'];
+    if (await fs_extra_1.default.pathExists(gitignorePath)) {
+        const content = await fs_extra_1.default.readFile(gitignorePath, 'utf-8');
+        const userIgnores = content.split('\n')
+            .map(l => l.trim())
+            .filter(l => l && !l.startsWith('#'));
+        ignorePatterns = [...ignorePatterns, ...userIgnores];
+    }
+    const isIgnored = (name) => {
+        // Very basic glob matching for common patterns
+        return ignorePatterns.some(pattern => {
+            const cleanPattern = pattern.replace(/\/$/, '').replace(/^\//, '');
+            if (pattern.startsWith('*'))
+                return name.endsWith(pattern.slice(1));
+            if (pattern.endsWith('*'))
+                return name.startsWith(pattern.slice(0, -1));
+            return name === cleanPattern || matchGlob(name, cleanPattern);
+        });
+    };
+    // Helper for simple glob matching
+    const matchGlob = (str, glob) => {
+        const regex = new RegExp('^' + glob.replace(/\./g, '\\.').replace(/\*/g, '.*') + '$');
+        return regex.test(str);
+    };
+    async function traverse(currentDir, currentDepth, prefix = '') {
+        if (currentDepth > maxDepth)
+            return;
+        const entries = await fs_extra_1.default.readdir(currentDir, { withFileTypes: true });
+        // Sort: directories first, then files
+        entries.sort((a, b) => {
+            if (a.isDirectory() === b.isDirectory())
+                return a.name.localeCompare(b.name);
+            return a.isDirectory() ? -1 : 1;
+        });
+        const filtered = entries.filter(e => !isIgnored(e.name));
+        for (let i = 0; i < filtered.length; i++) {
+            const entry = filtered[i];
+            const isLast = i === filtered.length - 1;
+            const marker = isLast ? '└── ' : '├── ';
+            lines.push(`${prefix}${marker}${entry.name}${entry.isDirectory() ? '/' : ''}`);
+            if (entry.isDirectory()) {
+                const newPrefix = prefix + (isLast ? '    ' : '│   ');
+                await traverse(path_1.default.join(currentDir, entry.name), currentDepth + 1, newPrefix);
+            }
+        }
+    }
+    lines.push(path_1.default.basename(dir) + '/');
+    await traverse(dir, 1);
+    return lines.join('\n');
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@esotech/contextuate",
+  "version": "2.0.0",
+  "description": "**Standardized AI Context for Software Projects**",
+  "main": "dist/index.js",
+  "bin": {
+    "contextuate": "dist/index.js"
+  },
+  "directories": {
+    "doc": "docs"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc && mkdir -p dist/templates && cp -r src/templates/* dist/templates/",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/esotech/contextuate.git"
+  },
+  "files": [
+    "dist",
+    "docs/ai/.context"
+  ],
+  "keywords": [
+    "ai",
+    "context",
+    "llm",
+    "agent",
+    "coding-assistant",
+    "copilot",
+    "cursor",
+    "anthropic",
+    "claude"
+  ],
+  "author": "Alexander David Conroy <alex@esotech.com> (https://github.com/geilt)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/esotech/contextuate/issues"
+  },
+  "homepage": "https://contextuate.md",
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/inquirer": "^9.0.9",
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "fs-extra": "^11.3.2",
+    "gray-matter": "^4.0.3",
+    "inquirer": "^13.0.1"
+  }
+}