@factadev/cli 0.2.6 → 0.2.8

package/README.md

@@ -1,145 +1,97 @@
-# nest CLI
+# NEST CLI
 
-Run Claude Code, Codex, Cursor Agent, Gemini, or OpenCode sessions from your terminal and control them remotely through the NEST hub.
+Run Claude Code, Codex, Cursor Agent, Gemini, or OpenCode in your terminal and control sessions remotely through the NEST server—from a browser, PWA, or Telegram.
 
 ## What it does
 
-- Starts Claude Code sessions and registers them with nest-hub.
-- Starts Codex mode for OpenAI-based sessions.
-- Starts Cursor Agent mode for Cursor CLI sessions.
-- Starts Gemini mode via ACP (Anthropic Code Plugins).
-- Starts OpenCode mode via ACP and its plugin hook system.
-- Provides an MCP stdio bridge for external tools.
-- Manages a background runner for long-running sessions.
-- Includes diagnostics and auth helpers.
+- **Unified AI coding** — Start and manage Claude Code, Codex, Cursor Agent, Gemini, and OpenCode from one CLI. Sessions sync with the NEST server for remote access.
+- **Remote control** — Monitor and steer sessions from the web app or Telegram Mini App. Approve permissions, send messages, and run commands from your phone.
+- **Background worker** — Run a worker so sessions can be started remotely without keeping a terminal open. Your machine stays available in the NEST dashboard.
+- **MCP bridge** — Expose tools to external clients via the MCP stdio bridge.
+- **Diagnostics and auth** — Check connectivity, token, and agent setup with `nest diagnose`. Manage credentials with `nest auth login` / `logout`.
 
-## Typical flow
+## Quick start
 
-1. Start the hub and set env vars (see ../hub/README.md).
-2. Set the same CLI_API_TOKEN on this machine or run `nest auth login`.
-3. Run `nest` to start a session.
-4. Use the web app or Telegram Mini App to monitor and control.
+1. Start the NEST server and set `CLI_API_TOKEN` (see server docs).
+2. On this machine: set the same `CLI_API_TOKEN` or run `nest auth login`.
+3. Run `nest` to start a Claude Code session.
+4. Open the web app or Telegram Mini App to monitor and control.
 
 ## Commands
 
-### Session commands
+### Sessions
 
-- `nest` - Start a Claude Code session (passes through Claude CLI flags). See `src/index.ts`.
-- `nest codex` - Start Codex mode. See `src/codex/runCodex.ts`.
-- `nest codex resume <sessionId>` - Resume existing Codex session.
-- `nest cursor` - Start Cursor Agent mode. See `src/cursor/runCursor.ts`.
-  Supports `nest cursor resume <chatId>`, `nest cursor --continue`, `--mode plan|ask`, `--yolo`, `--model`.
-  Local and remote modes supported; remote uses `agent -p` with stream-json.
-- `nest gemini` - Start Gemini mode via ACP. See `src/agent/runners/runAgentSession.ts`.
-  Note: Gemini runs in remote mode only; it waits for messages from the hub UI/Telegram.
-- `nest opencode` - Start OpenCode mode via ACP. See `src/opencode/runOpencode.ts`.
-  Note: OpenCode supports local and remote modes; local mode streams via OpenCode plugins.
+- `nest` — Start a Claude Code session (forwards Claude CLI flags).
+- `nest codex` — Codex mode (OpenAI). Use `nest codex resume <sessionId>` to resume.
+- `nest cursor` — Cursor Agent mode. Supports resume, `--continue`, `--mode plan|ask`, `--yolo`, `--model`. Local and remote.
+- `nest gemini` — Gemini via ACP (remote mode; receives messages from server UI/Telegram).
+- `nest opencode` — OpenCode via ACP. Local and remote modes.
 
-### Authentication
+### Auth
 
-- `nest auth status` - Show authentication configuration and token source.
-- `nest auth login` - Interactively enter and save CLI_API_TOKEN.
-- `nest auth logout` - Clear saved credentials.
+- `nest auth status` — Show auth config and token source.
+- `nest auth login` — Save `CLI_API_TOKEN` interactively.
+- `nest auth logout` — Clear saved credentials.
 
-See `src/commands/auth.ts`.
+### Worker
 
