vigthoria-cli 1.6.53 → 1.6.55

package/dist/commands/chat.js

@@ -47,6 +47,7 @@ const api_js_1 = require("../utils/api.js");
 const tools_js_1 = require("../utils/tools.js");
 const session_js_1 = require("../utils/session.js");
 const bridge_client_js_1 = require("../utils/bridge-client.js");
+const workspace_stream_js_1 = require("../utils/workspace-stream.js");
 const DEFAULT_V3_AGENT_TIMEOUT_MS = (() => {
     const rawValue = process.env.VIGTHORIA_AGENT_TIMEOUT_MS || process.env.V3_AGENT_TIMEOUT_MS || '3900000';
     const parsed = Number.parseInt(rawValue, 10);
@@ -1442,6 +1443,17 @@ class ChatCommand {
             targetPath: this.currentProjectPath,
             ...runtimeContext,
         };
+        // Start workspace watcher for bidirectional real-time sync
+        let watcher = null;
+        if (this.currentProjectPath && fs.existsSync(this.currentProjectPath)) {
+            watcher = new workspace_stream_js_1.WorkspaceWatcher({
+                workspaceRoot: this.currentProjectPath,
+                onFileChange: (relativePath, content, action) => {
+                    this.logger.debug(`Local change detected: ${action} ${relativePath}`);
+                },
+            });
+            watcher.start();
+        }
         try {
             const workflowPromise = this.api.runV3AgentWorkflow(executionPrompt, {
                 workspace: { path: this.currentProjectPath },
@@ -1484,6 +1496,7 @@ class ChatCommand {
                     }
                     this.logger.warn('Falling back to legacy CLI agent loop');
                     this.logger.debug(`V3 agent workflow returned an incomplete result: ${previewGate?.error || 'workspace changes were not fully validated'}`);
+                    watcher?.stop();
                     return false;
                 }
                 const errorMessage = `V3 agent workflow returned an incomplete result and legacy fallback is disabled. ${previewGate?.error || 'Workspace changes were not fully validated.'}`;
@@ -1504,6 +1517,7 @@ class ChatCommand {
                         metadata: { executionPath: 'v3-agent', previewGate },
                     }, null, 2));
                 }
+                watcher?.stop();
                 return true;
             }
             if (!this.jsonOutput && previewGate?.required && previewGate?.passed !== true && workspaceHasOutput) {
@@ -1542,10 +1556,26 @@ class ChatCommand {
                     console.log(chalk_1.default.yellow(`Template Service preview gate: failed${previewGate.error ? ` - ${previewGate.error}` : ''}`));
                 }
             }
+            // Show change summary for files touched by the agent
+            if (!this.jsonOutput && !this.directPromptMode && response.changedFiles) {
+                const fileCount = Object.keys(response.changedFiles).length;
+                if (fileCount > 0) {
+                    console.log(chalk_1.default.gray(`\nFiles changed: ${fileCount}`));
+                    for (const relPath of Object.keys(response.changedFiles).slice(0, 15)) {
+                        console.log(chalk_1.default.gray(`  ${chalk_1.default.green('+')} ${relPath}`));
+                    }
+                    if (fileCount > 15) {
+                        console.log(chalk_1.default.gray(`  ... and ${fileCount - 15} more`));
+                    }
+                    console.log(chalk_1.default.gray(`Run ${chalk_1.default.cyan('vigthoria preview --diff')} for full visual diffs.`));
+                }
+            }
             this.messages.push({ role: 'assistant', content: response.content || 'V3 agent workflow completed.' });
