clawkit-doctor 1.0.0 → 2.0.1

package/bin/index.js

@@ -6,113 +6,430 @@ const os = require('os');
 const chalk = require('chalk');
 const ora = require('ora');
 const http = require('http');
+const net = require('net');
+const { execSync } = require('child_process');
 
-console.clear();
-console.log(chalk.cyan.bold('\n🦞 ClawKit Doctor starting...\n'));
+// --- Help & Version ---
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    console.log(`
+${chalk.cyan.bold('🦞 ClawKit Doctor v2.0')} — Diagnose & fix your OpenClaw environment
 
-const steps = [
-    checkNodeVersion,
-    checkConfigDir,
-    checkConfigFile,
-    checkPermissions,
-    checkAgentConnection,
-];
+${chalk.bold('Usage:')}
+  npx clawkit-doctor@latest           Run all diagnostics (read-only)
+  npx clawkit-doctor@latest --fix     Run diagnostics + auto-repair issues
+  npx clawkit-doctor@latest --help    Show this help message
+  npx clawkit-doctor@latest --version Show version
 
-async function run() {
-    for (const step of steps) {
-        await step();
+${chalk.bold('What it checks (11 items):')}
+  ${chalk.green('✓')} Node.js version (v18+ required)
+  ${chalk.green('✓')} Git installed and in PATH
+  ${chalk.green('✓')} Docker installed and in PATH
+  ${chalk.green('✓')} Config directory (~/.openclaw)
+  ${chalk.green('✓')} Config file validity (clawhub.json JSON syntax)
+  ${chalk.green('✓')} Directory write permissions
+  ${chalk.green('✓')} Gateway token alignment (auth vs remote vs env)
+  ${chalk.green('✓')} Stale lock files
+  ${chalk.green('✓')} Gateway port 18789
+  ${chalk.green('✓')} Agent port 3000
+  ${chalk.green('✓')} Browser CDP port 18800
+
+${chalk.bold('What --fix auto-repairs:')}
+  ${chalk.yellow('⚡')} Creates missing config directory
+  ${chalk.yellow('⚡')} Removes stale session lock files
+  ${chalk.yellow('⚡')} Aligns mismatched gateway tokens
+  ${chalk.yellow('⚡')} Fixes directory ownership (macOS/Linux)
+
+${chalk.bold('Report:')}
+  After running, a shareable report URL is generated.
+  Paste it in GitHub issues or Discord for quick support.
+
+${chalk.gray('More info: https://getclawkit.com/tools/doctor')}
+`);
+    process.exit(0);
+}
+
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+    console.log('clawkit-doctor v2.0.0');
+    process.exit(0);
+}
+
+// --- Configuration ---
+const SITE_URL = 'https://getclawkit.com';
+const CONFIG_DIR = path.join(os.homedir(), '.openclaw');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'clawhub.json');
+const SESSIONS_DIR = path.join(CONFIG_DIR, 'sessions');
+const FIX_MODE = process.argv.includes('--fix');
+
+// --- Report collector ---
+const report = {
+    ts: new Date().toISOString(),
+    os: `${os.platform()} ${os.arch()} ${os.release()}`,
+    node: process.version,
+    fix: FIX_MODE,
+    checks: [],
+};
+
+function record(id, status, message, helpUrl) {
+    report.checks.push({ id, status, message });
+    return { id, status, message, helpUrl };
+}
+
+// --- Helpers ---
+function commandExists(cmd) {
+    try {
+        const where = os.platform() === 'win32' ? 'where' : 'which';
+        execSync(`${where} ${cmd}`, { stdio: 'ignore' });
+        return true;
+    } catch {
+        return false;
     }
-    console.log(chalk.cyan.bold('\n✅ Diagnosis Complete. Screenshot this if you need help!\n'));
-    console.log(chalk.gray('For more help, visit: https://getclawkit.com/docs\n'));
 }
 
-run().catch(err => {
-    console.error(chalk.red('\n❌ Unexpected Error:'), err);
-    process.exit(1);
-});
+function getCommandVersion(cmd) {
+    try {
+        return execSync(`${cmd} --version`, { encoding: 'utf8', timeout: 5000 }).trim().split('\n')[0];
+    } catch {
+        return null;
+    }
+}
 
