@mindexec/cli 0.2.0

package/launch-bridge.cjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { spawn } = require('child_process');
+const packageInfo = require('./package.json');
+const { normalizePort, releaseBridgePort } = require('./port-guard.cjs');
+
+const bridgeRoot = __dirname;
+const serverPath = path.resolve(bridgeRoot, 'server.js');
+const inheritedWorkspacePath = String(process.env.WORKSPACE_PATH || '').trim();
+const workspacePath = inheritedWorkspacePath || path.resolve(bridgeRoot, '..');
+const rawArgs = process.argv.slice(2);
+const appUrl = `http://localhost:${normalizePort(process.env.BRIDGE_PORT)}/mindcanvas`;
+const statusUrl = `http://127.0.0.1:${normalizePort(process.env.BRIDGE_PORT)}/api/status`;
+
+function printHelp() {
+    console.log(`MindExec CLI ${packageInfo.version}
+
+Usage:
+  mindexec [start] [node-options]
+  npx @mindexec/cli
+
+Runs the MindExec local app and bridge on http://localhost:5147/mindcanvas by default.
+
+Environment:
+  BRIDGE_PORT       Local bridge port. Default: 5147
+  WORKSPACE_PATH    Workspace root. Default: parent of the installed package
+  BRIDGE_TOKEN      Fixed token for protected REST APIs
+  MINDEXEC_WEB_ROOT Published MindCanvas wwwroot override. Default: package wwwroot
+  MINDEXEC_NO_OPEN=1
+                    Do not open the local app in the default browser
+  BRIDGE_SKIP_PORT_REAP=1
+                    Do not stop an existing MindExec bridge on the same port
+  BRIDGE_FORCE_KILL_PORT_OWNER=1
+                    Stop any process that owns BRIDGE_PORT before starting
+
+Examples:
+  mindexec
+  mindexec --no-open
+  BRIDGE_PORT=8080 WORKSPACE_PATH=/path/to/work mindexec
+  mindexec --watch
+`);
+}
+
+if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
+    printHelp();
+    process.exit(0);
+}
+
+if (rawArgs.includes('--version') || rawArgs.includes('-v')) {
+    console.log(packageInfo.version);
+    process.exit(0);
+}
+
+const command = rawArgs[0];
+const commandArgs = command === 'start' || command === 'bridge'
+    ? rawArgs.slice(1)
+    : rawArgs;
+const shouldOpenApp = !commandArgs.some(arg => arg === '--no-open' || arg === '--no-browser')
+    && !/^(1|true|yes|on)$/i.test(String(process.env.MINDEXEC_NO_OPEN || '').trim())
+    && !/^(0|false|no|off)$/i.test(String(process.env.MINDEXEC_OPEN_APP || '').trim());
+const runtimeArgs = commandArgs.filter(arg => arg !== '--no-open' && arg !== '--no-browser');
+const childArgs = [...runtimeArgs, serverPath];
+const port = normalizePort(process.env.BRIDGE_PORT);
+
+function delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function waitForBridgeReady(timeoutMs = 15000) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+        try {
+            const response = await fetch(statusUrl, { cache: 'no-store' });
+            if (response.ok) {
+                return true;
+            }
+        } catch {
+            // Server is still booting.
+        }
+
+        await delay(300);
+    }
+
+    return false;
+}
+
+function openLocalApp() {
+    let child;
+    if (process.platform === 'win32') {
+        child = spawn('cmd', ['/c', 'start', '', appUrl], {
+            detached: true,
+            stdio: 'ignore',
+            windowsHide: true
+        });
+    } else if (process.platform === 'darwin') {
+        child = spawn('open', [appUrl], {
+            detached: true,
+            stdio: 'ignore'
+        });
+    } else {
+        child = spawn('xdg-open', [appUrl], {
+            detached: true,
+            stdio: 'ignore'
+        });
+    }
+
+    child.on('error', () => {
+        console.log(`[MindExec CLI] Open the app manually: ${appUrl}`);
+    });
+    child.unref();
+}
+
+async function main() {
+    await releaseBridgePort({
+        port,
+        bridgeRoot,
+        log: message => console.log(`[MindExec CLI] ${message}`)
+    });
+
+    const child = spawn(process.execPath, childArgs, {
+        cwd: bridgeRoot,
+        env: {
+            ...process.env,
+            WORKSPACE_PATH: workspacePath
+        },
+        stdio: 'inherit',
+        windowsHide: false
+    });
+
+    child.on('exit', (code, signal) => {
+        if (signal) {
+            process.kill(process.pid, signal);
+            return;
+        }
+
+        process.exit(code ?? 0);
+    });
+
+    child.on('error', (error) => {
+        console.error('[MindExec CLI] Failed to start local bridge:', error);
+        process.exit(1);
+    });
+
+    if (shouldOpenApp) {
+        void (async () => {
+            const ready = await waitForBridgeReady();
+            if (!ready || child.exitCode !== null) {
+                console.log(`[MindExec CLI] Open the app manually: ${appUrl}`);
+                return;
+            }
+
+            console.log(`[MindExec CLI] opening ${appUrl}`);
+            openLocalApp();
+        })();
+    }
+}
+
+main().catch(error => {
+    console.error('[MindExec CLI] Failed to prepare local bridge port:', error.message || error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@mindexec/cli",
+  "version": "0.2.0",
+  "description": "MindExec local runtime and bridge CLI",
+  "main": "server.js",
+  "type": "module",
+  "files": [
+    "start-bridge.bat",
+    "start-bridge.sh",
+    "launch-bridge.cjs",
+    "server.js",
+    "codex-runtime.js",
+    "port-guard.cjs",
+    "wwwroot/",
+    "scripts/",
+    "tree-sitter-grammars/",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node launch-bridge.cjs",
+    "dev": "node launch-bridge.cjs --watch",
+    "test:syntax": "node --check server.js && node --check codex-runtime.js && node --check launch-bridge.cjs && node --check port-guard.cjs && node --check scripts/setup-tree-sitter-grammars.mjs",
+    "pack:dry": "npm pack --dry-run",
+    "setup:grammars": "node scripts/setup-tree-sitter-grammars.mjs",
+    "postinstall": "npm run setup:grammars"
+  },
+  "keywords": [
+    "mindexec",
+    "mindcanvas",
+    "cli",
+    "bridge",
+    "local",
+    "ai"
+  ],
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@openai/codex-sdk": "^0.137.0",
+    "chokidar": "^3.6.0",
+    "cors": "^2.8.5",
+    "express": "^4.18.2",
+    "multer": "^2.1.1",
+    "playwright-core": "^1.53.0",
+    "sharp": "^0.33.2",
+    "web-tree-sitter": "^0.22.6",
+    "ws": "^8.16.0"
+  },
+  "bin": {
+    "mindexec": "launch-bridge.cjs",
+    "mind-bridge": "launch-bridge.cjs"
+  },
+  "devDependencies": {
+    "tree-sitter-wasms": "^0.1.13"
+  }
+}

package/port-guard.cjs

@@ -0,0 +1,232 @@
+const { execFile } = require('child_process');
+const path = require('path');
+const { promisify } = require('util');
+
+const execFileAsync = promisify(execFile);
+const DEFAULT_WAIT_MS = 3500;
+
+function normalizePort(value, fallback = 5147) {
+    const parsed = Number.parseInt(String(value || '').trim(), 10);
+    return Number.isInteger(parsed) && parsed > 0 && parsed <= 65535
+        ? parsed
+        : fallback;
+}
+
+function normalizePath(value) {
+    return String(value || '').replace(/\\/g, '/').toLowerCase();
+}
+
+function isTruthy(value) {
+    return /^(1|true|yes|on)$/i.test(String(value || '').trim());
+}
+
+function endpointUsesPort(endpoint, port) {
+    const text = String(endpoint || '').trim();
+    return text.endsWith(`:${port}`)
+        || text.endsWith(`.${port}`)
+        || text.includes(`:${port} `)
+        || text.includes(`]:${port}`);
+}
+
+async function getWindowsListeners(port) {
+    const { stdout } = await execFileAsync('netstat.exe', ['-ano', '-p', 'tcp'], {
+        windowsHide: true,
+        maxBuffer: 1024 * 1024
+    });
+
+    const pids = new Set();
+    for (const rawLine of String(stdout || '').split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || !/\bLISTENING\b/i.test(line)) {
+            continue;
+        }
+
+        const parts = line.split(/\s+/);
+        if (parts.length < 5 || !endpointUsesPort(parts[1], port)) {
+            continue;
+        }
+
+        const pid = Number.parseInt(parts[parts.length - 1], 10);
+        if (Number.isInteger(pid) && pid > 0 && pid !== process.pid) {
+            pids.add(pid);
+        }
+    }
+
+    return [...pids];
+}
+
+async function getUnixListeners(port) {
+    try {
+        const { stdout } = await execFileAsync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'], {
+            maxBuffer: 256 * 1024
+        });
+        return String(stdout || '')
+            .split(/\r?\n/)
+            .map(line => Number.parseInt(line.trim(), 10))
+            .filter(pid => Number.isInteger(pid) && pid > 0 && pid !== process.pid);
+    } catch {
+        return [];
+    }
+}
+
+async function getPortListeners(port) {
+    try {
+        return process.platform === 'win32'
+            ? await getWindowsListeners(port)
+            : await getUnixListeners(port);
+    } catch {
+        return [];
+    }
+}
+
+async function getWindowsProcessDetails(pid) {
+    const script = [
+        '$ErrorActionPreference = "SilentlyContinue";',
+        `$p = Get-CimInstance Win32_Process -Filter "ProcessId=${pid}";`,
+        'if ($p) {',
+        '  [pscustomobject]@{ ProcessId = $p.ProcessId; ExecutablePath = $p.ExecutablePath; CommandLine = $p.CommandLine } | ConvertTo-Json -Compress',
+        '}'
+    ].join(' ');
+    const { stdout } = await execFileAsync('powershell.exe', ['-NoProfile', '-Command', script], {
+        windowsHide: true,
+        maxBuffer: 256 * 1024
+    });
+    const parsed = JSON.parse(String(stdout || '{}').trim() || '{}');
+    return {
+        pid,
+        executablePath: parsed.ExecutablePath || '',
+        commandLine: parsed.CommandLine || ''
+    };
+}
+
+async function getUnixProcessDetails(pid) {
+    const { stdout } = await execFileAsync('ps', ['-p', String(pid), '-o', 'comm=', '-o', 'args='], {
+        maxBuffer: 256 * 1024
+    });
+    const text = String(stdout || '').trim();
+    return {
+        pid,
+        executablePath: text.split(/\s+/)[0] || '',
+        commandLine: text
+    };
+}
+
+async function getProcessDetails(pid) {
+    try {
+        return process.platform === 'win32'
+            ? await getWindowsProcessDetails(pid)
+            : await getUnixProcessDetails(pid);
+    } catch {
+        return {
+            pid,
+            executablePath: '',
+            commandLine: ''
+        };
+    }
+}
+
+function looksLikeMindExecBridge(details, bridgeRoot) {
+    const text = normalizePath(`${details.executablePath || ''} ${details.commandLine || ''}`);
+    const root = normalizePath(bridgeRoot);
+    const packageRoot = normalizePath(path.dirname(bridgeRoot));
+
+    return (root && text.includes(root))
+        || (packageRoot && text.includes(`${packageRoot}/localbridge/`))
+        || text.includes('localbridge/server.js')
+        || text.includes('localbridge/launch-bridge.cjs')
+        || text.includes('/localbridge/server.js')
+        || text.includes('/localbridge/launch-bridge.cjs')
+        || text.includes('@mindexec/cli')
+        || text.includes('mind-bridge')
+        || /\bmindexec(\.cmd|\.ps1|\.exe)?\b/i.test(text);
+}
+
+async function waitForPortRelease(port, timeoutMs = DEFAULT_WAIT_MS) {
+    const started = Date.now();
+    while (Date.now() - started < timeoutMs) {
+        const listeners = await getPortListeners(port);
+        if (listeners.length === 0) {
+            return true;
+        }
+
+        await new Promise(resolve => setTimeout(resolve, 120));
+    }
+
+    return false;
+}
+
+function killPid(pid, signal) {
+    try {
+        process.kill(pid, signal);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+async function releaseBridgePort(options = {}) {
+    const port = normalizePort(options.port || process.env.BRIDGE_PORT);
+    const bridgeRoot = options.bridgeRoot || __dirname;
+    const log = typeof options.log === 'function' ? options.log : () => {};
+    const force = isTruthy(process.env.BRIDGE_FORCE_KILL_PORT_OWNER)
+        || isTruthy(process.env.BRIDGE_KILL_ANY_PORT_OWNER);
+    const disabled = isTruthy(process.env.BRIDGE_SKIP_PORT_REAP);
+
+    if (disabled) {
+        return { port, killed: [], skipped: [], disabled: true };
+    }
+
+    const pids = await getPortListeners(port);
+    const killed = [];
+    const skipped = [];
+
+    for (const pid of pids) {
+        const details = await getProcessDetails(pid);
+        const canKill = force || looksLikeMindExecBridge(details, bridgeRoot);
+        if (!canKill) {
+            skipped.push(details);
+            continue;
+        }
+
+        if (killPid(pid, 'SIGTERM')) {
+            killed.push(details);
+            log(`stopping existing LocalBridge listener on port ${port} (pid ${pid})`);
+        }
+    }
+
+    if (killed.length > 0) {
+        const released = await waitForPortRelease(port);
+        if (!released) {
+            const remaining = await getPortListeners(port);
+            for (const details of killed) {
+                if (remaining.includes(details.pid)) {
+                    killPid(details.pid, 'SIGKILL');
+                    log(`force-stopping LocalBridge listener on port ${port} (pid ${details.pid})`);
+                }
+            }
+
+            await waitForPortRelease(port, 1200);
+        }
+    }
+
+    if (skipped.length > 0) {
+        const owners = skipped
+            .map(item => `pid ${item.pid}${item.commandLine ? ` (${item.commandLine})` : ''}`)
+            .join('; ');
+        const error = new Error(
+            `Port ${port} is already in use by a non-MindExec process: ${owners}. ` +
+            'Close it or set BRIDGE_FORCE_KILL_PORT_OWNER=1 to terminate any owner of this bridge port.'
+        );
+        error.code = 'BRIDGE_PORT_IN_USE';
+        error.port = port;
+        error.skipped = skipped;
+        throw error;
+    }
+
+    return { port, killed, skipped, disabled: false };
+}
+
+module.exports = {
+    normalizePort,
+    releaseBridgePort
+};

package/scripts/setup-tree-sitter-grammars.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const bridgeRoot = path.resolve(__dirname, '..');
+const sourceDir = path.join(bridgeRoot, 'node_modules', 'tree-sitter-wasms', 'out');
+const destDir = path.join(bridgeRoot, 'tree-sitter-grammars');
+
+const requiredFiles = [
+    'tree-sitter-javascript.wasm',
+    'tree-sitter-typescript.wasm',
+    'tree-sitter-tsx.wasm',
+    'tree-sitter-c_sharp.wasm',
+    'tree-sitter-python.wasm',
+    'tree-sitter-java.wasm',
+    'tree-sitter-go.wasm',
+    'tree-sitter-rust.wasm'
+];
+
+async function ensureDirectory(dir) {
+    await fs.mkdir(dir, { recursive: true });
+}
+
+async function copyGrammarFiles() {
+    await ensureDirectory(destDir);
+
+    let copied = 0;
+    const missing = [];
+
+    for (const fileName of requiredFiles) {
+        const src = path.join(sourceDir, fileName);
+        const dst = path.join(destDir, fileName);
+
+        try {
+            await fs.access(src);
+            await fs.copyFile(src, dst);
+            copied += 1;
+        } catch {
+            missing.push(fileName);
+        }
+    }
+
+    if (copied > 0) {
+        console.log(`[setup:grammars] Copied ${copied} grammar files to ${destDir}`);
+    }
+
+    if (missing.length > 0) {
+        console.warn('[setup:grammars] Missing grammar files:', missing.join(', '));
+    }
+}
+
+copyGrammarFiles().catch((err) => {
+    console.error(`[setup:grammars] Failed: ${err?.message || err}`);
+    process.exitCode = 1;
+});