lazy-gravity 0.0.2 → 0.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LazyGravity Project
+
+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.

package/README.md

@@ -0,0 +1,224 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/tokyoweb3/LazyGravity/main/docs/assets/LazyGravityBanner.png" alt="LazyGravity Banner" width="100%" />
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-0.0.1-blue?style=flat-square" alt="Version" />
+  <img src="https://img.shields.io/badge/node-18.x+-brightgreen?style=flat-square&logo=node.js" alt="Node.js" />
+  <img src="https://img.shields.io/badge/discord.js-14.x-5865F2?style=flat-square&logo=discord&logoColor=white" alt="discord.js" />
+  <img src="https://img.shields.io/badge/protocol-CDP%20%2F%20WebSocket-orange?style=flat-square" alt="CDP/WebSocket" />
+  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License" />
+</p>
+
+# LazyGravity
+
+**LazyGravity** is a local, secure Discord Bot that lets you remotely operate [Antigravity](https://antigravity.dev) on your home PC — from your smartphone's Discord app, anywhere.
+
+Send natural language instructions like "fix that bug" or "start designing the new feature" from your phone. Antigravity executes them locally on your home PC using its full resources, and reports results back to Discord.
+
+<p align="center">
+  <video src="https://github.com/user-attachments/assets/84eca973-59e8-4ffa-93e9-fba78ba72f74" width="100%" controls autoplay muted loop>
+    Your browser does not support the video tag.
+  </video>
+</p>
+
+
+## Quick Setup
+
+Runtime: **Node >= 18**.
+
+```bash
+npm install -g lazy-gravity
+lazy-gravity setup
+```
+
+The interactive wizard walks you through Discord bot creation, token setup, and workspace configuration. When done:
+
+```bash
+lazy-gravity open     # Launch Antigravity with CDP enabled
+lazy-gravity start    # Start the Discord bot
+```
+
+Or run directly without installing:
+
+```bash
+npx lazy-gravity
+```
+
+---
+
+## Features
+
+1. **Fully Local & Secure**
+   - **No external server or port exposure** — runs as a local process on your PC, communicating directly with Discord.
+   - **Whitelist access control**: only authorized Discord user IDs (`allowedUserIds`) can interact with the bot.
+   - **Secure credential management**: Bot tokens and API keys are stored locally (never in source code).
+   - **Path traversal prevention & resource protection**: sandboxed directory access and concurrent task limits prevent abuse.
+
+2. **Project Management (Channel-Directory Binding)**
+   - Use `/project` to bind a Discord channel to a local project directory via an interactive select menu with buttons.
+   - Messages sent in a bound channel are automatically forwarded to Antigravity with the correct project context.
+
+3. **Context-Aware Embed Replies**
+   - Results are delivered as rich Discord Embeds. Use Discord's Reply feature on any result to continue the conversation — the bot preserves full context (directory, task history) across reply chains.
+
+4. **Real-Time Progress Monitoring**
+   - Long-running Antigravity tasks report progress as a series of messages (delivery confirmed / planning / analysis / execution / implementation / final summary).
+
+5. **File Attachments & Context Parsing**
+   - Send images (screenshots, mockups) or text files via Discord — they are automatically forwarded to Antigravity as context.
+
+## Usage & Commands
+
+### Natural Language Messages
+Just type in any bound channel:
+> `refactor the components under src/components. Make the layout look like yesterday's screenshot` (with image attached)
+
+### Slash Commands
+
+- `📂 /project list` — Browse projects via select menu; selecting one auto-creates a category and session channel
+- `📂 /project create <name>` — Create a new project directory + Discord category/channel
+- `💬 /new` — Start a new Antigravity chat session in the current project
+- `💬 /chat` — Show current session info and list all sessions in the project
+- `⚙️ /model [name]` — Switch the LLM model (e.g. `gpt-4o`, `claude-3-opus`, `gemini-1.5-pro`)
+- `⚙️ /mode` — Switch execution mode via dropdown (`code`, `architect`, `ask`, etc.)
+- `📝 /template list` — Display registered templates with execute buttons
+- `📝 /template add <name> <prompt>` — Register a new prompt template
+- `📝 /template delete <name>` — Delete a template
+- `🛑 /stop` — Force-stop a running Antigravity task
+- `📸 /screenshot` — Capture and send Antigravity's current screen
+- `🔧 /status` — Show bot connection status, current mode, and active project
+- `✅ /autoaccept [on|off|status]` — Toggle auto-approval of file edit dialogs
+- `🧹 /cleanup [days]` — Scan and clean up inactive session channels (default: 7 days)
+- `❓ /help` — Display list of available commands
+
+### CLI Commands
+
+```bash
+lazy-gravity              # Auto: runs setup if unconfigured, otherwise starts the bot
+lazy-gravity setup        # Interactive setup wizard
+lazy-gravity open         # Open Antigravity with CDP (auto-selects available port)
+lazy-gravity start        # Start the Discord bot
+lazy-gravity doctor       # Check environment and dependencies
+lazy-gravity --version    # Show version
+lazy-gravity --help       # Show help
+```
+
+---
+
+## Setup (Detailed)
+
+### Option A: npm (Recommended)
+
+```bash
+npm install -g lazy-gravity
+lazy-gravity setup
+```
+
+The wizard guides you through 4 steps:
+
+1. **Discord Bot Token** — create a bot at the [Discord Developer Portal](https://discord.com/developers/applications), enable Privileged Gateway Intents (PRESENCE, SERVER MEMBERS, MESSAGE CONTENT), and copy the token. Client ID is extracted from the token automatically.
+2. **Guild (Server) ID** — for instant slash command registration (optional; press Enter to skip).
+3. **Allowed User IDs** — Discord users authorized to interact with the bot.
+4. **Workspace Directory** — parent directory where your coding projects live.
+
+Config is saved to `~/.lazy-gravity/config.json`.
+
+### Option B: From source
+
+```bash
+git clone https://github.com/tokyoweb3/LazyGravity.git
+cd LazyGravity
+npm install
+```
+
+Set up your `.env` file:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and fill in the required values:
+
+```env
+DISCORD_BOT_TOKEN=your_bot_token_here
+GUILD_ID=your_guild_id_here
+ALLOWED_USER_IDS=123456789,987654321
+WORKSPACE_BASE_DIR=~/Code
+```
+
+Then start the bot:
+
+```bash
+npm run start
+```
+
+Alternatively, you can build and use the CLI:
+
+```bash
+npm run build
+node dist/bin/cli.js setup    # or: node dist/bin/cli.js start
+```
+
+### Launch Antigravity with CDP
+
+LazyGravity connects to Antigravity via Chrome DevTools Protocol (CDP).
+You need to launch Antigravity with a remote debugging port enabled.
+
+```bash
+# Easiest way (auto-selects an available port):
+lazy-gravity open
+```
+
+If you cloned from source, you can also use the bundled launcher scripts (they auto-detect an available port from 9222–9666):
+
+#### macOS
+Double-click **`start_antigravity_mac.command`** in the repo root.
+
+- **First run**: if you get a permission error, run `chmod +x start_antigravity_mac.command` once in the terminal.
+
+#### Windows
+Double-click **`start_antigravity_win.bat`** in the repo root.
+
+- **If it doesn't launch**: the executable may not be in your PATH. Right-click the file, edit it, and replace `"Antigravity.exe"` with the full install path (e.g. `"%LOCALAPPDATA%\Programs\Antigravity\Antigravity.exe"`).
+
+> **Tip**: CDP ports are auto-scanned from candidates (9222, 9223, 9333, 9444, 9555, 9666).
+> Launch Antigravity first, then start the bot — it connects automatically.
+
+---
+
+## Troubleshooting
+
+If the bot is unresponsive or you've updated the code, restart it:
+
+1. **Stop the bot** — press `Ctrl + C` in the terminal, or:
+   ```bash
+   pkill -f "lazy-gravity"
+   ```
+2. **Restart**
+   ```bash
+   lazy-gravity start
+   # or, from source: npm run start
+   ```
+
+If Antigravity is restarted, the bot automatically attempts CDP reconnection. Sending a message triggers automatic project reconnection.
+
+Run `lazy-gravity doctor` to diagnose configuration and connectivity issues.
+
+---
+
+## How CDP Connection Works
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/tokyoweb3/LazyGravity/main/docs/images/architecture.svg" alt="LazyGravity Architecture" width="100%" />
+</p>
+
+1. The bot scans debug ports (default: 9222) and auto-detects the Antigravity target
+2. Connects via WebSocket to CDP (`Runtime.evaluate` for DOM operations)
+3. Injects messages into the chat input, monitors Antigravity responses, and captures screenshots
+
+**On disconnect**: automatically retries up to 3 times (`maxReconnectAttempts`). If all retries fail, an error notification is sent to Discord.
+
+## License
+
+[MIT](LICENSE)

package/dist/bin/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const commander_1 = require("commander");
+const package_json_1 = require("../../package.json");
+const start_1 = require("./commands/start");
+const doctor_1 = require("./commands/doctor");
+const setup_1 = require("./commands/setup");
+const open_1 = require("./commands/open");
+const configLoader_1 = require("../utils/configLoader");
+let commandRan = false;
+const markRan = (fn) => ((...args) => { commandRan = true; return fn(...args); });
+const program = new commander_1.Command()
+    .name('lazy-gravity')
+    .description('Control your AI coding assistant from Discord')
+    .version(package_json_1.version);
+program
+    .command('start')
+    .description('Start the Discord bot')
+    .action(markRan(start_1.startAction));
+program
+    .command('doctor')
+    .description('Check environment and dependencies')
+    .action(markRan(doctor_1.doctorAction));
+program
+    .command('setup')
+    .description('Interactive setup wizard')
+    .action(markRan(setup_1.setupAction));
+program
+    .command('open')
+    .description('Open Antigravity with CDP enabled (auto-selects available port)')
+    .action(markRan(open_1.openAction));
+program.parse();
+// Default behavior: if no subcommand was matched, decide what to run
+if (!commandRan) {
+    const hasConfig = configLoader_1.ConfigLoader.configExists();
+    const hasEnv = fs.existsSync(path.resolve(process.cwd(), '.env'));
+    if (!hasConfig && !hasEnv) {
+        (0, setup_1.setupAction)();
+    }
+    else {
+        (0, start_1.startAction)();
+    }
+}

package/dist/bin/commands/doctor.js

@@ -0,0 +1,156 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.doctorAction = doctorAction;
+const http = __importStar(require("http"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const cdpPorts_1 = require("../../utils/cdpPorts");
+const configLoader_1 = require("../../utils/configLoader");
+function checkPort(port) {
+    return new Promise((resolve) => {
+        const req = http.get(`http://127.0.0.1:${port}/json/list`, (res) => {
+            let data = '';
+            res.on('data', (chunk) => (data += chunk));
+            res.on('end', () => {
+                try {
+                    const parsed = JSON.parse(data);
+                    resolve(Array.isArray(parsed));
+                }
+                catch {
+                    resolve(false);
+                }
+            });
+        });
+        req.on('error', () => resolve(false));
+        req.setTimeout(2000, () => {
+            req.destroy();
+            resolve(false);
+        });
+    });
+}
+function checkEnvFile() {
+    const envPath = path.resolve(process.cwd(), '.env');
+    return { exists: fs.existsSync(envPath), path: envPath };
+}
+function checkRequiredEnvVars() {
+    const required = ['DISCORD_BOT_TOKEN', 'CLIENT_ID', 'ALLOWED_USER_IDS'];
+    return required.map((name) => ({
+        name,
+        set: Boolean(process.env[name]),
+    }));
+}
+async function doctorAction() {
+    console.log('lazy-gravity doctor\n');
+    let allOk = true;
+    // 1. Config directory check
+    const configDir = configLoader_1.ConfigLoader.getConfigDir();
+    if (fs.existsSync(configDir)) {
+        console.log(`  [OK] Config directory exists: ${configDir}`);
+    }
+    else {
+        console.log(`  [--] Config directory not found: ${configDir}`);
+        console.log('       Run: lazy-gravity setup  (optional if using .env)');
+    }
+    // 2. Config file check
+    const configFilePath = configLoader_1.ConfigLoader.getConfigFilePath();
+    if (configLoader_1.ConfigLoader.configExists()) {
+        console.log(`  [OK] Config file found: ${configFilePath}`);
+    }
+    else {
+        console.log(`  [--] Config file not found: ${configFilePath} (optional — .env fallback used)`);
+    }
+    // 3. .env file check
+    const env = checkEnvFile();
+    if (env.exists) {
+        // Load .env so subsequent checks can see the variables
+        require('dotenv').config({ path: env.path });
+        console.log(`  [OK] .env file found: ${env.path}`);
+    }
+    else {
+        if (!configLoader_1.ConfigLoader.configExists()) {
+            console.log(`  [!!] .env file not found: ${env.path}`);
+            allOk = false;
+        }
+        else {
+            console.log(`  [--] .env file not found: ${env.path} (not needed — config.json used)`);
+        }
+    }
+    // 4. Required environment variables (check both env and config.json sources)
+    const vars = checkRequiredEnvVars();
+    for (const v of vars) {
+        if (v.set) {
+            console.log(`  [OK] ${v.name} is set`);
+        }
+        else {
+            console.log(`  [!!] ${v.name} is NOT set`);
+            allOk = false;
+        }
+    }
+    // 5. CDP port check
+    console.log('\n  Checking CDP ports...');
+    let cdpOk = false;
+    for (const port of cdpPorts_1.CDP_PORTS) {
+        const alive = await checkPort(port);
+        if (alive) {
+            console.log(`  [OK] CDP port ${port} is responding`);
+            cdpOk = true;
+        }
+    }
+    if (!cdpOk) {
+        console.log('  [!!] No CDP ports responding');
+        console.log('       Run: open -a Antigravity --args --remote-debugging-port=9222');
+        allOk = false;
+    }
+    // 6. Node.js version check
+    const nodeVersion = process.versions.node;
+    const major = parseInt(nodeVersion.split('.')[0], 10);
+    if (major >= 18) {
+        console.log(`\n  [OK] Node.js ${nodeVersion}`);
+    }
+    else {
+        console.log(`\n  [!!] Node.js ${nodeVersion} (>= 18.0.0 required)`);
+        allOk = false;
+    }
+    // Summary
+    console.log('');
+    if (allOk) {
+        console.log('  All checks passed!');
+    }
+    else {
+        console.log('  Some checks failed. Please fix the issues above.');
+        process.exitCode = 1;
+    }
+}

package/dist/bin/commands/open.js

@@ -0,0 +1,145 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openAction = openAction;
+const net = __importStar(require("net"));
+const os = __importStar(require("os"));
+const child_process_1 = require("child_process");
+const cdpPorts_1 = require("../../utils/cdpPorts");
+const APP_NAME = 'Antigravity';
+const C = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    cyan: '\x1b[36m',
+    green: '\x1b[32m',
+    red: '\x1b[31m',
+};
+/**
+ * Check whether a TCP port is available (not in use) by attempting to listen on it.
+ */
+function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once('error', () => resolve(false));
+        server.once('listening', () => {
+            server.close(() => resolve(true));
+        });
+        server.listen(port, '127.0.0.1');
+    });
+}
+async function findAvailablePort() {
+    for (const port of cdpPorts_1.CDP_PORTS) {
+        if (await isPortAvailable(port)) {
+            return port;
+        }
+    }
+    return null;
+}
+function openMacOS(port) {
+    return new Promise((resolve, reject) => {
+        (0, child_process_1.execFile)('open', ['-a', APP_NAME, '--args', `--remote-debugging-port=${port}`], (err) => {
+            if (err) {
+                reject(new Error(`Failed to open ${APP_NAME}: ${err.message}`));
+                return;
+            }
+            resolve();
+        });
+    });
+}
+function openWindows(port) {
+    return new Promise((resolve, reject) => {
+        (0, child_process_1.execFile)(`${APP_NAME}.exe`, [`--remote-debugging-port=${port}`], { shell: true }, (err) => {
+            if (err) {
+                reject(new Error(`Failed to open ${APP_NAME}: ${err.message}`));
+                return;
+            }
+            resolve();
+        });
+    });
+}
+function openLinux(port) {
+    return new Promise((resolve, reject) => {
+        try {
+            const child = (0, child_process_1.spawn)(APP_NAME.toLowerCase(), [`--remote-debugging-port=${port}`], {
+                detached: true,
+                stdio: 'ignore',
+            });
+            child.unref();
+            child.on('error', (err) => {
+                reject(new Error(`Failed to open ${APP_NAME}: ${err.message}`));
+            });
+            // Give it a moment to detect spawn errors
+            setTimeout(() => resolve(), 500);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            reject(new Error(`Failed to open ${APP_NAME}: ${msg}`));
+        }
+    });
+}
+async function openAction() {
+    const platform = os.platform();
+    console.log(`\n  ${C.cyan}Searching for an available CDP port...${C.reset}`);
+    const port = await findAvailablePort();
+    if (port === null) {
+        console.log(`  ${C.red}No available CDP ports found.${C.reset}`);
+        console.log(`  ${C.dim}All candidate ports are in use: ${cdpPorts_1.CDP_PORTS.join(', ')}${C.reset}`);
+        console.log(`  ${C.dim}Close an application using one of these ports and try again.${C.reset}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`  ${C.green}Found available port: ${port}${C.reset}`);
+    console.log(`  ${C.dim}Opening ${APP_NAME} with --remote-debugging-port=${port}...${C.reset}\n`);
+    try {
+        if (platform === 'darwin') {
+            await openMacOS(port);
+        }
+        else if (platform === 'win32') {
+            await openWindows(port);
+        }
+        else {
+            await openLinux(port);
+        }
+        console.log(`  ${C.green}${APP_NAME} opened on CDP port ${port}${C.reset}`);
+        console.log(`  ${C.dim}Run ${C.reset}${C.cyan}lazy-gravity start${C.reset}${C.dim} to connect the bot.${C.reset}\n`);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.log(`  ${C.red}${msg}${C.reset}`);
+        console.log(`  ${C.dim}Make sure ${APP_NAME} is installed on your system.${C.reset}\n`);
+        process.exitCode = 1;
+    }
+}