agent-stage 0.2.0 → 0.2.1

package/dist/commands/run/index.js

@@ -0,0 +1,13 @@
+import { Command } from 'commander';
+import { runExecCommand } from './exec.js';
+import { runSetStateCommand } from './set-state.js';
+import { runGetStateCommand } from './get-state.js';
+import { runWatchCommand } from './watch.js';
+import { runInspectCommand } from './inspect.js';
+export const runCommand = new Command('run')
+    .description('Runtime commands for controlling pages (Agent operations)')
+    .addCommand(runExecCommand)
+    .addCommand(runSetStateCommand)
+    .addCommand(runGetStateCommand)
+    .addCommand(runWatchCommand)
+    .addCommand(runInspectCommand);

package/dist/commands/run/inspect.d.ts

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

package/dist/commands/run/inspect.js

@@ -0,0 +1,80 @@
+import { Command } from 'commander';
+import consola from 'consola';
+import c from 'picocolors';
+import { isInitialized, readRuntimeConfig } from '../../utils/paths.js';
+import { BridgeClient } from '@agentstage/bridge/sdk';
+export const runInspectCommand = new Command('inspect')
+    .description('Inspect a page\'s state and schema')
+    .argument('<page>', 'Page ID')
+    .action(async (pageId) => {
+    if (!isInitialized()) {
+        consola.error('Project not initialized. Please run `agentstage init` first.');
+        process.exit(1);
+    }
+    const config = await readRuntimeConfig();
+    if (!config) {
+        consola.error('Runtime is not running. Start it first with `agentstage dev start`.');
+        process.exit(1);
+    }
+    const client = new BridgeClient(`ws://localhost:${config.port}/_bridge`);
+    try {
+        await client.connect();
+        const store = await client.findStoreByKey(pageId, 'main');
+        if (!store) {
+            consola.error(`Page "${pageId}" is not connected. Make sure the page is open in browser.`);
+            process.exit(1);
+        }
+        // Get description
+        const description = await client.describe(store.id);
+        // Get current state
+        const state = await client.getState(store.id);
+        console.log();
+        console.log(c.bold('Page:'), c.cyan(pageId));
+        console.log(c.bold('Store ID:'), c.gray(store.id));
+        console.log(c.bold('Version:'), c.gray(store.version.toString()));
+        console.log(c.bold('Connected:'), c.gray(store.connectedAt.toISOString()));
+        console.log();
+        if (description) {
+            console.log(c.bold('Schema:'));
+            console.log(c.gray(JSON.stringify(description.schema, null, 2)));
+            console.log();
+            console.log(c.bold('Actions:'));
+            if (description.actions && Object.keys(description.actions).length > 0) {
+                for (const [name, def] of Object.entries(description.actions)) {
+                    console.log(`  ${c.cyan(name)}`);
+                    console.log(`    ${c.gray(def.description || 'No description')}`);
+                    if (def.payload) {
+                        console.log(`    payload: ${c.gray(JSON.stringify(def.payload))}`);
+                    }
+                }
+            }
+            else {
+                console.log(c.gray('  No actions defined'));
+            }
+            console.log();
+            if (description.events && Object.keys(description.events).length > 0) {
+                console.log(c.bold('Events:'));
+                for (const [name, def] of Object.entries(description.events)) {
+                    console.log(`  ${c.cyan(name)}`);
+                    console.log(`    ${c.gray(def.description || 'No description')}`);
+                }
+                console.log();
+            }
+        }
+        console.log(c.bold('Current State:'));
+        if (state) {
+            console.log(c.gray(JSON.stringify(state.state, null, 2)));
+        }
+        else {
+            console.log(c.gray('  No state available'));
+        }
+        console.log();
+    }
+    catch (error) {
+        consola.error('Failed to inspect:', error.message);
+        process.exit(1);
+    }
+    finally {
+        client.disconnect();
+    }
+});

package/dist/commands/run/set-state.d.ts

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

package/dist/commands/run/set-state.js