-// --- Checks ---
+function checkPort(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.listen(port, '127.0.0.1', () => {
+            server.close(() => resolve(false)); // port is free
+        });
+        server.on('error', () => resolve(true)); // port is in use
+    });
+}
+
+function readConfig() {
+    try {
+        const raw = fs.readFileSync(CONFIG_FILE, 'utf8');
+        return JSON.parse(raw);
+    } catch {
+        return null;
+    }
+}
+
+function getNestedValue(obj, keyPath) {
+    return keyPath.split('.').reduce((o, k) => (o && o[k] !== undefined ? o[k] : undefined), obj);
+}
+
+// ============================================================
+// Checks
+// ============================================================
 
 async function checkNodeVersion() {
     const spinner = ora('Checking Node.js version...').start();
-    const version = process.version;
-    const major = parseInt(version.substring(1).split('.')[0], 10);
+    const major = parseInt(process.version.substring(1).split('.')[0], 10);
 
     if (major >= 18) {
-        spinner.succeed(chalk.green(`Node.js found: ${version}`));
+        spinner.succeed(chalk.green(`Node.js ${process.version}`));
+        return record('node', 'pass', `Node.js ${process.version}`);
     } else {
-        spinner.fail(chalk.red(`Node.js ${version} is too old. Please install Node.js v18+.`));
+        spinner.fail(chalk.red(`Node.js ${process.version} is too old. Install Node.js v18+.`));
+        return record('node', 'fail', `Node.js ${process.version} — requires v18+`);
     }
 }
 
