@ekkos/cli 0.2.9 → 0.2.11

package/dist/commands/doctor.js

@@ -1,4 +1,14 @@
 "use strict";
+/**
+ * ekkOS CLI: doctor command
+ * Checks system prerequisites for ekkOS
+ *
+ * Per ekkOS Onboarding Spec v1.2 + Addendum:
+ * - Node gate: Node >= 18 required (FAIL if missing)
+ * - PTY gate: WARN on Windows if missing (monitor-only mode available)
+ * - Hooks gate: Verifies hook installation
+ * - NO jq checks (jq dependency eliminated)
+ */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -6,8 +16,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runDiagnostics = runDiagnostics;
 exports.doctor = doctor;
 const os_1 = require("os");
+const path_1 = require("path");
+const fs_1 = require("fs");
 const child_process_1 = require("child_process");
 const chalk_1 = __importDefault(require("chalk"));
+const hooks_1 = require("./hooks");
 /**
  * Check if a command exists in PATH
  */
@@ -65,25 +78,22 @@ function checkPty() {
  */
 function checkMcpConfig() {
     try {
-        const output = (0, child_process_1.execSync)('claude mcp list', {
+        const output = (0, child_process_1.execSync)('claude mcp list 2>&1', {
             encoding: 'utf-8',
-            timeout: 10000,
+            timeout: 30000, // 30s - health checks can be slow
             stdio: ['pipe', 'pipe', 'pipe']
         });
-        // Parse server names from output
-        const servers = [];
-        const lines = output.split('\n');
-        for (const line of lines) {
-            // Look for server names (varies by Claude version)
-            if (line.includes('ekkos') || line.includes('memory')) {
-                servers.push(line.trim());
-            }
-        }
-        const hasEkkos = output.toLowerCase().includes('ekkos') ||
-            output.toLowerCase().includes('memory');
-        return { configured: hasEkkos, servers };
+        return parseMcpOutput(output);
     }
     catch (error) {
+        // Even on timeout/error, stdout may contain partial output
+        const partialOutput = error?.stdout || error?.output?.[1] || '';
+        if (partialOutput) {
+            const result = parseMcpOutput(partialOutput);
+            if (result.configured) {
+                return result; // Got what we needed despite timeout
+            }
+        }
         return {
             configured: false,
             servers: [],
@@ -92,18 +102,58 @@ function checkMcpConfig() {
     }
 }
 /**
- * Check if bash is available (for hooks on Windows)
+ * Parse MCP list output to find ekkOS servers
  */
-function checkBash() {
-    if ((0, os_1.platform)() !== 'win32')
-        return true;
-    try {
-        (0, child_process_1.execSync)('bash --version', { stdio: 'ignore', timeout: 5000 });
-        return true;
+function parseMcpOutput(output) {
+    const servers = [];
+    const lines = output.split('\n');
+    for (const line of lines) {
+        // Look for server names (varies by Claude version)
+        if (line.includes('ekkos') || line.includes('memory')) {
+            servers.push(line.trim());
+        }
     }
-    catch {
-        return false;
+    const hasEkkos = output.toLowerCase().includes('ekkos') ||
+        output.toLowerCase().includes('memory');
+    return { configured: hasEkkos, servers };
+}
+/**
+ * Check hooks installation status
+ */
+function checkHooksInstallation() {
+    const isWindows = (0, os_1.platform)() === 'win32';
+    const manifestData = (0, hooks_1.loadManifest)();
+    if (!manifestData) {
+        return { installed: false, details: 'Source manifest not found' };
+    }
+    const platformConfig = manifestData.manifest.platforms[(0, os_1.platform)()];
+    const globalHooksDir = (0, hooks_1.expandPath)(platformConfig.globalHooksDir);
+    const configDir = (0, hooks_1.expandPath)(platformConfig.configDir);
+    // Check installed manifest
+    const installedManifestPath = (0, path_1.join)(globalHooksDir, '.ekkos-manifest.json');
+    if (!(0, fs_1.existsSync)(installedManifestPath)) {
+        return { installed: false, details: 'No installed manifest found' };
+    }
+    // Check helper
+    const helperPath = (0, path_1.join)(configDir, '.helpers', 'json-parse.cjs');
+    if (!(0, fs_1.existsSync)(helperPath)) {
+        return { installed: false, details: 'json-parse.cjs helper missing' };
     }
+    // Check defaults
+    const defaultsPath = (0, path_1.join)(configDir, '.defaults', 'session-words.json');
+    if (!(0, fs_1.existsSync)(defaultsPath)) {
+        return { installed: false, details: 'Default session words missing' };
+    }
+    // Check required hooks
+    const hookExt = isWindows ? '.ps1' : '.sh';
+    const requiredHooks = ['user-prompt-submit', 'stop', 'session-start'];
+    for (const hookName of requiredHooks) {
+        const hookPath = (0, path_1.join)(globalHooksDir, `${hookName}${hookExt}`);
+        if (!(0, fs_1.existsSync)(hookPath)) {
+            return { installed: false, details: `${hookName}${hookExt} missing` };
+        }
+    }
+    return { installed: true, details: 'All hooks and helpers installed' };
 }
 /**
  * Run diagnostic checks and return report
@@ -115,11 +165,38 @@ function runDiagnostics() {
     const nodeVersion = getVersion('node') || 'Not found';
     const claudeVersion = getVersion('claude');
     // ═══════════════════════════════════════════════════════════════════════════
-    // GATE 1: Interactive Claude Works
+    // GATE 1: Node.js Version (>= 18 required per spec)
+    // ═══════════════════════════════════════════════════════════════════════════
+    const nodeChecks = [];
+    let nodeGatePass = true;
+    const nodeMatch = nodeVersion.match(/v?(\d+)\./);
+    const nodeMajor = nodeMatch ? parseInt(nodeMatch[1], 10) : 0;
+    const nodeOk = nodeMajor >= 18;
+    nodeChecks.push({
+        name: 'Node.js version >= 18',
+        passed: nodeOk,
+        detail: nodeOk
+            ? `${nodeVersion} (OK)`
+            : `${nodeVersion} (Need Node.js 18 or higher)`
+    });
+    if (!nodeOk) {
+        nodeGatePass = false;
+    }
+    gates.push({
+        id: 'node',
+        title: 'Node.js',
+        status: nodeGatePass ? 'PASS' : 'FAIL',
+        checks: nodeChecks,
+        fix: nodeGatePass ? undefined : isWindows
+            ? 'winget install OpenJS.NodeJS.LTS'
+            : 'Install Node.js 20 or 22 LTS from nodejs.org'
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // GATE 2: Interactive Claude Works
     // ═══════════════════════════════════════════════════════════════════════════
     const claudeChecks = [];
     let claudeGatePass = true;
-    // Check 1.1: claude command exists
+    // Check 2.1: claude command exists
     const claudeExists = commandExists('claude');
     claudeChecks.push({
         name: 'Claude CLI installed',
@@ -128,7 +205,7 @@ function runDiagnostics() {
     });
     if (!claudeExists)
         claudeGatePass = false;
-    // Check 1.2: claude --version works
+    // Check 2.2: claude --version works
     if (claudeExists) {
         const versionWorks = claudeVersion !== null;
         claudeChecks.push({
@@ -139,15 +216,6 @@ function runDiagnostics() {
         if (!versionWorks)
             claudeGatePass = false;
     }
-    // Check 1.3: On Windows, PTY is required for interactive mode
-    // This is checked in Gate 2, but we note it here
-    if (isWindows) {
-        claudeChecks.push({
-            name: 'Interactive mode (requires PTY)',
-            passed: true, // Will be validated in Gate 2
-            detail: 'See PTY gate below'
-        });
-    }
     gates.push({
         id: 'interactive-claude',
         title: 'Interactive Claude',
@@ -156,52 +224,71 @@ function runDiagnostics() {
         fix: claudeGatePass ? undefined : 'npm install -g @anthropic-ai/claude-code'
     });
     // ═══════════════════════════════════════════════════════════════════════════
-    // GATE 2: PTY Works (Windows-critical)
+    // GATE 3: PTY Works (WARN on Windows if missing per spec v1.2 Addendum)
     // ═══════════════════════════════════════════════════════════════════════════
     const ptyChecks = [];
-    let ptyGatePass = true;
-    // Check Node version (20.x or 22.x recommended)
-    const nodeMatch = nodeVersion.match(/v?(\d+)\./);
-    const nodeMajor = nodeMatch ? parseInt(nodeMatch[1], 10) : 0;
-    const nodeOk = nodeMajor >= 18 && nodeMajor <= 22;
-    ptyChecks.push({
-        name: 'Node.js version',
-        passed: nodeOk,
-        detail: nodeOk
-            ? `${nodeVersion} (OK)`
-            : `${nodeVersion} (Need 20.x or 22.x LTS for PTY support)`
-    });
-    if (!nodeOk && isWindows)
-        ptyGatePass = false;
+    let ptyGateStatus = 'PASS';
     // Check PTY availability
     const ptyResult = checkPty();
     ptyChecks.push({
         name: 'node-pty loadable',
         passed: ptyResult.available,
-        detail: ptyResult.available ? 'ConPTY available' : ptyResult.error
+        detail: ptyResult.available
+            ? isWindows ? 'ConPTY available' : 'PTY available'
+            : ptyResult.error
     });
-    if (!ptyResult.available && isWindows)
-        ptyGatePass = false;
-    // On macOS/Linux, PTY is typically available, mark as PASS with note
-    if (!isWindows && !ptyResult.available) {
-        ptyChecks.push({
-            name: 'Fallback available',
-            passed: true,
-            detail: 'Unix script(1) fallback available'
-        });
-        ptyGatePass = true; // Unix has fallback
+    if (!ptyResult.available) {
+        if (isWindows) {
+            // Per spec: Windows without PTY is WARN (monitor-only mode available)
+            ptyGateStatus = 'WARN';
+            ptyChecks.push({
+                name: 'Monitor-only mode',
+                passed: true,
+                detail: 'Auto-continue disabled; manual /clear + /continue required'
+            });
+        }
+        else {
+            // Unix has script(1) fallback
+            ptyChecks.push({
+                name: 'Unix fallback',
+                passed: true,
+                detail: 'script(1) fallback available'
+            });
+            ptyGateStatus = 'PASS';
+        }
     }
     gates.push({
         id: 'pty',
         title: 'PTY (Terminal)',
-        status: ptyGatePass ? 'PASS' : (isWindows ? 'FAIL' : 'WARN'),
+        status: ptyGateStatus,
         checks: ptyChecks,
-        fix: ptyGatePass ? undefined : isWindows
-            ? 'npm install node-pty-prebuilt-multiarch OR install VS Build Tools and run: npm rebuild node-pty'
+        fix: ptyGateStatus === 'WARN'
+            ? 'npm install node-pty-prebuilt-multiarch (optional for auto-continue)'
             : undefined
     });
     // ═══════════════════════════════════════════════════════════════════════════
-    // GATE 3: MCP Works
+    // GATE 4: Hooks Installation (per spec v1.2)
+    // ═══════════════════════════════════════════════════════════════════════════
+    const hooksChecks = [];
+    let hooksGateStatus = 'PASS';
+    const hooksResult = checkHooksInstallation();
+    hooksChecks.push({
+        name: 'ekkOS hooks installed',
+        passed: hooksResult.installed,
+        detail: hooksResult.details
+    });
+    if (!hooksResult.installed) {
+        hooksGateStatus = 'WARN';
+    }
+    gates.push({
+        id: 'hooks',
+        title: 'ekkOS Hooks',
+        status: hooksGateStatus,
+        checks: hooksChecks,
+        fix: hooksGateStatus === 'WARN' ? 'ekkos hooks install --global' : undefined
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // GATE 5: MCP Works
     // ═══════════════════════════════════════════════════════════════════════════
     const mcpChecks = [];
     let mcpGatePass = true;
@@ -227,16 +314,6 @@ function runDiagnostics() {
         if (!mcpResult.configured)
             mcpGatePass = false;
     }
-    // Check bash on Windows (for hooks, WARN only)
-    if (isWindows) {
-        const bashOk = checkBash();
-        mcpChecks.push({
-            name: 'Bash available (for hooks)',
-            passed: bashOk,
-            detail: bashOk ? 'Git Bash/WSL detected' : 'PowerShell hooks will be used'
-        });
-        // Don't fail gate for missing bash, just note it
-    }
     gates.push({
         id: 'mcp',
         title: 'MCP Configuration',
@@ -248,7 +325,6 @@ function runDiagnostics() {
     // ═══════════════════════════════════════════════════════════════════════════
     // Calculate overall status
     // ═══════════════════════════════════════════════════════════════════════════
-    const allPass = gates.every(g => g.status === 'PASS');
     const hasBlocker = gates.some(g => g.status === 'FAIL');
     return {
         platform: isWindows ? 'Windows' : (0, os_1.platform)() === 'darwin' ? 'macOS' : 'Linux',
@@ -263,8 +339,8 @@ function runDiagnostics() {
  */
 function displayReport(report) {
     console.log('');
-    console.log(chalk_1.default.cyan.bold('🩺 ekkOS Doctor'));
-    console.log(chalk_1.default.gray('─'.repeat(60)));
+    console.log(chalk_1.default.cyan.bold('ekkOS Doctor'));
+    console.log(chalk_1.default.gray('-'.repeat(60)));
     console.log('');
     // Platform info
     console.log(chalk_1.default.gray(`Platform: ${report.platform}`));
@@ -289,13 +365,13 @@ function displayReport(report) {
                 console.log(chalk_1.default.gray(`      ${check.detail}`));
             }
         }
-        if (gate.fix && gate.status === 'FAIL') {
+        if (gate.fix && (gate.status === 'FAIL' || gate.status === 'WARN')) {
             console.log(chalk_1.default.yellow(`  → Fix: ${gate.fix}`));
         }
         console.log('');
     }
     // Summary
-    console.log(chalk_1.default.gray('─'.repeat(60)));
+    console.log(chalk_1.default.gray('-'.repeat(60)));
     const blockers = report.gates.filter(g => g.status === 'FAIL').length;
     const warnings = report.gates.filter(g => g.status === 'WARN').length;
     if (blockers > 0) {
@@ -307,7 +383,7 @@ function displayReport(report) {
         console.log(chalk_1.default.green('ekkOS can run, but some features may be limited.'));
     }
     else {
-        console.log(chalk_1.default.green.bold('✓ All systems operational'));
+        console.log(chalk_1.default.green.bold('All systems operational'));
         console.log(chalk_1.default.green('ekkOS is ready to use.'));
     }
     console.log('');
@@ -340,7 +416,6 @@ async function attemptAutoFixes(report) {
                 // Try prebuilt PTY first (safe, non-admin)
                 console.log(chalk_1.default.yellow('\nAttempting to install prebuilt PTY...'));
                 try {
-                    // Try homebridge prebuilt first
                     (0, child_process_1.execSync)('npm install -g @homebridge/node-pty-prebuilt-multiarch', {
                         stdio: 'inherit',
                         timeout: 60000
@@ -352,6 +427,19 @@ async function attemptAutoFixes(report) {
                     manual.push('If that fails: Install VS Build Tools, then: npm rebuild node-pty');
                 }
                 break;
+            case 'hooks':
+                // Try to install hooks
+                console.log(chalk_1.default.yellow('\nAttempting to install hooks...'));
+                try {
+                    // Import and call directly
+                    const { hooksInstall } = require('./hooks');
+                    await hooksInstall({ global: true, verbose: false });
+                    fixed.push('Hooks installed');
+                }
+                catch {
+                    manual.push('ekkos hooks install --global');
+                }
+                break;
             case 'mcp':
                 // Try to configure MCP (safe)
                 console.log(chalk_1.default.yellow('\nAttempting to configure MCP...'));
@@ -388,26 +476,26 @@ async function doctor(options = {}) {
     displayReport(report);
     // Fix mode - attempt safe auto-fixes
     if (options.fix && !report.canProceed) {
-        console.log(chalk_1.default.cyan.bold('\n🔧 Attempting auto-fixes...\n'));
+        console.log(chalk_1.default.cyan.bold('\nAttempting auto-fixes...\n'));
         const { fixed, manual } = await attemptAutoFixes(report);
         if (fixed.length > 0) {
             console.log(chalk_1.default.green('\n✓ Auto-fixed:'));
             for (const f of fixed) {
-                console.log(chalk_1.default.green(`  • ${f}`));
+                console.log(chalk_1.default.green(`  - ${f}`));
             }
         }
         if (manual.length > 0) {
-            console.log(chalk_1.default.yellow('\n⚠ Manual steps required:'));
+            console.log(chalk_1.default.yellow('\nManual steps required:'));
             for (const m of manual) {
                 console.log(chalk_1.default.white(`  ${m}`));
             }
         }
         // Re-run diagnostics to check if fixes worked
-        console.log(chalk_1.default.cyan('\n🔄 Re-checking...'));
+        console.log(chalk_1.default.cyan('\nRe-checking...'));
         const recheck = runDiagnostics();
         displayReport(recheck);
         if (recheck.canProceed) {
-            console.log(chalk_1.default.green.bold('✓ All issues resolved!'));
+            console.log(chalk_1.default.green.bold('All issues resolved!'));
         }
         process.exit(recheck.canProceed ? 0 : 1);
     }

package/dist/commands/hooks.d.ts

@@ -0,0 +1,109 @@
+/**
+ * ekkOS CLI: hooks subcommand
+ * Implements: ekkos hooks install | verify | status
+ *
+ * Per ekkOS Onboarding Spec v1.2 + Addendum:
+ * - Manifest-driven deployment
+ * - SHA256 checksum verification
+ * - Installed-state manifest tracking
+ */
+interface ManifestFile {
+    source: string;
+    destination: string;
+    description: string;
+    checksum: string | null;
+    overwrite?: 'always' | 'createOnly';
+    executable?: boolean;
+}
+interface Manifest {
+    $schema?: string;
+    manifestVersion: string;
+    generatedAt: string | null;
+    platforms: {
+        darwin: {
+            configDir: string;
+            globalHooksDir: string;
+            shell: string;
+        };
+        linux: {
+            configDir: string;
+            globalHooksDir: string;
+            shell: string;
+        };
+        win32: {
+            configDir: string;
+            globalHooksDir: string;
+            shell: string;
+        };
+    };
+    files: {
+        managed: ManifestFile[];
+        helpers: ManifestFile[];
+        userEditable: ManifestFile[];
+        hooks: {
+            bash: ManifestFile[];
+            powershell: ManifestFile[];
+            lib: ManifestFile[];
+        };
+    };
+    projectStubs?: {
+        description?: string;
+        bash: ManifestFile[];
+        powershell: ManifestFile[];
+    };
+    cli: {
+        minVersion: string;
+        legacySupported: boolean;
+        requiredCommands: Record<string, string[]>;
+    };
+    validation: {
+        requiredFiles: string[];
+        checksumAlgorithm: string;
+    };
+}
+interface VerifyResult {
+    status: 'PASS' | 'WARN' | 'FAIL';
+    issues: Array<{
+        severity: 'error' | 'warning';
+        file?: string;
+        message: string;
+    }>;
+}
+declare function expandPath(p: string): string;
+/**
+ * Find the ekkos-manifest.json file
+ * Search order per spec:
+ * 1. <packageRoot>/templates/ekkos-manifest.json
+ * 2. <distRoot>/../templates/ekkos-manifest.json
+ * 3. In monorepo dev: <repoRoot>/templates/ekkos-manifest.json
+ */
+export declare function findManifest(): {
+    path: string;
+    templatesDir: string;
+} | null;
+/**
+ * Load manifest from disk
+ */
+export declare function loadManifest(): {
+    manifest: Manifest;
+    path: string;
+    templatesDir: string;
+} | null;
+declare function findProjectRoot(startDir?: string): string;
+interface InstallOptions {
+    global?: boolean;
+    project?: boolean;
+    verbose?: boolean;
+}
+export declare function hooksInstall(options: InstallOptions): Promise<void>;
+interface VerifyOptions {
+    global?: boolean;
+    project?: boolean;
+    verbose?: boolean;
+}
+export declare function hooksVerify(options: VerifyOptions): Promise<VerifyResult>;
+interface StatusOptions {
+    verbose?: boolean;
+}
+export declare function hooksStatus(options: StatusOptions): Promise<void>;
+export { findProjectRoot, expandPath };