@@ -0,0 +1,93 @@
+import { Command } from 'commander';
+import consola from 'consola';
+import c from 'picocolors';
+import { isInitialized, readRuntimeConfig, getPagesDir } from '../../utils/paths.js';
+import { BridgeClient } from '@agentstage/bridge/sdk';
+import { FileStore } from '@agentstage/bridge';
+export const runSetStateCommand = new Command('set-state')
+    .description('Set state on a page')
+    .argument('<page>', 'Page ID')
+    .argument('<json>', 'State as JSON string')
+    .option('--live', 'Also sync to connected browser via WebSocket', false)
+    .option('--wait [timeoutMs]', 'Wait for browser ACK when using --live')
+    .action(async (pageId, jsonStr, options) => {
+    if (!isInitialized()) {
+        consola.error('Project not initialized. Please run `agentstage init` first.');
+        process.exit(1);
+    }
+    // Parse state
+    let state;
+    try {
+        state = JSON.parse(jsonStr);
+    }
+    catch {
+        consola.error('Invalid JSON state');
+        process.exit(1);
+    }
+    const config = await readRuntimeConfig();
+    // If --live is specified, require running runtime
+    if (options.live) {
+        if (!config) {
+            consola.error('Runtime is not running. Start it first or remove --live flag.');
+            process.exit(1);
+        }
+        const client = new BridgeClient(`ws://localhost:${config.port}/_bridge`);
+        try {
+            await client.connect();
+            const store = await client.findStoreByKey(pageId, 'main');
+            if (!store) {
+                consola.error(`Page "${pageId}" is not connected. Make sure the page is open in browser.`);
+                process.exit(1);
+            }
+            const waitForAck = options.wait !== undefined && options.wait !== false;
+            const timeoutMs = typeof options.wait === 'string' && Number.isFinite(Number(options.wait))
+                ? Number(options.wait)
+                : 5000;
+            if (waitForAck) {
+                consola.info(`Setting state on "${pageId}" (waiting ${timeoutMs}ms)...`);
+            }
+            else {
+                consola.info(`Setting state on "${pageId}"...`);
+            }
+            await client.setStateByKey(pageId, 'main', state, waitForAck ? { waitForAck: true, timeoutMs } : {});
+            consola.success('State updated');
+            console.log(`  Page: ${c.cyan(pageId)}`);
+            console.log(`  State:`);
+            console.log(c.gray(JSON.stringify(state, null, 2)));
+            if (waitForAck) {
+                console.log(`  ACK: ${c.green('received')}`);
+            }
+        }
+        catch (error) {
+            consola.error('Failed to set state:', error.message);
+            process.exit(1);
+        }
+        finally {
+            client.disconnect();
+        }
+    }
+    else {
+        // File-only mode (works without running server)
+        const pagesDir = await getPagesDir();
+        const fileStore = new FileStore({ pagesDir });
+        try {
+            const saved = await fileStore.save(pageId, {
+                state,
+                version: 0,
+                updatedAt: new Date().toISOString(),
+                pageId,
+            });
+            consola.success('State saved to file');
+            console.log(`  Page: ${c.cyan(pageId)}`);
+            console.log(`  File: ${c.gray(`${pagesDir}/${pageId}/store.json`)}`);
+            console.log(`  Version: ${c.gray(saved.version)}`);
+            console.log();
+            console.log(c.dim('Note: State will apply when the page is next opened.'));
+            console.log(c.dim('      Use --live to apply to a running browser immediately.'));
+        }
+        catch (error) {
+            consola.error('Failed to save state:', error.message);
+            process.exit(1);
+        }
+    }
+});

package/dist/commands/run/watch.d.ts

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

package/dist/commands/run/watch.js

