@esotech/contextuate 2.0.0 → 2.1.0

package/README.md

@@ -68,6 +68,7 @@ Contextuate is a directory structure and set of conventions that helps AI agents
 - **`docs/ai/standards/`**: Explicit coding standards and behavioral guidelines.
 - **`docs/ai/quickrefs/`**: Condensed documentation optimized for AI token limits.
 - **`docs/ai/tasks/`**: A workflow for managing multi-session AI tasks.
+- **`docs/ai/skills/`**: Slash commands that activate special behaviors (e.g., `/orchestrate`).
 
 ## How LLMs Use Contextuate
 
@@ -119,6 +120,7 @@ contextuate -V         # Short form for version
 | `index`        | Generate a project file tree             |
 | `add-context`  | Interactively add files to context       |
 | `remove`       | Clean up framework files                 |
+| `monitor`      | Real-time Claude Code session monitoring |
 
 ---
 
@@ -168,6 +170,7 @@ contextuate install --all
 contextuate install --agents archon base canvas
 contextuate install --standards php javascript
 contextuate install --tools quickref
+contextuate install --skills orchestrate
 
 # Subcommand style
 contextuate install agents archon base
@@ -175,6 +178,7 @@ contextuate install agents --all
 contextuate install standards php javascript python
 contextuate install standards --all
 contextuate install tools --all
+contextuate install skills --all
 
 # Force overwrite
 contextuate install agents --all --force
@@ -184,14 +188,16 @@ contextuate install agents --all --force
 - `-a, --agents <names...>` - Install specific agents
 - `-s, --standards <names...>` - Install language standards
 - `-t, --tools <names...>` - Install tools
+- `-k, --skills <names...>` - Install skills (slash commands)
 - `--all` - Install all available templates
 - `-l, --list` - List available templates
 - `-f, --force` - Overwrite existing files
 
 **Subcommands:**
-- `install agents [names...]` - Install agent templates
+- `install agents [names...]` - Install agent templates (also installs skills by default)
 - `install standards [names...]` - Install language standard templates
 - `install tools [names...]` - Install tool templates
+- `install skills [names...]` - Install skill templates (slash commands like `/orchestrate`)
 
 ---
 