+            watcher?.stop();
             return true;
         }
         catch (error) {
+            watcher?.stop();
             if (rescueEligible && !this.api.hasAgentWorkspaceOutput(workspaceContext)) {
                 const rescued = await this.tryCommandLevelSaaSRescue(executionPrompt, prompt, workspaceContext, routingPolicy, spinner, error);
                 if (rescued) {

package/dist/commands/preview.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Vigthoria CLI - Preview Command
+ *
+ * Local preview server + consolidated visual diffs + Template Service proof gate
+ *
+ * Usage:
+ *   vigthoria preview                     - Preview project in browser
+ *   vigthoria preview --diff              - Show consolidated diff of recent agent changes
+ *   vigthoria preview --proof             - Run Template Service preview gate
+ *   vigthoria preview -p /path/to/project - Preview specific project
+ */
+import { Config } from '../utils/config.js';
+import { Logger } from '../utils/logger.js';
+interface PreviewOptions {
+    project: string;
+    entry?: string;
+    port?: number;
+    open?: boolean;
+    diff?: boolean;
+    proof?: boolean;
+    screenshot?: boolean;
+}
+export declare class PreviewCommand {
+    private config;
+    private logger;
+    private api;
+    private server;
+    constructor(config: Config, logger: Logger);
+    run(options: PreviewOptions): Promise<void>;
+    /**
+     * Detect the HTML entry file in the project
+     */
+    private detectEntryFile;
+    /**
+     * Find an available port starting from the given number
+     */
+    private findAvailablePort;
+    /**
+     * Start a local HTTP server for preview
+     */
+    private startServer;
+    /**
+     * Open URL in default browser
+     */
+    private openBrowser;
+    /**
+     * Show consolidated diff of recent agent changes using git
+     */
+    showConsolidatedDiff(projectPath: string): Promise<void>;
+    /**
+     * Run Template Service preview gate and persist proof bundle
+     */
+    private runProofGate;
+}
+export {};

package/dist/commands/preview.js

@@ -0,0 +1,478 @@
+"use strict";
+/**
+ * Vigthoria CLI - Preview Command
+ *
+ * Local preview server + consolidated visual diffs + Template Service proof gate
+ *
+ * Usage:
+ *   vigthoria preview                     - Preview project in browser
+ *   vigthoria preview --diff              - Show consolidated diff of recent agent changes
+ *   vigthoria preview --proof             - Run Template Service preview gate
+ *   vigthoria preview -p /path/to/project - Preview specific project
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PreviewCommand = void 0;
+const chalk_1 = __importDefault(require("chalk"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const http = __importStar(require("http"));
+const diff_1 = require("diff");
+const logger_js_1 = require("../utils/logger.js");
+const api_js_1 = require("../utils/api.js");
+// Common MIME types for static file serving
+const MIME_TYPES = {
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.css': 'text/css',
+    '.js': 'application/javascript',
+    '.mjs': 'application/javascript',
+    '.json': 'application/json',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.webp': 'image/webp',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.eot': 'application/vnd.ms-fontobject',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.pdf': 'application/pdf',
+    '.xml': 'application/xml',
+    '.txt': 'text/plain',
+    '.map': 'application/json',
+};
+class PreviewCommand {
+    config;
+    logger;
+    api;
+    server = null;
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+        this.api = new api_js_1.APIClient(config, logger);
+    }
+    async run(options) {
+        const projectPath = path.resolve(options.project || process.cwd());
+        if (!fs.existsSync(projectPath) || !fs.statSync(projectPath).isDirectory()) {
+            this.logger.error(`Project directory not found: ${projectPath}`);
+            this.api.destroy();
+            return;
+        }
+        console.log();
+        console.log(chalk_1.default.bold.white(`  ${logger_js_1.CH.hLine.repeat(3)} Vigthoria Preview ${logger_js_1.CH.hLine.repeat(40)}`));
+        console.log(chalk_1.default.gray(`  Project: ${projectPath}`));
+        console.log();
+        // Show consolidated diff of recent agent changes
+        if (options.diff) {
+            await this.showConsolidatedDiff(projectPath);
+        }
+        // Run Template Service preview proof gate
+        if (options.proof) {
+            await this.runProofGate(projectPath, options.screenshot);
+        }
+        // If only --diff or --proof without a preview server, exit
+        if ((options.diff || options.proof) && options.open === false) {
+            this.api.destroy();
+            return;
+        }
+        // Detect entry file
+        const entryFile = this.detectEntryFile(projectPath, options.entry);
+        if (!entryFile) {
+            this.logger.warn('No HTML entry file found. Use --entry <file> to specify one.');
+            if (!options.diff && !options.proof) {
+                this.api.destroy();
+                return;
+            }
+            this.api.destroy();
+            return;
+        }
+        // Start local preview server
+        const port = options.port || (await this.findAvailablePort(3500));
+        await this.startServer(projectPath, entryFile, port, options.open !== false);
+    }
+    /**
+     * Detect the HTML entry file in the project
+     */
+    detectEntryFile(projectPath, specified) {
+        if (specified) {
+            const fullPath = path.join(projectPath, specified);
+            if (fs.existsSync(fullPath))
+                return specified;
+            this.logger.warn(`Specified entry file not found: ${specified}`);
+            return null;
+        }
+        // Common entry point candidates
+        const candidates = [
+            'index.html',
+            'public/index.html',
+            'dist/index.html',
+            'build/index.html',
+            'src/index.html',
+            'out/index.html',
+        ];
+        for (const candidate of candidates) {
+            if (fs.existsSync(path.join(projectPath, candidate))) {
+                return candidate;
+            }
+        }
+        // Fallback: find any .html file at root
+        try {
+            const rootFiles = fs.readdirSync(projectPath);
+            const htmlFile = rootFiles.find(f => f.endsWith('.html'));
+            if (htmlFile)
+                return htmlFile;
+        }
+        catch { /* ignore */ }
+        return null;
+    }
+    /**
+     * Find an available port starting from the given number
+     */
+    findAvailablePort(startPort) {
+        return new Promise((resolve) => {
+            const testServer = http.createServer();
+            testServer.on('error', () => {
+                resolve(this.findAvailablePort(startPort + 1));
+            });
+            testServer.listen(startPort, () => {
+                testServer.close(() => resolve(startPort));
+            });
+        });
+    }
+    /**
+     * Start a local HTTP server for preview
+     */
+    async startServer(projectPath, entryFile, port, autoOpen) {
+        return new Promise((resolve) => {
+            this.server = http.createServer((req, res) => {
+                // Sanitize URL to prevent path traversal
+                const urlPath = decodeURIComponent(new URL(req.url || '/', `http://localhost:${port}`).pathname);
+                const safePath = path.normalize(urlPath).replace(/^(\.\.[/\\])+/, '');
+                let filePath = path.join(projectPath, safePath);
+                // Ensure the resolved path is within the project directory
+                const resolvedPath = path.resolve(filePath);
+                if (!resolvedPath.startsWith(path.resolve(projectPath))) {
+                    res.writeHead(403);
+                    res.end('Forbidden');
+                    return;
+                }
+                // Directory → serve index.html
+                if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
+                    filePath = path.join(filePath, 'index.html');
+                }
+                // SPA fallback
+                if (!fs.existsSync(filePath)) {
+                    const spaFallback = path.join(projectPath, entryFile);
+                    if (fs.existsSync(spaFallback)) {
+                        filePath = spaFallback;
+                    }
+                    else {
+                        res.writeHead(404);
+                        res.end('Not found');
+                        return;
+                    }
+                }
+                const ext = path.extname(filePath).toLowerCase();
+                const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+                try {
+                    const content = fs.readFileSync(filePath);
+                    res.writeHead(200, { 'Content-Type': contentType });
+                    res.end(content);
+                }
+                catch {
+                    res.writeHead(500);
+                    res.end('Internal server error');
+                }
+            });
+            this.server.listen(port, () => {
+                const url = `http://localhost:${port}/${entryFile}`;
+                console.log(chalk_1.default.green(`  ${logger_js_1.CH.success} Preview server running`));
+                console.log(chalk_1.default.gray(`  URL: `) + chalk_1.default.cyan.underline(url));
+                console.log(chalk_1.default.gray(`  Entry: ${entryFile}`));
+                console.log(chalk_1.default.gray(`  Press Ctrl+C to stop`));
+                console.log();
+                if (autoOpen) {
+                    this.openBrowser(url);
+                }
+            });
+            // Handle graceful shutdown
+            const shutdown = () => {
+                console.log(chalk_1.default.gray('\n  Stopping preview server...'));
+                this.server?.close();
+                this.api.destroy();
+                resolve();
+            };
+            process.on('SIGINT', shutdown);
+            process.on('SIGTERM', shutdown);
+        });
+    }
+    /**
+     * Open URL in default browser
+     */
+    openBrowser(url) {
+        const { exec } = require('child_process');
+        const platform = process.platform;
+        const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start' : 'xdg-open';
+        exec(`${cmd} ${url}`, (err) => {
+            if (err) {
+                this.logger.debug(`Could not auto-open browser: ${err.message}`);
+            }
+        });
+    }
+    /**
+     * Show consolidated diff of recent agent changes using git
+     */
+    async showConsolidatedDiff(projectPath) {
+        console.log(chalk_1.default.bold.white(`  ${logger_js_1.CH.hLine.repeat(3)} Change Summary ${logger_js_1.CH.hLine.repeat(43)}`));
+        console.log();
+        const proofDir = path.join(projectPath, '.vigthoria', 'proof', 'preview');
+        const hasProof = fs.existsSync(proofDir);
+        // Try git diff first (most reliable)
+        try {
+            const { execSync } = require('child_process');
+            const isGit = fs.existsSync(path.join(projectPath, '.git'));
+            if (isGit) {
+                // Get list of changed files (unstaged + staged)
+                const statusOutput = execSync('git status --porcelain', { cwd: projectPath, encoding: 'utf-8' }).trim();
+                if (!statusOutput) {
+                    console.log(chalk_1.default.gray('  No changes detected (working tree clean).'));
+                    console.log();
+                    return;
+                }
+                const changedLines = statusOutput.split('\n').filter(Boolean);
+                const created = [];
+                const modified = [];
+                const deleted = [];
+                for (const line of changedLines) {
+                    const status = line.substring(0, 2).trim();
+                    const filePath = line.substring(3);
+                    if (status === '??' || status === 'A')
+                        created.push(filePath);
+                    else if (status === 'D')
+                        deleted.push(filePath);
+                    else
+                        modified.push(filePath);
+                }
+                // Summary header
+                const total = created.length + modified.length + deleted.length;
+                console.log(chalk_1.default.white(`  ${total} file${total !== 1 ? 's' : ''} changed:`));
+                for (const f of created)
+                    console.log(chalk_1.default.green(`    + ${f}`));
+                for (const f of modified)
+                    console.log(chalk_1.default.yellow(`    ~ ${f}`));
+                for (const f of deleted)
+                    console.log(chalk_1.default.red(`    - ${f}`));
+                console.log();
+                // Show unified diffs for modified and created files (limit to keep terminal manageable)
+                const diffTargets = [...modified, ...created].slice(0, 20);
+                for (const relPath of diffTargets) {
+                    const absPath = path.join(projectPath, relPath);
+                    if (!fs.existsSync(absPath))
+                        continue;
+                    const ext = path.extname(relPath).toLowerCase();
+                    const textExts = ['.html', '.css', '.js', '.ts', '.jsx', '.tsx', '.json', '.md', '.yml', '.yaml', '.txt', '.xml', '.svg', '.py', '.sh', '.env'];
+                    if (!textExts.includes(ext))
+                        continue;
+                    try {
+                        const newContent = fs.readFileSync(absPath, 'utf-8');
+                        let oldContent = '';
+                        if (modified.includes(relPath)) {
+                            try {
+                                oldContent = execSync(`git show HEAD:${relPath}`, { cwd: projectPath, encoding: 'utf-8' });
+                            }
+                            catch {
+                                // File is new or not tracked
+                            }
+                        }
+                        const patch = (0, diff_1.structuredPatch)(relPath, relPath, oldContent, newContent, 'before', 'after', { context: 3 });
+                        if (patch.hunks.length === 0)
+                            continue;
+                        console.log(chalk_1.default.bold.white(`  ${logger_js_1.CH.hLine.repeat(3)} ${relPath} ${logger_js_1.CH.hLine.repeat(Math.max(1, 50 - relPath.length))}`));
+                        console.log(chalk_1.default.gray(`  --- a/${relPath}`));
+                        console.log(chalk_1.default.gray(`  +++ b/${relPath}`));
+                        for (const hunk of patch.hunks) {
+                            console.log(chalk_1.default.cyan(`  @@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`));
+                            for (const line of hunk.lines) {
+                                if (line.startsWith('+')) {
+                                    console.log(chalk_1.default.green(`  ${line}`));
+                                }
+                                else if (line.startsWith('-')) {
+                                    console.log(chalk_1.default.red(`  ${line}`));
+                                }
+                                else {
+                                    console.log(chalk_1.default.gray(`  ${line}`));
+                                }
+                            }
+                        }
+                        console.log();
+                    }
+                    catch {
+                        // Skip files that can't be diffed
+                    }
+                }
+                if (diffTargets.length < modified.length + created.length) {
+                    console.log(chalk_1.default.gray(`  ... and ${modified.length + created.length - diffTargets.length} more files`));
+                    console.log();
+                }
+                return;
+            }
+        }
+        catch {
+            // git not available, fall through
+        }
+        // Fallback: list .vigthoria/proof manifests
+        if (hasProof) {
+            const manifests = fs.readdirSync(proofDir)
+                .filter(f => f.endsWith('.json'))
+                .sort()
+                .reverse()
+                .slice(0, 5);
+            if (manifests.length > 0) {
+                console.log(chalk_1.default.white('  Recent proof bundles:'));
+                for (const m of manifests) {
+                    try {
+                        const manifest = JSON.parse(fs.readFileSync(path.join(proofDir, m), 'utf-8'));
+                        const passed = manifest.previewGate?.passed ? chalk_1.default.green('passed') : chalk_1.default.red('failed');
+                        console.log(chalk_1.default.gray(`    ${manifest.createdAt || m}  `) + passed + chalk_1.default.gray(`  ${manifest.entryPath || '-'}`));
+                    }
+                    catch {
+                        console.log(chalk_1.default.gray(`    ${m}`));
+                    }
+                }
+                console.log();
+            }
+        }
+        else {
+            console.log(chalk_1.default.gray('  No git history or proof bundles found.'));
+            console.log(chalk_1.default.gray('  Run an agent task first to generate changes.'));
+            console.log();
+        }
+    }
+    /**
+     * Run Template Service preview gate and persist proof bundle
+     */
+    async runProofGate(projectPath, captureScreenshot) {
+        const spinner = (0, logger_js_1.createSpinner)('Running preview proof gate...').start();
+        try {
+            const result = await this.api.runTemplateServicePreviewGate('', {
+                workspacePath: projectPath,
+                projectPath: projectPath,
+                targetPath: projectPath,
+            });
+            spinner.stop();
+            console.log(chalk_1.default.bold.white(`  ${logger_js_1.CH.hLine.repeat(3)} Preview Proof Gate ${logger_js_1.CH.hLine.repeat(39)}`));
+            console.log();
+            if (!result.required) {
+                console.log(chalk_1.default.gray('  Preview gate: not required (no frontend artifacts detected)'));
+                console.log();
+                return;
+            }
+            const statusIcon = result.passed ? chalk_1.default.green(logger_js_1.CH.success) : chalk_1.default.red(logger_js_1.CH.error);
+            console.log(`  ${statusIcon} Preview gate: ${result.passed ? chalk_1.default.green('PASSED') : chalk_1.default.red('FAILED')}`);
+            if (result.error) {
+                console.log(chalk_1.default.yellow(`  Error: ${result.error}`));
+            }
+            // Show modes
+            if (result.modes) {
+                const modes = result.modes;
+                console.log();
+                if (modes.design) {
+                    const designStatus = modes.design.ready ? chalk_1.default.green('ready') : chalk_1.default.gray('not ready');
+                    console.log(chalk_1.default.gray(`  Design mode:     `) + designStatus);
+                    if (modes.design.devices) {
+                        console.log(chalk_1.default.gray(`    Devices: ${modes.design.devices.join(', ')}`));
+                    }
+                }
+                if (modes.live) {
+                    const liveStatus = modes.live.ready ? chalk_1.default.green('ready') : chalk_1.default.gray('not ready');
+                    console.log(chalk_1.default.gray(`  Live mode:       `) + liveStatus);
+                    if (modes.live.entryPoint) {
+                        console.log(chalk_1.default.gray(`    Entry: ${modes.live.entryPoint}`));
+                    }
+                }
+                if (modes.production) {
+                    const prodStatus = modes.production.ready ? chalk_1.default.green('ready') : chalk_1.default.gray('not ready');
+                    console.log(chalk_1.default.gray(`  Production mode: `) + prodStatus);
+                }
+            }
+            // Show summary
+            if (result.summary) {
+                console.log();
+                const summary = result.summary;
+                if (summary.hasViewportMeta !== undefined) {
+                    console.log(chalk_1.default.gray(`  Viewport meta:    `) + (summary.hasViewportMeta ? chalk_1.default.green('yes') : chalk_1.default.yellow('missing')));
+                }
+                if (summary.hasResponsiveSignals !== undefined) {
+                    console.log(chalk_1.default.gray(`  Responsive CSS:   `) + (summary.hasResponsiveSignals ? chalk_1.default.green('yes') : chalk_1.default.gray('no')));
+                }
+                if (summary.hasInteractiveSignals !== undefined) {
+                    console.log(chalk_1.default.gray(`  Interactive JS:   `) + (summary.hasInteractiveSignals ? chalk_1.default.green('yes') : chalk_1.default.gray('no')));
+                }
+                if (typeof summary.sectionCount === 'number') {
+                    console.log(chalk_1.default.gray(`  Section count:    ${summary.sectionCount}`));
+                }
+            }
+            // Show artifacts
+            if (result.artifacts) {
+                console.log();
+                if (result.artifacts.manifestPath) {
+                    console.log(chalk_1.default.gray(`  Manifest: ${result.artifacts.manifestPath}`));
+                }
+                if (result.artifacts.screenshotCaptured && result.artifacts.screenshotPath) {
+                    console.log(chalk_1.default.gray(`  Screenshot: ${result.artifacts.screenshotPath}`));
+                }
+                if (result.artifacts.previewFileUrl) {
+                    console.log(chalk_1.default.gray(`  File URL: `) + chalk_1.default.cyan.underline(result.artifacts.previewFileUrl));
+                }
+            }
+            console.log();
+        }
+        catch (error) {
+            spinner.stop();
+            this.logger.error(`Preview proof gate failed: ${error?.message || String(error)}`);
+        }
+    }
+}
+exports.PreviewCommand = PreviewCommand;

package/dist/index.js

@@ -66,6 +66,7 @@ const repo_js_1 = require("./commands/repo.js");
 const deploy_js_1 = require("./commands/deploy.js");
 const bridge_js_1 = require("./commands/bridge.js");
 const workflow_js_1 = require("./commands/workflow.js");
+const preview_js_1 = require("./commands/preview.js");
 const config_js_2 = require("./utils/config.js");
 const logger_js_1 = require("./utils/logger.js");
 const chalk_1 = __importDefault(require("chalk"));
@@ -661,6 +662,29 @@ async function main() {
             project: options.project
         });
     });
