agent-stage 0.2.15 → 0.2.18

package/dist/commands/guide.js

@@ -17,9 +17,9 @@ const guides = {
                 explanation: 'Creates a page with UI and initial state'
             },
             {
-                scenario: '3. Start dev server',
-                command: 'agentstage dev start',
-                explanation: 'Starts the development server'
+                scenario: '3. Start page runtime',
+                command: 'agentstage serve mypage',
+                explanation: 'Starts the page runtime process'
             }
         ],
         commonErrors: [
@@ -160,8 +160,8 @@ push/pop: Navigate forward/back`
             },
             {
                 error: 'Runtime is not running',
-                cause: 'Dev server is not started',
-                fix: 'Run: agentstage dev start'
+                cause: 'Page runtime is not started',
+                fix: 'Run: agentstage serve <pageId>'
             }
         ]
     },

package/dist/commands/init.d.ts

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

package/dist/commands/init.js

@@ -0,0 +1,164 @@
+import { Command } from "commander";
+import * as p from "@clack/prompts";
+import consola from "consola";
+import c from "picocolors";
+import { execa } from "execa";
+import { mkdir, readdir, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { resolve, join } from "pathe";
+import { homedir } from "os";
+import { setWorkspaceDir } from "../utils/paths.js";
+import { checkCloudflared, printInstallInstructions, } from "../utils/cloudflared.js";
+const PROJECT_NAME = "webapp";
+const workspaceDependencies = {
+    "@agentstage/render": "^0.2.2",
+    "@agentstage/bridge": "^0.1.2",
+    react: "^19.0.0",
+    "react-dom": "^19.0.0",
+    zod: "^3.23.0",
+};
+export const initCommand = new Command("init")
+    .description("Initialize a new Agentstage runtime workspace")
+    .option("-y, --yes", "Use default settings (non-interactive)", false)
+    .option("--skip-cloudflared-check", "Skip cloudflared installation check", false)
+    .action(async (options) => {
+    const useDefault = options.yes;
+    try {
+        await execa("bun", ["--version"], { stdio: "pipe" });
+    }
+    catch {
+        consola.error("Bun is required to initialize workspace.");
+        consola.info("Install Bun: https://bun.sh/docs/installation");
+        process.exit(1);
+    }
+    if (!options.skipCloudflaredCheck) {
+        const cloudflaredInfo = await checkCloudflared();
+        if (!cloudflaredInfo.installed) {
+            printInstallInstructions(cloudflaredInfo);
+            const shouldContinue = await p.confirm({
+                message: "Continue with initialization? (You can install cloudflared later)",
+                initialValue: true,
+            });
+            if (p.isCancel(shouldContinue) || !shouldContinue) {
+                consola.info("Cancelled");
+                process.exit(0);
+            }
+        }
+        else {
+            consola.success(`Cloudflare Tunnel available: ${c.dim(cloudflaredInfo.version)}`);
+        }
+    }
+    let locationMode;
+    if (useDefault) {
+        locationMode = "default";
+    }
+    else {
+        const result = await p.select({
+            message: "Where to store the workspace?",
+            options: [
+                {
+                    value: "default",
+                    label: `Default (~/.agentstage/${PROJECT_NAME})`,
+                    hint: "Recommended",
+                },
+                {
+                    value: "current",
+                    label: "Current directory (./.agentstage)",
+                },
+                {
+                    value: "custom",
+                    label: "Custom path",
+                },
+            ],
+        });
+        if (p.isCancel(result)) {
+            consola.info("Cancelled");
+            return;
+        }
+        locationMode = result;
+    }
+    let targetDir;
+    switch (locationMode) {
+        case "default":
+            targetDir = join(homedir(), ".agentstage", PROJECT_NAME);
+            break;
+        case "current":
+            targetDir = join(process.cwd(), ".agentstage");
+            break;
+        case "custom": {
+            const customPath = await p.text({
+                message: "Enter custom path:",
+                placeholder: "/path/to/workspace",
+                validate: (value) => {
+                    if (!value || value.trim() === "") {
+                        return "Path is required";
+                    }
+                },
+            });
+            if (p.isCancel(customPath)) {
+                consola.info("Cancelled");
+                return;
+            }
+            targetDir = resolve(customPath);
+            break;
+        }
+        default:
+            targetDir = join(homedir(), ".agentstage", PROJECT_NAME);
+    }
+    if (existsSync(targetDir)) {
+        const files = await readdirSafe(targetDir);
+        if (files.length > 0) {
+            console.log();
+            consola.info("Workspace already initialized!");
+            console.log(`  Location: ${c.cyan(targetDir)}`);
+            console.log();
+            console.log(`  cd ${c.cyan(targetDir)}`);
+            console.log(`  ${c.cyan("agentstage serve <pageId>")}`);
+            console.log();
+            await setWorkspaceDir(targetDir);
+            return;
+        }
+    }
+    await setWorkspaceDir(targetDir);
+    const s = p.spinner();
+    try {
+        s.start("Creating workspace structure...");
+        await mkdir(join(targetDir, "pages"), { recursive: true });
+        await mkdir(join(targetDir, ".agentstage"), { recursive: true });
+        const packageJson = {
+            name: "agentstage-workspace",
+            private: true,
+            version: "0.0.0",
+            type: "module",
+            dependencies: workspaceDependencies,
+        };
+        await writeFile(join(targetDir, "package.json"), JSON.stringify(packageJson, null, 2));
+        s.stop("Workspace created");
+        s.start("Installing dependencies with Bun...");
+        await execa("bun", ["install"], { cwd: targetDir, stdio: "pipe" });
+        s.stop("Dependencies installed");
+        console.log();
+        consola.success("Workspace initialized successfully");
+        console.log(`  Location: ${c.cyan(targetDir)}`);
+        console.log(`  Pages:    ${c.cyan("pages/<pageId>/ui.json")}`);
+        console.log();
+        console.log(`  cd ${c.cyan(targetDir)}`);
+        console.log(`  ${c.cyan("agentstage page add counter")}`);
+        console.log(`  ${c.cyan("agentstage serve counter")}`);
+        console.log();
+    }
+    catch (error) {
+        s.stop("Failed to initialize workspace");
+        const message = error instanceof Error ? error.message : "Unknown initialization error";
+        consola.error(message);
+        process.exit(1);
+    }
+});
+async function readdirSafe(dir) {
+    try {
+        return await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/commands/page/add.js

@@ -2,7 +2,6 @@ import { Command } from 'commander';
 import consola from 'consola';
 import c from 'picocolors';
 import { writeFile, mkdir } from 'fs/promises';
-import { existsSync } from 'fs';
 import { join } from 'pathe';
 import { getWorkspaceDir, isInitialized, readRuntimeConfig, getPagesDir } from '../../utils/paths.js';
 import { FileStore } from '@agentstage/bridge';
@@ -35,19 +34,9 @@ export const pageAddCommand = new Command('add')
     try {
         const workspaceDir = await getWorkspaceDir();
         const config = await readRuntimeConfig();
-        const routesDir = join(workspaceDir, 'src', 'routes');
-        const pagesDir = join(workspaceDir, 'src', 'pages', name);
-        const pageFile = join(routesDir, `${name}.tsx`);
+        const pagesDir = join(workspaceDir, 'pages', name);
         // 确保目录存在
-        await mkdir(routesDir, { recursive: true });
         await mkdir(pagesDir, { recursive: true });
-        if (existsSync(pageFile)) {
-            printAgentErrorHelp(`Page "${name}" already exists`);
-            process.exit(1);
-        }
-        // 生成 .tsx 路由文件
-        const pageContent = generateTsxContent(name);
-        await writeFile(pageFile, pageContent);
         // 处理 UI
         let uiContent;
         if (options.uiStdin) {
@@ -122,17 +111,16 @@ export const pageAddCommand = new Command('add')
         if (options.ui) {
             // 提供了完整 UI
             printAgentSuccess(`Page "${name}" created with custom UI and state`, [
-                `Start dev server: agentstage dev start`,
-                `Open http://localhost:${port}/${name} to see your page`,
+                `Start runtime: agentstage serve ${name}`,
+                `Open http://localhost:${port} to see your page`,
                 `Update state: agentstage run set-state ${name} '{"key": "value"}'`
             ]);
         }
         else {
             // 默认 UI，输出 prompts
             consola.success(`Page "${name}" created`);
-            console.log(`  Route: ${c.cyan(`src/routes/${name}.tsx`)}`);
-            console.log(`  UI:    ${c.cyan(`src/pages/${name}/ui.json`)}`);
-            console.log(`  Store: ${c.cyan(`src/pages/${name}/store.json`)}`);
+            console.log(`  UI:    ${c.cyan(`pages/${name}/ui.json`)}`);
+            console.log(`  Store: ${c.cyan(`pages/${name}/store.json`)}`);
             console.log(`  URL:   ${c.cyan(`http://localhost:${port}/${name}`)}`);
             console.log();
             console.log(c.bold('─'.repeat(60)));
@@ -152,26 +140,6 @@ export const pageAddCommand = new Command('add')
         process.exit(1);
     }
 });
