@esotech/contextuate 2.0.0

package/dist/index.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const init_1 = require("./commands/init");
+const remove_1 = require("./commands/remove");
+const run_1 = require("./commands/run");
+const create_1 = require("./commands/create");
+const index_1 = require("./commands/index");
+const context_1 = require("./commands/context");
+const install_1 = require("./commands/install");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const program = new commander_1.Command();
+// Try to read version from package.json
+let version = '0.0.0';
+try {
+    const packageJson = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(__dirname, '../package.json'), 'utf-8'));
+    version = packageJson.version;
+}
+catch (error) {
+    // Ignore error if package.json is not found (e.g. during development)
+}
+program
+    .name('contextuate')
+    .description('Standardized AI context framework for any project. Powered by Esotech.')
+    .version(version);
+program
+    .command('init [platforms...]')
+    .description('Initialize Contextuate in the current project')
+    .option('-f, --force', 'Overwrite existing files')
+    .option('-a, --agents <agents...>', 'Install specific agents (e.g., "base archon" or "all")')
+    .action(init_1.initCommand);
+program
+    .command('remove')
+    .description('Remove unmodified platform jump files')
+    .action(remove_1.removeCommand);
+program
+    .command('create-agent')
+    .alias('new-agent')
+    .description('Create a new agent definition')
+    .argument('[name]', 'Name of the agent (kebab-case)')
+    .option('-d, --description <text>', 'Description of the agent')
+    .action(create_1.createAgentCommand);
+program
+    .command('index')
+    .description('Generate a project structure index for AI context')
+    .option('-d, --depth <number>', 'Maximum depth of the file tree', '5')
+    .option('-f, --force', 'Overwrite existing index')
+    .action(index_1.indexCommand);
+program
+    .command('add-context')
+    .description('Interactively add files to docs/ai/context.md')
+    .action(context_1.addContextCommand);
+program
+    .command('run')
+    .description('Run an agent definition')
+    .argument('<agent>', 'Name of the agent to run (e.g. "documentation-expert")')
+    .option('--dry-run', 'Simulate execution without running logic')
+    .option('--isolation <mode>', 'Isolation mode (worktree, none)', 'none')
+    .option('--goal <text>', 'Goal or instructions for the agent')
+    .option('--task <name>', 'Load a task context (scope and latest log)')
+    .action(run_1.runCommand);
+// Install command with subcommands and flag-based usage
+const install = program
+    .command('install')
+    .description('Install templates from the Contextuate repository')
+    .option('-a, --agents <names...>', 'Install specific agents (use "all" for all)')
+    .option('-s, --standards <names...>', 'Install language standards (use "all" for all)')
+    .option('-t, --tools <names...>', 'Install tools (use "all" for all)')
+    .option('--all', 'Install all available templates')
+    .option('-l, --list', 'List available templates')
+    .option('-f, --force', 'Overwrite existing files')
+    .action(install_1.installCommand);
+// Subcommand: install agents
+install
+    .command('agents [names...]')
+    .description('Install agent templates')
+    .option('--all', 'Install all agents')
+    .option('-f, --force', 'Overwrite existing files')
+    .action(install_1.installAgentsCommand);
+// Subcommand: install standards
+install
+    .command('standards [names...]')
+    .description('Install language standard templates')
+    .option('--all', 'Install all standards')
+    .option('-f, --force', 'Overwrite existing files')
+    .action(install_1.installStandardsCommand);
+// Subcommand: install tools
+install
+    .command('tools [names...]')
+    .description('Install tool templates')
+    .option('--all', 'Install all tools')
+    .option('-f, --force', 'Overwrite existing files')
+    .action(install_1.installToolsCommand);
+program.parse();