-async function checkConfigDir() {
-    const spinner = ora('Checking Config Directory...').start();
-    const homeDir = os.homedir();
-    const configPath = path.join(homeDir, '.openclaw');
+async function checkGit() {
+    const spinner = ora('Checking Git...').start();
+    if (commandExists('git')) {
+        const ver = getCommandVersion('git') || 'found';
+        spinner.succeed(chalk.green(`Git: ${ver}`));
+        return record('git', 'pass', ver);
+    } else {
+        const helpUrl = `${SITE_URL}/docs/troubleshooting/spawn-git-enoent`;
+        spinner.fail(chalk.red(`Git not found. npm packages that use Git will fail.`));
+        console.log(chalk.gray(`  Fix: ${helpUrl}`));
+        if (FIX_MODE && os.platform() === 'win32') {
+            console.log(chalk.yellow('  Auto-fix: running winget install Git.Git ...'));
+            try { execSync('winget install Git.Git', { stdio: 'inherit' }); } catch { /* ignore */ }
+        }
+        return record('git', 'fail', 'Git not installed or not in PATH', helpUrl);
+    }
+}
+
+async function checkDocker() {
+    const spinner = ora('Checking Docker...').start();
+    if (commandExists('docker')) {
+        const ver = getCommandVersion('docker') || 'found';
+        spinner.succeed(chalk.green(`Docker: ${ver}`));
+        return record('docker', 'pass', ver);
+    } else {
+        const helpUrl = `${SITE_URL}/docs/troubleshooting/spawn-docker-enoent`;
+        spinner.warn(chalk.yellow('Docker not found. Agent sandbox mode will fail.'));
+        console.log(chalk.gray(`  Fix: Install Docker or disable sandbox: openclaw config set agents.defaults.sandbox.mode off`));
+        console.log(chalk.gray(`  Guide: ${helpUrl}`));
+        return record('docker', 'warn', 'Docker not installed (sandbox mode will fail)', helpUrl);
+    }
+}
 
+async function checkConfigDir() {
+    const spinner = ora('Checking config directory...').start();
     try {
-        await fs.promises.access(configPath);
-        spinner.succeed(chalk.green(`Config directory exists at: ${configPath}`));
-    } catch (error) {
-        spinner.fail(chalk.red(`Config directory missing at ${configPath}. Run 'clawhub init' first.`));
+        await fs.promises.access(CONFIG_DIR);
+        spinner.succeed(chalk.green(`Config directory: ${CONFIG_DIR}`));
+        return record('config_dir', 'pass', CONFIG_DIR);
+    } catch {
+        spinner.fail(chalk.red(`Config directory missing: ${CONFIG_DIR}`));
+        console.log(chalk.gray(`  Fix: Run 'openclaw init' or use ${SITE_URL}/tools/config`));
+        if (FIX_MODE) {
+            console.log(chalk.yellow('  Auto-fix: creating directory...'));
+            fs.mkdirSync(CONFIG_DIR, { recursive: true });
+            console.log(chalk.green('  Created.'));
+        }
+        return record('config_dir', 'fail', `Missing: ${CONFIG_DIR}`);
     }
 }
 
 async function checkConfigFile() {
-    const spinner = ora('Checking Config File...').start();
-    const homeDir = os.homedir();
-    const configFilePath = path.join(homeDir, '.openclaw', 'clawhub.json');
+    const spinner = ora('Checking config file (clawhub.json)...').start();
+    try {
+        await fs.promises.access(CONFIG_FILE);
+    } catch {
+        const helpUrl = `${SITE_URL}/tools/config`;
+        spinner.fail(chalk.yellow('Config file missing (clawhub.json).'));
+        console.log(chalk.gray(`  Generate one: ${helpUrl}`));
+        return record('config_file', 'fail', 'clawhub.json not found', helpUrl);
+    }
 
+    // Validate JSON syntax
     try {
-        await fs.promises.access(configFilePath);
-        spinner.succeed(chalk.green('Config file found (clawhub.json).'));
-    } catch (error) {
-        spinner.fail(chalk.yellow('Config file missing (clawhub.json). Use Config Generator to create one.'));
+        const raw = fs.readFileSync(CONFIG_FILE, 'utf8');
+        JSON.parse(raw);
+        spinner.succeed(chalk.green('Config file found and valid JSON.'));
+        return record('config_file', 'pass', 'clawhub.json valid');
+    } catch (e) {
+        const helpUrl = `${SITE_URL}/docs/troubleshooting/json-parse-errors`;
+        spinner.fail(chalk.red(`Config file has invalid JSON: ${e.message}`));
+        console.log(chalk.gray(`  Fix: ${helpUrl}`));
+        return record('config_file', 'fail', `Invalid JSON: ${e.message}`, helpUrl);
     }
 }
 
 async function checkPermissions() {
-    const spinner = ora('Checking Directory Permissions...').start();
-    const homeDir = os.homedir();
-    const configPath = path.join(homeDir, '.openclaw');
-
+    const spinner = ora('Checking directory permissions...').start();
     try {
-        // Only check if dir exists
-        if (fs.existsSync(configPath)) {
-            await fs.promises.access(configPath, fs.constants.W_OK);
-            spinner.succeed(chalk.green('Write permission OK for ~/.openclaw'));
-        } else {
-            spinner.info(chalk.gray('Skipping permission check (directory missing).'));
+        if (!fs.existsSync(CONFIG_DIR)) {
+            spinner.info(chalk.gray('Skipped (directory missing).'));
+            return record('permissions', 'skip', 'Directory missing');
         }
+        await fs.promises.access(CONFIG_DIR, fs.constants.W_OK);
+        spinner.succeed(chalk.green('Write permission OK for ~/.openclaw'));
+        return record('permissions', 'pass', 'Write permission OK');
+    } catch {
+        spinner.fail(chalk.red('No write permission for ~/.openclaw'));
+        console.log(chalk.gray('  Fix: sudo chown -R $(whoami) ~/.openclaw'));
+        if (FIX_MODE && os.platform() !== 'win32') {
+            console.log(chalk.yellow('  Auto-fix: fixing ownership...'));
+            try { execSync(`chown -R $(whoami) "${CONFIG_DIR}"`, { stdio: 'inherit' }); } catch { /* ignore */ }
+        }
+        return record('permissions', 'fail', 'No write permission');
+    }
+}
+
+async function checkGatewayTokens() {
+    const spinner = ora('Checking gateway token alignment...').start();
+    const config = readConfig();
+    if (!config) {
+        spinner.info(chalk.gray('Skipped (no valid config).'));
+        return record('tokens', 'skip', 'No config to check');
+    }
+
+    const authToken = getNestedValue(config, 'gateway.auth.token');
+    const remoteToken = getNestedValue(config, 'gateway.remote.token');
+    const envToken = process.env.OPENCLAW_GATEWAY_TOKEN;
+
+    if (!authToken && !remoteToken) {
+        spinner.info(chalk.gray('No gateway tokens configured (will auto-generate).'));
+        return record('tokens', 'info', 'No tokens configured');
+    }
+
+    // Check env override
+    if (envToken && authToken && envToken !== authToken) {
+        const helpUrl = `${SITE_URL}/docs/troubleshooting/gateway-token-mismatch`;
+        spinner.fail(chalk.red('OPENCLAW_GATEWAY_TOKEN env var overrides config! Tokens will mismatch.'));
+        console.log(chalk.gray(`  Env: ${envToken.substring(0, 8)}...  Config: ${authToken.substring(0, 8)}...`));
+        console.log(chalk.gray(`  Fix: ${helpUrl}`));
+        return record('tokens', 'fail', 'Env var overrides gateway.auth.token', helpUrl);
+    }
 
-    } catch (error) {
-        spinner.fail(chalk.red('No write permission for ~/.openclaw. Fix ownership with: sudo chown -R $(whoami) ~/.openclaw'));
+    if (authToken && remoteToken && authToken !== remoteToken) {
+        const helpUrl = `${SITE_URL}/docs/troubleshooting/gateway-token-mismatch`;
+        spinner.fail(chalk.red('gateway.auth.token ≠ gateway.remote.token — clients cannot connect.'));
+        console.log(chalk.gray(`  Auth:   ${authToken.substring(0, 8)}...`));
+        console.log(chalk.gray(`  Remote: ${remoteToken.substring(0, 8)}...`));
+        console.log(chalk.gray(`  Fix: ${helpUrl}`));
+        if (FIX_MODE) {
+            console.log(chalk.yellow('  Auto-fix: aligning remote token to match auth token...'));
+            config.gateway.remote.token = authToken;
+            fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), 'utf8');
+            console.log(chalk.green('  Fixed. Restart gateway: openclaw gateway restart'));
+        }
+        return record('tokens', 'fail', 'auth.token ≠ remote.token', helpUrl);
     }
+
+    spinner.succeed(chalk.green('Gateway tokens aligned.'));
+    return record('tokens', 'pass', 'Tokens aligned');
 }
 