-function generateTsxContent(name) {
-    const pascalName = toPascalCase(name);
-    return `import { createFileRoute } from '@tanstack/react-router'
-import { useMemo } from 'react'
-import { PageRenderer } from '../components/PageRenderer'
-import { createPageBridge } from '../lib/bridge'
-
-export const Route = createFileRoute('/${name}')({
-  component: ${pascalName}Page,
-})
-
-function ${pascalName}Page() {
-  const bridge = useMemo(() => createPageBridge({
-    pageId: '${name}',
-  }), [])
-
-  return <PageRenderer pageId="${name}" bridge={bridge} />
-}
-`;
-}
 function generateDefaultUi(name) {
     const titleName = toTitleCase(name);
     return {
@@ -211,9 +179,6 @@ function generateDefaultState(name) {
         pageId: name,
     };
 }
-function toPascalCase(str) {
-    return str.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('');
-}
 function toTitleCase(str) {
     return str.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
 }

package/dist/commands/run/exec.js

@@ -16,7 +16,7 @@ export const runExecCommand = new Command('exec')
     }
     const config = await readRuntimeConfig();
     if (!config) {
-        consola.error('Runtime is not running. Start it first with `agentstage dev start`.');
+        consola.error('Runtime is not running. Start it first with `agentstage serve <pageId>`.');
         process.exit(1);
     }
     // Parse payload

