nstantpage-agent 0.2.0

package/README.md

@@ -0,0 +1,207 @@
+# nstantpage-agent
+
+Local development agent for [nstantpage.com](https://nstantpage.com) — run your projects on your own machine with full native performance while editing in the cloud.
+
+## What it does
+
+The agent **replaces cloud Docker containers** for your project. Instead of running your dev server in a remote container (which can be slow for heavy projects), the agent:
+
+- 🖥️ Runs the dev server (Vite/Next.js) **natively on your machine**
+- 📁 Receives file changes from the cloud editor through a secure tunnel
+- 🔍 Runs TypeScript type checking locally (full speed, no container limits)
+- 📦 Installs packages using your local npm/pnpm
+- 🔗 Connects to the cloud editor through a WebSocket tunnel
+
+Your browser still uses the nstantpage.com editor — but all the heavy lifting happens on your computer.
+
+## Requirements
+
+- **Node.js 18+** (20+ recommended)
+- **npm**, **pnpm**, or **yarn**
+- Works on **macOS**, **Windows**, and **Linux**
+
+## Installation & Usage
+
+### Quick Start (no install needed)
+
+```bash
+npx nstantpage-agent start --project-id YOUR_PROJECT_ID
+```
+
+### Global Install
+
+```bash
+npm install -g nstantpage-agent
+
+# Then:
+nstantpage login
+nstantpage start --project-id YOUR_PROJECT_ID
+```
+
+### Step by Step
+
+1. **Authenticate** (one-time):
+   ```bash
+   npx nstantpage-agent login
+   ```
+   This opens your browser to authenticate with nstantpage.com.
+
+2. **Start the agent** in your project directory:
+   ```bash
+   cd /path/to/your/project
+   npx nstantpage-agent start --project-id 1234
+   ```
+   
+   Or from anywhere:
+   ```bash
+   npx nstantpage-agent start /path/to/your/project --project-id 1234
+   ```
+
+3. **Open nstantpage.com** — you'll see the purple "Local" indicator in the header, confirming the agent is connected.
+
+### Project Configuration
+
+Create a `.nstantpage.json` file in your project root to skip the `--project-id` flag:
+
+```json
+{
+  "projectId": "1234"
+}
+```
+
+Then just run:
+```bash
+npx nstantpage-agent start
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `nstantpage login` | Authenticate with nstantpage.com |
+| `nstantpage start [dir]` | Start the agent for a project |
+| `nstantpage stop` | Stop the running agent |
+| `nstantpage status` | Show agent connection status |
+
+### Start Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-p, --port <port>` | `3000` | Local dev server port |
+| `-a, --api-port <port>` | `18924` | Internal API port |
+| `--project-id <id>` | — | Link to a specific project |
+| `--gateway <url>` | `wss://webprev.live` | Gateway URL |
+| `--no-dev` | — | Don't start dev server automatically |
+
+## How It Works
+
+```
+┌─────────────────────┐         WebSocket Tunnel         ┌──────────────────┐
+│  nstantpage.com     │ ◄──────────────────────────────► │  Your Computer   │
+│  (Cloud Editor)     │    /live/* API + Dev traffic      │                  │
+│                     │                                   │  ┌────────────┐  │
+│  - Chat with AI     │                                   │  │ API Server │  │
+│  - Edit code        │         All /live/* requests      │  │ (port 18924)│  │
+│  - See preview      │ ──────────────────────────────►  │  └────────────┘  │
+│                     │                                   │                  │
+│  ┌───────────────┐  │                                   │  ┌────────────┐  │
+│  │ Preview iFrame│  │         Dev server traffic       │  │ Vite/Next  │  │
+│  │               │◄─│─────────────────────────────────│  │ (port 3000) │  │
+│  └───────────────┘  │                                   │  └────────────┘  │
+└─────────────────────┘                                   └──────────────────┘
+```
+
+1. **API Server** (port 18924): Handles file sync, type checking, error tracking, package installation — everything the cloud containers used to do.
+
+2. **Dev Server** (port 3000): Runs Vite/Next.js natively with full access to your machine's CPU and RAM. No container memory limits.
+
+3. **Tunnel**: Secure WebSocket connection to the gateway. Routes cloud editor requests to your local servers.
+
+## Testing Locally
+
+### Test the agent against a local gateway
+
+```bash
+# Terminal 1: Start the gateway
+cd PreviewGateway && node dist/index-v2.js
+
+# Terminal 2: Start the agent
+cd nstantpage-agent
+npx tsx src/cli.ts start /path/to/project \
+  --project-id 1234 \
+  --gateway ws://localhost:4000
+
+# Terminal 3: Verify connection
+curl http://localhost:4000/live/agent-status?projectId=1234
+# → {"connected":true,"projectId":"1234","agent":{"version":"0.2.0",...}}
+```
+
+### Test individual components
+
+```bash
+cd nstantpage-agent
+
+# Type check
+npx tsc --noEmit
+
+# Run in dev mode (auto-reloads)
+npx tsx src/cli.ts start . --project-id test --gateway ws://localhost:4000
+
+# Build
+npm run build
+
+# Run built version
+node dist/cli.js start . --project-id test --gateway ws://localhost:4000
+```
+
+## Troubleshooting
+
+### "Not authenticated" error
+Run `npx nstantpage-agent login` to authenticate.
+
+### Port already in use
+Use `--port` and `--api-port` flags to change ports:
+```bash
+npx nstantpage-agent start --port 3001 --api-port 18925
+```
+
+### Agent connects but preview doesn't load
+- Make sure your project has a valid `package.json`
+- Check that `npx vite` or `npx next dev` works in your project directory
+- Try `--no-dev` to skip auto-starting the dev server, then start it manually
+
+### Windows: `npx` not found
+Make sure Node.js is in your PATH. Try running from PowerShell or Git Bash.
+
+### macOS: Permission denied
+If you get EACCES errors, the agent may need access to the project directory. Check file permissions.
+
+## Platform Notes
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| macOS (Intel/Apple Silicon) | ✅ Full support | Recommended |
+| Windows 10/11 | ✅ Full support | Use PowerShell or Git Bash |
+| Linux (Ubuntu/Debian/Fedora) | ✅ Full support | Tested on Ubuntu 22.04+ |
+| WSL2 | ✅ Works | Run inside WSL2 terminal |
+
+## Architecture
+
+The agent consists of these modules:
+
+- **`localServer.ts`** — HTTP server handling all `/live/*` API endpoints locally
+- **`tunnel.ts`** — WebSocket client that connects to the gateway and routes requests
+- **`devServer.ts`** — Manages local Vite/Next.js/Express dev server processes
+- **`fileManager.ts`** — File I/O (replaces `docker cp`)
+- **`checker.ts`** — TypeScript type checking (replaces container-based `tsc`)
+- **`packageInstaller.ts`** — npm/pnpm/yarn package installation
+- **`errorStore.ts`** — Error tracking and deduplication
+
+## Development
+
+```bash
+cd nstantpage-agent
+npm install
+npm run build     # Compile TypeScript
+npm run dev       # Run in watch mode with tsx
+```

package/dist/checker.d.ts

@@ -0,0 +1,35 @@
+/**
+ * TypeScript Checker — runs tsc to detect type errors.
+ * Replaces the container-based type checking from the gateway.
+ *
+ * Uses the TypeScript compiler API or `npx tsc --noEmit` for checking.
+ */
+import { type StructuredError } from './errorStore.js';
+export interface CheckerOptions {
+    projectDir: string;
+    projectId: string;
+}
+export declare class Checker {
+    private projectDir;
+    private projectId;
+    constructor(options: CheckerOptions);
+    /**
+     * Run TypeScript type checking on the project.
+     * Returns structured errors.
+     */
+    checkTypes(filterFiles?: string[]): Promise<StructuredError[]>;
+    /**
+     * Run a full check: type check + collect build errors from Vite stderr.
+     */
+    fullCheck(filterFiles?: string[]): Promise<{
+        typeErrors: StructuredError[];
+        allErrors: StructuredError[];
+    }>;
+    /**
+     * Validate hard patterns in source code (fast, stateless).
+     * Checks for common anti-patterns that break builds.
+     */
+    validateHardPatterns(filePath: string, code: string): Promise<StructuredError[]>;
+    private runTsc;
+    private parseTscOutput;
+}

package/dist/checker.js

@@ -0,0 +1,151 @@
+/**
+ * TypeScript Checker — runs tsc to detect type errors.
+ * Replaces the container-based type checking from the gateway.
+ *
+ * Uses the TypeScript compiler API or `npx tsc --noEmit` for checking.
+ */
+import { spawn } from 'child_process';
+import path from 'path';
+import { existsSync } from 'fs';
+import { parseErrorString } from './errorStore.js';
+export class Checker {
+    projectDir;
+    projectId;
+    constructor(options) {
+        this.projectDir = options.projectDir;
+        this.projectId = options.projectId;
+    }
+    /**
+     * Run TypeScript type checking on the project.
+     * Returns structured errors.
+     */
+    async checkTypes(filterFiles) {
+        const tsconfigPath = path.join(this.projectDir, 'tsconfig.json');
+        if (!existsSync(tsconfigPath)) {
+            // No tsconfig — skip type checking
+            return [];
+        }
+        try {
+            const output = await this.runTsc(filterFiles);
+            return this.parseTscOutput(output, filterFiles);
+        }
+        catch (err) {
+            console.error(`  [Checker] Type check failed: ${err.message}`);
+            return [];
+        }
+    }
+    /**
+     * Run a full check: type check + collect build errors from Vite stderr.
+     */
+    async fullCheck(filterFiles) {
+        const typeErrors = await this.checkTypes(filterFiles);
+        const allErrors = [...typeErrors];
+        // Deduplicate
+        const seen = new Set();
+        const deduped = allErrors.filter(e => {
+            if (seen.has(e.signature))
+                return false;
+            seen.add(e.signature);
+            return true;
+        });
+        return { typeErrors, allErrors: deduped };
+    }
+    /**
+     * Validate hard patterns in source code (fast, stateless).
+     * Checks for common anti-patterns that break builds.
+     */
+    async validateHardPatterns(filePath, code) {
+        const errors = [];
+        // Check for common issues
+        const lines = code.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const lineNum = i + 1;
+            // Detect require() in ES module context
+            if (/\brequire\s*\(/.test(line) && !line.includes('// eslint-disable')) {
+                // Only flag if it's not in a comment
+                const trimmed = line.trim();
+                if (!trimmed.startsWith('//') && !trimmed.startsWith('*')) {
+                    errors.push({
+                        file: filePath,
+                        line: lineNum,
+                        message: 'require() is not allowed in ES modules. Use import instead.',
+                        type: 'hard',
+                        signature: `hard:${filePath}:${lineNum}:require-in-esm`,
+                    });
+                }
+            }
+            // Detect document/window in server-side code
+            if (filePath.startsWith('server/') && (/\bdocument\b/.test(line) || /\bwindow\b/.test(line))) {
+                const trimmed = line.trim();
+                if (!trimmed.startsWith('//') && !trimmed.startsWith('*')) {
+                    errors.push({
+                        file: filePath,
+                        line: lineNum,
+                        message: 'Browser APIs (document/window) cannot be used in server-side code.',
+                        type: 'hard',
+                        signature: `hard:${filePath}:${lineNum}:browser-api-in-server`,
+                    });
+                }
+            }
+        }
+        return errors;
+    }
+    runTsc(filterFiles) {
+        return new Promise((resolve) => {
+            const args = ['tsc', '--noEmit', '--pretty', 'false'];
+            // If filtering specific files, pass them directly
+            // Otherwise use the project tsconfig
+            if (filterFiles && filterFiles.length > 0 && filterFiles.length <= 10) {
+                // For a small number of files, check them directly
+                // This is faster than checking the whole project
+                args.push('--project', path.join(this.projectDir, 'tsconfig.json'));
+            }
+            const proc = spawn('npx', args, {
+                cwd: this.projectDir,
+                env: { ...process.env, NODE_OPTIONS: '--max-old-space-size=512' },
+                shell: true,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let stderr = '';
+            proc.stdout?.on('data', (d) => { stdout += d.toString(); });
+            proc.stderr?.on('data', (d) => { stderr += d.toString(); });
+            proc.on('close', () => {
+                // tsc outputs errors to stdout
+                resolve(stdout || stderr);
+            });
+            proc.on('error', () => {
+                resolve(stderr || stdout);
+            });
+            // Timeout after 30 seconds
+            setTimeout(() => {
+                try {
+                    proc.kill();
+                }
+                catch { }
+                resolve(stdout || stderr || 'Type check timed out');
+            }, 30_000);
+        });
+    }
+    parseTscOutput(output, filterFiles) {
+        if (!output.trim())
+            return [];
+        const lines = output.split('\n').filter(l => l.trim());
+        const errors = [];
+        const filterSet = filterFiles ? new Set(filterFiles.map(f => f.replace(/^\.\//, ''))) : null;
+        for (const line of lines) {
+            // Skip non-error lines
+            if (!line.includes('error TS') && !line.includes('warning TS'))
+                continue;
+            const parsed = parseErrorString(line, 'type');
+            // Filter to relevant files if specified
+            if (filterSet && parsed.file && !filterSet.has(parsed.file)) {
+                continue;
+            }
+            errors.push(parsed);
+        }
+        return errors;
+    }
+}
+//# sourceMappingURL=checker.js.map

package/dist/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * nstantpage-agent CLI
+ *
+ * Usage:
+ *   nstantpage login              — Authenticate with nstantpage.com
+ *   nstantpage start [dir]        — Start agent for a project directory
+ *   nstantpage stop               — Stop running agent
+ *   nstantpage status             — Show agent status
+ *
+ * The agent replaces Docker containers — your project runs natively on your
+ * machine with full performance, and the cloud editor connects through a tunnel.
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * nstantpage-agent CLI
+ *
+ * Usage:
+ *   nstantpage login              — Authenticate with nstantpage.com
+ *   nstantpage start [dir]        — Start agent for a project directory
+ *   nstantpage stop               — Stop running agent
+ *   nstantpage status             — Show agent status
+ *
+ * The agent replaces Docker containers — your project runs natively on your
+ * machine with full performance, and the cloud editor connects through a tunnel.
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { loginCommand } from './commands/login.js';
+import { startCommand } from './commands/start.js';
+import { statusCommand } from './commands/status.js';
+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.2.0');
+program
+    .command('login')
+    .description('Authenticate with nstantpage.com')
+    .action(loginCommand);
+program
+    .command('start')
+    .description('Start the agent for a project (replaces cloud containers)')
+    .argument('[directory]', 'Project directory (defaults to current directory)', '.')
+    .option('-p, --port <port>', 'Local dev server port', '3000')
+    .option('-a, --api-port <port>', 'Local API server port (internal)', '18924')
+    .option('--project-id <id>', 'Link to a specific project ID')
+    .option('--gateway <url>', 'Gateway URL', 'wss://webprev.live')
+    .option('--no-dev', 'Skip starting the dev server (start manually later)')
+    .action(startCommand);
+program
+    .command('stop')
+    .description('Stop the running agent')
+    .action(async () => {
+    console.log(chalk.yellow('Stopping agent...'));
+    // Send SIGTERM to running agent process
+    const { getConfig } = await import('./config.js');
+    const conf = getConfig();
+    const pid = conf.get('agentPid');
+    if (pid) {
+        try {
+            process.kill(pid, 'SIGTERM');
+            conf.delete('agentPid');
+            console.log(chalk.green('Agent stopped'));
+        }
+        catch {
+            console.log(chalk.gray('Agent was not running'));
+            conf.delete('agentPid');
+        }
+    }
+    else {
+        console.log(chalk.gray('No agent running'));
+    }
+});
+program
+    .command('status')
+    .description('Show agent status')
+    .action(statusCommand);
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/commands/login.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Login command — authenticate with nstantpage.com
+ */
+export declare function loginCommand(): Promise<void>;

package/dist/commands/login.js

@@ -0,0 +1,62 @@
+/**
+ * Login command — authenticate with nstantpage.com
+ */
+import chalk from 'chalk';
+import open from 'open';
+import http from 'http';
+import { getConfig } from '../config.js';
+export async function loginCommand() {
+    const conf = getConfig();
+    // Check if already logged in
+    const existingToken = conf.get('token');
+    if (existingToken) {
+        console.log(chalk.green('✓ Already authenticated'));
+        console.log(chalk.gray('  Run "nstantpage login --force" to re-authenticate'));
+        return;
+    }
+    console.log(chalk.blue('🔐 Authenticating with nstantpage.com...\n'));
+    // Start local callback server
+    const callbackPort = 18923;
+    const token = await new Promise((resolve, reject) => {
+        const server = http.createServer((req, res) => {
+            const url = new URL(req.url, `http://localhost:${callbackPort}`);
+            const token = url.searchParams.get('token');
+            if (token) {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end(`
+          <html>
+            <body style="font-family: sans-serif; display: flex; align-items: center; justify-content: center; height: 100vh; margin: 0; background: #0f172a; color: #f8fafc;">
+              <div style="text-align: center;">
+                <h1>✓ Authenticated!</h1>
+                <p>You can close this tab and return to the terminal.</p>
+              </div>
+            </body>
+          </html>
+        `);
+                server.close();
+                resolve(token);
+            }
+            else {
+                res.writeHead(400);
+                res.end('Missing token');
+            }
+        });
+        server.listen(callbackPort, () => {
+            const loginUrl = `https://nstantpage.com/auth/agent?callback=http://localhost:${callbackPort}/callback`;
+            console.log(chalk.gray(`  Opening browser to authenticate...`));
+            console.log(chalk.gray(`  If browser doesn't open, visit: ${loginUrl}\n`));
+            open(loginUrl).catch(() => {
+                // Browser didn't open, user can copy URL
+            });
+        });
+        // Timeout after 5 minutes
+        setTimeout(() => {
+            server.close();
+            reject(new Error('Authentication timed out'));
+        }, 5 * 60 * 1000);
+    });
+    conf.set('token', token);
+    console.log(chalk.green('\n✓ Successfully authenticated!'));
+    console.log(chalk.gray('  Run "nstantpage start" to connect a project'));
+}
+//# sourceMappingURL=login.js.map

package/dist/commands/start.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Start command — launch the nstantpage agent
+ *
+ * Architecture:
+ * 1. Start local API server (handles /live/* requests for file sync, checks, etc.)
+ * 2. Start local dev server (Vite/Next.js — runs project on user's machine)
+ * 3. Connect tunnel to gateway (relays requests from cloud to local machine)
+ *
+ * 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
+ */
+interface StartOptions {
+    port: string;
+    apiPort: string;
+    projectId?: string;
+    gateway: string;
+    noDev?: boolean;
+}
+export declare function startCommand(directory: string, options: StartOptions): Promise<void>;
+export {};