-### Worker management
-
-- `nest worker start` - Start worker as detached process.
-- `nest worker stop` - Stop worker gracefully.
-- `nest worker status` - Show worker diagnostics.
-- `nest worker list` - List active sessions managed by worker.
-- `nest worker stop-session <sessionId>` - Terminate specific session.
-- `nest worker logs` - Print path to latest worker log file.
-
-See `src/runner/run.ts`.
-
-### Diagnostics
-
-- `nest diagnose` - Show full diagnostics (version, worker status, logs, processes).
-- `nest diagnose clean` - Kill runaway NEST processes.
-
-See `src/ui/doctor.ts`.
+- `nest worker start` — Start worker (detached).
+- `nest worker stop` — Stop worker.
+- `nest worker status` — Worker diagnostics.
+- `nest worker list` — Active sessions.
+- `nest worker stop-session <sessionId>` — End a session.
+- `nest worker logs` — Path to latest worker log.
 
 ### Other
 
-- `nest mcp` - Start MCP stdio bridge. See `src/codex/happyMcpStdioBridge.ts`.
-- `nest server` - Start the bundled server (single binary workflow).
+- `nest diagnose` — Full diagnostics (version, worker, logs, processes).
+- `nest diagnose clean` — Kill runaway NEST processes.
+- `nest mcp` — Start MCP stdio bridge.
+- `nest server` — Start the bundled server (single-binary workflow).
 
 ## Configuration
 
-See `src/configuration.ts` for all options.
-
-### Required
+**Required**
 