package/dist/runtime/driver.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMDriver = void 0;
+const chalk_1 = __importDefault(require("chalk"));
+const tools_1 = require("./tools");
+class LLMDriver {
+    constructor(config, goal, cwd, contextFiles = []) {
+        this.activeTools = [];
+        this.config = config;
+        this.goal = goal;
+        this.cwd = cwd;
+        this.toolLoader = new tools_1.ToolLoader(cwd);
+        this.contextFiles = contextFiles;
+    }
+    async run() {
+        // Load Tools
+        if (this.config.capabilities) {
+            this.activeTools = await this.toolLoader.loadTools(this.config.capabilities);
+        }
+        console.log(chalk_1.default.bold('\n[DRIVER] Starting Execution Loop'));
+        console.log(`Provider: ${this.config.provider}`);
+        console.log(`Model:    ${this.config.model}`);
+        console.log(`Goal:     ${this.goal}`);
+        if (this.activeTools.length > 0) {
+            console.log(chalk_1.default.bold('\nLoaded Tools:'));
+            this.activeTools.forEach(t => console.log(`- ${t.name} (${t.path})`));
+        }
+        else {
+            console.log(chalk_1.default.yellow('\n[INFO] No tools loaded (check agent capabilities)'));
+        }
+        if (this.contextFiles.length > 0) {
+            console.log(chalk_1.default.bold('\nContext Files:'));
+            this.contextFiles.forEach(f => console.log(`- ${f}`));
+        }
+        console.log('------------------------------------------------');
+        if (this.config.provider === 'mock') {
+            await this.runMockLoop();
+        }
+        else {
+            // Placeholder for real API implementation
+            throw new Error(`Provider '${this.config.provider}' not yet implemented.`);
+        }
+    }
+    async runMockLoop() {
+        console.log(chalk_1.default.gray('(Mock Mode: Simulating reasoning...)'));
+        await new Promise(r => setTimeout(r, 1000));
+        console.log(chalk_1.default.yellow('\n🤖 Agent Thought:'));
+        console.log('I need to check the files to understand the context.');
+        await new Promise(r => setTimeout(r, 500));
+        console.log(chalk_1.default.cyan('\n🛠️  Tool Call: list_files'));
+        console.log('  path: "."');
+        await new Promise(r => setTimeout(r, 500));
+        console.log(chalk_1.default.green('\n✅ Tool Result:'));
+        console.log('  ["src", "package.json", "README.md"]');
+        await new Promise(r => setTimeout(r, 1000));
+        console.log(chalk_1.default.yellow('\n🤖 Agent Thought:'));
+        console.log('Okay, I see the structure. I have completed the basic check.');
+        console.log(chalk_1.default.bold('\n[DRIVER] Execution Complete.'));
+    }
+}
+exports.LLMDriver = LLMDriver;

package/dist/runtime/tools.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolLoader = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+class ToolLoader {
+    constructor(projectRoot) {
+        this.toolsDir = path_1.default.join(projectRoot, 'docs/ai/.contextuate/tools');
+    }
+    async loadTools(capabilities) {
+        const loadedTools = [];
+        // 1. Check if tools dir exists
+        if (!await fs_extra_1.default.pathExists(this.toolsDir)) {
+            console.warn(`[WARN] Tools directory not found at: ${this.toolsDir}`);
+            return [];
+        }
+        // 2. Map capabilities to files
+        // Convention: capability "spawn_agent" -> "spawn.tool.md" or "spawn_agent.tool.md"
+        // We'll search for matches.
+        const files = await fs_extra_1.default.readdir(this.toolsDir);
+        for (const cap of capabilities) {
+            // rigorous matching: 
+            // 1. Exact match: cap + ".tool.md"
+            // 2. Name match: file starts with cap + "."
+            // 3. Simple fuzzy?
+            const match = files.find(f => f === `${cap}.tool.md` ||
+                f === `${cap.replace(/_/g, '-')}.tool.md` ||
+                f.startsWith(`${cap}.`));
+            if (match) {
+                const toolPath = path_1.default.join(this.toolsDir, match);
+                const content = await fs_extra_1.default.readFile(toolPath, 'utf-8');
+                loadedTools.push({
+                    name: cap,
+                    path: toolPath,
+                    content: content
+                });
+            }
+            else {
+                console.warn(`[WARN] No tool definition found for capability: ${cap}`);
+            }
+        }
+        return loadedTools;
+    }
+}
+exports.ToolLoader = ToolLoader;

package/dist/templates/README.md

