twinclaw 1.0.0

package/dist/core/doctor.js

@@ -0,0 +1,365 @@
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getConfigPath } from '../config/json-config.js';
+import { getConfigValue } from '../config/config-loader.js';
+import { getSecretVaultService } from '../services/secret-vault.js';
+import { getIdentityDir, getWorkspaceSubdir } from '../config/workspace.js';
+import { IDENTITY_FILE_CHECKS } from '../config/identity-bootstrap.js';
+// ── Built-in check definitions ───────────────────────────────────────────────
+export const BINARY_CHECKS = [
+    {
+        kind: 'binary',
+        name: 'node',
+        description: 'Node.js runtime (v22+ required)',
+        severity: 'critical',
+        remediation: 'Install Node.js v22+ from https://nodejs.org',
+    },
+    {
+        kind: 'binary',
+        name: 'git',
+        description: 'Git version control',
+        severity: 'warning',
+        remediation: 'Install Git from https://git-scm.com',
+    },
+];
+export const ENV_VAR_CHECKS = [
+    {
+        kind: 'env-var',
+        name: 'GROQ_API_KEY',
+        description: 'Groq API key for Speech-to-Text and TTS',
+        severity: 'critical',
+        remediation: 'Get a free API key at https://console.groq.com and set GROQ_API_KEY via `twinbot onboard`.',
+    },
+    {
+        kind: 'env-var',
+        name: 'TELEGRAM_BOT_TOKEN',
+        description: 'Telegram Bot token for messaging integration',
+        severity: 'warning',
+        remediation: 'Create a bot via @BotFather on Telegram and set TELEGRAM_BOT_TOKEN via `twinbot onboard`.',
+    },
+    {
+        kind: 'env-var',
+        name: 'TELEGRAM_USER_ID',
+        description: 'Optional Telegram user ID bootstrap allowlist seed',
+        severity: 'info',
+        remediation: 'Optional: set TELEGRAM_USER_ID via `twinbot onboard` to pre-authorize your own Telegram account.',
+    },
+    {
+        kind: 'env-var',
+        name: 'API_SECRET',
+        description: 'API secret for webhook callback authentication',
+        severity: 'critical',
+        remediation: 'Generate a strong secret and set API_SECRET via `twinbot onboard`. Example: openssl rand -hex 32',
+    },
+    {
+        kind: 'env-var',
+        name: 'OPENROUTER_API_KEY',
+        description: 'Primary AI model provider routing',
+        severity: 'warning',
+        remediation: 'Get an OpenRouter key at https://openrouter.ai/keys and set OPENROUTER_API_KEY via `twinbot onboard`.',
+    },
+    {
+        kind: 'env-var',
+        name: 'ELEVENLABS_API_KEY',
+        description: 'Text-to-Speech voice synthesis',
+        severity: 'warning',
+        remediation: 'Get an ElevenLabs key at https://elevenlabs.io and set ELEVENLABS_API_KEY via `twinbot onboard`.',
+    },
+    {
+        kind: 'env-var',
+        name: 'GEMINI_API_KEY',
+        description: 'Fallback AI model provider',
+        severity: 'info',
+        remediation: 'Get a Gemini API key at https://aistudio.google.com and set GEMINI_API_KEY via `twinbot onboard`.',
+    },
+];
+export const FILESYSTEM_CHECKS = [
+    {
+        kind: 'filesystem',
+        name: 'memory-dir',
+        description: 'Memory directory for logs and state persistence',
+        severity: 'warning',
+        remediation: 'Create the ./memory directory: mkdir -p memory',
+    },
+    {
+        kind: 'filesystem',
+        name: 'env-file',
+        description: '.env configuration file',
+        severity: 'info',
+        remediation: 'Copy .env.example to .env and fill in required values: cp .env.example .env',
+    },
+    ...IDENTITY_FILE_CHECKS,
+];
+export const CONFIG_CHECKS = [
+    {
+        kind: 'config-schema',
+        name: 'twinbot.json',
+        description: 'TwinBot local JSON configuration schema',
+        severity: 'critical',
+        remediation: 'Run `node src/index.ts onboard` to initialize or repair your configuration.',
+    }
+];
+export const CHANNEL_CHECKS = [
+    {
+        kind: 'channel-auth',
+        name: 'whatsapp',
+        description: 'WhatsApp QR session linking state',
+        severity: 'warning',
+        remediation: 'Run `node src/index.ts channels login whatsapp` to link your device.',
+    }
+];
+/** All built-in checks in default run order. */
+export const DEFAULT_CHECKS = [
+    ...BINARY_CHECKS,
+    ...ENV_VAR_CHECKS,
+    ...FILESYSTEM_CHECKS,
+    ...CONFIG_CHECKS,
+    ...CHANNEL_CHECKS,
+];
+// ── Individual check executors ───────────────────────────────────────────────
+/** @internal exported for testing */
+export function checkBinary(check) {
+    try {
+        const cmd = `where ${check.name}`;
+        execSync(cmd, { stdio: 'pipe', timeout: 5_000 });
+        if (check.name === 'node') {
+            const versionRaw = execSync('node --version', { stdio: 'pipe' })
+                .toString()
+                .trim();
+            const match = versionRaw.match(/^v(\d+)\./);
+            const major = match ? parseInt(match[1], 10) : 0;
+            if (major < 22) {
+                return {
+                    check,
+                    passed: false,
+                    actual: versionRaw,
+                    message: `Node.js ${versionRaw} found but v22+ is required.`,
+                };
+            }
+            return {
+                check,
+                passed: true,
+                actual: versionRaw,
+                message: `Node.js ${versionRaw} found.`,
+            };
+        }
+        return {
+            check,
+            passed: true,
+            message: `'${check.name}' binary found.`,
+        };
+    }
+    catch {
+        return {
+            check,
+            passed: false,
+            message: `'${check.name}' binary not found in PATH.`,
+        };
+    }
+}
+/** @internal exported for testing */
+export function checkEnvVar(check) {
+    const secret = getSecretVaultService().readSecret(check.name);
+    const value = secret ?? getConfigValue(check.name);
+    if (!value || value.trim().length === 0) {
+        return {
+            check,
+            passed: false,
+            message: `Environment variable '${check.name}' is not set.`,
+        };
+    }
+    // Mask the value for safe display
+    const masked = value.length > 8
+        ? `${value.slice(0, 4)}${'*'.repeat(Math.min(8, value.length - 4))}`
+        : '****';
+    return {
+        check,
+        passed: true,
+        actual: masked,
+        message: `'${check.name}' is set (${masked}).`,
+    };
+}
+/** @internal exported for testing */
+export function checkFilesystem(check) {
+    const targetMap = {
+        'memory-dir': path.resolve('memory'),
+        'env-file': path.resolve('.env'),
+        'identity-soul': path.join(getIdentityDir(), 'soul.md'),
+        'identity-identity': path.join(getIdentityDir(), 'identity.md'),
+        'identity-memory': path.join(getWorkspaceSubdir('memory'), 'memory.md'),
+    };
+    const target = targetMap[check.name];
+    if (!target) {
+        return {
+            check,
+            passed: false,
+            message: `Unknown filesystem check target: '${check.name}'.`,
+        };
+    }
+    if (!fs.existsSync(target)) {
+        return {
+            check,
+            passed: false,
+            actual: target,
+            message: `'${target}' does not exist.`,
+        };
+    }
+    return {
+        check,
+        passed: true,
+        actual: target,
+        message: `'${target}' exists.`,
+    };
+}
+// ── Individual check executors ───────────────────────────────────────────────
+/** @internal exported for testing */
+export function checkConfigSchema(check) {
+    const configPath = getConfigPath();
+    if (!fs.existsSync(configPath)) {
+        return {
+            check,
+            passed: false,
+            message: `Config file not found at ${configPath}.`,
+        };
+    }
+    try {
+        const raw = fs.readFileSync(configPath, 'utf8');
+        JSON.parse(raw);
+        return {
+            check,
+            passed: true,
+            message: 'twinbot.json config is valid JSON and accessible.',
+        };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+            check,
+            passed: false,
+            message: `Config file is invalid JSON: ${msg}`,
+        };
+    }
+}
+/** @internal exported for testing */
+export function checkChannelAuth(check) {
+    if (check.name === 'whatsapp') {
+        const authDir = path.resolve('memory', 'whatsapp_auth');
+        if (!fs.existsSync(authDir)) {
+            return {
+                check,
+                passed: false,
+                message: 'WhatsApp auth session directory does not exist.',
+            };
+        }
+        // simple heuristic: if it has files, it might be linked
+        return {
+            check,
+            passed: true,
+            message: 'WhatsApp auth session directory exists.',
+        };
+    }
+    return {
+        check,
+        passed: false,
+        message: `Unknown channel: ${check.name}`,
+    };
+}
+// ── Report utilities ─────────────────────────────────────────────────────────
+function deriveStatus(results) {
+    const hasCriticalFailure = results.some((r) => !r.passed && r.check.severity === 'critical');
+    if (hasCriticalFailure)
+        return 'critical';
+    if (results.some((r) => !r.passed))
+        return 'degraded';
+    return 'ok';
+}
+// ── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Execute all doctor checks and return a structured report.
+ * Accepts an optional override list for targeted or test-only runs.
+ */
+export function runDoctorChecks(checks) {
+    const allChecks = checks ?? DEFAULT_CHECKS;
+    const results = allChecks.map((check) => {
+        switch (check.kind) {
+            case 'binary':
+                return checkBinary(check);
+            case 'env-var':
+                return checkEnvVar(check);
+            case 'filesystem':
+                return checkFilesystem(check);
+            case 'config-schema':
+                return checkConfigSchema(check);
+            case 'channel-auth':
+                return checkChannelAuth(check);
+            case 'service-endpoint':
+                // Service endpoint checks are intentionally deferred for interactive local use
+                return {
+                    check,
+                    passed: true,
+                    message: 'Service endpoint checks are skipped in local mode.',
+                };
+            default: {
+                const exhaustive = check.kind;
+                return {
+                    check,
+                    passed: false,
+                    message: `Unknown check kind: '${exhaustive}'.`,
+                };
+            }
+        }
+    });
+    const status = deriveStatus(results);
+    const passed = results.filter((r) => r.passed).length;
+    return {
+        status,
+        results,
+        checkedAt: new Date().toISOString(),
+        passed,
+        failed: results.length - passed,
+    };
+}
+const SEVERITY_ICON = {
+    critical: '✗',
+    warning: '⚠',
+    info: 'ℹ',
+};
+const STATUS_LABEL = {
+    ok: '✓ OK',
+    degraded: '⚠ DEGRADED',
+    critical: '✗ CRITICAL',
+};
+/**
+ * Format a DoctorReport for display.
+ * Set `asJson=true` to emit machine-readable JSON.
+ */
+export function formatDoctorReport(report, asJson = false) {
+    if (asJson) {
+        return JSON.stringify(report, null, 2);
+    }
+    const lines = [];
+    lines.push(`TwinBot Doctor — ${STATUS_LABEL[report.status]}`);
+    lines.push(`Checked at: ${report.checkedAt}`);
+    lines.push(`Passed: ${report.passed}  Failed: ${report.failed}`);
+    lines.push('');
+    for (const result of report.results) {
+        const icon = result.passed ? '✓' : SEVERITY_ICON[result.check.severity];
+        const kindLabel = `[${result.check.kind}]`;
+        lines.push(`  ${icon} ${kindLabel} ${result.check.name}: ${result.message}`);
+        if (!result.passed) {
+            lines.push(`      → Remediation: ${result.check.remediation}`);
+        }
+    }
+    lines.push('');
+    if (report.status === 'ok') {
+        lines.push('All checks passed. TwinBot is ready to run.');
+    }
+    else if (report.status === 'degraded') {
+        lines.push('Some checks failed. TwinBot may run with limited functionality.');
+    }
+    else {
+        lines.push('Critical checks failed. Fix the issues above before running TwinBot.');
+    }
+    return lines.join('\n');
+}

