agent-stage 0.2.18 → 0.2.19

package/dist/commands/guide.js

@@ -4,7 +4,7 @@ import c from 'picocolors';
 const guides = {
     'quickstart': {
         title: 'Quick Start for Agents',
-        description: 'Get started with agentstage in 3 steps',
+        description: 'Get started with agentstage in 4 steps',
         examples: [
             {
                 scenario: '1. Initialize project (first time only)',
@@ -13,11 +13,16 @@ const guides = {
             },
             {
                 scenario: '2. Create a page',
-                command: 'agentstage page add mypage --ui \'{...}\' --state \'{...}\'',
-                explanation: 'Creates a page with UI and initial state'
+                command: 'agentstage page add mypage',
+                explanation: 'Creates page files at pages/mypage/ui.json and pages/mypage/store.json'
             },
             {
-                scenario: '3. Start page runtime',
+                scenario: '3. Generate prompt for AI UI JSON',
+                command: 'agentstage prompt ui --page mypage',
+                explanation: 'Prints a prompt you can send to AI to generate valid ui.json'
+            },
+            {
+                scenario: '4. Start page runtime',
                 command: 'agentstage serve mypage',
                 explanation: 'Starts the page runtime process'
             }
@@ -40,9 +45,9 @@ const guides = {
                 explanation: 'Creates page with UI spec and initial state'
             },
             {
-                scenario: 'Create empty page (get prompts)',
+                scenario: 'Create empty page then generate prompt',
                 command: 'agentstage page add todo',
-                explanation: 'Creates page with default UI and outputs prompts for AI'
+                explanation: 'Creates skeleton files. Then run: agentstage prompt ui --page todo'
             },
             {
                 scenario: 'Create page from stdin (for large JSON)',
@@ -68,6 +73,39 @@ const guides = {
             }
         ]
     },
+    'prompt-ui': {
+        title: 'Prompt for UI JSON',
+        description: 'Generate prompt text for AI to produce valid json-render ui.json',
+        examples: [
+            {
+                scenario: 'Generate a generic prompt',
+                command: 'agentstage prompt ui',
+                explanation: 'Outputs a reusable prompt with JSON shape and binding rules'
+            },
+            {
+                scenario: 'Generate with page context',
+                command: 'agentstage prompt ui --page todo',
+                explanation: 'Includes current ui.json/store.json context to guide refinement'
+            },
+            {
+                scenario: 'Pipe prompt into a file',
+                command: 'agentstage prompt ui --page todo > /tmp/todo.prompt.txt',
+                explanation: 'Useful for automation or LLM pipeline integration'
+            }
+        ],
+        commonErrors: [
+            {
+                error: 'Project not initialized',
+                cause: 'Using --page without initialized workspace',
+                fix: 'Run: agentstage init'
+            },
+            {
+                error: 'Page "xxx" not found',
+                cause: 'The target page has no pages/<id>/ui.json yet',
+                fix: 'Run: agentstage page add <id> first'
+            }
+        ]
+    },
     'ui-json': {
         title: 'UI JSON Format',
         description: 'Complete guide to json-render UI specification',
@@ -201,7 +239,7 @@ push/pop: Navigate forward/back`
 };
 export const guideCommand = new Command('guide')
     .description('Get guidance for using agentstage (for AI Agents)')
-    .argument('[topic]', 'Topic to get guidance on (quickstart, page-add, ui-json, state-management, validate)')
+    .argument('[topic]', 'Topic to get guidance on (quickstart, page-add, prompt-ui, ui-json, state-management, validate)')
     .option('--list', 'List all available topics')
     .action(async (topic, options) => {
     if (options.list || !topic) {
@@ -216,6 +254,7 @@ export const guideCommand = new Command('guide')
         console.log();
         console.log(c.dim('Example:'));
         console.log(`  ${c.cyan('agentstage guide quickstart')}`);
+        console.log(`  ${c.cyan('agentstage guide prompt-ui')}`);
         console.log(`  ${c.cyan('agentstage guide ui-json')}`);
         console.log();
         return;

package/dist/commands/page/add.js

@@ -39,6 +39,7 @@ export const pageAddCommand = new Command('add')
         await mkdir(pagesDir, { recursive: true });
         // 处理 UI
         let uiContent;
+        const hasCustomUi = options.uiStdin || options.ui;
         if (options.uiStdin) {
             // 从 stdin 读取 UI
             const input = await readStdin();
@@ -108,30 +109,20 @@ export const pageAddCommand = new Command('add')
         }
         // 输出结果
         const port = config?.port || 3000;
-        if (options.ui) {
-            // 提供了完整 UI
-            printAgentSuccess(`Page "${name}" created with custom UI and state`, [
+        if (hasCustomUi) {
+            printAgentSuccess(`Page "${name}" created with custom UI`, [
                 `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(`  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)));
-            console.log(c.bold('🤖 AI Prompts'));
-            console.log(c.bold('─'.repeat(60)));
-            console.log();
-            console.log(c.dim('Send this to AI to generate UI:'));
-            console.log();
-            console.log(generatePromptContent(name));
-            console.log(c.bold('─'.repeat(60)));
-            console.log();
+            printAgentHint(`Generate prompt: agentstage prompt ui --page ${name}`);
             printAgentHint(`Or provide UI directly: agentstage page add ${name} --ui '{...}' --state '{...}'`);
         }
     }
@@ -182,46 +173,3 @@ function generateDefaultState(name) {
 function toTitleCase(str) {
     return str.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
 }
-function generatePromptContent(name) {
-    const titleName = toTitleCase(name);
-    return `# Generate UI for "${titleName}" page
-
-Output JSON format:
-\`\`\`json
-{
-  "root": "main",
-  "elements": {
-    "element-id": {
-      "type": "ComponentName",
-      "props": { ... },
-      "children": ["child-id-1"],
-      "on": { "press": { "action": "setState", "params": {...} } }
-    }
-  }
-}
-\`\`\`
-
-## Components
-
-**Layout**: Stack(direction, gap, align, justify), Card(title, description), Separator
-**Typography**: Heading(text, level), Text(text, variant), Badge(text, variant)  
-**Inputs**: Input(label, name, type, placeholder), Button(label, variant)
-**Data**: Table(columns, rows), Tabs(tabs), Dialog(title, openPath)
-
-## State Bindings
-- Read: \`{ "$state": "/path" }\`
-- Write: \`{ "$bindState": "/path" }\`
-- List item: \`{ "$item": "field" }\`
-
-## Actions
-- \`setState\`: { statePath: string, value: any }
-- \`pushState\`: { statePath: string, value: any }
-- \`removeState\`: { statePath: string, index: number }
-
-## Usage
-\`\`\`bash
-agentstage page add ${name} --ui '{"root":"main",...}' --state '{"count":0}'
-\`\`\`
-
-Generate UI for: [describe your page here]`;
-}

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

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

package/dist/commands/prompt/index.js

@@ -0,0 +1,5 @@
+import { Command } from "commander";
+import { promptUiCommand } from "./ui.js";
+export const promptCommand = new Command("prompt")
+    .description("Generate prompts for AI-assisted page creation")
+    .addCommand(promptUiCommand);

package/dist/commands/prompt/ui.d.ts

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

package/dist/commands/prompt/ui.js

@@ -0,0 +1,60 @@
+import { Command } from "commander";
+import consola from "consola";
+import { existsSync } from "fs";
+import { readFile } from "fs/promises";
+import { join } from "pathe";
+import { buildUiPrompt } from "../../lib/prompt/ui-prompt.js";
+import { getWorkspaceDir, isInitialized } from "../../utils/paths.js";
+function parsePageId(pageId) {
+    if (!/^[a-z0-9-]+$/.test(pageId)) {
+        throw new Error("Invalid pageId. Allowed: lowercase letters, numbers, hyphen");
+    }
+}
+async function readJson(path) {
+    const content = await readFile(path, "utf8");
+    return JSON.parse(content);
+}
+export const promptUiCommand = new Command("ui")
+    .description("Print prompt text for generating json-render ui.json")
+    .option("--page <pageId>", "Use an existing page as context")
+    .option("--compact", "Hide verbose context sections", false)
+    .action(async (options) => {
+    const pageId = options.page;
+    const compact = options.compact === true;
+    try {
+        if (!pageId) {
+            process.stdout.write(`${buildUiPrompt({ compact })}\n`);
+            return;
+        }
+        parsePageId(pageId);
+        if (!isInitialized()) {
+            throw new Error("Project not initialized. Please run `agentstage init` first.");
+        }
+        const workspaceDir = await getWorkspaceDir();
+        const pageDir = join(workspaceDir, "pages", pageId);
+        const uiPath = join(pageDir, "ui.json");
+        const storePath = join(pageDir, "store.json");
+        if (!existsSync(uiPath)) {
+            throw new Error(`Page "${pageId}" not found: ${uiPath}`);
+        }
+        const uiSpec = await readJson(uiPath);
+        let state = undefined;
+        if (existsSync(storePath)) {
+            const store = await readJson(storePath);
+            if (typeof store === "object" && store !== null && "state" in store) {
+                state = store.state;
+            }
+        }
+        process.stdout.write(`${buildUiPrompt({
+            pageId,
+            uiSpec,
+            state,
+            compact,
+        })}\n`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Failed to build ui prompt";
+        consola.error(message);
+        process.exit(1);
+    }
+});

package/dist/index.js

@@ -12,6 +12,7 @@ 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 { promptCommand } from './commands/prompt/index.js';
 import { guideCommand } from './commands/guide.js';
 import { cleanupCommand } from './commands/cleanup.js';
 import { componentsCommand } from './commands/components.js';
@@ -30,6 +31,7 @@ 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(promptCommand); // prompt ui
 program.addCommand(guideCommand); // guide
 program.addCommand(cleanupCommand); // cleanup
 program.addCommand(componentsCommand); // components

package/dist/lib/prompt/ui-prompt.d.ts

@@ -0,0 +1,7 @@
+export interface BuildUiPromptInput {
+    pageId?: string;
+    uiSpec?: unknown;
+    state?: unknown;
+    compact?: boolean;
+}
+export declare function buildUiPrompt(input?: BuildUiPromptInput): string;

package/dist/lib/prompt/ui-prompt.js

@@ -0,0 +1,49 @@
+function toJson(value) {
+    return JSON.stringify(value, null, 2);
+}
+export function buildUiPrompt(input = {}) {
+    const sections = [];
+    const compact = input.compact === true;
+    const pageLabel = input.pageId ? ` for page "${input.pageId}"` : "";
+    sections.push(`Generate a json-render UI spec${pageLabel}.`);
+    sections.push("Return ONLY one valid JSON object.");
+    sections.push("Do not output markdown fences.");
+    sections.push("Do not output explanations.");
+    sections.push("");
+    sections.push("Required output shape:");
+    sections.push('{ "root": "element-id", "elements": { "element-id": { "type": "ComponentName", "props": {}, "children": [] } } }');
+    sections.push("");
+    sections.push("Rules:");
+    sections.push("1. root must reference an existing element key in elements.");
+    sections.push("2. Every children element id must exist in elements.");
+    sections.push("3. Use only registered component names.");
+    sections.push("4. Keep all props JSON-serializable.");
+    sections.push('5. State read binding: { "$state": "/path" }');
+    sections.push('6. Two-way binding: { "$bindState": "/path" }');
+    sections.push('7. List item binding: { "$item": "fieldName" }');
+    sections.push('8. List index binding: { "$index": true }');
+    sections.push("");
+    sections.push("Common components:");
+    sections.push("Layout: Stack, Card, Grid, Separator");
+    sections.push("Typography: Heading, Text, Badge");
+    sections.push("Input: Input, Button, Select, Checkbox, Switch");
+    sections.push("Data/Feedback: Table, Tabs, Dialog, Accordion, Alert, Progress, Skeleton, Spinner");
+    sections.push("");
+    sections.push("Actions:");
+    sections.push('Use event handlers like: "on": { "press": { "action": "setState", "params": { ... } } }');
+    sections.push("Common actions: setState, pushState, removeState");
+    if (input.state !== undefined) {
+        sections.push("");
+        sections.push("Current state context:");
+        sections.push(toJson(input.state));
+    }
+    if (input.uiSpec !== undefined && !compact) {
+        sections.push("");
+        sections.push("Existing ui.json context:");
+        sections.push(toJson(input.uiSpec));
+        sections.push("If you improve it, keep ids stable when possible.");
+    }
+    sections.push("");
+    sections.push("Now output the final JSON object only.");
+    return sections.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-stage",
-  "version": "0.2.18",
+  "version": "0.2.19",
   "files": [
     "dist"
   ],