@@ -269,6 +275,168 @@ Remove unmodified platform jump files.
 contextuate remove
 ```
 
+---
+
+### `contextuate monitor`
+
+Real-time monitoring dashboard for Claude Code sessions. Tracks tool usage, events, and session activity.
+
+#### Architecture
+
+The monitor uses a 3-layer architecture:
+
+1. **Hooks** - Claude Code hooks emit events to the daemon
+2. **Daemon** - Background process that collects and processes events (runs independently)
+3. **UI Server** - Web dashboard and WebSocket server for real-time updates
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│   Claude Code   │────▶│     Daemon      │────▶│   UI Server     │
+│     (Hooks)     │     │   (Background)  │     │   (Dashboard)   │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+```
+
+**Important:** The daemon runs independently of the UI server. Starting the monitor will spawn the daemon, but stopping the monitor will NOT stop the daemon (so it can continue collecting events). Use `--all` to stop both.
+
+#### Commands
+
+```bash
+# Initial setup (interactive)
+contextuate monitor init
+contextuate monitor init --global   # Install hooks at user level (~/.claude/)
+contextuate monitor init --project  # Install hooks at project level (.claude/)
+
+# Start the monitor (auto-starts daemon if not running)
+contextuate monitor
+contextuate monitor start
+contextuate monitor start --port 8080       # Custom HTTP port
+contextuate monitor start --ws-port 8081    # Custom WebSocket port
+contextuate monitor start --no-open         # Don't open browser
+contextuate monitor start --foreground      # Run in foreground (blocking)
+
+# Stop the monitor
+contextuate monitor stop          # Stop UI server only (daemon keeps running)
+contextuate monitor stop --all    # Stop both UI server and daemon
+
+# Check status
+contextuate monitor status
+
+# Daemon management (advanced)
+contextuate monitor daemon start            # Start daemon only
+contextuate monitor daemon start --detach   # Start daemon in background
+contextuate monitor daemon stop             # Stop daemon
+contextuate monitor daemon status           # Check daemon status
+contextuate monitor daemon logs             # View daemon logs
+contextuate monitor daemon logs -f          # Follow daemon logs
+contextuate monitor daemon logs -n 100      # Show last 100 lines
+```
+
+#### Configuration
+
+Configuration is stored in `~/.contextuate/monitor/config.json`. Run `contextuate monitor init` for interactive setup, or edit the file directly.
+
+##### Full Configuration Example
+
+```json
+{
+  "mode": "local",
+  "server": {
+    "host": "0.0.0.0",
+    "port": 3847,
+    "wsPort": 3848
+  },
+  "redis": {
+    "host": "localhost",
+    "port": 6379,
+    "password": null,
+    "channel": "contextuate:events"
+  },
+  "persistence": {
+    "enabled": true,
+    "type": "file",
+    "database": {
+      "host": "localhost",
+      "port": 3306,
+      "database": "contextuate",
+      "user": "contextuate",
+      "password": "secret"
+    }
+  },
+  "socketPath": "/tmp/contextuate-monitor.sock"
+}
+```
+
+##### Configuration Parameters
+
+| Parameter | Type | Default | Description |
+|:----------|:-----|:--------|:------------|
+| `mode` | `"local"` \| `"redis"` | `"local"` | Communication mode between components |
+| `socketPath` | string | `"/tmp/contextuate-monitor.sock"` | Unix socket path (local mode only) |
+
+**Server Settings** (`server`):
+
+| Parameter | Type | Default | Description |
+|:----------|:-----|:--------|:------------|
+| `host` | string | `"0.0.0.0"` | Host to bind the HTTP server |
+| `port` | number | `3847` | HTTP port for the dashboard |
+| `wsPort` | number | `3848` | WebSocket port for real-time updates |
+
+**Redis Settings** (`redis`) - for distributed/multi-machine setups:
+
+| Parameter | Type | Default | Description |
+|:----------|:-----|:--------|:------------|
+| `host` | string | `"localhost"` | Redis server host |
+| `port` | number | `6379` | Redis server port |
+| `password` | string \| null | `null` | Redis password (optional) |
+| `channel` | string | `"contextuate:events"` | Redis pub/sub channel name |
+
+**Persistence Settings** (`persistence`):
+
+| Parameter | Type | Default | Description |
+|:----------|:-----|:--------|:------------|
+| `enabled` | boolean | `true` | Enable session persistence |
+| `type` | `"file"` \| `"mysql"` \| `"postgresql"` | `"file"` | Storage backend |
+| `database` | object | - | Database connection settings (required for mysql/postgresql) |
+
+**Database Settings** (`persistence.database`) - for MySQL/PostgreSQL:
+
+| Parameter | Type | Description |
+|:----------|:-----|:------------|
+| `host` | string | Database server host |
+| `port` | number | Database server port (3306 for MySQL, 5432 for PostgreSQL) |
+| `database` | string | Database name |
+| `user` | string | Database username |
+| `password` | string | Database password |
+
+> **Note:** MySQL and PostgreSQL persistence are planned features. Currently only file-based persistence is fully implemented.
+
+##### Mode Comparison
+
+| Feature | Local Mode | Redis Mode |
+|:--------|:-----------|:-----------|
+| Setup complexity | Simple | Requires Redis server |
+| Multi-machine support | No | Yes |
+| Single machine | Recommended | Overkill |
+| Event delivery | Unix socket | Redis pub/sub |
+| Use case | Personal development | Team/distributed environments |
+
+#### Files and Directories
+
+```
+~/.contextuate/monitor/
+├── config.json      # Monitor configuration
+├── sessions/        # Persisted session data
+├── raw/             # Raw event files from hooks
+├── processed/       # Processed event files
+├── hooks/           # Hook scripts
+├── daemon.pid       # Daemon process ID
+├── daemon.log       # Daemon logs
+├── server.pid       # UI server process ID
+└── server.log       # UI server logs
+```
+
+---
+
 ## Documentation
 
 For full documentation, see [contextuate.md](https://contextuate.md) or browse the `docs/ai/.contextuate/` directory.

package/dist/commands/claude.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Claude Wrapper Command
+ *
+ * Spawns a Claude session managed by the daemon.
+ * The daemon handles PTY management, so the session persists
+ * even after this command exits.
+ *
+ * Usage: contextuate claude [claude-args...]
+ */
+/**
+ * Main command entry point
+ */
+export declare function claudeCommand(args: string[]): Promise<void>;
+/**
+ * List active wrappers
+ */
+export declare function listWrappersCommand(): Promise<void>;
+/**
+ * Kill a wrapper session
+ */
+export declare function killWrapperCommand(wrapperId: string): Promise<void>;

package/dist/commands/claude.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Claude Wrapper Command
+ *
+ * Spawns a Claude session managed by the daemon.
+ * The daemon handles PTY management, so the session persists
+ * even after this command exits.
+ *
+ * Usage: contextuate claude [claude-args...]
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCommand = claudeCommand;
+exports.listWrappersCommand = listWrappersCommand;
+exports.killWrapperCommand = killWrapperCommand;
+const net = __importStar(require("net"));
+const fs = __importStar(require("fs"));
+// Daemon socket path
+const DAEMON_SOCKET = '/tmp/contextuate-daemon.sock';
+/**
+ * Connect to daemon and spawn a wrapper
+ */
+async function spawnWrapper(args, cwd) {
+    return new Promise((resolve) => {
+        // Check if daemon socket exists
+        if (!fs.existsSync(DAEMON_SOCKET)) {
+            resolve({ success: false, error: 'Daemon not running. Start with: contextuate monitor' });
+            return;
+        }
+        const socket = new net.Socket();
+        let responseReceived = false;
+        socket.connect(DAEMON_SOCKET, () => {
+            // Send spawn request
+            const message = {
+                type: 'spawn_wrapper',
+                args,
+                cwd,
+                cols: process.stdout.columns || 120,
+                rows: process.stdout.rows || 40,
+            };
+            socket.write(JSON.stringify(message) + '\n');
+        });
+        socket.on('data', (data) => {
+            try {
+                const lines = data.toString().split('\n').filter(l => l.trim());
+                for (const line of lines) {
+                    const response = JSON.parse(line);
+                    if (response.type === 'wrapper_spawned') {
+                        responseReceived = true;
+                        socket.end();
+                        resolve({
+                            success: response.success,
+                            wrapperId: response.wrapperId,
+                            error: response.error,
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                // Ignore parse errors
+            }
+        });
+        socket.on('error', (err) => {
+            if (!responseReceived) {
+                resolve({ success: false, error: `Connection error: ${err.message}` });
+            }
+        });
+        socket.on('close', () => {
+            if (!responseReceived) {
+                resolve({ success: false, error: 'Connection closed without response' });
+            }
+        });
+        // Timeout after 10 seconds
+        setTimeout(() => {
+            if (!responseReceived) {
+                socket.destroy();
+                resolve({ success: false, error: 'Spawn request timed out' });
+            }
+        }, 10000);
+    });
+}
+/**
+ * Main command entry point
+ */
+async function claudeCommand(args) {
+    const cwd = process.cwd();
+    console.log('Spawning Claude session via daemon...');
+    const result = await spawnWrapper(args, cwd);
+    if (result.success) {
+        console.log(`\nClaude session started: ${result.wrapperId}`);
+        console.log('\nThe session is now running in the background, managed by the daemon.');
+        console.log('Access it via the monitor UI at http://localhost:3456');
+        console.log('\nTo view active wrappers: contextuate wrapper list');
+        console.log('To kill a wrapper: contextuate wrapper kill <wrapper-id>');
+    }
+    else {
+        console.error(`\nFailed to spawn Claude session: ${result.error}`);
+        process.exit(1);
+    }
+}
+/**
+ * List active wrappers
+ */
+async function listWrappersCommand() {
+    return new Promise((resolve) => {
+        if (!fs.existsSync(DAEMON_SOCKET)) {
+            console.error('Daemon not running. Start with: contextuate monitor');
+            process.exit(1);
+        }
+        const socket = new net.Socket();
+        socket.connect(DAEMON_SOCKET, () => {
+            socket.write(JSON.stringify({ type: 'get_wrappers' }) + '\n');
+        });
+        socket.on('data', (data) => {
+            try {
+                const lines = data.toString().split('\n').filter(l => l.trim());
+                for (const line of lines) {
+                    const response = JSON.parse(line);
+                    if (response.type === 'wrappers_list') {
+                        socket.end();
+                        if (response.wrappers.length === 0) {
+                            console.log('No active wrapper sessions.');
+                        }
+                        else {
+                            console.log('Active wrapper sessions:\n');
+                            for (const wrapper of response.wrappers) {
+                                const type = wrapper.managed ? 'managed' : 'legacy';
+                                console.log(`  ${wrapper.wrapperId} [${type}]`);
+                                console.log(`    State: ${wrapper.state}`);
+                                console.log(`    PID: ${wrapper.pid}`);
+                                console.log(`    CWD: ${wrapper.cwd}`);
+                                if (wrapper.claudeSessionId) {
+                                    console.log(`    Claude Session: ${wrapper.claudeSessionId.slice(0, 8)}...`);
+                                }
+                                console.log();
+                            }
+                        }
+                        resolve();
+                    }
+                }
+            }
+            catch (err) {
+                // Ignore parse errors
+            }
+        });
+        socket.on('error', (err) => {
+            console.error(`Connection error: ${err.message}`);
+            process.exit(1);
+        });
+        setTimeout(() => {
+            socket.destroy();
+            console.error('Request timed out');
+            process.exit(1);
+        }, 5000);
+    });
+}
+/**
+ * Kill a wrapper session
+ */
+async function killWrapperCommand(wrapperId) {
+    return new Promise((resolve) => {
+        if (!fs.existsSync(DAEMON_SOCKET)) {
+            console.error('Daemon not running. Start with: contextuate monitor');
+            process.exit(1);
+        }
+        const socket = new net.Socket();
+        socket.connect(DAEMON_SOCKET, () => {
+            socket.write(JSON.stringify({ type: 'kill_wrapper', wrapperId }) + '\n');
+            // Give daemon time to process, then close
+            setTimeout(() => {
+                socket.end();
+                console.log(`Kill request sent for wrapper ${wrapperId}`);
+                resolve();
+            }, 500);
+        });
+        socket.on('error', (err) => {
+            console.error(`Connection error: ${err.message}`);
+            process.exit(1);
+        });
+    });
+}

package/dist/commands/context.d.ts

@@ -0,0 +1 @@
+export declare function addContextCommand(): Promise<void>;

package/dist/commands/create.d.ts

@@ -0,0 +1,3 @@
+export declare function createAgentCommand(name: string, options: {
+    description?: string;
+}): Promise<void>;

package/dist/commands/index.d.ts

@@ -0,0 +1,4 @@
+export declare function indexCommand(options: {
+    depth?: string;
+    force?: boolean;
+}): Promise<void>;

package/dist/commands/init.d.ts

@@ -0,0 +1,7 @@
+export declare function initCommand(platformArgs: string[] | {
+    force?: boolean;
+    agents?: string[];
+}, options?: {
+    force?: boolean;
+    agents?: string[];
+}): Promise<void>;

package/dist/commands/init.js

@@ -8,6 +8,37 @@ const inquirer_1 = __importDefault(require("inquirer"));
 const chalk_1 = __importDefault(require("chalk"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
+const fs_1 = require("fs");
+// Get package version dynamically
+function getPackageVersion() {
+    try {
+        const packageJson = JSON.parse((0, fs_1.readFileSync)(path_1.default.join(__dirname, '../../package.json'), 'utf-8'));
+        return packageJson.version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+// Get package info for version.json
+function getPackageInfo() {
+    try {
+        const packageJson = JSON.parse((0, fs_1.readFileSync)(path_1.default.join(__dirname, '../../package.json'), 'utf-8'));
+        return {
+            name: packageJson.name || 'contextuate',
+            version: packageJson.version || '0.0.0',
+            description: packageJson.description || 'AI Context Framework',
+            repository: packageJson.repository?.url?.replace('git+', '').replace('.git', '') || 'https://github.com/esotech/contextuate'
+        };
+    }
+    catch {
+        return {
+            name: 'contextuate',
+            version: '0.0.0',
+            description: 'AI Context Framework',
+            repository: 'https://github.com/esotech/contextuate'
+        };
+    }
+}
 // Platform definitions with metadata
 const PLATFORMS = [
     { id: 'agents', name: 'Agents.ai', src: 'templates/platforms/AGENTS.md', dest: 'AGENTS.md' },
@@ -57,7 +88,7 @@ async function initCommand(platformArgs, options) {
     console.log(chalk_1.default.blue('╔════════════════════════════════════════╗'));
     console.log(chalk_1.default.blue('║     Contextuate Installer              ║'));
     console.log(chalk_1.default.blue('║     AI Context Framework               ║'));
-    console.log(chalk_1.default.blue('║     Powered by Esotech                 ║'));
+    console.log(chalk_1.default.blue('║                                        ║'));
     console.log(chalk_1.default.blue('╚════════════════════════════════════════╝'));
     console.log('');
     try {
@@ -168,7 +199,11 @@ async function initCommand(platformArgs, options) {
         }
         if (opts.agents && opts.agents.length > 0) {
             // Non-interactive agent selection via --agents flag
-            if (opts.agents.includes('all')) {
+            if (opts.agents.includes('none')) {
+                // Explicitly skip agent installation
+                console.log(chalk_1.default.blue('[INFO] Skipping agent installation (--agents none)'));
+            }
+            else if (opts.agents.includes('all')) {
                 selectedAgents = availableAgents;
                 console.log(chalk_1.default.blue('[INFO] Installing all agents'));
             }
@@ -185,7 +220,7 @@ async function initCommand(platformArgs, options) {
                         console.log(chalk_1.default.yellow(`[WARN] Could not match agent "${agentArg}" - skipping`));
                     }
                 }
-                if (selectedAgents.length === 0 && opts.agents.length > 0 && !opts.agents.includes('all')) {
+                if (selectedAgents.length === 0 && opts.agents.length > 0) {
                     console.log(chalk_1.default.yellow('[WARN] No valid agents matched. Available agents:'));
                     availableAgents.forEach(a => console.log(`  - ${a}`));
                 }
@@ -226,6 +261,11 @@ async function initCommand(platformArgs, options) {
                 }
             }
         }
+        else {
+            // Non-interactive mode without --agents flag: default to all agents
+            selectedAgents = availableAgents;
+            console.log(chalk_1.default.blue('[INFO] Installing all agents (default in non-interactive mode)'));
+        }
         console.log('');
         console.log(chalk_1.default.blue('[INFO] Installing Contextuate framework...'));
         console.log('');
@@ -301,7 +341,18 @@ async function initCommand(platformArgs, options) {
             console.log(chalk_1.default.green(`[OK] Created: ${dest}`));
         };
         // Copy core engine files only to .contextuate
-        await copyFile(path_1.default.join(templateSource, 'version.json'), path_1.default.join(installDir, 'version.json'));
+        // Generate version.json dynamically from package.json
+        const pkgInfo = getPackageInfo();
+        const versionData = {
+            name: pkgInfo.name,
+            version: pkgInfo.version,
+            description: pkgInfo.description,
+            repository: pkgInfo.repository,
+            installed: new Date().toISOString(),
+            updated: new Date().toISOString()
+        };
+        await fs_extra_1.default.writeFile(path_1.default.join(installDir, 'version.json'), JSON.stringify(versionData, null, 2));
+        console.log(chalk_1.default.green(`[OK] Created: ${path_1.default.join(installDir, 'version.json')}`));
         await copyFile(path_1.default.join(templateSource, 'README.md'), path_1.default.join(installDir, 'README.md'));
         // Copy directories - only core framework files
         const copyDirContents = async (srcSubDir, destDir) => {
@@ -337,7 +388,14 @@ async function initCommand(platformArgs, options) {
         // Copy contextuate.md (main entry point) directly from templates to docs/ai/.contextuate/ (protected)
         await copyFile(path_1.default.join(templateSource, 'templates/contextuate.md'), 'docs/ai/.contextuate/contextuate.md');
         // Copy context.md (user customizable) directly from templates to docs/ai/
-        await copyFile(path_1.default.join(templateSource, 'templates/context.md'), 'docs/ai/context.md');
+        // IMPORTANT: Never overwrite context.md even with --force, as it contains project-specific context
+        const contextMdPath = 'docs/ai/context.md';
+        if (fs_extra_1.default.existsSync(contextMdPath)) {
+            console.log(chalk_1.default.yellow(`[WARN] Preserved (project context): ${contextMdPath}`));
+        }
+        else {
+            await copyFile(path_1.default.join(templateSource, 'templates/context.md'), contextMdPath);
+        }
         console.log('');
         // 5. Generate jump files for selected platforms
         console.log(chalk_1.default.blue('[INFO] Generating platform jump files...'));
@@ -391,6 +449,9 @@ async function initCommand(platformArgs, options) {
                     { target: 'docs/ai/agents', link: '.claude/agents' },
                     { target: 'docs/ai/hooks', link: '.claude/hooks' },
                     { target: 'docs/ai/skills', link: '.claude/skills' },
+                    // Link .contextuate so relative paths from agents work correctly
+                    // (e.g., ../.contextuate/agents/base.md resolves properly)
+                    { target: 'docs/ai/.contextuate', link: '.claude/.contextuate' },
                 ];
                 for (const symlink of symlinks) {
                     await createSymlink(symlink.target, symlink.link);
@@ -429,7 +490,7 @@ async function initCommand(platformArgs, options) {
         console.log('');
         console.log('Documentation: https://contextuate.md');
         console.log('');
-        console.log(chalk_1.default.gray('Powered by Esotech.'));
+        console.log(chalk_1.default.gray('Contextuate Framework'));
         console.log(chalk_1.default.gray('Created by Alexander Conroy (@geilt)'));
         console.log('');
     }

package/dist/commands/install.d.ts

@@ -0,0 +1,28 @@
+interface InstallOptions {
+    agents?: string[];
+    standards?: string[];
+    tools?: string[];
+    skills?: string[];
+    all?: boolean;
+    list?: boolean;
+    force?: boolean;
+}
+export declare function installAgentsCommand(names: string[], options: {
+    all?: boolean;
+    force?: boolean;
+    includeSkills?: boolean;
+}): Promise<void>;
+export declare function installStandardsCommand(names: string[], options: {
+    all?: boolean;
+    force?: boolean;
+}): Promise<void>;
+export declare function installToolsCommand(names: string[], options: {
+    all?: boolean;
+    force?: boolean;
+}): Promise<void>;
+export declare function installSkillsCommand(names: string[], options: {
+    all?: boolean;
+    force?: boolean;
+}): Promise<void>;
+export declare function installCommand(options: InstallOptions): Promise<void>;
+export {};