@@ -0,0 +1,152 @@
+# Contextuate Framework
+
+> **DO NOT MODIFY FILES IN THIS DIRECTORY**
+>
+> This folder contains the core Contextuate framework files. These are managed by the installer and will be overwritten during updates.
+
+---
+
+## Quick Start
+
+After installation, customize your project context in `docs/ai/context.md`. AI assistants will automatically read this file when they start.
+
+---
+
+## Available Tools
+
+Contextuate includes AI tool guides - markdown files that AI assistants read and follow to perform tasks. Ask your AI assistant to use these tools with natural language.
+
+### Standards Detector
+
+Analyzes your codebase to detect and document coding standards.
+
+**How to use:** Ask your AI assistant:
+> "Detect the coding standards for this project"
+> "Analyze my code and create coding standards"
+> "Generate standards documentation from my source files"
+
+**What it does:**
+1. Scans for source files (PHP, JS, TS, etc.)
+2. Checks for config files (.eslintrc, phpcs.xml, etc.)
+3. Analyzes patterns (indentation, naming, braces)
+4. Creates standards files in `docs/ai/standards/`
+
+**Guide:** [tools/standards-detector.tool.md](tools/standards-detector.tool.md)
+
+---
+
+### Quickref Generator
+
+Creates condensed, AI-friendly references from large documentation files.
+
+**How to use:** Ask your AI assistant:
+> "Generate a quickref for docs/classes/user-service.md"
+> "Create a quick reference for the API documentation"
+> "Make a condensed reference for this class"
+
+**What it does:**
+1. Reads source documentation
+2. Extracts method/API signatures
+3. Creates scannable reference tables
+4. Outputs to `docs/ai/quickrefs/{name}.quickref.md`
+
+**When to use:**
+- Documentation exceeds ~200 lines
+- Methods are frequently looked up
+- AI needs method awareness without full context
+
+**Guide:** [tools/quickref.tool.md](tools/quickref.tool.md)
+
+---
+
+### Agent Creator
+
+Creates new AI agent definitions following Contextuate patterns.
+
+**How to use:** Ask your AI assistant:
+> "Create an agent for database operations"
+> "Make a new agent for the authentication system"
+> "Generate an agent definition for React components"
+
+**What it does:**
+1. Determines agent scope and responsibilities
+2. Creates supporting docs if needed
+3. Generates agent file from template
+4. Outputs to `docs/ai/agents/{domain}-expert.md`
+
+**Guide:** [tools/agent-creator.tool.md](tools/agent-creator.tool.md)
+
+---
+
+## Directory Structure
+
+```
+docs/ai/
+├── .context/           # Framework files (DO NOT MODIFY)
+│   ├── agents/         # Base agent definitions
+│   ├── standards/      # Default coding/behavioral standards
+│   ├── templates/      # Platform jump-files and standards templates
+│   ├── tools/          # AI tool guides
+│   └── bin/            # Install/update scripts
+├── agents/             # Your custom agents (user-editable)
+├── standards/          # Your project standards (user-editable)
+├── quickrefs/          # Generated quick references
+├── tasks/              # Task tracking (gitignored)
+└── context.md          # Your project context (user-editable)
+```
+
+---
+
+## Standards Resolution
+
+When AI looks up coding standards for a language:
+
+1. **User Standards (First):** `docs/ai/standards/{language}.standards.md`
+2. **Framework Standards (Fallback):** `docs/ai/.context/templates/standards/{language}.standards.md`
+3. **General Principles (Always):** `docs/ai/.context/standards/coding-standards.md`
+
+---
+
+## Framework Scripts
+
+### install.sh
+
+```bash
+# Remote installation
+curl -fsSL https://contextuate.md/install.sh | bash
+
+# With options
+curl -fsSL https://contextuate.md/install.sh | bash -s -- --force
+```
+
+**Options:**
+- `--force` - Overwrite existing files
+- `--no-git` - Don't modify .gitignore
+
+### update.sh
+
+```bash
+./docs/ai/.context/bin/update.sh
+```
+
+Updates framework files while preserving your customizations.
+
+---
+
+## Agents vs Tools
+
+| Type | Purpose | Location |
+|------|---------|----------|
+| **Agent** | Persona with expertise, decision-making | `agents/*.md` |
+| **Tool** | Step-by-step process guide | `tools/*.tool.md` |
+
+**Agents** define *who* the AI is acting as (e.g., "documentation expert").
+**Tools** define *how* to accomplish a specific task (e.g., "follow these steps to generate a quickref").
+
+---
+
+## Support
+
+- Documentation: https://contextuate.md
+- Repository: https://github.com/esotech/contextuate
+- Issues: https://github.com/esotech/contextuate/issues