package/dist/commands/run/inspect.js

@@ -13,7 +13,7 @@ export const runInspectCommand = new Command('inspect')
     }
     const config = await readRuntimeConfig();
     if (!config) {
-        consola.error('Runtime is not running. Start it first with `agentstage dev start`.');
+        consola.error('Runtime is not running. Start it first with `agentstage serve <pageId>`.');
         process.exit(1);
     }
     const client = new BridgeClient(`ws://localhost:${config.port}/_bridge`);

package/dist/commands/run/watch.js

@@ -14,7 +14,7 @@ export const runWatchCommand = new Command('watch')
     }
     const config = await readRuntimeConfig();
     if (!config) {
-        consola.error('Runtime is not running. Start it first with `agentstage dev start`.');
+        consola.error('Runtime is not running. Start it first with `agentstage serve <pageId>`.');
         process.exit(1);
     }
     const client = new BridgeClient(`ws://localhost:${config.port}/_bridge`);

package/dist/commands/serve.d.ts

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

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

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

package/dist/commands/{dev/status.js → status.js}

@@ -1,41 +1,39 @@
-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 devStatusCommand = new Command('status')
-    .description('Check 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 () => {
     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();
     const config = await readRuntimeConfig();
     console.log();
-    console.log(c.bold('Workspace:'), c.cyan(workspaceDir));
+    console.log(c.bold("Workspace:"), c.cyan(workspaceDir));
     console.log();
-    // Check cloudflared
     const cloudflared = await checkCloudflared();
-    console.log(c.bold('Cloudflare Tunnel:'));
+    console.log(c.bold("Cloudflare Tunnel:"));
     if (cloudflared.installed) {
-        console.log(`  Status: ${c.green('✓ installed')}`);
-        console.log(`  Version: ${c.gray(cloudflared.version || 'unknown')}`);
+        console.log(`  Status: ${c.green("✓ installed")}`);
+        console.log(`  Version: ${c.gray(cloudflared.version || "unknown")}`);
     }
     else {
-        console.log(`  Status: ${c.yellow('✗ not installed')}`);
+        console.log(`  Status: ${c.yellow("✗ not installed")}`);
         console.log(`  Install: ${c.gray(cloudflared.installCommand)}`);
     }
     console.log();
-    // Check runtime
-    console.log(c.bold('Runtime:'));
+    console.log(c.bold("Runtime:"));
     if (!config) {
-        console.log(`  Status: ${c.gray('stopped')}`);
+        console.log(`  Status: ${c.gray("stopped")}`);
     }
     else {
         try {
             process.kill(config.pid, 0);
-            console.log(`  Status: ${c.green('running')}`);
+            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}`)}`);
@@ -46,7 +44,7 @@ export const devStatusCommand = new Command('status')
             console.log(`  Started: ${c.gray(new Date(config.startedAt).toLocaleString())}`);
         }
         catch {
-            console.log(`  Status: ${c.yellow('stale (process not found)')}`);
+            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)}`);
         }

package/dist/commands/stop.d.ts

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

package/dist/commands/stop.js

@@ -0,0 +1,40 @@
+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 () => {
+    if (!isInitialized()) {
+        consola.error("Project not initialized. Please run `agentstage init` first.");
+        process.exit(1);
+    }
+    const config = await readRuntimeConfig();
+    if (!config) {
+        consola.warn("Runtime is not running");
+        return;
+    }
+    try {
+        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();
+        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)}`);
+        }
+    }
+    catch {
+        await removeRuntimeConfig();
+        consola.info("Runtime was not running (stale config cleaned up)");
+    }
+});