agent-stage 0.2.14 → 0.2.17

package/dist/commands/serve.js

@@ -0,0 +1,238 @@
+import { Command } from "commander";
+import * as p from "@clack/prompts";
+import consola from "consola";
+import c from "picocolors";
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { createServer } from "node:net";
+import { execa } from "execa";
+import { existsSync } from "fs";
+import { dirname, join } from "pathe";
+import { getWorkspaceDir, isInitialized, readRuntimeConfig, saveRuntimeConfig, } from "../utils/paths.js";
+import { canStartTunnel, startTunnel, printTunnelInfo } from "../utils/tunnel.js";
+import { checkCloudflared, printInstallInstructions } from "../utils/cloudflared.js";
+const require = createRequire(import.meta.url);
+async function ensurePortAvailable(port, host) {
+    await new Promise((resolve, reject) => {
+        const probe = createServer();
+        probe.once("error", (error) => {
+            probe.close();
+            if (error.code === "EADDRINUSE") {
+                reject(new Error(`Port ${port} is already in use`));
+                return;
+            }
+            reject(error);
+        });
+        probe.listen(port, host, () => {
+            probe.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        });
+    });
+}
+async function waitForRuntimeReady(port, pageId, timeoutMs = 5000) {
+    const start = Date.now();
+    let lastError = null;
+    while (Date.now() - start < timeoutMs) {
+        try {
+            const response = await fetch(`http://127.0.0.1:${port}/health`, {
+                signal: AbortSignal.timeout(500),
+            });
+            if (response.ok) {
+                const health = (await response.json());
+                if (health.ok === true && health.pageId === pageId) {
+                    return;
+                }
+                lastError = new Error("runtime health mismatch");
+            }
+            else {
+                lastError = new Error(`health returned ${response.status}`);
+            }
+        }
+        catch (error) {
+            lastError = error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+    throw lastError instanceof Error
+        ? lastError
+        : new Error("Runtime health check timed out");
+}
+function resolveRenderServeBin() {
+    const override = process.env.AGENTSTAGE_RENDER_SERVE_BIN;
+    if (override) {
+        return override;
+    }
+    try {
+        const serveModulePath = require.resolve("@agentstage/render/serve");
+        const candidate = join(dirname(serveModulePath), "serve-cli.js");
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    catch {
+        // ignore resolution failure
+    }
+    return null;
+}
+async function waitForRuntimeProcessOrReady(subprocess, ready) {
+    let onError = null;
+    let onExit = null;
+    const exited = new Promise((_, reject) => {
+        onError = (error) => {
+            reject(error);
+        };
+        onExit = (code, signal) => {
+            const detail = code !== null ? `code ${code}` : `signal ${signal ?? "unknown"}`;
+            reject(new Error(`Runtime process exited before becoming ready (${detail})`));
+        };
+        subprocess.once("error", onError);
+        subprocess.once("exit", onExit);
+    });
+    try {
+        await Promise.race([ready, exited]);
+    }
+    finally {
+        if (onError) {
+            subprocess.off("error", onError);
+        }
+        if (onExit) {
+            subprocess.off("exit", onExit);
+        }
+    }
+}
+export const serveCommand = new Command("serve")
+    .description("Serve a single page runtime (Bun required)")
+    .argument("<pageId>", "Page id to serve")
+    .option("-p, --port <port>", "Port to run the server on", "3000")
+    .option("--host <host>", "Host to bind", "0.0.0.0")
+    .option("-t, --tunnel", "Expose server to internet via Cloudflare Tunnel", false)
+    .option("--open", "Open browser automatically", false)
+    .action(async (pageId, options) => {
+    if (!isInitialized()) {
+        consola.error("Project not initialized. Please run `agentstage init` first.");
+        process.exit(1);
+    }
+    if (!/^[a-z0-9-]+$/.test(pageId)) {
+        consola.error("Invalid pageId. Allowed: lowercase letters, numbers, hyphen");
+        process.exit(1);
+    }
+    const workspaceDir = await getWorkspaceDir();
+    const port = Number.parseInt(String(options.port), 10);
+    const host = String(options.host || "0.0.0.0");
+    if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+        consola.error(`Invalid port: ${options.port}`);
+        process.exit(1);
+    }
+    const pageUiPath = join(workspaceDir, "pages", pageId, "ui.json");
+    if (!existsSync(pageUiPath)) {
+        consola.error(`Page "${pageId}" not found: ${pageUiPath}`);
+        process.exit(1);
+    }
+    try {
+        await execa("bun", ["--version"], { stdio: "pipe" });
+    }
+    catch {
+        consola.error("Bun is required but not found.");
+        consola.info("Install Bun: https://bun.sh/docs/installation");
+        process.exit(1);
+    }
+    const serveBin = resolveRenderServeBin();
+    if (!serveBin) {
+        consola.error("Cannot resolve @agentstage/render serve runtime entry.");
+        process.exit(1);
+    }
+    const existingConfig = await readRuntimeConfig();
+    if (existingConfig) {
+        try {
+            process.kill(existingConfig.pid, 0);
+            consola.warn(`Runtime is already running (PID: ${existingConfig.pid}, Port: ${existingConfig.port})`);
+            console.log(`  Web:    ${c.cyan(`http://localhost:${existingConfig.port}`)}`);
+            if (existingConfig.tunnelUrl) {
+                console.log(`  Public: ${c.cyan(c.underline(existingConfig.tunnelUrl))}`);
+            }
+            console.log(`  Bridge: ${c.cyan(`ws://localhost:${existingConfig.port}/_bridge`)}`);
+            return;
+        }
+        catch {
+            // stale runtime config
+        }
+    }
+    await ensurePortAvailable(port, host);
+    let tunnelUrl;
+    if (options.tunnel) {
+        const canTunnel = await canStartTunnel();
+        if (!canTunnel) {
+            const info = await checkCloudflared();
+            printInstallInstructions(info);
+            consola.error("Cannot start with --tunnel: cloudflared not installed");
+            process.exit(1);
+        }
+    }
+    const s = p.spinner();
+    s.start(`Starting page runtime (${pageId})...`);
+    try {
+        const subprocess = spawn("bun", [
+            serveBin,
+            "--workspace",
+            workspaceDir,
+            "--page",
+            pageId,
+            "--port",
+            String(port),
+            "--host",
+            host,
+        ], {
+            cwd: workspaceDir,
+            detached: true,
+            stdio: "ignore",
+        });
+        if (!subprocess.pid) {
+            throw new Error("Failed to start runtime process");
+        }
+        subprocess.unref();
+        if (options.tunnel) {
+            s.message("Starting Cloudflare Tunnel...");
+            const tunnel = await startTunnel(port);
+            tunnelUrl = tunnel.url;
+        }
+        await waitForRuntimeProcessOrReady(subprocess, waitForRuntimeReady(port, pageId));
+        const config = {
+            pid: subprocess.pid,
+            port,
+            startedAt: new Date().toISOString(),
+            tunnelUrl,
+        };
+        await saveRuntimeConfig(config);
+        s.stop(`Runtime started (${pageId})`);
+        console.log();
+        consola.success("Agentstage runtime is running");
+        console.log(`  Page:   ${c.cyan(pageId)}`);
+        console.log(`  Web:    ${c.cyan(`http://localhost:${port}`)}`);
+        if (tunnelUrl) {
+            printTunnelInfo(tunnelUrl);
+        }
+        console.log(`  Bridge: ${c.cyan(`ws://localhost:${port}/_bridge`)}`);
+        console.log(`  Workspace: ${c.gray(workspaceDir)}`);
+        console.log();
+        if (options.open) {
+            const openUrl = tunnelUrl || `http://localhost:${port}`;
+            try {
+                await execa("open", [openUrl]);
+            }
+            catch {
+                // ignore open errors
+            }
+        }
+    }
+    catch (error) {
+        s.stop("Failed to start runtime");
+        const message = error instanceof Error ? error.message : "Unknown error";
+        consola.error(message);
+        process.exit(1);
+    }
+});

package/dist/commands/status.d.ts

@@ -1,2 +1,2 @@
-import { Command } from 'commander';
+import { Command } from "commander";
 export declare const statusCommand: Command;

package/dist/commands/status.js

@@ -1,52 +1,53 @@
-import { Command } from 'commander';
-import consola from 'consola';
-import c from 'picocolors';
-import { getWorkspaceDir, readRuntimeConfig, isInitialized } from '../utils/paths.js';
-function isRunning(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-export const statusCommand = new Command('status')
-    .description('Show the Agentstage Runtime status')
+import { Command } from "commander";
+import consola from "consola";
+import c from "picocolors";
+import { readRuntimeConfig, isInitialized, getWorkspaceDir, } from "../utils/paths.js";
+import { checkCloudflared } from "../utils/cloudflared.js";
+export const statusCommand = new Command("status")
+    .description("Check the Agentstage Runtime status")
     .action(async () => {
-    // 1. 检查是否已初始化
     if (!isInitialized()) {
-        consola.error('Project not initialized. Please run `agentstage init` first.');
+        consola.error("Project not initialized. Please run `agentstage init` first.");
         process.exit(1);
     }
     const workspaceDir = await getWorkspaceDir();
-    console.log();
-    console.log(c.bold('Agentstage Runtime'));
-    console.log(c.gray('─'.repeat(40)));
-    console.log(`Workspace: ${c.cyan(workspaceDir)}`);
-    // 2. 读取运行时配置
     const config = await readRuntimeConfig();
-    if (!config) {
-        console.log(`Status:    ${c.red('●')} Stopped`);
-        console.log();
-        console.log(c.gray('Run `agentstage start` to start the runtime.'));
-        console.log();
-        return;
+    console.log();
+    console.log(c.bold("Workspace:"), c.cyan(workspaceDir));
+    console.log();
+    const cloudflared = await checkCloudflared();
+    console.log(c.bold("Cloudflare Tunnel:"));
+    if (cloudflared.installed) {
+        console.log(`  Status: ${c.green("✓ installed")}`);
+        console.log(`  Version: ${c.gray(cloudflared.version || "unknown")}`);
+    }
+    else {
+        console.log(`  Status: ${c.yellow("✗ not installed")}`);
+        console.log(`  Install: ${c.gray(cloudflared.installCommand)}`);
     }
-    // 3. 检查进程是否存活
-    const running = isRunning(config.pid);
-    if (running) {
-        console.log(`Status:    ${c.green('●')} Running`);
-        console.log(`PID:       ${config.pid}`);
-        console.log(`Port:      ${config.port}`);
-        console.log(`Started:   ${new Date(config.startedAt).toLocaleString()}`);
-        console.log(`Web:       ${c.cyan(`http://localhost:${config.port}`)}`);
-        console.log(`Bridge:    ${c.cyan(`ws://localhost:${config.port}/_bridge`)}`);
+    console.log();
+    console.log(c.bold("Runtime:"));
+    if (!config) {
+        console.log(`  Status: ${c.gray("stopped")}`);
     }
     else {
-        console.log(`Status:    ${c.yellow('●')} Dead (PID file exists but process not found)`);
-        console.log();
-        console.log(c.gray('Run `agentstage start` to restart the runtime.'));
+        try {
+            process.kill(config.pid, 0);
+            console.log(`  Status: ${c.green("running")}`);
+            console.log(`  PID: ${c.gray(config.pid)}`);
+            console.log(`  Port: ${c.cyan(config.port)}`);
+            console.log(`  Local: ${c.cyan(`http://localhost:${config.port}`)}`);
+            if (config.tunnelUrl) {
+                console.log(`  Public: ${c.cyan(c.underline(config.tunnelUrl))}`);
+            }
+            console.log(`  Bridge: ${c.cyan(`ws://localhost:${config.port}/_bridge`)}`);
+            console.log(`  Started: ${c.gray(new Date(config.startedAt).toLocaleString())}`);
+        }
+        catch {
+            console.log(`  Status: ${c.yellow("stale (process not found)")}`);
+            console.log(`  Last PID: ${c.gray(config.pid)}`);
+            console.log(`  Last Port: ${c.gray(config.port)}`);
+        }
     }
     console.log();
 });

package/dist/commands/stop.d.ts

@@ -1,2 +1,2 @@
-import { Command } from 'commander';
+import { Command } from "commander";
 export declare const stopCommand: Command;

package/dist/commands/stop.js

@@ -1,58 +1,40 @@
-import { Command } from 'commander';
-import consola from 'consola';
-import { unlink } from 'fs/promises';
-import { existsSync } from 'fs';
-import { getPidFile, readRuntimeConfig, removeRuntimeConfig, isInitialized } from '../utils/paths.js';
-async function killProcess(pid) {
-    try {
-        process.kill(pid, 'SIGTERM');
-        let attempts = 0;
-        while (attempts < 10) {
-            await new Promise(r => setTimeout(r, 500));
-            try {
-                process.kill(pid, 0);
-                attempts++;
-            }
-            catch {
-                break;
-            }
-        }
-        if (attempts >= 10) {
-            process.kill(pid, 'SIGKILL');
-        }
-    }
-    catch (error) {
-        if (error.code !== 'ESRCH')
-            throw error;
-    }
-}
-export const stopCommand = new Command('stop')
-    .description('Stop the Agentstage Runtime')
+import { Command } from "commander";
+import consola from "consola";
+import c from "picocolors";
+import { readRuntimeConfig, removeRuntimeConfig, isInitialized, } from "../utils/paths.js";
+export const stopCommand = new Command("stop")
+    .description("Stop the Agentstage Runtime")
     .action(async () => {
-    // 1. 检查是否已初始化
     if (!isInitialized()) {
-        consola.error('Project not initialized. Please run `agentstage init` first.');
+        consola.error("Project not initialized. Please run `agentstage init` first.");
         process.exit(1);
     }
-    // 2. 读取运行时配置
     const config = await readRuntimeConfig();
     if (!config) {
-        consola.info('Runtime is not running');
+        consola.warn("Runtime is not running");
         return;
     }
-    // 3. 停止进程
     try {
-        await killProcess(config.pid);
+        process.kill(config.pid, 0);
+        process.kill(config.pid, "SIGTERM");
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        try {
+            process.kill(config.pid, 0);
+            process.kill(config.pid, "SIGKILL");
+        }
+        catch {
+            // process already stopped
+        }
         await removeRuntimeConfig();
-        // 兼容旧版本：删除 pid 文件
-        const pidFile = await getPidFile();
-        if (existsSync(pidFile)) {
-            await unlink(pidFile).catch(() => { });
+        consola.success("Runtime stopped");
+        console.log(`  PID: ${c.gray(config.pid)}`);
+        console.log(`  Port: ${c.gray(config.port)}`);
+        if (config.tunnelUrl) {
+            console.log(`  Tunnel: ${c.gray(config.tunnelUrl)}`);
         }
-        consola.success('Runtime stopped');
     }
-    catch (error) {
-        consola.error('Failed to stop runtime:', error.message);
-        process.exit(1);
+    catch {
+        await removeRuntimeConfig();
+        consola.info("Runtime was not running (stale config cleaned up)");
     }
 });

package/dist/index.js

@@ -7,48 +7,34 @@ import { dirname, join } from 'pathe';
 // Read version from package.json
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
-import { devCommand } from './commands/dev/index.js';
+import { initCommand } from './commands/init.js';
+import { stopCommand } from './commands/stop.js';
+import { statusCommand } from './commands/status.js';
 import { pageCommand } from './commands/page/index.js';
 import { runCommand } from './commands/run/index.js';
 import { guideCommand } from './commands/guide.js';
 import { cleanupCommand } from './commands/cleanup.js';
 import { componentsCommand } from './commands/components.js';
 import { doctorCommand } from './commands/doctor.js';
-import { execCommand } from './commands/exec.js';
-import { initCommand } from './commands/init.js';
-import { inspectCommand } from './commands/inspect.js';
-import { lsCommand } from './commands/ls.js';
-import { restartCommand } from './commands/restart.js';
-import { rmPageCommand } from './commands/rm-page.js';
-import { startCommand } from './commands/start.js';
-import { statusCommand } from './commands/status.js';
-import { stopCommand } from './commands/stop.js';
 import { verifyCommand } from './commands/verify.js';
-import { watchCommand } from './commands/watch.js';
+import { serveCommand } from './commands/serve.js';
 const program = new Command();
 program
     .name('agentstage')
     .description('Agent UI Stage CLI - Create interactive UI for AI agents')
     .version(pkg.version);
-// Register all commands
-program.addCommand(devCommand);
-program.addCommand(pageCommand);
-program.addCommand(runCommand);
-program.addCommand(guideCommand);
-program.addCommand(cleanupCommand);
-program.addCommand(componentsCommand);
-program.addCommand(doctorCommand);
-program.addCommand(execCommand);
-program.addCommand(initCommand);
-program.addCommand(inspectCommand);
-program.addCommand(lsCommand);
-program.addCommand(restartCommand);
-program.addCommand(rmPageCommand);
-program.addCommand(startCommand);
-program.addCommand(statusCommand);
-program.addCommand(stopCommand);
-program.addCommand(verifyCommand);
-program.addCommand(watchCommand);
+// Register commands
+program.addCommand(initCommand); // init
+program.addCommand(serveCommand); // serve <pageId>
+program.addCommand(stopCommand); // stop
+program.addCommand(statusCommand); // status
+program.addCommand(pageCommand); // page add/rm/ls/manifest
+program.addCommand(runCommand); // run get-state/set-state/exec/inspect/watch
+program.addCommand(guideCommand); // guide
+program.addCommand(cleanupCommand); // cleanup
+program.addCommand(componentsCommand); // components
+program.addCommand(doctorCommand); // doctor
+program.addCommand(verifyCommand); // verify
 // Error handling
 program.exitOverride();
 try {

package/dist/utils/agent-helper.js

@@ -53,17 +53,17 @@ const errorGuides = {
     // 运行时相关
     'runtime_not_running': {
         message: 'Runtime is not running',
-        cause: 'The development server is not started',
-        fix: 'Start the dev server in another terminal',
-        example: 'agentstage dev start',
-        relatedCommands: ['dev start', 'dev status']
+        cause: 'The runtime process is not started',
+        fix: 'Start a page runtime in another terminal',
+        example: 'agentstage serve <pageId>',
+        relatedCommands: ['serve', 'status']
     },
     'page_not_connected': {
         message: 'Page is not connected',
         cause: 'Using --live flag but page is not open in browser',
         fix: 'Either remove --live, or open the page in browser first',
         example: '# Option 1: File-only update\nagentstage run set-state mypage \'{...}\'\n\n# Option 2: Open page first\n# Then use --live',
-        relatedCommands: ['run set-state', 'dev start']
+        relatedCommands: ['run set-state', 'serve']
     },
     // 路径遍历（安全）
     'path_traversal_detected': {

package/dist/utils/paths.js

@@ -52,15 +52,15 @@ export async function getPidFile() {
  */
 export async function getPagesDir() {
     const workspace = await getWorkspaceDir();
-    // New Vite template structure (src/routes for TanStack Router)
-    if (existsSync(join(workspace, 'src', 'routes'))) {
-        return join(workspace, 'src', 'pages');
+    // New runtime data structure
+    if (existsSync(join(workspace, 'pages'))) {
+        return join(workspace, 'pages');
     }
-    // Legacy Vite template structure
+    // Legacy template structure fallback
     if (existsSync(join(workspace, 'src', 'pages'))) {
         return join(workspace, 'src', 'pages');
     }
-    throw new Error('Routes directory not found at src/routes');
+    throw new Error('Pages directory not found at pages/');
 }
 // 运行时配置文件路径
 export async function getRuntimeConfigFile() {

package/dist/utils/tunnel.d.ts

@@ -1,5 +1,5 @@
 /**
- * Cloudflare Tunnel management for exposing local dev server
+ * Cloudflare Tunnel management for exposing local runtime server
  */
 export interface Tunnel {
     /** Public URL assigned by Cloudflare */

package/dist/utils/tunnel.js

@@ -1,5 +1,5 @@
 /**
- * Cloudflare Tunnel management for exposing local dev server
+ * Cloudflare Tunnel management for exposing local runtime server
  */
 import { spawn } from 'child_process';
 import { findCloudflared } from './cloudflared.js';

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "agent-stage",
-  "version": "0.2.14",
+  "version": "0.2.17",
   "files": [
-    "dist",
-    "template"
+    "dist"
   ],
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/parkgogogo/agent-stage"
+  },
   "bin": {
     "agent-stage": "./dist/index.js"
   },
@@ -16,8 +19,8 @@
     "execa": "^9.3.1",
     "pathe": "^1.1.2",
     "picocolors": "^1.1.1",
-    "@agentstage/bridge": "0.1.2",
-    "@agentstage/render": "0.2.2"
+    "@agentstage/render": "0.2.5",
+    "@agentstage/bridge": "0.1.3"
   },
   "devDependencies": {
     "@types/node": "^22.13.5",

package/dist/commands/dev/index.d.ts

@@ -1,2 +0,0 @@
-import { Command } from 'commander';
-export declare const devCommand: Command;

package/dist/commands/dev/index.js

@@ -1,11 +0,0 @@
-import { Command } from 'commander';
-import { devInitCommand } from './init.js';
-import { devStartCommand } from './start.js';
-import { devStopCommand } from './stop.js';
-import { devStatusCommand } from './status.js';
-export const devCommand = new Command('dev')
-    .description('Development commands for Agentstage')
-    .addCommand(devInitCommand)
-    .addCommand(devStartCommand)
-    .addCommand(devStopCommand)
-    .addCommand(devStatusCommand);

package/dist/commands/dev/init.d.ts

@@ -1,2 +0,0 @@
-import { Command } from 'commander';
-export declare const devInitCommand: Command;