ai-agent-command-center 1.0.0 → 1.0.1

package/README.md

@@ -14,6 +14,8 @@
 
 ### *Next-Generation Spatial 3D/2D Orchestration Bridge & Autonomous Multi-Agent Swarm OS*
 
+[![NPM Version](https://img.shields.io/npm/v/ai-agent-command-center.svg?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/ai-agent-command-center)
+[![NPM Unpacked Size](https://img.shields.io/badge/unpacked%20size-2.2%20MB-blue?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/ai-agent-command-center)
 [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/NexGen-X/Ai-Center-Workspace/ci.yml?branch=main&label=CI%20Quality%20Gate&logo=github&style=for-the-badge)](https://github.com/NexGen-X/Ai-Center-Workspace/actions)
 [![Tests Passing](https://img.shields.io/badge/TESTS-209%20PASSED%20%2F%20100%25-00FF66?style=for-the-badge&logo=vitest&logoColor=white)](https://github.com/NexGen-X/Ai-Center-Workspace/actions)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.4.5-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
@@ -203,9 +205,60 @@ Security is not an afterthought in AI Command Center — it is baked into every
 
 ---
 
-## 🚀 Quickstart & Local Development
+## 🚀 Quickstart
 
-### Prerequisites
+### Method 1: Instant Zero-Install Run (Recommended)
+Run the complete Command Bridge in seconds without manually cloning or configuring dependencies:
+
+```bash
+# Instant launch (auto-provisions & opens browser on local machine)
+npx ai-agent-command-center
+
+# With custom port and database connection
+npx ai-agent-command-center --port 8080 --db "postgres://user:pass@localhost:5432/ai_center"
+```
+
+### Method 2: Global CLI Installation
+```bash
+# Install globally
+npm install -g ai-agent-command-center
+
+# Launch the Command Center
+ai-center start
+
+# View all CLI options
+ai-center --help
+```
+
+### 🧭 Intelligent Deployment Environment Auto-Detection
+`ai-agent-command-center` features built-in environment perception to seamlessly adapt between local workstations and headless cloud servers:
+
+| Target Environment | Detection Criteria | Startup Behavior |
+| :--- | :--- | :--- |
+| **Local Desktop / Laptop** | Windows, macOS, or Linux with active `$DISPLAY` / `$WAYLAND_DISPLAY` | Prints `http://localhost:3000` and **automatically opens default browser** within 1.5s. |
+| **Remote Server / Headless VPS** | Headless Linux (AWS EC2, DigitalOcean, VPS, Docker container) | **Suppresses browser invocation** (prevents X11 errors), binds Express to `0.0.0.0`, and outputs LAN & Public access URLs. |
+
+```text
+✔ AI Agent Command Center aktif & siap melayani:
+  ➜  Local:   http://localhost:3000
+  ➜  Network: http://192.168.1.50:3000
+  ➜  Mode:    Remote Server / VPS (Headless — browser lokal dinonaktifkan)
+```
+
+### CLI Command & Flags Reference
+| Flag | Alias | Description | Default |
+| :--- | :---: | :--- | :--- |
+| `--port <num>` | `-p` | Port for the backend API and frontend static server | `3000` or `$PORT` |
+| `--db <url>` | `-d` | PostgreSQL connection URL with pgvector support | `$DATABASE_URL` |
+| `--no-open` | | Do not launch the browser automatically on local desktop | `false` |
+| `--version` | `-v` | Print the current installed CLI version | `1.0.0` |
+| `--help` | `-h` | Display help guidelines and usage examples | |
+
+---
+
+### Method 3: Monorepo Developer Setup (From Source)
+
+#### Prerequisites
 - **Node.js**: `v20.x` or higher
 - **PostgreSQL**: `v16.x` with `pgvector` extension
 - **npm**: `v10.x` or higher
@@ -226,7 +279,7 @@ npm run dev:server
 # In a separate terminal:
 npm run dev:client
 ```
-Visit `http://localhost:5173` to access the Command Bridge.
+Visit `http://localhost:5173` to access the Vite HMR development server.
 
 ---
 

package/bin/ai-center.js

@@ -125,6 +125,22 @@ if (!process.env.DATABASE_URL) {
   console.log(`  npx ai-agent-command-center --db "postgres://user:pass@localhost:5432/ai_center"\x1b[0m\n`);
 }
 
+// Resolves external Public IP asynchronously for cloud VPS
+async function getPublicIp() {
+  try {
+    const res = await fetch('https://api.ipify.org?format=json', {
+      signal: AbortSignal.timeout(1200)
+    });
+    if (res.ok) {
+      const data = await res.json();
+      return data.ip;
+    }
+  } catch {
+    // Graceful silent fallback if offline or timeout
+  }
+  return null;
+}
+
 // Function to auto-open browser (strictly on local desktop with GUI display)
 function openBrowser(targetUrl) {
   if (noOpen || envInfo.isRemoteVPS) return;
@@ -157,25 +173,44 @@ async function launch() {
     await import(serverModulePath);
 
     console.log(`\n\x1b[1m\x1b[32m✔ AI Agent Command Center aktif & siap melayani:\x1b[0m`);
-    console.log(`  \x1b[36m➜\x1b[0m  \x1b[1mLocal:\x1b[0m   \x1b[4m${localUrl}\x1b[0m`);
+    console.log(`  \x1b[36m➜\x1b[0m  \x1b[1mLocal:\x1b[0m    \x1b[4m${localUrl}\x1b[0m`);
     
-    if (envInfo.networkIps.length > 0) {
-      envInfo.networkIps.forEach(ip => {
-        console.log(`  \x1b[36m➜\x1b[0m  \x1b[1mNetwork:\x1b[0m \x1b[4mhttp://${ip}:${port}\x1b[0m`);
-      });
-    }
-
     if (envInfo.isRemoteVPS) {
-      console.log(`  \x1b[33m➜\x1b[0m  \x1b[1mMode:\x1b[0m    Remote Server / VPS (Headless — browser lokal dinonaktifkan)`);
+      const publicIp = await getPublicIp();
+      if (publicIp) {
+        console.log(`  \x1b[36m➜\x1b[0m  \x1b[1mPublic:\x1b[0m   \x1b[4mhttp://${publicIp}:${port}\x1b[0m (Cloud VPS / Remote)`);
+      }
+      if (envInfo.networkIps.length > 0) {
+        envInfo.networkIps.forEach(ip => {
+          if (ip !== publicIp) {
+            console.log(`  \x1b[36m➜\x1b[0m  \x1b[1mInternal:\x1b[0m \x1b[4mhttp://${ip}:${port}\x1b[0m (VPC / LAN)`);
+          }
+        });
+      }
+      console.log(`  \x1b[33m➜\x1b[0m  \x1b[1mMode:\x1b[0m     Remote Server / VPS (Headless — browser lokal dinonaktifkan)`);
     } else {
-      console.log(`  \x1b[35m➜\x1b[0m  \x1b[1mMode:\x1b[0m    Local Desktop (Membuka browser otomatis...)`);
+      if (envInfo.networkIps.length > 0) {
+        envInfo.networkIps.forEach(ip => {
+          console.log(`  \x1b[36m➜\x1b[0m  \x1b[1mNetwork:\x1b[0m  \x1b[4mhttp://${ip}:${port}\x1b[0m`);
+        });
+      }
+      console.log(`  \x1b[35m➜\x1b[0m  \x1b[1mMode:\x1b[0m     Local Desktop (Membuka browser otomatis...)`);
       setTimeout(() => {
         openBrowser(localUrl);
       }, 1500);
     }
     console.log('');
   } catch (err) {
-    console.error(`\x1b[31m[AI Center Startup Error]\x1b[0m`, err);
+    if (err && (err.code === '28P01' || err.code === 'ECONNREFUSED' || err.message?.includes('password authentication failed'))) {
+      console.error(`\n\x1b[31m[AI Center Database Error] Gagal terhubung ke database PostgreSQL:\x1b[0m`);
+      console.error(`\x1b[33mDetail:\x1b[0m ${err.message}`);
+      console.error(`\n\x1b[36mPanduan Solusi:\x1b[0m`);
+      console.error(`  1. Pastikan PostgreSQL berjalan dan database sudah dibuat.`);
+      console.error(`  2. Pastikan username dan password di parameter --db atau DATABASE_URL benar.`);
+      console.error(`  3. Contoh: ai-center start --db "postgres://user:password@localhost:5432/ai_center"\n`);
+    } else {
+      console.error(`\x1b[31m[AI Center Startup Error]\x1b[0m`, err);
+    }
     process.exit(1);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-agent-command-center",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Next-Generation Spatial 3D/2D Orchestration Bridge & Autonomous Multi-Agent Swarm OS",
   "main": "server/dist/server/src/index.js",
   "type": "module",
@@ -37,7 +37,7 @@
     "dotenv": "^16.4.5",
     "express": "^4.19.2",
     "pg": "^8.13.0",
-    "uuid": "^9.0.1"
+    "uuid": "^14.0.3"
   },
   "repository": {
     "type": "git",

package/server/dist/server/src/index.js

@@ -235,7 +235,17 @@ process.on('unhandledRejection', (reason) => {
 // Auto-start if executed directly
 if (process.env.NODE_ENV !== 'test') {
     startServer().catch(err => {
-        console.error('Failed to start server:', err);
+        if (err && (err.code === '28P01' || err.code === 'ECONNREFUSED' || err.message?.includes('password authentication failed'))) {
+            console.error(`\n\x1b[31m[AI Center Error] Gagal terhubung ke basis data PostgreSQL:\x1b[0m`);
+            console.error(`\x1b[33mRincian:\x1b[0m ${err.message}`);
+            console.error(`\n\x1b[36mPanduan Perbaikan:\x1b[0m`);
+            console.error(`  1. Pastikan PostgreSQL berjalan dan database sudah dibuat.`);
+            console.error(`  2. Pastikan username dan password di DATABASE_URL sudah sesuai.`);
+            console.error(`  3. Contoh: DATABASE_URL="postgres://user:password@localhost:5432/ai_center" npx ai-agent-command-center\n`);
+        }
+        else {
+            console.error('Failed to start server:', err);
+        }
         process.exit(1);
     });
 }