+    // ==================== PREVIEW COMMAND ====================
+    program
+        .command('preview')
+        .description('Preview project locally with visual diffs and proof validation')
+        .option('-p, --project <path>', 'Project directory path', process.cwd())
+        .option('-e, --entry <file>', 'Entry HTML file (auto-detected if omitted)')
+        .option('--port <number>', 'Local server port', parseInt)
+        .option('--no-open', 'Do not auto-open browser')
+        .option('--diff', 'Show consolidated diff of recent agent changes')
+        .option('--proof', 'Run Template Service preview gate and persist proof bundle')
+        .option('--screenshot', 'Capture screenshot via Puppeteer')
+        .action(async (options) => {
+        const preview = new preview_js_1.PreviewCommand(config, logger);
+        await preview.run({
+            project: options.project,
+            entry: options.entry,
+            port: options.port,
+            open: options.open,
+            diff: options.diff,
+            proof: options.proof,
+            screenshot: options.screenshot,
+        });
+    });
     // ==================== AUTH COMMANDS ====================
     // Auth commands
     program

package/dist/utils/api.d.ts

@@ -39,6 +39,7 @@ export interface V3AgentWorkflowResponse {
     contextId?: string | null;
     backendUrl: string;
     partial?: boolean;
+    changedFiles?: Record<string, string>;
     metadata?: Record<string, unknown>;
 }
 export interface FrontendPreviewGateResult {

package/dist/utils/api.js

@@ -17,6 +17,7 @@ const https_1 = __importDefault(require("https"));
 const net_1 = __importDefault(require("net"));
 const path_1 = __importDefault(require("path"));
 const ws_1 = __importDefault(require("ws"));
+const workspace_stream_js_1 = require("./workspace-stream.js");
 class CLIError extends Error {
     category;
     statusCode;
@@ -2636,6 +2637,19 @@ document.addEventListener('DOMContentLoaded', () => {
                     serverWorkspaceRoot = event.workspace_root.trim();
                 }
                 this.captureV3AgentStreamMutation(event, streamedFiles, serverWorkspaceRoot);
+                // Real-time workspace streaming: apply file mutations to local disk immediately
+                if (event.type === 'file_mutation') {
+                    const localRoot = context.projectPath || context.workspacePath || context.targetPath;
+                    if (localRoot && typeof event.path === 'string') {
+                        (0, workspace_stream_js_1.applyFileMutation)(event, localRoot);
+                        if (typeof event.content === 'string') {
+                            const relPath = this.normalizeAgentWorkspaceRelativePath(event.path, serverWorkspaceRoot || undefined);
+                            if (relPath) {
+                                streamedFiles[relPath] = event.content;
+                            }
+                        }
+                    }
+                }
                 // Empty workspace guard: if the remote agent lists its root
                 // and finds nothing while our local workspace has files, the
                 // workspace was not hydrated. Abort early with a clear error
@@ -2817,6 +2831,7 @@ document.addEventListener('DOMContentLoaded', () => {
                             contextId: finalContextId,
                             backendUrl: baseUrl,
                             partial: continuationData.checkpointed === true,
+                            changedFiles: continuationData.files || data.files || {},
                             metadata: { source: 'v3-agent', mode: 'agent', contextId: finalContextId, continuations, previewGate },
                         };
                     }
@@ -2835,6 +2850,7 @@ document.addEventListener('DOMContentLoaded', () => {
                         taskId: data.task_id || null,
                         contextId,
                         backendUrl: baseUrl,
+                        changedFiles: data.files || {},
                         metadata: { source: 'v3-agent', mode: 'agent', contextId, mcpContextId, previewGate },
                     };
                 }
@@ -2850,6 +2866,7 @@ document.addEventListener('DOMContentLoaded', () => {
                             contextId: error.partialData.context_id || requestExecutionContext.contextId || executionContext.contextId || null,
                             backendUrl: baseUrl,
                             partial: true,
+                            changedFiles: error.partialData.files || {},
                             metadata: { source: 'v3-agent', mode: 'agent', partial: true, contextId: error.partialData.context_id || requestExecutionContext.contextId || executionContext.contextId || null, mcpContextId: requestExecutionContext.mcpContextId || executionContext.mcpContextId || null, previewGate },
                         };
                     }

package/dist/utils/workspace-stream.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Workspace Stream — Real-time bidirectional file sync between CLI and V3.
+ *
+ * Architecture:
+ *   1. WorkspaceWatcher — chokidar-based file watcher that detects local changes
+ *      and pushes them to V3 via WebSocket.
+ *   2. MutationApplier — receives file_mutation events from V3's SSE stream
+ *      and applies them to the local workspace IN REAL TIME (not at completion).
+ *   3. WorkspaceWSClient — WebSocket client connected to V3's /ws/workspace
+ *      for bidirectional file sync outside the SSE stream.
+ *
+ * Event types (V3 → CLI via SSE):
+ *   {"type": "file_mutation", "path": "rel/path", "content": "...", "action": "write"|"edit", "tool": "write_file"|"edit_file"}
+ *
+ * Event types (CLI → V3 via /ws/workspace):
+ *   {"type": "bind", "context_id": "...", "workspace_root": "..."}
+ *   {"type": "file_sync", "path": "rel/path", "content": "...", "action": "write"|"delete"}
+ *   {"type": "file_batch", "files": [{path, content}, ...]}
+ */
+/**
+ * Apply a file_mutation event from V3's SSE stream to the local workspace.
+ * Call this from the SSE event handler for real-time file application.
+ */
+export declare function applyFileMutation(event: {
+    type: string;
+    path: string;
+    content: string;
+    action: string;
+}, workspaceRoot: string): boolean;
+export interface WatcherOptions {
+    workspaceRoot: string;
+    onFileChange?: (relativePath: string, content: string | null, action: 'write' | 'delete') => void;
+}
+export declare class WorkspaceWatcher {
+    private watcher;
+    private workspaceRoot;
+    private onFileChange;
+    private _ready;
+    constructor(options: WatcherOptions);
+    start(): void;
+    stop(): void;
+    get isReady(): boolean;
+    private _handleChange;
+}
+export interface WorkspaceWSOptions {
+    serverUrl: string;
+    token: string;
+    contextId: string;
+    workspaceRoot: string;
+    onMutation?: (event: any) => void;
+}
+export declare class WorkspaceWSClient {
+    private ws;
+    private opts;
+    private reconnectTimer;
+    private _connected;
+    private _queue;
+    private _maxQueue;
+    constructor(opts: WorkspaceWSOptions);
+    connect(): void;
+    disconnect(): void;
+    /**
+     * Push a local file change to V3's workspace.
+     */
+    syncFile(relativePath: string, content: string | null, action: 'write' | 'delete'): void;
+    /**
+     * Push multiple files at once.
+     */
+    syncBatch(files: Array<{
+        path: string;
+        content: string;
+    }>): void;
+    get isConnected(): boolean;
+    private _send;
+}

package/dist/utils/workspace-stream.js

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * Workspace Stream — Real-time bidirectional file sync between CLI and V3.
+ *
+ * Architecture:
+ *   1. WorkspaceWatcher — chokidar-based file watcher that detects local changes
+ *      and pushes them to V3 via WebSocket.
+ *   2. MutationApplier — receives file_mutation events from V3's SSE stream
+ *      and applies them to the local workspace IN REAL TIME (not at completion).
+ *   3. WorkspaceWSClient — WebSocket client connected to V3's /ws/workspace
+ *      for bidirectional file sync outside the SSE stream.
+ *
+ * Event types (V3 → CLI via SSE):
+ *   {"type": "file_mutation", "path": "rel/path", "content": "...", "action": "write"|"edit", "tool": "write_file"|"edit_file"}
+ *
+ * Event types (CLI → V3 via /ws/workspace):
+ *   {"type": "bind", "context_id": "...", "workspace_root": "..."}
+ *   {"type": "file_sync", "path": "rel/path", "content": "...", "action": "write"|"delete"}
+ *   {"type": "file_batch", "files": [{path, content}, ...]}
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkspaceWSClient = exports.WorkspaceWatcher = void 0;
+exports.applyFileMutation = applyFileMutation;
+const chokidar = __importStar(require("chokidar"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const ws_1 = __importDefault(require("ws"));
+const logger_js_1 = require("./logger.js");
+const logger = new logger_js_1.Logger();
+logger.setVerbose(!!process.env.VIGTHORIA_DEBUG);
+// Files/dirs to ignore in the watcher
+const IGNORE_PATTERNS = [
+    '**/node_modules/**',
+    '**/.git/**',
+    '**/__pycache__/**',
+    '**/.venv/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/.next/**',
+    '**/.cache/**',
+    '**/.vigthoria/**',
+    '**/coverage/**',
+    '**/*.pyc',
+];
+const BINARY_EXTENSIONS = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.ico', '.svg', '.webp', '.bmp',
+    '.mp3', '.mp4', '.wav', '.ogg', '.webm', '.avi',
+    '.zip', '.tar', '.gz', '.bz2', '.7z', '.rar',
+    '.woff', '.woff2', '.ttf', '.eot', '.otf',
+    '.pdf', '.doc', '.docx', '.xls', '.xlsx',
+    '.pyc', '.pyo', '.so', '.dll', '.exe', '.bin',
+    '.db', '.sqlite', '.sqlite3',
+]);
+const MAX_SYNC_FILE_BYTES = 500 * 1024; // 500 KB
+// ── Mutation Applier ─────────────────────────────────────────
+/**
+ * Tracks files that V3 has mutated so the watcher doesn't echo them back.
+ */
+const _v3MutatedFiles = new Set();
+const _v3MuteTimeout = 2000; // 2s mute window after V3 writes a file
+/**
+ * Apply a file_mutation event from V3's SSE stream to the local workspace.
+ * Call this from the SSE event handler for real-time file application.
+ */
+function applyFileMutation(event, workspaceRoot) {
+    if (event.type !== 'file_mutation')
+        return false;
+    if (!event.path || !workspaceRoot)
+        return false;
+    const absPath = path_1.default.resolve(workspaceRoot, event.path);
+    // Safety: ensure the resolved path is within the workspace
+    if (!absPath.startsWith(path_1.default.resolve(workspaceRoot) + path_1.default.sep) && absPath !== path_1.default.resolve(workspaceRoot)) {
+        logger.warn(`Refusing to apply mutation outside workspace: ${event.path}`);
+        return false;
+    }
+    try {
+        if (event.action === 'delete') {
+            if (fs_1.default.existsSync(absPath)) {
+                fs_1.default.unlinkSync(absPath);
+                logger.debug(`Deleted: ${event.path}`);
+            }
+        }
+        else if (typeof event.content === 'string') {
+            fs_1.default.mkdirSync(path_1.default.dirname(absPath), { recursive: true });
+            fs_1.default.writeFileSync(absPath, event.content, 'utf8');
+            // Mute the watcher for this file to prevent echo
+            _v3MutatedFiles.add(absPath);
+            setTimeout(() => _v3MutatedFiles.delete(absPath), _v3MuteTimeout);
+            logger.debug(`Applied: ${event.path} (${event.action})`);
+        }
+        return true;
+    }
+    catch (err) {
+        logger.error(`Failed to apply mutation for ${event.path}: ${err}`);
+        return false;
+    }
+}
+class WorkspaceWatcher {
+    watcher = null;
+    workspaceRoot;
+    onFileChange;
+    _ready = false;
+    constructor(options) {
+        this.workspaceRoot = path_1.default.resolve(options.workspaceRoot);
+        this.onFileChange = options.onFileChange;
+    }
+    start() {
+        if (this.watcher)
+            return;
+        this.watcher = chokidar.watch(this.workspaceRoot, {
+            ignored: IGNORE_PATTERNS,
+            persistent: true,
+            ignoreInitial: true,
+            awaitWriteFinish: { stabilityThreshold: 300, pollInterval: 100 },
+        });
+        this.watcher
+            .on('ready', () => {
+            this._ready = true;
+            logger.debug('Workspace watcher ready');
+        })
+            .on('add', (filePath) => this._handleChange(filePath, 'write'))
+            .on('change', (filePath) => this._handleChange(filePath, 'write'))
+            .on('unlink', (filePath) => this._handleChange(filePath, 'delete'));
+    }
+    stop() {
+        if (this.watcher) {
+            this.watcher.close();
+            this.watcher = null;
+            this._ready = false;
+        }
+    }
+    get isReady() {
+        return this._ready;
+    }
+    _handleChange(filePath, action) {
+        // Skip if this file was just written by V3 (echo prevention)
+        if (_v3MutatedFiles.has(filePath))
+            return;
+        const ext = path_1.default.extname(filePath).toLowerCase();
+        if (BINARY_EXTENSIONS.has(ext))
+            return;
+        const relativePath = path_1.default.relative(this.workspaceRoot, filePath);
+        if (relativePath.startsWith('..'))
+            return; // safety
+        if (action === 'delete') {
+            this.onFileChange?.(relativePath, null, 'delete');
+            return;
+        }
+        try {
+            const stat = fs_1.default.statSync(filePath);
+            if (stat.size > MAX_SYNC_FILE_BYTES)
+                return;
+            const content = fs_1.default.readFileSync(filePath, 'utf8');
+            this.onFileChange?.(relativePath, content, 'write');
+        }
+        catch {
+            // File might have been deleted between event and read
+        }
+    }
+}
+exports.WorkspaceWatcher = WorkspaceWatcher;
+class WorkspaceWSClient {
+    ws = null;
+    opts;
+    reconnectTimer = null;
+    _connected = false;
+    _queue = [];
+    _maxQueue = 200;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    connect() {
+        if (this.ws)
+            return;
+        const url = `${this.opts.serverUrl}/ws/workspace?token=${encodeURIComponent(this.opts.token)}`;
+        this.ws = new ws_1.default(url);
+        this.ws.on('open', () => {
+            this._connected = true;
+            // Bind to workspace
+            this._send({
+                type: 'bind',
+                context_id: this.opts.contextId,
+                workspace_root: this.opts.workspaceRoot,
+            });
+            // Flush queued messages
+            while (this._queue.length > 0) {
+                const msg = this._queue.shift();
+                this._send(msg);
+            }
+            logger.debug('WS workspace connected');
+        });
+        this.ws.on('message', (data) => {
+            try {
+                const event = JSON.parse(data.toString());
+                if (event.type === 'file_mutation') {
+                    this.opts.onMutation?.(event);
+                }
+            }
+            catch {
+                // ignore parse errors
+            }
+        });
+        this.ws.on('close', () => {
+            this._connected = false;
+            this.ws = null;
+            // Auto-reconnect after 3s
+            this.reconnectTimer = setTimeout(() => this.connect(), 3000);
+        });
+        this.ws.on('error', () => {
+            // error handler to prevent crash, close event handles reconnect
+        });
+    }
+    disconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        this._connected = false;
+    }
+    /**
+     * Push a local file change to V3's workspace.
+     */
+    syncFile(relativePath, content, action) {
+        const msg = {
+            type: 'file_sync',
+            path: relativePath,
+            content: content || '',
+            action,
+        };
+        if (this._connected) {
+            this._send(msg);
+        }
+        else if (this._queue.length < this._maxQueue) {
+            this._queue.push(msg);
+        }
+    }
+    /**
+     * Push multiple files at once.
+     */
+    syncBatch(files) {
+        const msg = { type: 'file_batch', files };
+        if (this._connected) {
+            this._send(msg);
+        }
+        else if (this._queue.length < this._maxQueue) {
+            this._queue.push(msg);
+        }
+    }
+    get isConnected() {
+        return this._connected;
+    }
+    _send(msg) {
+        try {
+            this.ws?.send(JSON.stringify(msg));
+        }
+        catch {
+            // connection lost
+        }
+    }
+}
+exports.WorkspaceWSClient = WorkspaceWSClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigthoria-cli",
-  "version": "1.6.53",
+  "version": "1.6.55",
   "description": "Vigthoria Coder CLI - AI-powered terminal coding assistant",
   "main": "dist/index.js",
   "files": [
@@ -61,6 +61,7 @@
     "archiver": "^6.0.1",
     "axios": "^1.6.0",
     "chalk": "^5.3.0",
+    "chokidar": "^5.0.0",
     "commander": "^11.1.0",
     "conf": "^12.0.0",
     "diff": "^5.1.0",
@@ -86,4 +87,4 @@
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}