-- `CLI_API_TOKEN` - Shared secret; must match the server. Can be set via env or `~/.nest/settings.json` (env wins).
-- `NEST_API_URL` - Server base URL (default: http://localhost:3006).
+- `CLI_API_TOKEN` — Shared secret; must match the server. Env or `~/.nest/settings.json` (env wins).
+- `NEST_API_URL` — Server URL (default: `http://localhost:3006`).
 
-### Optional
+**Optional**
 
-- `NEST_HOME` - Config/data directory (default: ~/.nest).
-- `NEST_EXPERIMENTAL` - Enable experimental features (true/1/yes).
-- `NEST_CLAUDE_PATH` - Path to a specific `claude` executable.
-- `NEST_HTTP_MCP_URL` - Default MCP target for `nest mcp`.
+- `NEST_HOME` — Config directory (default: `~/.nest`).
+- `NEST_EXPERIMENTAL` — Enable experimental features (`true` / `1` / `yes`).
+- `NEST_CLAUDE_PATH` — Path to `claude` executable.
+- `NEST_HTTP_MCP_URL` — Default MCP target for `nest mcp`.
 
-### Runner
+**Worker**
 
-- `NEST_RUNNER_HEARTBEAT_INTERVAL` - Heartbeat interval in ms (default: 60000).
-- `NEST_RUNNER_HTTP_TIMEOUT` - HTTP timeout for runner control in ms (default: 10000).
+- `NEST_RUNNER_HEARTBEAT_INTERVAL` — Heartbeat ms (default: 60000).
+- `NEST_RUNNER_HTTP_TIMEOUT` — HTTP timeout for worker control ms (default: 10000).
 
-### Worktree (set by runner)
+**Worktree** (set by worker when spawning in a worktree)
 
-- `NEST_WORKTREE_BASE_PATH` - Base repository path.
-- `NEST_WORKTREE_BRANCH` - Current branch name.
-- `NEST_WORKTREE_NAME` - Worktree name.
-- `NEST_WORKTREE_PATH` - Full worktree path.
-- `NEST_WORKTREE_CREATED_AT` - Creation timestamp (ms).
+- `NEST_WORKTREE_BASE_PATH`, `NEST_WORKTREE_BRANCH`, `NEST_WORKTREE_NAME`, `NEST_WORKTREE_PATH`, `NEST_WORKTREE_CREATED_AT`.
 
 ## Storage
 
-Data is stored in `~/.nest/` (or `$NEST_HOME`):
+Under `~/.nest/` (or `$NEST_HOME`):
 
-- `settings.json` - User settings (machineId, token, onboarding flag). See `src/persistence.ts`.
-- `runner.state.json` - Runner state (pid, port, version, heartbeat).
-- `logs/` - Log files.
+- `settings.json` — Machine id, token, onboarding.
+- `runner.state.json` — Worker state (pid, port, version, heartbeat).
+- `logs/` — Log files.
 
 ## Requirements
 
-- Claude CLI installed and logged in (`claude` on PATH).
-- Cursor Agent CLI installed (`agent` on PATH) for `nest cursor`. Install: `curl https://cursor.com/install -fsS | bash` (macOS/Linux), `irm 'https://cursor.com/install?win32=true' | iex` (Windows).
-- OpenCode CLI installed (`opencode` on PATH).
-- Bun for building from source.
-
-## Build from source
-
-From the repo root:
-
-```bash
-bun install
-bun run build:cli
-bun run build:cli:exe
-```
-
-For an all-in-one binary that also embeds the web app:
-
-```bash
-bun run build:single-exe
-```
+- Claude CLI on PATH (for `nest`).
+- Cursor Agent CLI on PATH for `nest cursor`: `curl https://cursor.com/install -fsS | bash` (macOS/Linux), or Windows install from Cursor.
+- OpenCode CLI on PATH for `nest opencode`.
 
-## Source structure
+## License
 
-- `src/api/` - Bot communication (Socket.IO + REST).
-- `src/claude/` - Claude Code integration.
-- `src/codex/` - Codex mode integration.
-- `src/cursor/` - Cursor Agent integration.
-- `src/agent/` - Multi-agent support (Gemini via ACP).
-- `src/opencode/` - OpenCode ACP + hook integration.
-- `src/runner/` - Background service.
-- `src/commands/` - CLI command handlers.
-- `src/ui/` - User interface and diagnostics.
-- `src/modules/` - Tool implementations (ripgrep, difftastic, git).
+AGPL-3.0-only. See [LICENSE](https://github.com/Facta-Dev/ctx0_nest_terminal/blob/main/LICENSE) in the repository.
 
-## Related docs
+## Links
 
-- `../hub/README.md`
-- `../web/README.md`
+- [Server and setup](https://github.com/Facta-Dev/ctx0_nest_terminal)
+- [Web app](https://github.com/Facta-Dev/ctx0_nest_terminal)
+- [Issues](https://github.com/Facta-Dev/ctx0_nest_terminal/issues)

package/bin/nest.cjs

@@ -1,46 +1,30 @@
 #!/usr/bin/env node
 
-const { execFileSync } = require('child_process');
+const { execFileSync, execSync } = require('child_process');
 const path = require('path');
+const fs = require('fs');
 
 const platform = process.platform;
 const arch = process.arch;
-const RELEASE_URL = 'https://github.com/ctx0/nest/releases';
-const OFFICIAL_NPM_REGISTRY = 'https://registry.npmjs.org';
+const RELEASE_URL = 'https://github.com/Facta-Dev/ctx0_nest/releases';
 const SUPPORTED_PLATFORMS = [
-    {
-        key: 'darwin-arm64',
-        label: 'darwin-arm64 (macOS Apple Silicon)',
-    },
-    {
-        key: 'darwin-x64',
-        label: 'darwin-x64 (macOS Intel)',
-    },
-    {
-        key: 'linux-arm64',
-        label: 'linux-arm64',
-    },
-    {
-        key: 'linux-x64',
-        label: 'linux-x64',
-    },
-    {
-        key: 'win32-x64',
-        label: 'win32-x64',
-    },
+    { key: 'darwin-arm64', label: 'darwin-arm64 (macOS Apple Silicon)' },
+    { key: 'darwin-x64', label: 'darwin-x64 (macOS Intel)' },
+    { key: 'linux-arm64', label: 'linux-arm64' },
+    { key: 'linux-x64', label: 'linux-x64' },
+    { key: 'win32-x64', label: 'win32-x64' },
 ];
 
-function getPlatformKey(platformName = platform, archName = arch) {
-    return `${platformName}-${archName}`;
+function getPlatformKey(p = platform, a = arch) {
+    return `${p}-${a}`;
 }
 
-function isSupportedPlatform(platformName = platform, archName = arch) {
-    return SUPPORTED_PLATFORMS.some((item) => item.key === getPlatformKey(platformName, archName));
+function isSupportedPlatform(p = platform, a = arch) {
+    return SUPPORTED_PLATFORMS.some(item => item.key === getPlatformKey(p, a));
 }
 
 function getBinaryPath(platformName = platform, archName = arch) {
     const pkgName = `@factadev/cli-${platformName}-${archName}`;
-
     try {
         const pkgPath = require.resolve(`${pkgName}/package.json`);
         const binName = platformName === 'win32' ? 'nest.exe' : 'nest';
@@ -50,6 +34,38 @@ function getBinaryPath(platformName = platform, archName = arch) {
     }
 }
 
+function installPlatformPackage(platformName = platform, archName = arch) {
+    const pkgName = `@factadev/cli-${platformName}-${archName}`;
+    console.log(`Installing ${pkgName}...`);
+    try {
+        execSync(`npm install -g ${pkgName}`, { stdio: 'inherit' });
+        return true;
+    } catch (e) {
+        return false;
+    }
+}
+
+function getInstalledVersion(platformName = platform, archName = arch) {
+    const pkgName = `@factadev/cli-${platformName}-${archName}`;
+    try {
+        const pkgPath = require.resolve(`${pkgName}/package.json`);
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        return pkg.version;
+    } catch (e) {
+        return null;
+    }
+}
+
+function getLatestVersion(platformName = platform, archName = arch) {
+    const pkgName = `@factadev/cli-${platformName}-${archName}`;
+    try {
+        const result = execSync(`npm view ${pkgName} version`, { encoding: 'utf8' });
+        return result.trim();
+    } catch (e) {
+        return null;
+    }
+}
+
 function getBunPath() {
     const bunPaths = [
         path.join(__dirname, '..', 'node_modules', '.bin', 'bun'),
@@ -58,124 +74,56 @@ function getBunPath() {
         '/usr/local/bin/bun',
         '/opt/homebrew/bin/bun',
     ];
-
     for (const p of bunPaths) {
-        try {
-            require('fs').accessSync(p, require('fs').constants.X_OK);
-            return p;
-        } catch {}
+        try { fs.accessSync(p, fs.constants.X_OK); return p; } catch {}
     }
-
     return 'bun';
 }
 
-function formatCommand(binPath, args) {
-    return [binPath, ...args].map((arg) => JSON.stringify(String(arg))).join(' ');
-}
-
-function normalizeExecError(error) {
-    return {
-        status: typeof error?.status === 'number' ? error.status : null,
-        signal: typeof error?.signal === 'string' ? error.signal : null,
-        message: error?.message ? String(error.message) : null,
-    };
-}
-
-function reportExecutionFailure(error, binPath, args, log = console.error) {
-    const { status, signal, message } = normalizeExecError(error);
-
-    log(`Failed to execute: ${formatCommand(binPath, args)}`);
-
-    if (signal) {
-        log(`Binary terminated by signal ${signal}.`);
-    }
-
-    if (status !== null) {
-        log(`Binary exited with status ${status}.`);
-    }
-
-    if (message) {
-        log(message);
-    }
-
-    return { status, signal };
-}
-
-function reportUnsupportedPlatform(platformName = platform, archName = arch, log = console.error) {
-    log(`Unsupported platform: ${platformName}-${archName}`);
-    log('');
-    log('Supported platforms:');
-    for (const item of SUPPORTED_PLATFORMS) {
-        log(`  - ${item.label}`);
-    }
-    log('');
-    log('You can download the binary manually from:');
-    log(`  ${RELEASE_URL}`);
-}
-
-function reportMissingPlatformPackage(platformName = platform, archName = arch, log = console.error) {
-    const platformPackage = `@factadev/cli-${platformName}-${archName}`;
-    log(`Missing platform package: ${platformPackage}`);
-    log('');
-    log(`Detected platform ${platformName}-${archName} is supported, but the platform binary package was not installed.`);
-    log('The CLI will attempt to fall back to using bun to run directly.');
-    log('');
-    log('To ensure fastest startup, try reinstalling with the official npm registry:');
-    log(`  npm install -g @factadev/cli --registry=${OFFICIAL_NPM_REGISTRY}`);
-    log('');
-    log('Or install bun and the CLI will use it as fallback:');
-    log('  curl -fsSL https://bun.sh/install | bash');
-    log('');
-    log('You can also download binaries manually from:');
-    log(`  ${RELEASE_URL}`);
-}
-
 function main() {
     if (!isSupportedPlatform()) {
-        reportUnsupportedPlatform();
+        console.error(`Unsupported platform: ${platform}-${arch}`);
         process.exit(1);
     }
 
+    const platformKey = getPlatformKey();
     let binPath = getBinaryPath();
-    let useBun = !binPath;
 
-    if (useBun) {
+    // Check if platform package needs update or install
+    if (!binPath) {
+        console.log('No platform binary found. Installing...');
+        installPlatformPackage();
+        binPath = getBinaryPath();
+    } else {
+        // Check version and update if needed
+        const currentVer = getInstalledVersion();
+        const latestVer = getLatestVersion();
+        if (currentVer && latestVer && currentVer !== latestVer) {
+            console.log(`Updating from v${currentVer} to v${latestVer}...`);
+            installPlatformPackage();
+            binPath = getBinaryPath();
+        }
+    }
+
+    // Fallback to bun if no binary
+    if (!binPath) {
         const bunPath = getBunPath();
         const cliPath = path.join(__dirname, '..', 'src', 'index.ts');
-        console.log('No pre-built binary for this platform. Using bun to run CLI...\n');
-
+        console.log('No pre-built binary. Using bun...\n');
         try {
-            execFileSync(bunPath, [cliPath, ...process.argv.slice(2)], {
-                stdio: 'inherit',
-                env: {
-                    ...process.env,
-                    npm_lifecycle_event: 'nest',
-                    npm_package_name: '@factadev/cli',
-                },
-            });
+            execFileSync(bunPath, [cliPath, ...process.argv.slice(2)], { stdio: 'inherit' });
             return;
         } catch (error) {
             console.error(`Failed to run with bun: ${error.message}`);
-            console.error('\nPlease install bun:');
-            console.error('  curl -fsSL https://bun.sh/install | bash');
             process.exit(1);
         }
     }
 
-    const args = process.argv.slice(2);
-
+    // Run the binary
     try {
-        execFileSync(binPath, args, {
-            stdio: 'inherit',
-            env: {
-                ...process.env,
-                npm_lifecycle_event: 'nest',
-                npm_package_name: '@factadev/cli',
-            },
-        });
+        execFileSync(binPath, process.argv.slice(2), { stdio: 'inherit' });
     } catch (error) {
-        const { status, signal } = reportExecutionFailure(error, binPath, args);
-        process.exit(status ?? (signal ? 1 : 1));
+        process.exit(error.status || 1);
     }
 }
 

package/package.json

@@ -1,9 +1,22 @@
 {
   "name": "@factadev/cli",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "NEST CLI - Enterprise AI coding agent control center. Run Claude Code, Codex, Cursor, Gemini, OpenCode locally and control remotely via web.",
   "author": "Carlos Matias Baglieri",
-  "license": "UNLICENSED",
+  "license": "AGPL-3.0-only",
+  "keywords": [
+    "nest",
+    "claude",
+    "codex",
+    "cursor",
+    "gemini",
+    "opencode",
+    "ai",
+    "coding",
+    "agent",
+    "remote",
+    "cli"
+  ],
   "type": "module",
   "homepage": "https://github.com/Facta-Dev/ctx0_nest_terminal",
   "bugs": "https://github.com/Facta-Dev/ctx0_nest_terminal/issues",
@@ -77,10 +90,10 @@
   },
   "packageManager": "bun@1.3.5",
   "optionalDependencies": {
-    "@factadev/cli-darwin-arm64": "0.2.6",
-    "@factadev/cli-darwin-x64": "0.2.6",
-    "@factadev/cli-linux-arm64": "0.2.6",
-    "@factadev/cli-linux-x64": "0.2.6",
-    "@factadev/cli-win32-x64": "0.2.6"
+    "@factadev/cli-darwin-arm64": "0.2.8",
+    "@factadev/cli-darwin-x64": "0.2.8",
+    "@factadev/cli-linux-arm64": "0.2.8",
+    "@factadev/cli-linux-x64": "0.2.8",
+    "@factadev/cli-win32-x64": "0.2.8"
   }
 }