twinclaw 1.0.0

package/dist/core/install-cli.js

@@ -0,0 +1,320 @@
+import { exec } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import * as readline from 'node:readline';
+import { promisify } from 'node:util';
+import { runSetupWizard, OnboardingCancelledError, } from './onboarding.js';
+function parseInstallArgs(args) {
+    const parsed = {
+        help: false,
+        nonInteractive: false,
+        skipOnboard: false,
+        asJson: false,
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        switch (token) {
+            case '--help':
+            case '-h':
+                parsed.help = true;
+                break;
+            case '--non-interactive':
+                parsed.nonInteractive = true;
+                break;
+            case '--skip-onboard':
+                parsed.skipOnboard = true;
+                break;
+            case '--json':
+                parsed.asJson = true;
+                break;
+            case '--config': {
+                const nextValue = args[i + 1];
+                if (!nextValue || nextValue.startsWith('--')) {
+                    parsed.error = 'Missing value for --config.';
+                    return parsed;
+                }
+                parsed.configPathOverride = nextValue;
+                i += 1;
+                break;
+            }
+            default:
+                parsed.error = `Unknown option '${token}'.`;
+                return parsed;
+        }
+    }
+    return parsed;
+}
+function printInstallUsage() {
+    console.log(`Install command usage:
+  install                                Run Windows install workflow and optional onboarding handoff
+  install --non-interactive              Run install without interactive prompts
+  install --skip-onboard                 Skip onboarding handoff
+  install --config <path>                Override twinbot.json path when onboarding runs
+  install --json                         Emit machine-readable install report
+`);
+}
+function statusIcon(status) {
+    switch (status) {
+        case 'passed':
+            return '✅';
+        case 'failed':
+            return '❌';
+        case 'warning':
+            return '⚠️';
+        default:
+            return '⏭️';
+    }
+}
+async function promptYesNo(question, defaultYes) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve, reject) => {
+        rl.on('SIGINT', () => {
+            rl.close();
+            reject(new OnboardingCancelledError('Installer confirmation cancelled by user.'));
+        });
+        rl.question(question, (answer) => {
+            rl.close();
+            const normalized = answer.trim().toLowerCase();
+            if (normalized.length === 0) {
+                resolve(defaultYes);
+                return;
+            }
+            resolve(normalized === 'y' || normalized === 'yes');
+        });
+    });
+}
+async function defaultCommandRunner(command, cwd) {
+    const execAsync = promisify(exec);
+    const started = Date.now();
+    try {
+        const { stdout, stderr } = await execAsync(command, {
+            cwd,
+            windowsHide: true,
+            maxBuffer: 10 * 1024 * 1024,
+        });
+        const output = [stdout, stderr].filter(Boolean).join('\n').trim();
+        return { ok: true, exitCode: 0, output, durationMs: Date.now() - started };
+    }
+    catch (error) {
+        const err = error;
+        const output = [err.stdout, err.stderr, err.message]
+            .filter((value) => typeof value === 'string' && value.length > 0)
+            .join('\n')
+            .trim();
+        return {
+            ok: false,
+            exitCode: typeof err.code === 'number' ? err.code : 1,
+            output,
+            durationMs: Date.now() - started,
+        };
+    }
+}
+export async function runInstallFlow(options) {
+    const logger = options.logger ?? console;
+    const cwd = options.cwd ?? process.cwd();
+    const commandRunner = options.commandRunner ?? defaultCommandRunner;
+    const onboardingRunner = options.onboardingRunner ?? runSetupWizard;
+    const confirmOnboard = options.confirmOnboard ??
+        (() => promptYesNo('\nLaunch onboarding wizard now? [Y/n]: ', true));
+    const steps = [];
+    const warnings = [];
+    const errors = [];
+    const packagePath = path.join(cwd, 'package.json');
+    const nodeMajor = Number.parseInt(process.versions.node.split('.')[0] ?? '0', 10);
+    if (!existsSync(packagePath)) {
+        errors.push(`package.json is missing from ${cwd}.`);
+        steps.push({
+            id: 'preflight',
+            status: 'failed',
+            detail: 'Missing package.json in current working directory.',
+        });
+        return { status: 'failed', steps, warnings, errors };
+    }
+    if (!Number.isInteger(nodeMajor) || nodeMajor < 22) {
+        errors.push(`Node.js v22+ required. Detected v${process.versions.node}.`);
+        steps.push({
+            id: 'preflight',
+            status: 'failed',
+            detail: `Node.js v22+ required. Detected v${process.versions.node}.`,
+        });
+        return { status: 'failed', steps, warnings, errors };
+    }
+    steps.push({
+        id: 'preflight',
+        status: 'passed',
+        detail: `Preflight checks passed (Node.js v${process.versions.node}, package.json present).`,
+    });
+    const dependenciesCommand = 'npm install --no-audit --no-fund';
+    const installRun = await commandRunner(dependenciesCommand, cwd);
+    if (!installRun.ok) {
+        const detail = `Dependency install failed (exit ${installRun.exitCode}).`;
+        errors.push(`${detail} ${installRun.output.trim().split('\n').slice(-5).join(' ')}`.trim());
+        steps.push({
+            id: 'dependencies',
+            status: 'failed',
+            detail,
+            command: dependenciesCommand,
+        });
+        return { status: 'failed', steps, warnings, errors };
+    }
+    steps.push({
+        id: 'dependencies',
+        status: 'passed',
+        detail: 'Dependencies installed successfully.',
+        command: dependenciesCommand,
+    });
+    const hooksCommand = 'npm run setup:hooks';
+    if (existsSync(path.join(cwd, '.git'))) {
+        const hooksRun = await commandRunner(hooksCommand, cwd);
+        if (!hooksRun.ok) {
+            warnings.push('Unable to configure .githooks path automatically.');
+            steps.push({
+                id: 'git-hooks',
+                status: 'warning',
+                detail: 'Hook setup failed. Continue manually with `npm run setup:hooks`.',
+                command: hooksCommand,
+            });
+        }
+        else {
+            steps.push({
+                id: 'git-hooks',
+                status: 'passed',
+                detail: 'Git hook path configured.',
+                command: hooksCommand,
+            });
+        }
+    }
+    else {
+        steps.push({
+            id: 'git-hooks',
+            status: 'skipped',
+            detail: 'No .git directory found; hook setup skipped.',
+            command: hooksCommand,
+        });
+    }
+    if (options.skipOnboard) {
+        steps.push({
+            id: 'onboarding',
+            status: 'skipped',
+            detail: 'Onboarding handoff skipped by --skip-onboard.',
+        });
+        return { status: 'success', steps, warnings, errors };
+    }
+    if (options.nonInteractive) {
+        warnings.push('Non-interactive install mode skips onboarding. Run `twinbot onboard` next.');
+        steps.push({
+            id: 'onboarding',
+            status: 'skipped',
+            detail: 'Onboarding skipped in non-interactive mode.',
+        });
+        return { status: 'success', steps, warnings, errors };
+    }
+    const shouldRunOnboard = await confirmOnboard();
+    if (!shouldRunOnboard) {
+        steps.push({
+            id: 'onboarding',
+            status: 'skipped',
+            detail: 'Onboarding deferred by operator.',
+        });
+        return { status: 'success', steps, warnings, errors };
+    }
+    const onboardingResult = await onboardingRunner({
+        configPathOverride: options.configPathOverride,
+    });
+    if (onboardingResult.status === 'cancelled') {
+        warnings.push('Onboarding cancelled; install completed without persisted onboarding updates.');
+        steps.push({
+            id: 'onboarding',
+            status: 'warning',
+            detail: 'Onboarding was cancelled by user.',
+        });
+        return { status: 'cancelled', steps, warnings, errors };
+    }
+    if (onboardingResult.status !== 'success') {
+        const detail = `Onboarding failed with status '${onboardingResult.status}'.`;
+        errors.push(...onboardingResult.errors);
+        steps.push({
+            id: 'onboarding',
+            status: 'failed',
+            detail,
+        });
+        return { status: 'failed', steps, warnings, errors };
+    }
+    warnings.push(...onboardingResult.warnings);
+    steps.push({
+        id: 'onboarding',
+        status: 'passed',
+        detail: `Onboarding completed. Config saved to ${onboardingResult.configPath}.`,
+    });
+    return { status: 'success', steps, warnings, errors };
+}
+function printInstallReport(report, logger) {
+    logger.log('\nTwinBot Install Report');
+    logger.log('──────────────────────────────────────────────────');
+    for (const step of report.steps) {
+        logger.log(`${statusIcon(step.status)} [${step.id}] ${step.detail}`);
+    }
+    if (report.warnings.length > 0) {
+        logger.warn('\nWarnings:');
+        for (const warning of report.warnings) {
+            logger.warn(`- ${warning}`);
+        }
+    }
+    if (report.errors.length > 0) {
+        logger.error('\nErrors:');
+        for (const error of report.errors) {
+            logger.error(`- ${error}`);
+        }
+    }
+}
+/**
+ * Handles one-shot `install` command.
+ */
+export async function handleInstallCli(argv) {
+    if (argv[0] !== 'install') {
+        return false;
+    }
+    const parsed = parseInstallArgs(argv.slice(1));
+    if (parsed.help) {
+        printInstallUsage();
+        process.exitCode = 0;
+        return true;
+    }
+    if (parsed.error) {
+        console.error(`[TwinBot Install] ${parsed.error}`);
+        printInstallUsage();
+        process.exitCode = 1;
+        return true;
+    }
+    try {
+        const result = await runInstallFlow({
+            nonInteractive: parsed.nonInteractive,
+            skipOnboard: parsed.skipOnboard,
+            configPathOverride: parsed.configPathOverride,
+        });
+        if (parsed.asJson) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            printInstallReport(result, console);
+        }
+        if (result.status === 'success') {
+            process.exitCode = 0;
+        }
+        else if (result.status === 'cancelled') {
+            process.exitCode = 130;
+        }
+        else {
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[TwinBot Install] ${message}`);
+        process.exitCode = error instanceof OnboardingCancelledError ? 130 : 1;
+    }
+    return true;
+}

package/dist/core/lane-executor.js

@@ -0,0 +1,134 @@
+import { logToolCall, scrubSensitiveText } from '../utils/logger.js';
+/** Convert a Skill (from the registry) into the internal Tool format used by LaneExecutor. */
+function skillToTool(skill) {
+    return {
+        name: skill.name,
+        description: skill.description,
+        parameters: skill.parameters ?? {},
+        group: skill.group,
+        aliases: skill.aliases,
+        mcpScope: skill.mcpScope,
+        serverId: skill.serverId,
+        adapter: skill.adapter,
+        execute: async (args) => {
+            const result = await skill.execute(args);
+            return result.output;
+        },
+    };
+}
+export class LaneExecutor {
+    tools = new Map();
+    constructor(tools = []) {
+        for (const tool of tools) {
+            this.tools.set(tool.name, tool);
+        }
+    }
+    registerTool(tool) {
+        this.tools.set(tool.name, tool);
+    }
+    registerSkill(skill) {
+        const converted = skillToTool(skill);
+        this.tools.set(converted.name, converted);
+        for (const alias of skill.aliases ?? []) {
+            const normalized = alias.trim();
+            if (!normalized || normalized === converted.name) {
+                continue;
+            }
+            this.tools.set(normalized, converted);
+        }
+    }
+    syncSkills(skills) {
+        this.tools.clear();
+        for (const skill of skills) {
+            this.registerSkill(skill);
+        }
+    }
+    /**
+     * Pull all skills from a SkillRegistry and replace the executable tool map.
+     */
+    syncFromRegistry(registry) {
+        this.syncSkills(registry.list());
+    }
+    parseArguments(args) {
+        try {
+            return JSON.parse(args);
+        }
+        catch {
+            console.warn(`[LaneExecutor] Failed to parse arguments: ${scrubSensitiveText(args)}`);
+            return {};
+        }
+    }
+    async executeToolCalls(message, sessionId, policyEngine) {
+        if (!message.tool_calls || message.tool_calls.length === 0) {
+            return [];
+        }
+        const results = [];
+        // Lane-Based Execution: Execute tools serially in an await loop
+        for (const toolCall of message.tool_calls) {
+            const toolName = toolCall.function.name;
+            const args = this.parseArguments(toolCall.function.arguments);
+            const tool = this.tools.get(toolName);
+            let content = '';
+            if (!tool) {
+                console.warn(`[LaneExecutor] Tool not found: ${toolName}`);
+                content = `Error: Tool '${toolName}' is not registered or unavailable.`;
+                await logToolCall(toolName, args, content);
+            }
+            else {
+                let allowed = true;
+                let decision = policyEngine ? policyEngine.evaluate(sessionId, toolName) : null;
+                // 1. MCP Scope Enforcement (Applies before or alongside PolicyEngine)
+                if (tool.serverId && tool.mcpScope) {
+                    if (tool.mcpScope === 'unclassified') {
+                        content = `Access Denied: MCP tool '${toolName}' is unclassified (secure default). Capability Profile: ${tool.mcpScope}`;
+                        allowed = false;
+                        tool.adapter?.auditScopeBlock(sessionId, toolName, tool.mcpScope, 'Secure default for unclassified tools');
+                    }
+                    else if (tool.mcpScope === 'high-risk') {
+                        // High-risk blocked-by-default: Needs explicit policy allow, not a fallback
+                        const isFallback = decision ? decision.reason.includes('Fell back to') : true;
+                        if (isFallback) {
+                            content = `Access Denied: MCP tool '${toolName}' is 'high-risk' and blocked by default. Requires explicit allow rule. Capability Profile: ${tool.mcpScope}`;
+                            allowed = false;
+                            tool.adapter?.auditScopeBlock(sessionId, toolName, tool.mcpScope, 'High-risk tools require explicit allow rule');
+                        }
+                    }
+                    if (allowed) {
+                        tool.adapter?.auditScopeAllow(sessionId, toolName, tool.mcpScope);
+                    }
+                }
+                // 2. Policy Governance Baseline
+                if (allowed && decision && decision.action === 'deny') {
+                    content = `Access Denied: Tool '${toolName}' is blocked by policy. Reason: ${decision.reason}`;
+                    allowed = false;
+                }
+                if (!allowed) {
+                    console.warn(`[LaneExecutor] Blocked tool ${toolName}: ${content}`);
+                    await logToolCall(toolName, args, content);
+                }
+                if (allowed) {
+                    try {
+                        console.log(`[LaneExecutor] Executing ${toolName} with args: ${scrubSensitiveText(JSON.stringify(args))}`);
+                        const result = await tool.execute(args);
+                        content = typeof result === 'string' ? result : JSON.stringify(result);
+                        await logToolCall(toolName, args, content);
+                    }
+                    catch (error) {
+                        const rawMessage = error instanceof Error ? error.message : String(error);
+                        const sanitizedMessage = scrubSensitiveText(rawMessage);
+                        console.error(`[LaneExecutor] Tool ${toolName} failed: ${sanitizedMessage}`);
+                        content = `Error executing tool: ${sanitizedMessage}`;
+                        await logToolCall(toolName, args, content);
+                    }
+                }
+            }
+            results.push({
+                role: 'tool',
+                tool_call_id: toolCall.id,
+                name: toolName,
+                content: content,
+            });
+        }
+        return results;
+    }
+}

package/dist/core/logs-cli.js

@@ -0,0 +1,70 @@
+import * as fs from 'node:fs';
+import * as fsPromises from 'node:fs/promises';
+import path from 'node:path';
+function currentDateIso() {
+    return new Date().toISOString().slice(0, 10);
+}
+/**
+ * Handle the `logs` command.
+ * Reads or tails the daily TwinBot memory log file.
+ */
+export async function handleLogsCli(argv) {
+    if (argv[0] !== 'logs')
+        return false;
+    const follow = argv.includes('--follow') || argv.includes('-f');
+    const dateIso = currentDateIso();
+    const logPath = path.resolve('memory', `${dateIso}.md`);
+    if (!fs.existsSync(logPath)) {
+        console.error(`[TwinBot Logs] No logs found for today (${dateIso}) at ${logPath}.`);
+        process.exitCode = 1;
+        return true;
+    }
+    if (follow) {
+        console.log(`[TwinBot Logs] Following logs from ${logPath}...\n`);
+        tailFile(logPath);
+        // We do not exit the process here to keep the watcher alive.
+    }
+    else {
+        const contents = await fsPromises.readFile(logPath, 'utf8');
+        process.stdout.write(contents);
+        process.exitCode = 0;
+    }
+    return true;
+}
+/**
+ * Tail a file similar to `tail -f`.
+ */
+function tailFile(filePath) {
+    let position = fs.statSync(filePath).size;
+    // For tailing, print the last 4KB of context first context
+    const startPos = Math.max(0, position - 4096);
+    if (startPos < position) {
+        const initialStream = fs.createReadStream(filePath, { start: startPos, encoding: 'utf8' });
+        initialStream.pipe(process.stdout);
+    }
+    try {
+        fs.watch(filePath, (eventType) => {
+            if (eventType === 'change') {
+                const stats = fs.statSync(filePath);
+                if (stats.size > position) {
+                    const stream = fs.createReadStream(filePath, {
+                        start: position,
+                        end: stats.size,
+                        encoding: 'utf8'
+                    });
+                    stream.on('data', (chunk) => {
+                        process.stdout.write(chunk);
+                    });
+                    position = stats.size;
+                }
+                else if (stats.size < position) {
+                    // File was truncated or rolled over
+                    position = stats.size;
+                }
+            }
+        });
+    }
+    catch (err) {
+        console.error(`[TwinBot Logs] Failed to watch file: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}