@factadev/cli 0.2.2

package/LICENSE

@@ -0,0 +1,17 @@
+NEST Software License
+Copyright © 2026 Carlos Matias Baglieri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use the Software for personal or internal business purposes, subject to the following conditions:
+
+1. Restrictions
+No Modifications: The Software must be used exactly as provided. You may not alter, transform, or build upon this work.
+
+No Redistribution: You may not redistribute, sub-license, or sell the Software to third parties without express written authorization from the owner.
+
+Authorization: Any use case not explicitly covered by this license requires prior written consent. Please contact matias@facta.dev for authorization inquiries.
+
+2. Disclaimer of Warranty
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+3. Limitation of Liability
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS (CARLOS MATIAS BAGLIERI) BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OF THE SOFTWARE. THE USERS USE THIS SOFTWARE AT THEIR OWN RISK AND RESPONSIBILITY.

package/NOTICE

@@ -0,0 +1,52 @@
+nest CLI
+Copyright (c) 2024-2026 Carlos Matias Baglieri
+
+This software contains code derived from happy-cli
+(https://github.com/slopus/happy-cli), which is licensed
+under the MIT License:
+
+---
+
+MIT License
+
+Copyright (c) 2024 Kirill Dubovitskiy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The following files/directories are derived from happy-cli:
+- src/api/
+- src/claude/
+- src/codex/
+- src/runner/
+- src/commands/
+- src/ui/
+- src/utils/
+- src/modules/ripgrep/
+- src/modules/difftastic/
+- src/modules/watcher/
+- src/modules/common/registerCommonHandlers.ts
+- src/modules/common/pathSecurity.ts
+- src/parsers/
+- src/configuration.ts
+- src/persistence.ts
+- src/projectPath.ts
+- src/lib.ts
+- src/index.ts

package/README.md

@@ -0,0 +1,146 @@
+# nest CLI
+
+Run Claude Code, Codex, Cursor Agent, Gemini, or OpenCode sessions from your terminal and control them remotely through the NEST hub.
+
+## 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.
+
+## Typical flow
+
+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.
+
+## Commands
+
+### Session commands
+
+- `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.
+
+### Authentication
+
+- `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.
+
+See `src/commands/auth.ts`.
+
+### Runner management
+
+- `nest runner start` - Start runner as detached process.
+- `nest runner stop` - Stop runner gracefully.
+- `nest runner status` - Show runner diagnostics.
+- `nest runner list` - List active sessions managed by runner.
+- `nest runner stop-session <sessionId>` - Terminate specific session.
+- `nest runner logs` - Print path to latest runner log file.
+
+See `src/runner/run.ts`.
+
+### Diagnostics
+
+- `nest doctor` - Show full diagnostics (version, runner status, logs, processes).
+- `nest doctor clean` - Kill runaway NEST processes.
+
+See `src/ui/doctor.ts`.
+
+### Other
+
+- `nest mcp` - Start MCP stdio bridge. See `src/codex/happyMcpStdioBridge.ts`.
+- `nest hub` - Start the bundled hub (single binary workflow).
+- `nest server` - Alias for `nest hub`.
+
+## Configuration
+
+See `src/configuration.ts` for all options.
+
+### Required
+
+- `CLI_API_TOKEN` - Shared secret; must match the hub. Can be set via env or `~/.nest/settings.json` (env wins).
+- `NEST_API_URL` - Hub base URL (default: http://localhost:3006).
+
+### 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`.
+
+### Runner
+
+- `NEST_RUNNER_HEARTBEAT_INTERVAL` - Heartbeat interval in ms (default: 60000).
+- `NEST_RUNNER_HTTP_TIMEOUT` - HTTP timeout for runner control in ms (default: 10000).
+
+### Worktree (set by runner)
+
+- `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).
+
+## Storage
+
+Data is stored in `~/.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.
+
+## 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
+```
+
+## Source structure
+
+- `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).
+
+## Related docs
+
+- `../hub/README.md`
+- `../web/README.md`

package/bin/nest.cjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+
+const { execFileSync } = require('child_process');
+const path = require('path');
+
+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 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',
+    },
+];
+
+function getPlatformKey(platformName = platform, archName = arch) {
+    return `${platformName}-${archName}`;
+}
+
+function isSupportedPlatform(platformName = platform, archName = arch) {
+    return SUPPORTED_PLATFORMS.some((item) => item.key === getPlatformKey(platformName, archName));
+}
+
+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';
+        return path.join(path.dirname(pkgPath), 'bin', binName);
+    } catch (e) {
+        return null;
+    }
+}
+
+function getBunPath() {
+    const bunPaths = [
+        path.join(__dirname, '..', 'node_modules', '.bin', 'bun'),
+        path.join(process.env.HOME || '', '.bun', 'bin', 'bun'),
+        path.join(process.env.APPDATA || '', 'bun', 'bin', 'bun.exe'),
+        '/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 {}
+    }
+
+    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();
+        process.exit(1);
+    }
+
+    let binPath = getBinaryPath();
+    let useBun = !binPath;
+
+    if (useBun) {
+        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');
+
+        try {
+            execFileSync(bunPath, [cliPath, ...process.argv.slice(2)], {
+                stdio: 'inherit',
+                env: {
+                    ...process.env,
+                    npm_lifecycle_event: 'nest',
+                    npm_package_name: '@factadev/cli',
+                },
+            });
+            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);
+
+    try {
+        execFileSync(binPath, args, {
+            stdio: 'inherit',
+            env: {
+                ...process.env,
+                npm_lifecycle_event: 'nest',
+                npm_package_name: '@factadev/cli',
+            },
+        });
+    } catch (error) {
+        const { status, signal } = reportExecutionFailure(error, binPath, args);
+        process.exit(status ?? (signal ? 1 : 1));
+    }
+}
+
+main();

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@factadev/cli",
+  "version": "0.2.2",
+  "description": "NEST CLI - Run AI coding agents and control them remotely",
+  "author": "Carlos Matias Baglieri",
+  "license": "UNLICENSED",
+  "type": "module",
+  "homepage": "https://github.com/ctx0/nest",
+  "bugs": "https://github.com/ctx0/nest/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ctx0/nest.git",
+    "directory": "cli"
+  },
+  "bin": {
+    "nest": "bin/nest.cjs"
+  },
+  "files": [
+    "bin/nest.cjs",
+    "NOTICE"
+  ],
+  "imports": {
+    "#embedded-assets": {
+      "bun": "./src/runtime/embeddedAssets.bun.ts",
+      "default": "./src/runtime/embeddedAssets.stub.ts"
+    }
+  },
+  "dependencies": {
+    "@factadev/protocol": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "@types/cross-spawn": "^6.0.6",
+    "@types/ps-list": "^6.2.1",
+    "@types/react": "^19.2.7",
+    "axios": "^1.13.2",
+    "chalk": "^5.6.2",
+    "cross-spawn": "^7.0.6",
+    "fastify": "^5.6.2",
+    "fastify-type-provider-zod": "6.1.0",
+    "ink": "^6.6.0",
+    "ps-list": "^9.0.0",
+    "react": "^19.2.3",
+    "socket.io-client": "^4.8.3",
+    "tar": "^7.5.2",
+    "yaml": "^2.8.2",
+    "zod": "^4.2.1"
+  },
+  "scripts": {
+    "postinstall": "node -e \"try{require('fs').chmodSync(require('path').join(__dirname,'bin','nest.cjs'),0o755)}catch(e){}\"",
+    "typecheck": "tsc --noEmit",
+    "build:exe": "bun run scripts/build-executable.ts",
+    "build:exe:all": "bun run scripts/build-executable.ts --all",
+    "build:exe:allinone": "bun run scripts/build-executable.ts --with-web-assets",
+    "build:exe:allinone:all": "bun run scripts/build-executable.ts --with-web-assets --all",
+    "prepare-npm-packages": "bun run scripts/prepare-npm-packages.ts",
+    "prepack": "bun run prepare-npm-packages",
+    "tools:unpack": "bun run scripts/unpack-tools.ts",
+    "update-homebrew-formula": "bun run scripts/update-homebrew-formula.ts",
+    "test": "bun run tools:unpack && vitest run",
+    "test:win": "vitest run",
+    "publish": "bash scripts/publish.sh",
+    "dev": "bun src/index.ts",
+    "dev:local-server": "bun --env-file .env.dev-local-server src/index.ts",
+    "dev:integration-test-env": "bun --env-file .env.integration-test src/index.ts",
+    "release-all": "bun run scripts/release-all.ts"
+  },
+  "devDependencies": {
+    "@types/node": ">=25",
+    "bun-types": "^1.3.5",
+    "dotenv": "^17.2.3",
+    "typescript": "^5",
+    "vitest": "^4.0.16"
+  },
+  "resolutions": {
+    "whatwg-url": "14.2.0",
+    "parse-path": "7.0.3",
+    "@types/parse-path": "7.0.3"
+  },
+  "packageManager": "bun@1.3.5",
+  "optionalDependencies": {
+    "@factadev/cli-darwin-arm64": "0.2.2",
+    "@factadev/cli-darwin-x64": "0.2.2",
+    "@factadev/cli-linux-arm64": "0.2.2",
+    "@factadev/cli-linux-x64": "0.2.2",
+    "@factadev/cli-win32-x64": "0.2.2"
+  }
+}