@@ -0,0 +1,72 @@
+import { Command } from 'commander';
+import consola from 'consola';
+import c from 'picocolors';
+import { isInitialized, readRuntimeConfig } from '../../utils/paths.js';
+import { BridgeClient } from '@agentstage/bridge/sdk';
+export const runWatchCommand = new Command('watch')
+    .description('Watch state changes on a page')
+    .argument('<page>', 'Page ID')
+    .option('-f, --format <type>', 'Output format (pretty|json)', 'pretty')
+    .action(async (pageId, options) => {
+    if (!isInitialized()) {
+        consola.error('Project not initialized. Please run `agentstage init` first.');
+        process.exit(1);
+    }
+    const config = await readRuntimeConfig();
+    if (!config) {
+        consola.error('Runtime is not running. Start it first with `agentstage dev start`.');
+        process.exit(1);
+    }
+    const client = new BridgeClient(`ws://localhost:${config.port}/_bridge`);
+    try {
+        await client.connect();
+        const store = await client.findStoreByKey(pageId, 'main');
+        if (!store) {
+            consola.error(`Page "${pageId}" is not connected. Make sure the page is open in browser.`);
+            process.exit(1);
+        }
+        consola.info(`Watching "${pageId}" for state changes...`);
+        console.log(c.dim('Press Ctrl+C to stop'));
+        console.log();
+        // Print initial state
+        const initialState = await client.getStateByKey(pageId, 'main');
+        if (initialState) {
+            printState('initial', initialState.state, initialState.version, options.format);
+        }
+        // Subscribe to changes
+        client.subscribe(store.id);
+        client.onEvent((event) => {
+            if (event.storeId !== store.id)
+                return;
+            if (event.type === 'stateChanged') {
+                printState('changed', event.state, event.version, options.format);
+            }
+            else if (event.type === 'disconnected') {
+                console.log(c.yellow(`[${new Date().toISOString()}] Page disconnected`));
+            }
+        });
+        // Keep running until interrupted
+        await new Promise(() => { });
+    }
+    catch (error) {
+        consola.error('Failed to watch:', error.message);
+        process.exit(1);
+    }
+});
+function printState(type, state, version, format) {
+    const timestamp = new Date().toISOString();
+    if (format === 'json') {
+        console.log(JSON.stringify({
+            timestamp,
+            type,
+            version,
+            state,
+        }));
+    }
+    else {
+        const label = type === 'initial' ? c.blue('[initial]') : c.green('[changed]');
+        console.log(`${c.gray(timestamp)} ${label} (v${version}):`);
+        console.log(c.gray(JSON.stringify(state, null, 2)));
+        console.log();
+    }
+}

package/dist/commands/verify.d.ts

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

package/dist/commands/verify.js

