nstantpage-agent 0.3.4 → 0.4.0

package/dist/commands/start.d.ts

@@ -8,12 +8,12 @@
  * 4. Start local API server (handles /live/* requests for file sync, checks, etc.)
  * 5. Start local dev server (Vite/Next.js — runs project on user's machine)
  * 6. Connect tunnel to gateway (relays requests from cloud to local machine)
+ * 7. Register device with backend (track connected devices)
  *
- * The agent fully replaces Docker containers:
- * - Files are on the user's disk (no docker cp needed)
- * - Dev server runs natively (no container overhead)
- * - Type checking runs locally (full IDE speed)
- * - Package installation uses local npm/pnpm
+ * Multi-project support:
+ * - Each project gets its own PID file and port allocation
+ * - Cleanup only kills the agent for the SAME project
+ * - Ports are auto-assigned per project (based on hash) to avoid collisions
  */
 interface StartOptions {
     port: string;

package/dist/commands/start.js

@@ -8,23 +8,23 @@
  * 4. Start local API server (handles /live/* requests for file sync, checks, etc.)
  * 5. Start local dev server (Vite/Next.js — runs project on user's machine)
  * 6. Connect tunnel to gateway (relays requests from cloud to local machine)
+ * 7. Register device with backend (track connected devices)
  *
- * The agent fully replaces Docker containers:
- * - Files are on the user's disk (no docker cp needed)
- * - Dev server runs natively (no container overhead)
- * - Type checking runs locally (full IDE speed)
- * - Package installation uses local npm/pnpm
+ * Multi-project support:
+ * - Each project gets its own PID file and port allocation
+ * - Cleanup only kills the agent for the SAME project
+ * - Ports are auto-assigned per project (based on hash) to avoid collisions
  */
 import chalk from 'chalk';
 import path from 'path';
 import fs from 'fs';
 import os from 'os';
 import { execSync } from 'child_process';
-import { getConfig } from '../config.js';
+import { getConfig, getProjectConfig, setProjectConfig, clearProjectConfig, getDeviceId, allocatePortsForProject } from '../config.js';
 import { TunnelClient } from '../tunnel.js';
 import { LocalServer } from '../localServer.js';
 import { PackageInstaller } from '../packageInstaller.js';
-const VERSION = '0.3.0';
+const VERSION = '0.4.0';
 /**
  * Resolve the backend API base URL.
  * - If --backend is passed, use it
@@ -127,24 +127,36 @@ function killPort(port) {
     }
 }
 /**
- * Clean up any previous agent instance (kill old PID + free ports).
+ * Clean up any previous agent instance for THIS PROJECT ONLY.
+ * Uses per-project config instead of global config so multiple projects can coexist.
  */
-function cleanupPreviousAgent(conf, apiPort, devPort) {
-    // 1. Try to kill the previously stored agent PID
-    const oldPid = conf.get('agentPid');
+function cleanupPreviousAgent(projectId, apiPort, devPort) {
+    const projectConf = getProjectConfig(projectId);
+    // 1. Try to kill the previously stored agent PID for this project
+    const oldPid = projectConf.pid;
     if (oldPid && oldPid !== process.pid) {
         try {
             process.kill(oldPid, 'SIGTERM');
-            console.log(chalk.gray(`  Stopped previous agent (PID ${oldPid})`));
+            console.log(chalk.gray(`  Stopped previous agent for project ${projectId} (PID ${oldPid})`));
         }
         catch {
             // Already dead
         }
-        conf.delete('agentPid');
     }
-    // 2. Free the ports in case orphaned processes are still holding them
-    killPort(apiPort);
-    killPort(devPort);
+    // 2. Free the ports that THIS project was using
+    const oldApiPort = projectConf.apiPort;
+    const oldDevPort = projectConf.devPort;
+    if (oldApiPort)
+        killPort(oldApiPort);
+    if (oldDevPort)
+        killPort(oldDevPort);
+    // 3. Also free the requested ports (in case they changed)
+    if (apiPort !== oldApiPort)
+        killPort(apiPort);
+    if (devPort !== oldDevPort)
+        killPort(devPort);
+    // 4. Clear stale project config
+    clearProjectConfig(projectId);
 }
 export async function startCommand(directory, options) {
     const conf = getConfig();
@@ -153,7 +165,6 @@ export async function startCommand(directory, options) {
         conf.set('token', options.token);
     }
     // Check authentication
-    // Allow unauthenticated connections to local gateways (ws://localhost, ws://127.0.0.1)
     const isLocalGateway = /^wss?:\/\/(localhost|127\.0\.0\.1)/.test(options.gateway);
     let token = conf.get('token');
     if (!token && !isLocalGateway) {
@@ -164,8 +175,6 @@ export async function startCommand(directory, options) {
     if (!token && isLocalGateway) {
         token = 'local-dev';
     }
-    const devPort = parseInt(options.port, 10);
-    const apiPort = parseInt(options.apiPort, 10);
     // Determine project ID
     let projectId = options.projectId || conf.get('projectId');
     if (!projectId) {
@@ -174,6 +183,22 @@ export async function startCommand(directory, options) {
         console.log(chalk.gray('  Example: npx nstantpage-agent start --project-id 1234'));
         process.exit(1);
     }
+    // Auto-assign ports per project (unless user explicitly specified them)
+    const userSpecifiedPort = options.port !== '3000';
+    const userSpecifiedApiPort = options.apiPort !== '18924';
+    let devPort;
+    let apiPort;
+    if (userSpecifiedPort || userSpecifiedApiPort) {
+        // User explicitly chose ports — respect their choice
+        devPort = parseInt(options.port, 10);
+        apiPort = parseInt(options.apiPort, 10);
+    }
+    else {
+        // Auto-allocate unique ports per project
+        const allocated = allocatePortsForProject(projectId);
+        devPort = allocated.devPort;
+        apiPort = allocated.apiPort;
+    }
     // Resolve project directory
     const projectDir = resolveProjectDir(directory, projectId, options.dir);
     // Create directory if it doesn't exist
@@ -183,12 +208,14 @@ export async function startCommand(directory, options) {
     // Save project ID
     conf.set('projectId', projectId);
     const backendUrl = resolveBackendUrl(options);
-    // Kill any leftover agent / free ports from a previous run
-    cleanupPreviousAgent(conf, apiPort, devPort);
+    const deviceId = getDeviceId();
+    // Kill any leftover agent for THIS PROJECT only (not other projects)
+    cleanupPreviousAgent(projectId, apiPort, devPort);
     // Small delay to let ports release
     await new Promise(r => setTimeout(r, 300));
     console.log(chalk.blue(`\n🚀 nstantpage agent v${VERSION}\n`));
     console.log(chalk.gray(`  Project ID:   ${projectId}`));
+    console.log(chalk.gray(`  Device ID:    ${deviceId.slice(0, 12)}...`));
     console.log(chalk.gray(`  Directory:    ${projectDir}`));
     console.log(chalk.gray(`  Dev server:   port ${devPort}`));
     console.log(chalk.gray(`  API server:   port ${apiPort}`));
@@ -219,7 +246,6 @@ export async function startCommand(directory, options) {
     catch (err) {
         console.log(chalk.yellow(`  ⚠ Could not fetch project files: ${err.message}`));
         console.log(chalk.gray('    Continuing with existing local files (if any)...'));
-        // Don't exit — maybe local files exist from a previous run
         if (!fs.existsSync(path.join(projectDir, 'package.json'))) {
             console.log(chalk.red(`\n✗ No package.json found and cannot fetch files from backend.`));
             console.log(chalk.gray('  Check your project ID and authentication.'));
@@ -246,18 +272,94 @@ export async function startCommand(directory, options) {
         apiPort,
         devPort,
     });
+    // 5. Register device with backend
+    let heartbeatInterval = null;
+    const registerDevice = async () => {
+        try {
+            const res = await fetch(`${backendUrl}/api/agent/register`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${token}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    deviceId,
+                    name: os.hostname(),
+                    hostname: os.hostname(),
+                    platform: `${os.platform()} ${os.arch()}`,
+                    agentVersion: VERSION,
+                    projectId: projectId,
+                    capabilities: ['file-sync', 'type-check', 'install', 'terminal', 'dev-server'],
+                }),
+            });
+            if (res.ok) {
+                console.log(chalk.green(`  ✓ Device registered with backend`));
+            }
+            else {
+                console.log(chalk.gray(`  ⚠ Device registration: ${res.status} (non-fatal)`));
+            }
+        }
+        catch (err) {
+            console.log(chalk.gray(`  ⚠ Could not register device: ${err.message} (non-fatal)`));
+        }
+    };
+    const startHeartbeat = () => {
+        heartbeatInterval = setInterval(async () => {
+            try {
+                await fetch(`${backendUrl}/api/agent/heartbeat`, {
+                    method: 'POST',
+                    headers: {
+                        'Authorization': `Bearer ${token}`,
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        deviceId,
+                        activeProjectIds: [projectId],
+                        agentVersion: VERSION,
+                    }),
+                });
+            }
+            catch {
+                // Heartbeat failure is non-fatal
+            }
+        }, 60_000); // Every 60s
+    };
+    const disconnectDevice = async () => {
+        try {
+            await fetch(`${backendUrl}/api/agent/disconnect`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${token}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ deviceId, projectId }),
+            });
+        }
+        catch {
+            // Best-effort
+        }
+    };
     // Handle graceful shutdown
     const shutdown = async () => {
         console.log(chalk.yellow('\n\n  Shutting down...\n'));
+        if (heartbeatInterval)
+            clearInterval(heartbeatInterval);
         tunnel.disconnect();
         await localServer.stop();
-        conf.delete('agentPid');
+        await disconnectDevice();
+        clearProjectConfig(projectId);
         process.exit(0);
     };
     process.on('SIGTERM', shutdown);
     process.on('SIGINT', shutdown);
-    // Store PID for "nstantpage stop"
-    conf.set('agentPid', process.pid);
+    // Store per-project PID and ports
+    setProjectConfig(projectId, {
+        pid: process.pid,
+        apiPort,
+        devPort,
+        startedAt: new Date().toISOString(),
+        deviceId,
+    });
     try {
         // Start local API server
         console.log(chalk.gray('  Starting local API server...'));
@@ -279,7 +381,9 @@ export async function startCommand(directory, options) {
         else {
             console.log(chalk.gray('  Dev server skipped (--no-dev)'));
         }
-        // Connect tunnel to gateway (non-fatal — dev server keeps running even if tunnel fails)
+        // Register device (non-blocking)
+        registerDevice().then(() => startHeartbeat());
+        // Connect tunnel to gateway (non-fatal)
         console.log(chalk.gray('  Connecting to gateway...'));
         let tunnelConnected = false;
         try {
@@ -291,7 +395,6 @@ export async function startCommand(directory, options) {
             console.log(chalk.yellow(`  ⚠ Tunnel connection failed: ${err.message || 'connection refused'}`));
             console.log(chalk.gray('    Local dev server is still running. Tunnel will retry in background.'));
             console.log(chalk.gray(`    Is the gateway running at ${options.gateway}?\n`));
-            // Start background reconnection
             tunnel.startBackgroundReconnect();
         }
         // Display status
@@ -308,6 +411,7 @@ export async function startCommand(directory, options) {
         console.log(chalk.white(`  │  Files:  ${projectDir}`));
         console.log(chalk.blue.bold(`  └──────────────────────────────────────────────┘\n`));
         console.log(chalk.gray(`  Mode: ${chalk.green('Agent')} (no containers needed)`));
+        console.log(chalk.gray(`  Device: ${os.hostname()} (${os.platform()} ${os.arch()})`));
         console.log(chalk.gray(`  All builds, checks, and previews run on this machine.`));
         console.log(chalk.gray(`  Press Ctrl+C to stop\n`));
         // Keep alive
@@ -316,7 +420,7 @@ export async function startCommand(directory, options) {
     catch (err) {
         console.error(chalk.red(`\n✗ Failed to start: ${err.message}`));
         await localServer.stop();
-        conf.delete('agentPid');
+        clearProjectConfig(projectId);
         process.exit(1);
     }
 }

package/dist/config.d.ts

@@ -1,5 +1,40 @@
 /**
  * Agent configuration store (persisted to disk)
+ *
+ * Two-tier config:
+ * 1. Global config: ~/.config/nstantpage-agent/config.json — shared settings (token, gateway)
+ * 2. Per-project config: ~/.nstantpage/projects/{projectId}/agent.json — PID, ports, etc.
+ *
+ * This allows running multiple agent instances (one per project) without conflicts.
  */
 import Conf from 'conf';
 export declare function getConfig(): Conf;
+export interface ProjectConfig {
+    pid?: number;
+    apiPort?: number;
+    devPort?: number;
+    startedAt?: string;
+    deviceId?: string;
+}
+export declare function getProjectConfig(projectId: string): ProjectConfig;
+export declare function setProjectConfig(projectId: string, config: ProjectConfig): void;
+export declare function clearProjectConfig(projectId: string): void;
+/**
+ * Generate a stable device ID for this machine.
+ * Based on hostname + username + platform → SHA256 hash.
+ * This allows the backend to recognize the same physical machine across restarts.
+ */
+export declare function getDeviceId(): string;
+/**
+ * Allocate a unique port range for a project.
+ * Uses the projectId to deterministically pick ports, avoiding conflicts
+ * when running multiple agents on the same machine.
+ *
+ * Port ranges:
+ *   API port: 18900 + (hash % 1000)  → range 18900-19899
+ *   Dev port: 3000 + (hash % 1000)   → range 3000-3999
+ */
+export declare function allocatePortsForProject(projectId: string): {
+    apiPort: number;
+    devPort: number;
+};

package/dist/config.js

@@ -1,7 +1,18 @@
 /**
  * Agent configuration store (persisted to disk)
+ *
+ * Two-tier config:
+ * 1. Global config: ~/.config/nstantpage-agent/config.json — shared settings (token, gateway)
+ * 2. Per-project config: ~/.nstantpage/projects/{projectId}/agent.json — PID, ports, etc.
+ *
+ * This allows running multiple agent instances (one per project) without conflicts.
  */
 import Conf from 'conf';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+// ── Global config (shared across all projects) ──────────────
 let _conf = null;
 export function getConfig() {
     if (!_conf) {
@@ -11,13 +22,90 @@ export function getConfig() {
                 token: { type: 'string', default: '' },
                 gatewayUrl: { type: 'string', default: 'wss://webprev.live' },
                 projectId: { type: 'string', default: '' },
+                // Legacy fields (kept for backward compat, but per-project config is preferred)
                 agentPid: { type: 'number' },
                 lastConnected: { type: 'string' },
                 devPort: { type: 'number', default: 3000 },
                 apiPort: { type: 'number', default: 18924 },
+                deviceId: { type: 'string', default: '' },
             },
         });
     }
     return _conf;
 }
+function projectConfigPath(projectId) {
+    return path.join(os.homedir(), '.nstantpage', 'projects', projectId, 'agent.json');
+}
+export function getProjectConfig(projectId) {
+    const configPath = projectConfigPath(projectId);
+    try {
+        if (fs.existsSync(configPath)) {
+            return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+    }
+    catch { }
+    return {};
+}
+export function setProjectConfig(projectId, config) {
+    const configPath = projectConfigPath(projectId);
+    const dir = path.dirname(configPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
+export function clearProjectConfig(projectId) {
+    const configPath = projectConfigPath(projectId);
+    try {
+        if (fs.existsSync(configPath)) {
+            fs.unlinkSync(configPath);
+        }
+    }
+    catch { }
+}
+// ── Device ID (stable per machine) ──────────────────────────
+let _deviceId = null;
+/**
+ * Generate a stable device ID for this machine.
+ * Based on hostname + username + platform → SHA256 hash.
+ * This allows the backend to recognize the same physical machine across restarts.
+ */
+export function getDeviceId() {
+    if (_deviceId)
+        return _deviceId;
+    // Check if we already stored a deviceId
+    const conf = getConfig();
+    const stored = conf.get('deviceId');
+    if (stored) {
+        _deviceId = stored;
+        return stored;
+    }
+    // Generate new stable ID
+    const raw = `${os.hostname()}|${os.userInfo().username}|${os.platform()}|${os.arch()}`;
+    _deviceId = crypto.createHash('sha256').update(raw).digest('hex').slice(0, 32);
+    conf.set('deviceId', _deviceId);
+    return _deviceId;
+}
+// ── Port allocation ─────────────────────────────────────────
+/**
+ * Allocate a unique port range for a project.
+ * Uses the projectId to deterministically pick ports, avoiding conflicts
+ * when running multiple agents on the same machine.
+ *
+ * Port ranges:
+ *   API port: 18900 + (hash % 1000)  → range 18900-19899
+ *   Dev port: 3000 + (hash % 1000)   → range 3000-3999
+ */
+export function allocatePortsForProject(projectId) {
+    // Simple hash of projectId for port offset
+    let hash = 0;
+    for (let i = 0; i < projectId.length; i++) {
+        hash = ((hash << 5) - hash + projectId.charCodeAt(i)) | 0;
+    }
+    const offset = Math.abs(hash) % 1000;
+    return {
+        apiPort: 18900 + offset,
+        devPort: 3000 + offset,
+    };
+}
 //# sourceMappingURL=config.js.map

package/dist/localServer.js

@@ -290,6 +290,8 @@ export class LocalServer {
     async handleContainerStatus(_req, res, _body, url) {
         this.json(res, {
             running: this.devServer.isRunning,
+            status: this.devServer.isRunning ? 'running' : 'stopped',
+            projectId: this.options.projectId,
             mode: 'agent',
             agentMode: true,
             hostname: os.hostname(),
@@ -298,32 +300,45 @@ export class LocalServer {
     }
     // ─── /live/container-stats ───────────────────────────────────
     async handleContainerStats(_req, res) {
-        const stats = this.devServer.getStats();
-        const totalMem = os.totalmem() / (1024 * 1024);
-        const freeMem = os.freemem() / (1024 * 1024);
+        const devStats = this.devServer.getStats();
+        const totalMemMb = Math.round(os.totalmem() / (1024 * 1024));
+        const freeMemMb = Math.round(os.freemem() / (1024 * 1024));
+        const usedMemMb = totalMemMb - freeMemMb;
+        const memPercent = totalMemMb > 0 ? Math.round((usedMemMb / totalMemMb) * 100) : 0;
+        // Return in the same format as the container stats (ContainerStatsSnapshot)
+        // so the frontend terminal panel can display it unchanged.
         this.json(res, {
             success: true,
+            running: this.devServer.isRunning,
             agentMode: true,
-            cpu: { percent: stats.cpuPercent, cores: os.cpus().length },
-            memory: {
-                usedMb: stats.memoryMb,
-                totalMb: Math.round(totalMem),
-                freeMb: Math.round(freeMem),
-                percent: totalMem > 0 ? Math.round((stats.memoryMb / totalMem) * 100) : 0,
+            stats: {
+                cpuPercent: devStats.cpuPercent,
+                memoryUsageBytes: usedMemMb * 1024 * 1024,
+                memoryLimitBytes: totalMemMb * 1024 * 1024,
+                memoryUsageMb: usedMemMb,
+                memoryLimitMb: totalMemMb,
+                memoryPercent: memPercent,
+                diskUsageMb: null,
+                diskUsageBytes: null,
+            },
+            agentInfo: {
+                hostname: os.hostname(),
+                platform: `${os.platform()} ${os.arch()}`,
+                cpuCores: os.cpus().length,
+                pid: devStats.pid,
+                uptime: this.devServer.uptime,
             },
-            pid: stats.pid,
-            uptime: this.devServer.uptime,
         });
     }
     // ─── /live/logs ──────────────────────────────────────────────
     async handleLogs(_req, res, _body, url) {
-        const limit = parseInt(url.searchParams.get('limit') || '100', 10);
+        const limit = parseInt(url.searchParams.get('limit') || url.searchParams.get('tail') || '100', 10);
         const logs = this.devServer.getLogs(limit);
         this.json(res, {
             success: true,
             logs: logs.map(l => ({
                 timestamp: new Date(l.timestamp).toISOString(),
-                type: l.type,
+                stream: l.type, // 'stdout' | 'stderr' — matches what the terminal panel expects
                 message: l.message,
                 source: 'frontend',
             })),

package/dist/tunnel.js

@@ -18,6 +18,7 @@
 import WebSocket from 'ws';
 import http from 'http';
 import os from 'os';
+import { getDeviceId } from './config.js';
 export class TunnelClient {
     ws = null;
     options;
@@ -55,12 +56,13 @@ export class TunnelClient {
                 clearTimeout(connectTimeout);
                 this.reconnectAttempts = 0;
                 this.connectedAt = Date.now();
-                // Send enhanced agent info with capabilities
+                // Send enhanced agent info with capabilities and deviceId
                 this.send({
                     type: 'agent-info',
-                    version: '0.3.2',
+                    version: '0.4.0',
                     hostname: os.hostname(),
                     platform: `${os.platform()} ${os.arch()}`,
+                    deviceId: getDeviceId(),
                     capabilities: [
                         'file-sync',
                         'type-check',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nstantpage-agent",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Local development agent for nstantpage.com — run your projects locally, preview in the cloud. Replaces cloud containers for faster builds.",
   "type": "module",
   "bin": {