nstantpage-agent 0.5.21 → 0.5.22

package/dist/commands/service.js

@@ -24,6 +24,7 @@ import { getConfig } from '../config.js';
 import { startCommand } from './start.js';
 const PLIST_LABEL = 'com.nstantpage.agent';
 const SYSTEMD_SERVICE = 'nstantpage-agent';
+const WIN_TASK_NAME = 'NstantpageAgent';
 /**
  * `nstantpage service start` — run agent in standby mode (foreground).
  * This keeps your machine online and visible from the web UI.
@@ -76,6 +77,14 @@ export async function serviceStopCommand() {
         }
         catch { }
     }
+    else if (platform === 'win32') {
+        try {
+            execSync(`schtasks /end /tn "${WIN_TASK_NAME}" 2>nul`, { encoding: 'utf-8' });
+            console.log(chalk.green('  ✓ Background task stopped'));
+            stopped = true;
+        }
+        catch { }
+    }
     // Also try PID-based stop from global config
     const conf = getConfig();
     const pid = conf.get('agentPid');
@@ -103,16 +112,35 @@ export async function serviceInstallCommand(options = {}) {
     }
     const gateway = options.gateway || 'wss://webprev.live';
     const platform = os.platform();
+    // On desktop platforms, prefer the Electron tray app (agent + tray icon in one)
+    const electronAppPath = findElectronApp();
+    if (electronAppPath && (platform === 'darwin' || platform === 'win32')) {
+        console.log(chalk.blue(`\n  Found nstantpage desktop app: ${electronAppPath}`));
+        console.log(chalk.blue('  Installing with system tray icon...\n'));
+        if (platform === 'darwin') {
+            await installElectronLaunchd(electronAppPath);
+        }
+        else if (platform === 'win32') {
+            await installElectronWindowsTask(electronAppPath);
+        }
+        return;
+    }
+    // Fallback: headless service (no tray icon)
+    if (electronAppPath === null) {
+        console.log(chalk.gray('  Tip: Install the nstantpage desktop app for a system tray icon.'));
+    }
     if (platform === 'darwin') {
         await installLaunchd(gateway, token);
     }
     else if (platform === 'linux') {
         await installSystemd(gateway, token);
     }
+    else if (platform === 'win32') {
+        await installWindowsTask(gateway, token);
+    }
     else {
         console.log(chalk.yellow('⚠ Background service not yet supported on this platform.'));
         console.log(chalk.gray('  Use "nstantpage start --project-id X" to run manually.'));
-        console.log(chalk.gray('  Windows support coming soon.'));
         process.exit(1);
     }
 }
@@ -124,6 +152,9 @@ export async function serviceUninstallCommand() {
     else if (platform === 'linux') {
         await uninstallSystemd();
     }
+    else if (platform === 'win32') {
+        await uninstallWindowsTask();
+    }
     else {
         console.log(chalk.yellow('  ⚠ Service uninstall not supported on this platform'));
     }
@@ -158,6 +189,22 @@ export async function serviceStatusCommand() {
             console.log(chalk.yellow('  ⚠ Service is not running or not installed'));
         }
     }
+    else if (platform === 'win32') {
+        try {
+            const result = execSync(`schtasks /query /tn "${WIN_TASK_NAME}" /fo CSV /nh 2>nul`, { encoding: 'utf-8' }).trim();
+            if (result) {
+                const parts = result.split('","');
+                const status = parts[2]?.replace(/"/g, '') || 'Unknown';
+                console.log(chalk.green(`  ✓ Task is installed (status: ${status})`));
+            }
+            else {
+                console.log(chalk.yellow('  ⚠ Task is not installed'));
+            }
+        }
+        catch {
+            console.log(chalk.yellow('  ⚠ Task is not installed'));
+        }
+    }
     else {
         console.log(chalk.gray('  Service status not available on this platform'));
     }
@@ -178,6 +225,114 @@ export async function serviceStatusCommand() {
     }
 }
 // ─── Helper Functions ─────────────────────────────────
+// ─── Electron App Detection ──────────────────────────────
+function findElectronApp() {
+    const platform = os.platform();
+    if (platform === 'darwin') {
+        // Check common macOS install paths
+        const candidates = [
+            '/Applications/nstantpage.app',
+            path.join(os.homedir(), 'Applications', 'nstantpage.app'),
+            // Dev build location (from electron-builder --dir)
+            path.join(__dirname, '..', '..', 'tray', 'dist', 'mac-arm64', 'nstantpage.app'),
+            path.join(__dirname, '..', '..', 'tray', 'dist', 'mac', 'nstantpage.app'),
+        ];
+        for (const p of candidates) {
+            if (fs.existsSync(p))
+                return p;
+        }
+    }
+    else if (platform === 'win32') {
+        const candidates = [
+            path.join(os.homedir(), 'AppData', 'Local', 'Programs', 'nstantpage', 'nstantpage.exe'),
+            path.join('C:\\Program Files', 'nstantpage', 'nstantpage.exe'),
+        ];
+        for (const p of candidates) {
+            if (fs.existsSync(p))
+                return p;
+        }
+    }
+    return null;
+}
+async function installElectronLaunchd(appPath) {
+    const plistDir = path.join(os.homedir(), 'Library', 'LaunchAgents');
+    const plistPath = path.join(plistDir, `${PLIST_LABEL}.plist`);
+    const logPath = path.join(os.homedir(), '.nstantpage', 'agent.log');
+    const errPath = path.join(os.homedir(), '.nstantpage', 'agent.err.log');
+    fs.mkdirSync(plistDir, { recursive: true });
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${PLIST_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/bin/open</string>
+        <string>-a</string>
+        <string>${appPath}</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+        <key>Crashed</key>
+        <true/>
+    </dict>
+    <key>ProcessType</key>
+    <string>Interactive</string>
+    <key>StandardOutPath</key>
+    <string>${logPath}</string>
+    <key>StandardErrorPath</key>
+    <string>${errPath}</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>NSAppSleepDisabled</key>
+        <string>YES</string>
+    </dict>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+</dict>
+</plist>`;
+    fs.writeFileSync(plistPath, plist, 'utf-8');
+    try {
+        execSync(`launchctl unload "${plistPath}" 2>/dev/null`, { encoding: 'utf-8' });
+    }
+    catch { }
+    execSync(`launchctl load "${plistPath}"`, { encoding: 'utf-8' });
+    console.log(chalk.green('\n  ✓ nstantpage installed as desktop app with tray icon\n'));
+    console.log(chalk.gray(`  App:     ${appPath}`));
+    console.log(chalk.gray(`  Plist:   ${plistPath}`));
+    console.log(chalk.gray(`  Log:     ${logPath}`));
+    console.log(chalk.gray(`  Status:  nstantpage service status`));
+    console.log(chalk.gray(`  Remove:  nstantpage service uninstall\n`));
+    console.log(chalk.blue('  The app will start on login with a tray icon showing connection status.'));
+    console.log(chalk.blue('  Right-click the tray icon for options. Open nstantpage.com to connect projects.\n'));
+}
+async function installElectronWindowsTask(appPath) {
+    const logPath = path.join(os.homedir(), '.nstantpage', 'agent.log');
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    try {
+        execSync(`schtasks /delete /tn "${WIN_TASK_NAME}" /f 2>nul`, { encoding: 'utf-8' });
+    }
+    catch { }
+    try {
+        execSync(`schtasks /create /tn "${WIN_TASK_NAME}" /tr "\\"${appPath}\\"" /sc onlogon /rl highest /delay 0000:10 /f`, { encoding: 'utf-8' });
+        // Start immediately
+        execSync(`start "" "${appPath}"`, { encoding: 'utf-8' });
+    }
+    catch (err) {
+        console.log(chalk.yellow(`  ⚠ Task Scheduler error: ${err.message}`));
+        return;
+    }
+    console.log(chalk.green('\n  ✓ nstantpage installed as desktop app with tray icon\n'));
+    console.log(chalk.gray(`  App:     ${appPath}`));
+    console.log(chalk.gray(`  Task:    ${WIN_TASK_NAME}`));
+    console.log(chalk.gray(`  Status:  nstantpage service status`));
+    console.log(chalk.gray(`  Remove:  nstantpage service uninstall\n`));
+    console.log(chalk.blue('  The app will start on login with a tray icon.\n'));
+}
 function getAgentBinPath() {
     try {
         const resolved = execSync('which nstantpage 2>/dev/null || which nstantpage-agent 2>/dev/null', { encoding: 'utf-8' }).trim();
@@ -233,10 +388,9 @@ async function installLaunchd(gateway, token) {
     <key>RunAtLoad</key>
     <true/>
     <key>KeepAlive</key>
-    <dict>
-        <key>SuccessfulExit</key>
-        <false/>
-    </dict>
+    <true/>
+    <key>ProcessType</key>
+    <string>Interactive</string>
     <key>StandardOutPath</key>
     <string>${logPath}</string>
     <key>StandardErrorPath</key>
@@ -245,9 +399,13 @@ async function installLaunchd(gateway, token) {
     <dict>
         <key>PATH</key>
         <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
+        <key>NSAppSleepDisabled</key>
+        <string>YES</string>
     </dict>
     <key>ThrottleInterval</key>
     <integer>10</integer>
+    <key>Nice</key>
+    <integer>-5</integer>
 </dict>
 </plist>`;
     fs.writeFileSync(plistPath, plist, 'utf-8');
@@ -337,4 +495,60 @@ async function uninstallSystemd() {
     console.log(chalk.green('  ✓ Agent service uninstalled (systemd)'));
     console.log(chalk.gray('  The agent will no longer start automatically.'));
 }
+// ─── Windows (Task Scheduler) ────────────────────────────
+async function installWindowsTask(gateway, token) {
+    const binPath = getAgentBinPath();
+    const nodePath = getNodePath();
+    const logPath = path.join(os.homedir(), '.nstantpage', 'agent.log');
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    // Create a wrapper batch script that redirects output to log
+    const batchDir = path.join(os.homedir(), '.nstantpage');
+    const batchPath = path.join(batchDir, 'agent-service.cmd');
+    const batchContent = `@echo off\r\n"${nodePath}" "${binPath}" start --gateway ${gateway} --token ${token} >> "${logPath}" 2>&1\r\n`;
+    fs.writeFileSync(batchPath, batchContent, 'utf-8');
+    // Remove existing task if any
+    try {
+        execSync(`schtasks /delete /tn "${WIN_TASK_NAME}" /f 2>nul`, { encoding: 'utf-8' });
+    }
+    catch { }
+    // Create a scheduled task that runs at logon and restarts on failure
+    // /sc onlogon — runs when any user logs on
+    // /rl highest — run with highest privileges available to user
+    // /delay 0000:10 — 10 second delay after trigger
+    try {
+        execSync(`schtasks /create /tn "${WIN_TASK_NAME}" /tr "\\"${batchPath}\\"" /sc onlogon /rl highest /delay 0000:10 /f`, { encoding: 'utf-8' });
+        // Start it immediately
+        execSync(`schtasks /run /tn "${WIN_TASK_NAME}"`, { encoding: 'utf-8' });
+    }
+    catch (err) {
+        console.log(chalk.yellow(`  ⚠ Task Scheduler error: ${err.message}`));
+        console.log(chalk.gray('  You may need to run this command as Administrator.'));
+        return;
+    }
+    console.log(chalk.green('\n  ✓ Agent installed as scheduled task (Windows Task Scheduler)\n'));
+    console.log(chalk.gray(`  Task:    ${WIN_TASK_NAME}`));
+    console.log(chalk.gray(`  Script:  ${batchPath}`));
+    console.log(chalk.gray(`  Log:     ${logPath}`));
+    console.log(chalk.gray(`  Status:  nstantpage service status`));
+    console.log(chalk.gray(`  Remove:  nstantpage service uninstall\n`));
+    console.log(chalk.blue('  The agent will start on login and stay connected to your account.'));
+    console.log(chalk.blue('  Open any project on nstantpage.com and click "Connect" to use it.\n'));
+}
+async function uninstallWindowsTask() {
+    try {
+        execSync(`schtasks /delete /tn "${WIN_TASK_NAME}" /f 2>nul`, { encoding: 'utf-8' });
+        console.log(chalk.green('  ✓ Agent task removed (Windows Task Scheduler)'));
+    }
+    catch {
+        console.log(chalk.yellow('  ⚠ Task is not installed or could not be removed'));
+    }
+    // Clean up batch script
+    const batchPath = path.join(os.homedir(), '.nstantpage', 'agent-service.cmd');
+    try {
+        if (fs.existsSync(batchPath))
+            fs.unlinkSync(batchPath);
+    }
+    catch { }
+    console.log(chalk.gray('  The agent will no longer start automatically.'));
+}
 //# sourceMappingURL=service.js.map

package/dist/commands/start.js

@@ -25,7 +25,8 @@ import { TunnelClient } from '../tunnel.js';
 import { LocalServer } from '../localServer.js';
 import { PackageInstaller } from '../packageInstaller.js';
 import { probeLocalPostgres, ensureLocalProjectDb, closeAdminPool, writeDatabaseUrlToEnv } from '../projectDb.js';
-const VERSION = '0.5.21';
+import { StatusServer } from '../statusServer.js';
+const VERSION = '0.5.22';
 /**
  * Resolve the backend API base URL.
  * - If --backend is passed, use it
@@ -296,15 +297,24 @@ export async function startCommand(directory, options) {
         serverEnv['DATABASE_URL'] = databaseUrl;
     }
     // 3. Start local server (API + dev server)
+    // Note: tunnel is created after localServer but before localServer.start(),
+    // so the onSyncDirty callback captures it via closure (late-binding).
+    let tunnel;
     const localServer = new LocalServer({
         projectDir,
         projectId,
         apiPort,
         devPort,
         env: serverEnv,
+        backendUrl,
+        onSyncDirty: (pid) => {
+            if (tunnel) {
+                tunnel.sendSyncDirty(pid);
+            }
+        },
     });
     // 4. Create tunnel client
-    const tunnel = new TunnelClient({
+    tunnel = new TunnelClient({
         gatewayUrl: options.gateway,
         token,
         projectId,
@@ -570,9 +580,39 @@ async function startStandbyMode(token, options, backendUrl, deviceId) {
         }
         catch { }
     }, 60_000);
+    // Start status server (for tray app IPC)
+    const startedAt = new Date().toISOString();
+    let shutdownFn = null;
+    const statusServer = new StatusServer(() => ({
+        tunnelStatus: standbyTunnel.status,
+        version: VERSION,
+        hostname: os.hostname(),
+        platform: `${os.platform()} ${os.arch()}`,
+        uptime: Date.now() - Date.parse(startedAt),
+        startedAt,
+        activeProjects: Array.from(activeProjects.entries()).map(([pid, proj]) => ({
+            projectId: pid,
+            devPort: allocatePortsForProject(pid).devPort,
+            apiPort: allocatePortsForProject(pid).apiPort,
+            tunnelStatus: proj.tunnel.status,
+        })),
+        requestsForwarded: standbyTunnel.stats.requestsForwarded +
+            Array.from(activeProjects.values()).reduce((sum, p) => sum + p.tunnel.stats.requestsForwarded, 0),
+        deviceId,
+        gatewayUrl: options.gateway,
+    }), async () => { if (shutdownFn)
+        await shutdownFn(); });
+    try {
+        await statusServer.start();
+        console.log(chalk.green(`  ✓ Status server on port 18999`));
+    }
+    catch (err) {
+        console.log(chalk.gray(`  ⚠ Status server: ${err.message} (non-fatal)`));
+    }
     // Shutdown handler
     const shutdown = async () => {
         console.log(chalk.yellow('\n  Shutting down...'));
+        await statusServer.stop();
         standbyTunnel.disconnect();
         for (const [, proj] of activeProjects) {
             proj.tunnel.disconnect();
@@ -589,6 +629,7 @@ async function startStandbyMode(token, options, backendUrl, deviceId) {
         catch { }
         process.exit(0);
     };
+    shutdownFn = shutdown;
     process.on('SIGTERM', shutdown);
     process.on('SIGINT', shutdown);
     console.log(chalk.blue.bold(`  ┌──────────────────────────────────────────────┐`));

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { TunnelClient } from './tunnel.js';
+export { TunnelClient, type TunnelStatus } from './tunnel.js';
 export { LocalServer } from './localServer.js';
 export { DevServer } from './devServer.js';
 export { FileManager } from './fileManager.js';

package/dist/localServer.d.ts

@@ -58,6 +58,10 @@ export interface LocalServerOptions {
     apiPort: number;
     devPort: number;
     env?: Record<string, string>;
+    /** Backend API URL (e.g., http://localhost:5001 or https://nstantpage.com) */
+    backendUrl?: string;
+    /** Called when file watcher detects changes — should send sync-dirty via tunnel */
+    onSyncDirty?: (projectId: string) => void;
 }
 export declare class LocalServer {
     private server;
@@ -67,6 +71,7 @@ export declare class LocalServer {
     private checker;
     private errorStore;
     private packageInstaller;
+    private agentSync;
     private lastHeartbeat;
     constructor(options: LocalServerOptions);
     /**
@@ -114,6 +119,10 @@ export declare class LocalServer {
     private handleStats;
     private handleUsage;
     private handleBuild;
+    private handleSyncStatus;
+    private handleSyncDiff;
+    private handlePushToBackend;
+    private handleDiskFile;
     private handleHealth;
     /**
      * Get a pg Pool connected to this project's local database.

package/dist/localServer.js

@@ -24,6 +24,7 @@ import { Checker } from './checker.js';
 import { ErrorStore, structuredErrorToString } from './errorStore.js';
 import { PackageInstaller } from './packageInstaller.js';
 import { probeLocalPostgres, ensureLocalProjectDb, isLocalPgAvailable, writeDatabaseUrlToEnv } from './projectDb.js';
+import { AgentSync } from './agentSync.js';
 // ─── Try to load node-pty for real PTY support ─────────────────
 let ptyModule = null;
 try {
@@ -101,6 +102,7 @@ export class LocalServer {
     checker;
     errorStore;
     packageInstaller;
+    agentSync = null;
     lastHeartbeat = Date.now();
     constructor(options) {
         this.options = options;
@@ -113,6 +115,15 @@ export class LocalServer {
         this.checker = new Checker({ projectDir: options.projectDir, projectId: options.projectId });
         this.errorStore = new ErrorStore();
         this.packageInstaller = new PackageInstaller({ projectDir: options.projectDir });
+        // Initialize sync manager if backendUrl is available
+        if (options.backendUrl) {
+            this.agentSync = new AgentSync({
+                projectDir: options.projectDir,
+                projectId: options.projectId,
+                backendUrl: options.backendUrl,
+                onSyncDirty: options.onSyncDirty,
+            });
+        }
     }
     /**
      * Ensure the project database is provisioned and DATABASE_URL is set in the DevServer env.
@@ -187,8 +198,16 @@ export class LocalServer {
             });
             this.server.on('error', reject);
         });
+        // Start file watcher for sync detection
+        if (this.agentSync) {
+            this.agentSync.startFileWatcher();
+        }
     }
     async stop() {
+        // Stop file watcher
+        if (this.agentSync) {
+            this.agentSync.destroy();
+        }
         await this.devServer.stop();
         if (this.server) {
             this.server.close();
@@ -250,6 +269,10 @@ export class LocalServer {
             '/live/db/query': this.handleDbQuery,
             '/live/db/create': this.handleDbCreate,
             '/live/build': this.handleBuild,
+            '/live/sync-status': this.handleSyncStatus,
+            '/live/sync-diff': this.handleSyncDiff,
+            '/live/push-to-backend': this.handlePushToBackend,
+            '/live/disk-file': this.handleDiskFile,
             '/health': this.handleHealth,
         };
         if (handlers[path])
@@ -264,7 +287,7 @@ export class LocalServer {
     // ─── /live/sync ──────────────────────────────────────────────
     async handleSync(_req, res, body) {
         const data = JSON.parse(body);
-        const { files, deletedFiles, filterFiles } = data;
+        const { files, deletedFiles, filterFiles, versionId } = data;
         let filesWritten = 0;
         let filesDeleted = 0;
         // Write files
@@ -276,6 +299,10 @@ export class LocalServer {
         if (deletedFiles && Array.isArray(deletedFiles) && deletedFiles.length > 0) {
             filesDeleted = await this.fileManager.deleteFiles(deletedFiles);
         }
+        // Mark sync baseline so the file watcher knows what "clean" looks like
+        if (this.agentSync && versionId) {
+            this.agentSync.markSynced(String(versionId));
+        }
         // Run type check
         const filesToCheck = filterFiles || (files ? Object.keys(files) : []);
         const { typeErrors, allErrors } = await this.checker.fullCheck(filesToCheck.length > 0 ? filesToCheck : undefined);
@@ -953,7 +980,7 @@ export class LocalServer {
             const buildResult = await new Promise((resolve) => {
                 const proc = spawn('sh', ['-c', buildCmd], {
                     cwd: projectDir,
-                    env: { ...process.env, ...this.options.env, NODE_OPTIONS: '--max-old-space-size=512' },
+                    env: { ...process.env, ...this.options.env, NODE_OPTIONS: '--max-old-space-size=4096' },
                     stdio: ['ignore', 'pipe', 'pipe'],
                 });
                 let stdout = '', stderr = '';
@@ -963,8 +990,9 @@ export class LocalServer {
                 proc.on('error', (err) => resolve({ exitCode: 1, stdout: '', stderr: err.message }));
             });
             if (buildResult.exitCode !== 0) {
-                console.error(`  [LocalServer] Build failed: ${buildResult.stderr}`);
-                this.json(res, { success: false, error: buildResult.stderr || 'Build failed' });
+                const errorMsg = buildResult.stderr || buildResult.stdout || `Build failed with exit code ${buildResult.exitCode}`;
+                console.error(`  [LocalServer] Build failed (exit ${buildResult.exitCode}): ${errorMsg.substring(0, 500)}`);
+                this.json(res, { success: false, error: errorMsg });
                 return;
             }
             // Collect dist/ files
@@ -1013,6 +1041,83 @@ export class LocalServer {
             this.json(res, { success: false, error: err.message });
         }
     }
+    // ─── /live/sync-status ────────────────────────────────────────
+    async handleSyncStatus(_req, res, _body, url) {
+        if (!this.agentSync) {
+            this.json(res, { success: false, error: 'Sync not available (no backendUrl configured)' }, 503);
+            return;
+        }
+        try {
+            const status = await this.agentSync.getSyncStatus();
+            this.json(res, { success: true, ...status });
+        }
+        catch (error) {
+            console.error(`  [LocalServer] sync-status error:`, error.message);
+            this.json(res, { success: false, error: error.message }, 500);
+        }
+    }
+    // ─── /live/sync-diff ─────────────────────────────────────────
+    async handleSyncDiff(_req, res, _body, url) {
+        if (!this.agentSync) {
+            this.json(res, { success: false, error: 'Sync not available (no backendUrl configured)' }, 503);
+            return;
+        }
+        try {
+            const files = await this.agentSync.getPerFileStatus();
+            const changed = files.filter(f => f.status !== 'same');
+            this.json(res, {
+                success: true,
+                totalFiles: files.length,
+                changedCount: changed.length,
+                files: changed,
+            });
+        }
+        catch (error) {
+            console.error(`  [LocalServer] sync-diff error:`, error.message);
+            this.json(res, { success: false, error: error.message }, 500);
+        }
+    }
+    // ─── /live/push-to-backend ───────────────────────────────────
+    async handlePushToBackend(_req, res, _body) {
+        if (!this.agentSync) {
+            this.json(res, { success: false, error: 'Sync not available (no backendUrl configured)' }, 503);
+            return;
+        }
+        try {
+            const result = await this.agentSync.pushToBackend();
+            this.json(res, result);
+        }
+        catch (error) {
+            console.error(`  [LocalServer] push-to-backend error:`, error.message);
+            this.json(res, { success: false, error: error.message }, 500);
+        }
+    }
+    // ─── /live/disk-file ─────────────────────────────────────────
+    async handleDiskFile(_req, res, _body, url) {
+        const filePath = url.searchParams.get('path');
+        if (!filePath) {
+            this.json(res, { error: 'Missing path parameter' }, 400);
+            return;
+        }
+        if (!this.agentSync) {
+            this.json(res, { success: false, error: 'Sync not available' }, 503);
+            return;
+        }
+        try {
+            const content = await this.agentSync.readDiskFile(filePath);
+            if (content === null) {
+                this.json(res, { error: 'File not found' }, 404);
+                return;
+            }
+            res.statusCode = 200;
+            res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+            res.setHeader('Access-Control-Allow-Origin', '*');
+            res.end(content);
+        }
+        catch (error) {
+            this.json(res, { success: false, error: error.message }, 500);
+        }
+    }
     // ─── /health ─────────────────────────────────────────────────
     async handleHealth(_req, res) {
         this.json(res, {
@@ -1197,7 +1302,9 @@ export class LocalServer {
         }
     }
     // ─── Helpers ─────────────────────────────────────────────────
-    json(res, data) {
+    json(res, data, statusCode) {
+        if (statusCode)
+            res.statusCode = statusCode;
         res.setHeader('Content-Type', 'application/json');
         res.setHeader('Access-Control-Allow-Origin', '*');
         res.end(JSON.stringify(data));

package/dist/statusServer.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Status Server — IPC endpoint for the system tray app.
+ *
+ * Provides a lightweight HTTP server on a local port (18999) that exposes:
+ *   GET /status  — Agent connection status, active projects, uptime
+ *   GET /health  — Simple health check
+ *   POST /quit   — Graceful shutdown
+ *
+ * The tray app polls GET /status to update its icon and menu.
+ * The port is also written to ~/.nstantpage/status.json for discovery.
+ */
+export interface AgentStatusInfo {
+    /** Current tunnel status: connected, connecting, disconnected, error */
+    tunnelStatus: string;
+    /** Agent version */
+    version: string;
+    /** Hostname of this machine */
+    hostname: string;
+    /** Platform string */
+    platform: string;
+    /** Agent uptime in ms */
+    uptime: number;
+    /** When the agent started (ISO string) */
+    startedAt: string;
+    /** Currently active projects */
+    activeProjects: ActiveProjectInfo[];
+    /** Total requests forwarded */
+    requestsForwarded: number;
+    /** Device ID */
+    deviceId: string;
+    /** Gateway URL */
+    gatewayUrl: string;
+}
+export interface ActiveProjectInfo {
+    projectId: string;
+    devPort: number;
+    apiPort: number;
+    tunnelStatus: string;
+    startedAt?: string;
+}
+type StatusProvider = () => AgentStatusInfo;
+type ShutdownHandler = () => Promise<void>;
+export declare class StatusServer {
+    private server;
+    private getStatus;
+    private onShutdown;
+    constructor(getStatus: StatusProvider, onShutdown: ShutdownHandler);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private writeStatusFile;
+}
+/**
+ * Read the status file to discover the running agent's status port.
+ */
+export declare function readAgentStatusFile(): {
+    port: number;
+    pid: number;
+    startedAt: string;
+} | null;
+export {};