@@ -0,0 +1,230 @@
+import { Command } from 'commander';
+import { execa } from 'execa';
+import consola from 'consola';
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'pathe';
+import picocolors from 'picocolors';
+import { getWorkspaceDir, readRuntimeConfig, isInitialized } from '../utils/paths.js';
+export const verifyCommand = new Command('verify')
+    .description('Verify page(s) before delivery - 交付前验收检查')
+    .argument('[page]', 'Page to verify (default: all pages)')
+    .option('--ci', 'CI mode (non-interactive, exit with error code)')
+    .action(async (page, options) => {
+    if (!isInitialized()) {
+        consola.error('No workspace found. Run `agentstage init` first.');
+        process.exit(1);
+    }
+    let workspace;
+    try {
+        workspace = await getWorkspaceDir();
+    }
+    catch (error) {
+        consola.error(error.message);
+        process.exit(1);
+    }
+    const checks = [];
+    // 1. TypeScript 编译检查
+    checks.push(await checkTypeScript(workspace));
+    // 2. 路由检查
+    if (page) {
+        checks.push(await checkRoute(workspace, page));
+    }
+    else {
+        checks.push(await checkAllRoutes(workspace));
+    }
+    // 3. 运行时检查
+    checks.push(await checkRuntime(workspace, page));
+    // 4. 输出报告
+    printReport(checks, options.ci);
+    // CI 模式下有问题就退出
+    if (options.ci && checks.some(c => !c.passed)) {
+        process.exit(1);
+    }
+});
+async function checkTypeScript(workspace) {
+    consola.info('Checking TypeScript compilation...');
+    try {
+        // 运行类型检查（忽略 node_modules 错误）
+        const { stderr } = await execa('npx', ['tsc', '--noEmit', '--skipLibCheck'], {
+            cwd: workspace,
+            reject: false,
+            timeout: 60000
+        });
+        if (stderr && stderr.includes('error')) {
+            const errors = parseTSErrors(stderr);
+            return {
+                name: 'TypeScript 编译',
+                passed: false,
+                errors: errors.slice(0, 5) // 只显示前5个
+            };
+        }
+        return { name: 'TypeScript 编译', passed: true };
+    }
+    catch (error) {
+        return {
+            name: 'TypeScript 编译',
+            passed: false,
+            errors: [`无法运行 TypeScript 检查: ${error.message}`]
+        };
+    }
+}
+function parseTSErrors(output) {
+    const errors = [];
+    const lines = output.split('\n');
+    for (const line of lines) {
+        // 匹配 TS 错误格式: file(line,col): error TSxxxx: message
+        const match = line.match(/(.+?)\((\d+),(\d+)\):\s+error\s+TS\d+:\s+(.+)/);
+        if (match) {
+            const [, file, lineNum, col, message] = match;
+            const shortFile = file.replace(process.cwd(), '');
+            errors.push(`${shortFile}:${lineNum}:${col} - ${message}`);
+        }
+    }
+    return errors.length > 0 ? errors : [output.slice(0, 200)];
+}
+async function checkRoute(workspace, pageId) {
+    const routeFile = resolve(workspace, 'src/routes', `${pageId}.tsx`);
+    if (!existsSync(routeFile)) {
+        return {
+            name: `路由检查 (${pageId})`,
+            passed: false,
+            errors: [`页面文件不存在: src/routes/${pageId}.tsx`]
+        };
+    }
+    // 检查文件内容
+    const content = readFileSync(routeFile, 'utf8');
+    const issues = [];
+    if (!content.includes('export const Route')) {
+        issues.push('缺少 Route 导出');
+    }
+    // 检查 HTML 实体（常见问题）
+    if (content.includes('"') || content.includes(''')) {
+        issues.push('发现 HTML 实体 ("/')，可能导致编译错误');
+    }
+    // 检查是否有未闭合的括号
+    const openBraces = (content.match(/{/g) || []).length;
+    const closeBraces = (content.match(/}/g) || []).length;
+    if (openBraces !== closeBraces) {
+        issues.push(`括号不匹配: {${openBraces} 个, }${closeBraces} 个`);
+    }
+    return {
+        name: `路由检查 (${pageId})`,
+        passed: issues.length === 0,
+        errors: issues,
+        warnings: issues.length > 0 ? ['这些问题可能导致页面无法正常工作'] : undefined
+    };
+}
+async function checkAllRoutes(workspace) {
+    const routesDir = resolve(workspace, 'src/routes');
+    if (!existsSync(routesDir)) {
+        return {
+            name: '路由检查 (all)',
+            passed: false,
+            errors: ['路由目录不存在: src/routes']
+        };
+    }
+    return {
+        name: '路由检查 (all)',
+        passed: true,
+        warnings: ['建议逐个页面检查: agentstage verify <page>']
+    };
+}
+async function checkRuntime(workspace, pageId) {
+    const config = await readRuntimeConfig();
+    if (!config) {
+        return {
+            name: '运行时检查',
+            passed: false,
+            errors: ['Server 未运行'],
+            warnings: ['请先执行: agentstage start']
+        };
+    }
+    // 检查进程是否真的存在
+    try {
+        process.kill(config.pid, 0);
+    }
+    catch {
+        return {
+            name: '运行时检查',
+            passed: false,
+            errors: [`Server 进程 (${config.pid}) 不存在，可能已崩溃`],
+            warnings: ['请重启: agentstage restart']
+        };
+    }
+    // HTTP 检查
+    const url = pageId
+        ? `http://localhost:${config.port || 3000}/${pageId}`
+        : `http://localhost:${config.port || 3000}/`;
+    try {
+        const response = await fetch(url, {
+            signal: AbortSignal.timeout(5000)
+        });
+        if (!response.ok) {
+            return {
+                name: '运行时检查',
+                passed: false,
+                errors: [`页面返回 ${response.status} ${response.statusText}`]
+            };
+        }
+        // 检查页面内容是否包含 Vite 错误
+        const html = await response.text();
+        if (html.includes('[plugin:') && html.includes('error')) {
+            return {
+                name: '运行时检查',
+                passed: false,
+                errors: ['页面包含 Vite 错误信息，请检查浏览器控制台']
+            };
+        }
+        return {
+            name: '运行时检查',
+            passed: true,
+            warnings: pageId ? undefined : ['建议检查具体页面: agentstage verify <page>']
+        };
+    }
+    catch (error) {
+        return {
+            name: '运行时检查',
+            passed: false,
+            errors: [`无法访问页面: ${error.message}`]
+        };
+    }
+}
+function printReport(checks, ci) {
+    const { green, red, yellow, bold } = picocolors;
+    console.log('\n' + bold('📋 交付验收检查报告'));
+    console.log('─'.repeat(60));
+    let errorCount = 0;
+    let warningCount = 0;
+    for (const check of checks) {
+        const icon = check.passed ? green('✅') : red('❌');
+        console.log(`\n${icon} ${bold(check.name)}`);
+        if (check.errors && check.errors.length > 0) {
+            errorCount += check.errors.length;
+            for (const error of check.errors) {
+                console.log(`   ${red('❌')} ${error}`);
+            }
+        }
+        if (check.warnings && check.warnings.length > 0) {
+            warningCount += check.warnings.length;
+            for (const warning of check.warnings) {
+                console.log(`   ${yellow('⚠️')} ${warning}`);
+            }
+        }
+    }
+    console.log('─'.repeat(60));
+    if (errorCount > 0) {
+        console.log('\n' + red(bold(`❌ 检查未通过 (${errorCount} 个错误)`)));
+        if (!ci) {
+            console.log('\n' + yellow('💡 建议修复步骤:'));
+            console.log('   1. 根据错误信息修改代码');
+            console.log('   2. 重新运行 agentstage verify');
+            console.log('   3. 确认所有检查通过后再交付');
+        }
+    }
+    else if (warningCount > 0) {
+        console.log('\n' + yellow(bold(`⚠️ 检查通过但有警告 (${warningCount} 个)`)));
+    }
+    else {
+        console.log('\n' + green(bold('✅ 所有检查通过，可以交付！')));
+    }
+}

package/dist/commands/watch.js

@@ -1,7 +1,7 @@
 import { Command } from 'commander';
 import consola from 'consola';
 import c from 'picocolors';
-import { BridgeClient } from 'agent-stage-bridge/sdk';
+import { BridgeClient } from '@agentstage/bridge/sdk';
 import { readRuntimeConfig, isInitialized } from '../utils/paths.js';
 export const watchCommand = new Command('watch')
     .description('Watch a page for real-time changes')

package/dist/index.js

@@ -1,41 +1,22 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import consola from 'consola';
-import { initCommand } from './commands/init.js';
-import { startCommand } from './commands/start.js';
-import { stopCommand } from './commands/stop.js';
-import { restartCommand } from './commands/restart.js';
-import { statusCommand } from './commands/status.js';
-import { lsCommand } from './commands/ls.js';
-import { inspectCommand } from './commands/inspect.js';
-import { watchCommand } from './commands/watch.js';
-import { execCommand } from './commands/exec.js';
-import { addPageCommand } from './commands/add-page.js';
-import { rmPageCommand } from './commands/rm-page.js';
-import { componentsCommand } from './commands/components.js';
-import { doctorCommand } from './commands/doctor.js';
-import { resetCommand } from './commands/reset.js';
+// New command structure
+import { devCommand } from './commands/dev/index.js';
+import { pageCommand } from './commands/page/index.js';
+import { runCommand } from './commands/run/index.js';
+import { guideCommand } from './commands/guide.js';
 const program = new Command();
 program
     .name('agentstage')
     .description('Agent UI Stage CLI - Create interactive UI for AI agents')
     .version('0.2.0');
-// 注册命令
-program.addCommand(initCommand);
-program.addCommand(startCommand);
-program.addCommand(stopCommand);
-program.addCommand(restartCommand);
-program.addCommand(statusCommand);
-program.addCommand(lsCommand);
-program.addCommand(inspectCommand);
-program.addCommand(watchCommand);
-program.addCommand(execCommand);
-program.addCommand(addPageCommand);
-program.addCommand(rmPageCommand);
-program.addCommand(componentsCommand);
-program.addCommand(doctorCommand);
-program.addCommand(resetCommand);
-// 错误处理
+// New command structure
+program.addCommand(devCommand);
+program.addCommand(pageCommand);
+program.addCommand(runCommand);
+program.addCommand(guideCommand);
+// Error handling
 program.exitOverride();
 try {
     await program.parseAsync(process.argv);

package/dist/utils/agent-helper.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Agent Error Helper - 为 Agent 提供自我修复指引
+ */
+export interface ErrorGuide {
+    message: string;
+    cause: string;
+    fix: string;
+    example: string;
+    relatedCommands: string[];
+}
+/**
+ * 根据错误消息匹配对应的指引
+ */
+export declare function findErrorGuide(errorMessage: string): ErrorGuide | null;
+/**
+ * 输出 Agent 友好的错误指引
+ */
+export declare function printAgentErrorHelp(error: Error | string, context?: string): void;
+/**
+ * 输出成功案例指引
+ */
+export declare function printAgentSuccess(message: string, nextSteps?: string[]): void;
+/**
+ * 输出 Agent 可用的提示
+ */
+export declare function printAgentHint(message: string): void;
+/**
+ * 输出 Agent 警告
+ */
+export declare function printAgentWarning(message: string): void;