-async function checkAgentConnection() {
-    const spinner = ora('Checking Local Agent (Port 3000)...').start();
+async function checkStaleLocks() {
+    const spinner = ora('Checking for stale lock files...').start();
+    if (!fs.existsSync(SESSIONS_DIR)) {
+        spinner.info(chalk.gray('No sessions directory.'));
+        return record('locks', 'skip', 'No sessions directory');
+    }
 
-    return new Promise((resolve) => {
-        const req = http.get('http://localhost:3000', (res) => {
-            spinner.succeed(chalk.green('Local Agent Port (3000) is OPEN.'));
-            resolve();
-        });
+    try {
+        const files = fs.readdirSync(SESSIONS_DIR).filter(f => f.endsWith('.lock'));
+        if (files.length === 0) {
+            spinner.succeed(chalk.green('No stale lock files.'));
+            return record('locks', 'pass', 'No lock files');
+        }
 
-        req.on('error', (e) => {
-            if (e.code === 'ECONNREFUSED') {
-                spinner.info(chalk.gray('Port 3000 is free (Agent not running).'));
-            } else {
-                spinner.info(chalk.gray(`Network check skipped: ${e.message}`));
+        const helpUrl = `${SITE_URL}/docs/troubleshooting/gateway-lock-timeout`;
+        spinner.warn(chalk.yellow(`Found ${files.length} lock file(s): ${files.join(', ')}`));
+        console.log(chalk.gray(`  This may cause "gateway already running" errors.`));
+        console.log(chalk.gray(`  Fix: ${helpUrl}`));
+
+        if (FIX_MODE) {
+            console.log(chalk.yellow('  Auto-fix: removing stale locks...'));
+            for (const f of files) {
+                fs.unlinkSync(path.join(SESSIONS_DIR, f));
             }
-            resolve();
-        });
+            console.log(chalk.green(`  Removed ${files.length} lock file(s).`));
+        }
+        return record('locks', 'warn', `${files.length} lock file(s) found`, helpUrl);
+    } catch (e) {
+        spinner.info(chalk.gray(`Could not check locks: ${e.message}`));
+        return record('locks', 'skip', e.message);
+    }
+}
 
-        req.setTimeout(2000, () => {
-            message = 'Connection timed out';
-            req.destroy();
-            spinner.info(chalk.gray('Network check timed out.'));
-            resolve();
-        });
+async function checkGatewayPort() {
+    const spinner = ora('Checking Gateway port (18789)...').start();
+    const inUse = await checkPort(18789);
+    if (inUse) {
+        spinner.succeed(chalk.green('Gateway port 18789 is in use (gateway likely running).'));
+        return record('gateway_port', 'pass', 'Port 18789 in use (gateway running)');
+    } else {
+        spinner.info(chalk.gray('Gateway port 18789 is free (gateway not running).'));
+        return record('gateway_port', 'info', 'Port 18789 free (gateway not running)');
+    }
+}
+
+async function checkAgentPort() {
+    const spinner = ora('Checking Agent port (3000)...').start();
+    const inUse = await checkPort(3000);
+    if (inUse) {
+        spinner.succeed(chalk.green('Agent port 3000 is in use (agent likely running).'));
+        return record('agent_port', 'pass', 'Port 3000 in use');
+    } else {
+        spinner.info(chalk.gray('Agent port 3000 is free (agent not running).'));
+        return record('agent_port', 'info', 'Port 3000 free');
+    }
+}
+
+async function checkCDPPort() {
+    const spinner = ora('Checking Browser CDP port (18800)...').start();
+    const inUse = await checkPort(18800);
+    if (inUse) {
+        spinner.info(chalk.gray('CDP port 18800 in use (browser control active or stray process).'));
+        return record('cdp_port', 'info', 'Port 18800 in use');
+    } else {
+        spinner.succeed(chalk.green('CDP port 18800 is free.'));
+        return record('cdp_port', 'pass', 'Port 18800 free');
+    }
+}
+
+// ============================================================
+// Report Generator
+// ============================================================
+
+function generateReportUrl() {
+    const compressed = JSON.stringify({
+        t: report.ts,
+        o: report.os,
+        n: report.node,
+        f: report.fix,
+        c: report.checks.map(c => [c.id, c.status[0], c.message.substring(0, 80)]),
     });
+    const encoded = Buffer.from(compressed).toString('base64url');
+    return `${SITE_URL}/tools/doctor?r=${encoded}`;
 }
+
+// ============================================================
+// Main
+// ============================================================
+
+const steps = [
+    checkNodeVersion,
+    checkGit,
+    checkDocker,
+    checkConfigDir,
+    checkConfigFile,
+    checkPermissions,
+    checkGatewayTokens,
+    checkStaleLocks,
+    checkGatewayPort,
+    checkAgentPort,
+    checkCDPPort,
+];
+
+async function run() {
+    console.clear();
+    console.log(chalk.cyan.bold('\n🦞 ClawKit Doctor v2.0\n'));
+
+    if (FIX_MODE) {
+        console.log(chalk.yellow.bold('⚡ Fix mode enabled — will auto-repair issues where possible.\n'));
+    }
+
+    for (const step of steps) {
+        await step();
+    }
+
+    // Summary
+    const fails = report.checks.filter(c => c.status === 'fail');
+    const warns = report.checks.filter(c => c.status === 'warn');
+    const passes = report.checks.filter(c => c.status === 'pass');
+
+    console.log('');
+    console.log(chalk.bold('─'.repeat(50)));
+
+    if (fails.length === 0 && warns.length === 0) {
+        console.log(chalk.green.bold('\n✅ All checks passed! Your environment looks healthy.\n'));
+    } else {
+        console.log(chalk.yellow.bold(`\n📋 Summary: ${passes.length} passed, ${warns.length} warnings, ${fails.length} failed\n`));
+
+        if (fails.length > 0) {
+            console.log(chalk.red.bold('  Issues to fix:'));
+            for (const f of fails) {
+                console.log(chalk.red(`    ✗ ${f.message}`));
+            }
+        }
+        if (warns.length > 0) {
+            console.log(chalk.yellow.bold('  Warnings:'));
+            for (const w of warns) {
+                console.log(chalk.yellow(`    ⚠ ${w.message}`));
+            }
+        }
+
+        if (!FIX_MODE && fails.length > 0) {
+            console.log(chalk.cyan(`\n  💡 Run with --fix to auto-repair: npx clawkit-doctor@latest --fix\n`));
+        }
+    }
+
+    // Report URL
+    const reportUrl = generateReportUrl();
+    console.log(chalk.gray('─'.repeat(50)));
+    console.log(chalk.cyan.bold('\n📋 Share this report:'));
+    console.log(chalk.white(`   ${reportUrl}\n`));
+    console.log(chalk.gray(`For full troubleshooting guides: ${SITE_URL}/docs/troubleshooting\n`));
+}
+
+run().catch(err => {
+    console.error(chalk.red('\n❌ Unexpected Error:'), err.message);
+    process.exit(1);
+});

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "clawkit-doctor",
-    "version": "1.0.0",
-    "description": "Diagnostic tool for OpenClaw environment",
+    "version": "2.0.1",
+    "description": "Diagnostic and auto-fix tool for OpenClaw environment",
     "main": "bin/index.js",
     "bin": {
-        "clawkit-doctor": "./bin/index.js"
+        "clawkit-doctor": "bin/index.js"
     },
     "scripts": {
         "test": "echo \"Error: no test specified\" && exit 1"