nstantpage-agent 0.5.6 → 0.5.8

package/dist/cli.js

@@ -25,7 +25,7 @@ const program = new Command();
 program
     .name('nstantpage')
     .description('Local development agent for nstantpage.com — run projects on your machine, preview in the cloud')
-    .version('0.5.4');
+    .version('0.5.8');
 program
     .command('login')
     .description('Authenticate with nstantpage.com')

package/dist/commands/start.js

@@ -24,7 +24,7 @@ import { getConfig, getProjectConfig, setProjectConfig, clearProjectConfig, getD
 import { TunnelClient } from '../tunnel.js';
 import { LocalServer } from '../localServer.js';
 import { PackageInstaller } from '../packageInstaller.js';
-const VERSION = '0.5.6';
+const VERSION = '0.5.8';
 /**
  * Resolve the backend API base URL.
  * - If --backend is passed, use it
@@ -82,16 +82,29 @@ async function fetchProjectFiles(backendUrl, projectId, projectDir, token) {
         console.log(chalk.gray(`  Files up-to-date (version ${data.version})`));
         return { fileCount: data.files.length, isNew: false };
     }
-    // Write all files to disk
-    let written = 0;
+    // Write all files to disk in parallel (batch I/O for speed)
+    // First, collect unique directories to create
+    const dirsToCreate = new Set();
     for (const file of data.files) {
         const filePath = path.join(projectDir, file.path);
-        const dir = path.dirname(filePath);
+        dirsToCreate.add(path.dirname(filePath));
+    }
+    // Create all directories first (sync is fine, there are few unique dirs)
+    for (const dir of dirsToCreate) {
         if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true });
         }
-        fs.writeFileSync(filePath, file.content, 'utf-8');
-        written++;
+    }
+    // Write files in parallel batches of 50
+    const BATCH_SIZE = 50;
+    let written = 0;
+    for (let i = 0; i < data.files.length; i += BATCH_SIZE) {
+        const batch = data.files.slice(i, i + BATCH_SIZE);
+        await Promise.all(batch.map(async (file) => {
+            const filePath = path.join(projectDir, file.path);
+            await fs.promises.writeFile(filePath, file.content, 'utf-8');
+        }));
+        written += batch.length;
     }
     // Write version marker
     fs.writeFileSync(versionFile, String(data.versionId), 'utf-8');
@@ -215,8 +228,8 @@ export async function startCommand(directory, options) {
     conf.set('projectId', projectId);
     // 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));
+    // Brief pause for OS to release ports (50ms is sufficient on macOS/Linux)
+    await new Promise(r => setTimeout(r, 50));
     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)}...`));
@@ -558,57 +571,97 @@ async function startStandbyMode(token, options, backendUrl, deviceId) {
  */
 async function startAdditionalProject(projectId, opts) {
     const progress = opts.onProgress || (() => { });
+    const timings = {};
+    const t0 = Date.now();
     console.log(chalk.blue(`\n  📦 Starting project ${projectId}...`));
-    progress('fetching-files', 'Fetching project files...');
     try {
         const allocated = allocatePortsForProject(projectId);
         const projectDir = resolveProjectDir('.', projectId);
         if (!fs.existsSync(projectDir))
             fs.mkdirSync(projectDir, { recursive: true });
-        // Fetch project files
+        // Ensure ports are clear for this project before starting
+        cleanupPreviousAgent(projectId, allocated.apiPort, allocated.devPort);
+        await new Promise(r => setTimeout(r, 50));
+        // ── Phase 1: Fetch files + start API server in parallel ──────────
+        progress('fetching-files', 'Fetching project files...');
+        const localServer = new LocalServer({
+            projectDir, projectId,
+            apiPort: allocated.apiPort, devPort: allocated.devPort,
+        });
+        // Start API server immediately (doesn't need project files)
+        const apiServerPromise = localServer.start().then(() => {
+            timings['api-server'] = Date.now() - t0;
+            console.log(chalk.green(`  ✓ API server on port ${allocated.apiPort} (${timings['api-server']}ms)`));
+        });
+        // Fetch project files concurrently with API server start
+        const fileStart = Date.now();
         try {
             await fetchProjectFiles(opts.backendUrl, projectId, projectDir, opts.token);
-            progress('fetching-files', 'Project files downloaded');
+            timings['fetch-files'] = Date.now() - fileStart;
+            progress('fetching-files', `Files downloaded (${timings['fetch-files']}ms)`);
         }
         catch (err) {
             console.log(chalk.yellow(`  ⚠ Could not fetch files: ${err.message}`));
             progress('fetching-files', `Warning: ${err.message}`);
         }
-        // Install dependencies (must complete before dev server can start)
+        // Wait for API server before proceeding
+        await apiServerPromise;
+        progress('starting-server', `API server ready`);
+        // ── Phase 2: Install deps (if needed) ────────────────────────────
         const installer = new PackageInstaller({ projectDir });
-        if (!installer.areDependenciesInstalled() && fs.existsSync(path.join(projectDir, 'package.json'))) {
+        const needsInstall = !installer.areDependenciesInstalled() && fs.existsSync(path.join(projectDir, 'package.json'));
+        if (needsInstall) {
+            const installStart = Date.now();
             console.log(chalk.gray(`  Installing dependencies...`));
             progress('installing-deps', 'Installing npm dependencies...');
             try {
                 await installer.ensureDependencies();
-                console.log(chalk.green(`  ✓ Dependencies installed`));
-                progress('installing-deps', 'Dependencies installed');
+                timings['install'] = Date.now() - installStart;
+                console.log(chalk.green(`  ✓ Dependencies installed (${timings['install']}ms)`));
+                progress('installing-deps', `Dependencies installed (${timings['install']}ms)`);
             }
             catch (err) {
+                timings['install'] = Date.now() - installStart;
                 console.log(chalk.red(`  ✗ Install failed: ${err.message}`));
                 console.log(chalk.yellow(`  ⚠ Dev server may fail — retrying install on first request`));
                 progress('installing-deps', `Install failed: ${err.message}`);
             }
         }
         else {
-            progress('installing-deps', 'Dependencies already installed');
+            progress('installing-deps', 'Dependencies already installed (cached)');
         }
-        // Start local server
-        progress('starting-server', 'Starting API server...');
-        const localServer = new LocalServer({
-            projectDir, projectId,
-            apiPort: allocated.apiPort, devPort: allocated.devPort,
+        // ── Phase 3: Start dev server + connect tunnel in parallel ───────
+        const tunnel = new TunnelClient({
+            gatewayUrl: opts.gatewayUrl,
+            token: opts.token,
+            projectId,
+            apiPort: allocated.apiPort,
+            devPort: allocated.devPort,
         });
-        await localServer.start();
-        console.log(chalk.green(`  ✓ API server on port ${allocated.apiPort}`));
-        progress('starting-server', `API server on port ${allocated.apiPort}`);
-        // Start dev server (only if dependencies are installed)
+        // Connect tunnel immediately (don't wait for dev server — tunnel is needed for status updates)
+        const tunnelPromise = (async () => {
+            progress('connecting', 'Connecting tunnel to gateway...');
+            try {
+                await tunnel.connect();
+                timings['tunnel'] = Date.now() - t0;
+                console.log(chalk.green(`  ✓ Tunnel connected for project ${projectId} (${timings['tunnel']}ms)`));
+                progress('connecting', 'Tunnel connected');
+            }
+            catch (err) {
+                console.log(chalk.yellow(`  ⚠ Tunnel: ${err.message}`));
+                tunnel.startBackgroundReconnect();
+                progress('connecting', `Warning: ${err.message} — reconnecting`);
+            }
+        })();
+        // Start dev server in parallel with tunnel connection
         if (!opts.noDev) {
             if (installer.areDependenciesInstalled()) {
                 progress('starting-dev', 'Starting dev server...');
                 try {
+                    const devStart = Date.now();
                     await localServer.getDevServer().start();
-                    console.log(chalk.green(`  ✓ Dev server on port ${allocated.devPort}`));
+                    timings['dev-server'] = Date.now() - devStart;
+                    console.log(chalk.green(`  ✓ Dev server on port ${allocated.devPort} (${timings['dev-server']}ms)`));
                     progress('starting-dev', `Dev server on port ${allocated.devPort}`);
                 }
                 catch (err) {
@@ -622,40 +675,22 @@ async function startAdditionalProject(projectId, opts) {
                 progress('starting-dev', 'Skipped — dependencies not installed');
             }
         }
-        // Connect project tunnel
-        progress('connecting', 'Connecting tunnel to gateway...');
-        const tunnel = new TunnelClient({
-            gatewayUrl: opts.gatewayUrl,
-            token: opts.token,
-            projectId,
-            apiPort: allocated.apiPort,
-            devPort: allocated.devPort,
-        });
-        try {
-            await tunnel.connect();
-            console.log(chalk.green(`  ✓ Tunnel connected for project ${projectId}`));
-            progress('connecting', 'Tunnel connected');
-        }
-        catch (err) {
-            console.log(chalk.yellow(`  ⚠ Tunnel: ${err.message}`));
-            tunnel.startBackgroundReconnect();
-            progress('connecting', `Warning: ${err.message} — reconnecting`);
-        }
-        // Register project with backend
-        try {
-            await fetch(`${opts.backendUrl}/api/agent/register`, {
-                method: 'POST',
-                headers: { 'Authorization': `Bearer ${opts.token}`, 'Content-Type': 'application/json' },
-                body: JSON.stringify({
-                    deviceId: opts.deviceId, name: os.hostname(), hostname: os.hostname(),
-                    platform: `${os.platform()} ${os.arch()}`, agentVersion: VERSION,
-                    projectId, capabilities: ['file-sync', 'type-check', 'install', 'terminal', 'dev-server'],
-                }),
-            });
-        }
-        catch { }
-        console.log(chalk.green(`  ✓ Project ${projectId} is live!\n`));
-        progress('ready', 'Project is live!');
+        // Wait for tunnel to be connected
+        await tunnelPromise;
+        // Register project with backend (non-blocking)
+        fetch(`${opts.backendUrl}/api/agent/register`, {
+            method: 'POST',
+            headers: { 'Authorization': `Bearer ${opts.token}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                deviceId: opts.deviceId, name: os.hostname(), hostname: os.hostname(),
+                platform: `${os.platform()} ${os.arch()}`, agentVersion: VERSION,
+                projectId, capabilities: ['file-sync', 'type-check', 'install', 'terminal', 'dev-server'],
+            }),
+        }).catch(() => { });
+        const totalTime = Date.now() - t0;
+        console.log(chalk.green(`  ✓ Project ${projectId} is live! (total: ${totalTime}ms)\n`));
+        console.log(chalk.gray(`    Timings: ${JSON.stringify(timings)}`));
+        progress('ready', `Project is live! (${totalTime}ms)`);
         return { localServer, tunnel };
     }
     catch (err) {

package/dist/devServer.js

@@ -294,14 +294,15 @@ export class DevServer {
                     resolve();
                 });
                 req.on('error', () => {
-                    setTimeout(check, 500);
+                    setTimeout(check, 300);
                 });
                 req.setTimeout(2000, () => {
                     req.destroy();
-                    setTimeout(check, 500);
+                    setTimeout(check, 300);
                 });
             };
-            setTimeout(check, 1000);
+            // Start checking after a short delay (Vite can be ready in <500ms)
+            setTimeout(check, 300);
         });
     }
 }

package/dist/localServer.js

@@ -13,6 +13,7 @@
  * Requests arrive through the tunnel from the gateway.
  */
 import http from 'http';
+import fs from 'fs';
 import os from 'os';
 import { createRequire } from 'module';
 import { spawn } from 'child_process';
@@ -202,7 +203,8 @@ export class LocalServer {
             '/live/normalize': this.handleNormalize,
             '/live/normalize-batch': this.handleNormalizeBatch,
             '/live/invalidate': this.handleInvalidate,
-            '/live/refetch': this.handleRefetch,
+            '/live/refetch': this.handleRefetch, // Legacy — no-op in agent mode
+            '/live/reset': this.handleRefetch, // New push-based reset — also no-op in agent mode
             '/live/grace-period': this.handleGracePeriod,
             '/live/stats': this.handleStats,
             '/live/usage': this.handleUsage,
@@ -405,6 +407,8 @@ export class LocalServer {
         const label = parsed.label || `Terminal ${sessionCounter}`;
         let shell = null;
         let ptyProcess = null;
+        // Ensure project directory exists (posix_spawnp fails if cwd is missing)
+        const spawnCwd = fs.existsSync(this.options.projectDir) ? this.options.projectDir : process.cwd();
         // Prefer node-pty for real PTY (interactive shell, echo, prompt, resize)
         if (ptyModule) {
             try {
@@ -412,39 +416,61 @@ export class LocalServer {
                     name: 'xterm-256color',
                     cols,
                     rows,
-                    cwd: this.options.projectDir,
+                    cwd: spawnCwd,
                     env: shellEnv,
                 });
             }
             catch (ptyErr) {
                 console.warn(`  [Terminal] node-pty spawn failed: ${ptyErr.message} — falling back to script`);
                 ptyProcess = null;
-                // Fall through to script/spawn fallbacks below
             }
         }
-        if (!ptyProcess && !shell && process.platform === 'darwin') {
-            // macOS fallback: use 'script' to allocate a PTY
-            shell = spawn('script', ['-q', '/dev/null', shellCmd], {
-                cwd: this.options.projectDir,
-                env: shellEnv,
-                stdio: ['pipe', 'pipe', 'pipe'],
-            });
-        }
-        else if (!ptyProcess && !shell && process.platform === 'linux') {
-            // Linux fallback: 'script' with -c flag
-            shell = spawn('script', ['-qc', shellCmd, '/dev/null'], {
-                cwd: this.options.projectDir,
-                env: shellEnv,
-                stdio: ['pipe', 'pipe', 'pipe'],
-            });
+        if (!ptyProcess && !shell) {
+            try {
+                if (process.platform === 'darwin') {
+                    // macOS fallback: use 'script' to allocate a PTY
+                    shell = spawn('script', ['-q', '/dev/null', shellCmd], {
+                        cwd: spawnCwd,
+                        env: shellEnv,
+                        stdio: ['pipe', 'pipe', 'pipe'],
+                    });
+                }
+                else if (process.platform === 'linux') {
+                    // Linux fallback: 'script' with -c flag
+                    shell = spawn('script', ['-qc', shellCmd, '/dev/null'], {
+                        cwd: spawnCwd,
+                        env: shellEnv,
+                        stdio: ['pipe', 'pipe', 'pipe'],
+                    });
+                }
+                else {
+                    // Windows / other: raw spawn (limited interactivity)
+                    shell = spawn(shellCmd, [], {
+                        cwd: spawnCwd,
+                        env: shellEnv,
+                        stdio: ['pipe', 'pipe', 'pipe'],
+                    });
+                }
+            }
+            catch (scriptErr) {
+                console.warn(`  [Terminal] script fallback failed: ${scriptErr.message} — trying raw spawn`);
+            }
         }
-        else if (!ptyProcess && !shell) {
-            // Windows / other: raw spawn (limited interactivity)
-            shell = spawn(shellCmd, [], {
-                cwd: this.options.projectDir,
-                env: shellEnv,
-                stdio: ['pipe', 'pipe', 'pipe'],
-            });
+        // Last resort: raw spawn with no PTY
+        if (!ptyProcess && !shell) {
+            try {
+                shell = spawn(shellCmd, [], {
+                    cwd: spawnCwd,
+                    env: shellEnv,
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+            }
+            catch (rawErr) {
+                console.error(`  [Terminal] All spawn methods failed: ${rawErr.message}`);
+                res.statusCode = 500;
+                this.json(res, { success: false, error: `Failed to spawn terminal: ${rawErr.message}` });
+                return;
+            }
         }
         const session = {
             id: sessionId,
@@ -566,7 +592,7 @@ export class LocalServer {
             connected: true,
             projectId: this.options.projectId,
             agent: {
-                version: '0.5.4',
+                version: '0.5.8',
                 hostname: os.hostname(),
                 platform: `${os.platform()} ${os.arch()}`,
             },

package/dist/packageInstaller.d.ts

@@ -21,8 +21,23 @@ export declare class PackageInstaller {
     /**
      * Ensure all project dependencies are installed.
      * Uses a lock to prevent concurrent installs.
+     * Skips install entirely if package.json + lockfile haven't changed (hash cache).
      */
     ensureDependencies(): Promise<void>;
+    /**
+     * Build the fastest possible install command:
+     * - npm ci (clean install from lockfile) if package-lock.json exists
+     * - npm install --prefer-offline otherwise
+     * - pnpm install --frozen-lockfile if pnpm
+     */
+    private buildFastInstallArgs;
+    /**
+     * Compute a hash of package.json + lockfile contents.
+     * Used to skip npm install when nothing has changed.
+     */
+    private computeDepsHash;
+    private isDepsHashMatch;
+    private writeDepsHash;
     /**
      * Check if dependencies are actually installed (not just that node_modules/ exists).
      * Verifies that at least one key dependency from package.json is present.

package/dist/packageInstaller.js

@@ -5,6 +5,7 @@
 import { spawn } from 'child_process';
 import path from 'path';
 import fs, { existsSync } from 'fs';
+import crypto from 'crypto';
 export class PackageInstaller {
     projectDir;
     /** Serializes concurrent install calls */
@@ -39,26 +40,100 @@ export class PackageInstaller {
     /**
      * Ensure all project dependencies are installed.
      * Uses a lock to prevent concurrent installs.
+     * Skips install entirely if package.json + lockfile haven't changed (hash cache).
      */
     async ensureDependencies() {
         // Serialize with any in-flight install
         await this.installLock;
-        if (this.areDependenciesInstalled())
+        // Fast path: check if deps are cached by hash
+        if (this.isDepsHashMatch()) {
+            console.log(`  [Installer] Dependencies up-to-date (hash match) — skipping install`);
             return;
+        }
+        if (this.areDependenciesInstalled()) {
+            // node_modules exists and looks valid — write hash and skip
+            this.writeDepsHash();
+            return;
+        }
         // Acquire lock for this install
         let releaseLock;
         this.installLock = new Promise(resolve => { releaseLock = resolve; });
         try {
             console.log(`  [Installer] Installing project dependencies...`);
             const pm = this.detectPackageManager();
-            const args = pm === 'pnpm' ? ['install'] : ['install'];
+            const args = this.buildFastInstallArgs(pm);
             await this.runCommand(pm, args, 300_000);
+            this.writeDepsHash();
             console.log(`  [Installer] Dependencies installed`);
         }
         finally {
             releaseLock();
         }
     }
+    /**
+     * Build the fastest possible install command:
+     * - npm ci (clean install from lockfile) if package-lock.json exists
+     * - npm install --prefer-offline otherwise
+     * - pnpm install --frozen-lockfile if pnpm
+     */
+    buildFastInstallArgs(pm) {
+        switch (pm) {
+            case 'pnpm': {
+                const hasLock = existsSync(path.join(this.projectDir, 'pnpm-lock.yaml'));
+                return hasLock ? ['install', '--frozen-lockfile', '--prefer-offline'] : ['install'];
+            }
+            case 'yarn': {
+                const hasLock = existsSync(path.join(this.projectDir, 'yarn.lock'));
+                return hasLock ? ['install', '--frozen-lockfile', '--prefer-offline'] : ['install'];
+            }
+            default: {
+                // npm: prefer ci (much faster) if lockfile exists
+                const hasLock = existsSync(path.join(this.projectDir, 'package-lock.json'));
+                return hasLock ? ['ci', '--prefer-offline'] : ['install', '--prefer-offline'];
+            }
+        }
+    }
+    /**
+     * Compute a hash of package.json + lockfile contents.
+     * Used to skip npm install when nothing has changed.
+     */
+    computeDepsHash() {
+        const hash = crypto.createHash('sha256');
+        const pkgPath = path.join(this.projectDir, 'package.json');
+        if (existsSync(pkgPath))
+            hash.update(fs.readFileSync(pkgPath));
+        // Include lockfile if present
+        for (const lockFile of ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock']) {
+            const lockPath = path.join(this.projectDir, lockFile);
+            if (existsSync(lockPath)) {
+                hash.update(fs.readFileSync(lockPath));
+                break;
+            }
+        }
+        return hash.digest('hex').slice(0, 16);
+    }
+    isDepsHashMatch() {
+        const hashFile = path.join(this.projectDir, 'node_modules', '.nstantpage-deps-hash');
+        if (!existsSync(hashFile))
+            return false;
+        try {
+            const stored = fs.readFileSync(hashFile, 'utf-8').trim();
+            return stored === this.computeDepsHash();
+        }
+        catch {
+            return false;
+        }
+    }
+    writeDepsHash() {
+        const hashFile = path.join(this.projectDir, 'node_modules', '.nstantpage-deps-hash');
+        try {
+            const dir = path.dirname(hashFile);
+            if (!existsSync(dir))
+                fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(hashFile, this.computeDepsHash(), 'utf-8');
+        }
+        catch { }
+    }
     /**
      * Check if dependencies are actually installed (not just that node_modules/ exists).
      * Verifies that at least one key dependency from package.json is present.

package/dist/tunnel.js

@@ -63,7 +63,7 @@ export class TunnelClient {
                 // Send enhanced agent info with capabilities and deviceId
                 this.send({
                     type: 'agent-info',
-                    version: '0.5.4',
+                    version: '0.5.8',
                     hostname: os.hostname(),
                     platform: `${os.platform()} ${os.arch()}`,
                     deviceId: getDeviceId(),

package/package.json

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