package/dist/core/gateway-cli.js

@@ -0,0 +1,323 @@
+import { execSync } from 'node:child_process';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getConfigPath, readConfig } from '../config/config-loader.js';
+const GATEWAY_COMMANDS = new Set([
+    'install',
+    'start',
+    'stop',
+    'restart',
+    'status',
+    'uninstall',
+    'tailscale',
+]);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PROJECT_ROOT = path.resolve(__dirname, '../../');
+const ENTRY_SCRIPT = path.join(PROJECT_ROOT, 'dist', 'index.js');
+const BASE_SERVICE_ID = 'ai.twinbot.gateway';
+const BASE_SERVICE_LABEL = 'TwinBot Gateway';
+const DEFAULT_API_PORT = 18789;
+function ensureCommand(input) {
+    if (!input || !GATEWAY_COMMANDS.has(input)) {
+        throw new Error(`Unknown gateway command '${input ?? ''}'. Available commands: ${[...GATEWAY_COMMANDS].join(', ')}`);
+    }
+    return input;
+}
+function requireValue(argv, index, flag) {
+    const next = argv[index + 1];
+    if (!next || next.startsWith('--')) {
+        throw new Error(`Missing value for ${flag}.`);
+    }
+    return next;
+}
+function parsePort(raw) {
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        throw new Error(`Invalid port '${raw}'. Expected integer in range 1-65535.`);
+    }
+    return parsed;
+}
+export function sanitizeServiceToken(raw) {
+    const token = raw
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (!token) {
+        throw new Error(`Service token '${raw}' is invalid.`);
+    }
+    return token;
+}
+export function parseGatewayArgs(argv) {
+    if (argv[0] !== 'gateway') {
+        throw new Error('Gateway parser expects argv beginning with "gateway".');
+    }
+    const parsed = {
+        command: ensureCommand(argv[1]),
+        asJson: false,
+        deep: false,
+    };
+    for (let i = 2; i < argv.length; i += 1) {
+        const token = argv[i];
+        switch (token) {
+            case '--instance':
+            case '-i':
+                parsed.instance = sanitizeServiceToken(requireValue(argv, i, token));
+                i += 1;
+                break;
+            case '--name':
+                parsed.serviceName = sanitizeServiceToken(requireValue(argv, i, token));
+                i += 1;
+                break;
+            case '--config':
+                parsed.configPathOverride = requireValue(argv, i, token);
+                i += 1;
+                break;
+            case '--port':
+                parsed.apiPortOverride = parsePort(requireValue(argv, i, token));
+                i += 1;
+                break;
+            case '--json':
+                parsed.asJson = true;
+                break;
+            case '--deep':
+                parsed.deep = true;
+                break;
+            default:
+                throw new Error(`Unknown gateway option '${token}'.`);
+        }
+    }
+    if (parsed.instance && parsed.serviceName) {
+        throw new Error('Use either --instance or --name, not both.');
+    }
+    return parsed;
+}
+export function buildTailscaleInstructions(context) {
+    return `
+TwinBot Remote Access Setup
+──────────────────────────────────────────────────
+Gateway service : ${context.serviceId}
+Config path     : ${context.configPath}
+API port        : ${context.apiPort}
+WebSocket path  : ws://127.0.0.1:${context.apiPort}/ws
+
+Recommended (Tailscale Funnel):
+  1. twinbot gateway start${context.instance ? ` --instance ${context.instance}` : ''}
+  2. tailscale funnel ${context.apiPort}
+  3. Use the printed HTTPS URL and authenticate using your API_SECRET token.
+
+Alternative (SSH tunnel):
+  ssh -N -L ${context.apiPort}:127.0.0.1:${context.apiPort} <user>@<host>
+  Then connect locally to ws://127.0.0.1:${context.apiPort}/ws
+
+Never expose 0.0.0.0:${context.apiPort} directly to the public internet.
+`;
+}
+function ensureWindowsPlatform(platform) {
+    if (platform !== 'win32') {
+        throw new Error(`TwinBot gateway commands support Windows only. Current platform '${platform}' is out of scope.`);
+    }
+}
+export async function resolveGatewayContext(parsed, platform = os.platform()) {
+    ensureWindowsPlatform(platform);
+    const configPath = getConfigPath(parsed.configPathOverride);
+    let configPort = DEFAULT_API_PORT;
+    try {
+        const config = await readConfig(parsed.configPathOverride);
+        if (Number.isInteger(config.runtime.apiPort)) {
+            configPort = config.runtime.apiPort;
+        }
+    }
+    catch {
+        // If config is malformed, continue with defaults and explicit overrides.
+    }
+    const suffix = parsed.serviceName ?? parsed.instance ?? '';
+    const serviceId = suffix ? `${BASE_SERVICE_ID}.${sanitizeServiceToken(suffix)}` : BASE_SERVICE_ID;
+    const serviceLabel = suffix
+        ? `${BASE_SERVICE_LABEL} (${sanitizeServiceToken(suffix)})`
+        : BASE_SERVICE_LABEL;
+    const apiPort = parsed.apiPortOverride ?? configPort;
+    return {
+        ...parsed,
+        platform,
+        projectRoot: PROJECT_ROOT,
+        nodePath: process.execPath,
+        entryScript: ENTRY_SCRIPT,
+        serviceId,
+        serviceLabel,
+        configPath,
+        apiPort,
+    };
+}
+function runCommand(command, ignoreFailure = false) {
+    try {
+        return execSync(command, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+    }
+    catch (error) {
+        if (ignoreFailure) {
+            const message = error instanceof Error ? error.message : String(error);
+            return message.trim();
+        }
+        throw error;
+    }
+}
+async function installWindowsService(context) {
+    const nodeWindows = await import('node-windows');
+    const svc = new nodeWindows.Service({
+        name: context.serviceLabel,
+        description: 'TwinBot background gateway service',
+        script: context.entryScript,
+        env: [
+            { name: 'NODE_ENV', value: 'production' },
+            { name: 'API_PORT', value: String(context.apiPort) },
+            { name: 'TWINBOT_CONFIG_PATH', value: context.configPath },
+        ],
+    });
+    await new Promise((resolve, reject) => {
+        svc.on('install', () => resolve());
+        svc.on('alreadyinstalled', () => resolve());
+        svc.on('error', (error) => reject(error));
+        svc.install();
+    });
+}
+async function installService(context) {
+    await installWindowsService(context);
+}
+async function startService(context) {
+    const nodeWindows = await import('node-windows');
+    const svc = new nodeWindows.Service({
+        name: context.serviceLabel,
+        description: 'TwinBot background gateway service',
+        script: context.entryScript,
+    });
+    await new Promise((resolve, reject) => {
+        svc.on('start', () => resolve());
+        svc.on('error', (error) => reject(error));
+        svc.start();
+    });
+}
+async function stopService(context) {
+    const nodeWindows = await import('node-windows');
+    const svc = new nodeWindows.Service({
+        name: context.serviceLabel,
+        description: 'TwinBot background gateway service',
+        script: context.entryScript,
+    });
+    await new Promise((resolve, reject) => {
+        svc.on('stop', () => resolve());
+        svc.on('error', (error) => reject(error));
+        svc.stop();
+    });
+}
+async function restartService(context) {
+    await stopService(context);
+    await startService(context);
+}
+async function uninstallService(context) {
+    const nodeWindows = await import('node-windows');
+    const svc = new nodeWindows.Service({
+        name: context.serviceLabel,
+        description: 'TwinBot background gateway service',
+        script: context.entryScript,
+    });
+    await new Promise((resolve, reject) => {
+        svc.on('uninstall', () => resolve());
+        svc.on('alreadyuninstalled', () => resolve());
+        svc.on('error', (error) => reject(error));
+        svc.uninstall();
+    });
+}
+function queryStatus(context) {
+    const command = `sc query "${context.serviceLabel}"`;
+    const details = runCommand(command, true);
+    return { running: /\bRUNNING\b/.test(details), details, command };
+}
+function printStatus(context, status) {
+    const payload = {
+        service: context.serviceId,
+        label: context.serviceLabel,
+        running: status.running,
+        platform: context.platform,
+        apiPort: context.apiPort,
+        configPath: context.configPath,
+        command: status.command,
+        details: status.details,
+    };
+    if (context.asJson) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    console.log(`[TwinBot] Gateway '${context.serviceId}' is ${status.running ? 'ACTIVE' : 'INACTIVE'} on ${context.platform}.`);
+    if (context.deep) {
+        console.log(`Config Path : ${context.configPath}`);
+        console.log(`API Port    : ${context.apiPort}`);
+        console.log('Mode        : windows service');
+        if (status.details.length > 0) {
+            console.log('\nStatus details:');
+            console.log(status.details);
+        }
+    }
+}
+function printGatewayUsage() {
+    console.log(`Gateway command usage:
+  gateway install [--instance <id>] [--name <suffix>] [--config <path>] [--port <num>]
+  gateway start [--instance <id>] [--name <suffix>]
+  gateway stop [--instance <id>] [--name <suffix>]
+  gateway restart [--instance <id>] [--name <suffix>]
+  gateway status [--instance <id>] [--name <suffix>] [--json | --deep]
+  gateway uninstall [--instance <id>] [--name <suffix>]
+  gateway tailscale [--instance <id>] [--name <suffix>] [--port <num>] [--config <path>]
+`);
+}
+/**
+ * Handle `gateway` lifecycle commands.
+ */
+export async function handleGatewayCli(argv) {
+    if (argv[0] !== 'gateway') {
+        return false;
+    }
+    try {
+        const parsed = parseGatewayArgs(argv);
+        const context = await resolveGatewayContext(parsed);
+        switch (context.command) {
+            case 'install':
+                await installService(context);
+                console.log(`[TwinBot] Installed gateway service '${context.serviceId}'.`);
+                break;
+            case 'start':
+                await startService(context);
+                console.log(`[TwinBot] Started gateway service '${context.serviceId}'.`);
+                break;
+            case 'stop':
+                await stopService(context);
+                console.log(`[TwinBot] Stopped gateway service '${context.serviceId}'.`);
+                break;
+            case 'restart':
+                await restartService(context);
+                console.log(`[TwinBot] Restarted gateway service '${context.serviceId}'.`);
+                break;
+            case 'status': {
+                const status = queryStatus(context);
+                printStatus(context, status);
+                process.exitCode = status.running ? 0 : 1;
+                break;
+            }
+            case 'uninstall':
+                await uninstallService(context);
+                console.log(`[TwinBot] Uninstalled gateway service '${context.serviceId}'.`);
+                break;
+            case 'tailscale':
+                console.log(buildTailscaleInstructions(context).trimStart());
+                break;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[TwinBot Gateway] ${message}`);
+        printGatewayUsage();
+        process.exitCode = 1;
+    }
+    return true;
+}