@next-vibe/checker 1.0.11 → 1.0.12

package/src/app/api/[locale]/system/unified-interface/README.md

@@ -0,0 +1,328 @@
+# Unified UI System
+
+> **Part of NextVibe Framework** (GPL-3.0) - Located in `src/app/api/[locale]/system/unified-interface/`
+
+**One Definition, All Platforms**
+
+## What Is This?
+
+The Unified UI System lets you write **one endpoint definition** and automatically get:
+
+- ✅ **AI Tools** - Your AI assistant can call your APIs
+- ✅ **CLI Commands** - Run from terminal with `vibe command-name`
+- ✅ **MCP Tools** - Works in Claude Desktop, Cline, and other MCP clients
+- ✅ **React Hooks** - Type-safe hooks for your web app
+- ✅ **React Native** - Same hooks work on mobile
+- ✅ **Widget-Based UI** - Results render beautifully everywhere
+
+## Why Use This?
+
+**Before**: Write separate code for AI tools, CLI, web UI, mobile UI
+**After**: Write one `definition.ts` file, get everything automatically
+
+**Benefits**:
+
+- 🚀 **10x Faster Development** - One definition instead of 5+ implementations
+- 🔒 **Type-Safe** - Full TypeScript inference everywhere
+- 🎨 **Beautiful UI** - Automatic widget-based rendering
+- 🔐 **Secure** - Permission system built-in
+- 💰 **Cost Tracking** - Credit system integrated
+- 🌍 **i18n Ready** - Multi-language support
+
+## Quick Example
+
+### 1. Write One Definition
+
+```typescript
+// definition.ts
+const { POST } = createEndpoint({
+  method: Methods.POST,
+  path: ["user", "create"],
+  credits: 0, // Free operation
+
+  fields: objectField(
+    { type: WidgetType.CONTAINER },
+    { request: "data", response: true },
+    {
+      email: requestDataField({ type: WidgetType.TEXT }, z.string().email()),
+      name: requestDataField({ type: WidgetType.TEXT }, z.string().min(1)),
+    },
+  ),
+});
+```
+
+### 2. Use Everywhere Automatically
+
+**Terminal (CLI)**:
+
+```bash
+vibe create-user --email=john@example.com --name="John Doe"
+```
+
+**AI Chat**:
+
+```
+User: "Create a user account for john@example.com named John Doe"
+AI: *calls create-user tool automatically*
+```
+
+**Claude Desktop (MCP)**:
+
+```json
+{
+  "mcpServers": {
+    "Vibe": { "command": "npx", "args": ["vibe", "mcp"] }
+  }
+}
+```
+
+**React App**:
+
+```typescript
+const { mutate } = useEndpoint(definition);
+mutate({ email: "john@example.com", name: "John Doe" });
+```
+
+**React Native App**:
+
+```typescript
+// Same hook works on mobile!
+const { mutate } = useEndpoint(definition);
+```
+
+## How It Works
+
+```
+┌─────────────────────────────────────────┐
+│         definition.ts                    │
+│  • Method, path, fields                 │
+│  • Widget types for UI                  │
+│  • Permissions & credits                │
+└─────────────────────────────────────────┘
+                  │
+    ┌─────────────┼─────────────┬─────────────┐
+    ▼             ▼             ▼             ▼
+┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐
+│   AI   │  │  CLI   │  │  MCP   │  │ React  │
+│  Tool  │  │Command │  │  Tool  │  │  Hook  │
+└────────┘  └────────┘  └────────┘  └────────┘
+```
+
+## Widget System
+
+Define how data should be displayed:
+
+```typescript
+// Text display
+{
+  type: WidgetType.TEXT;
+}
+
+// Clickable link
+{
+  type: WidgetType.LINK;
+}
+
+// Data table with sorting
+{
+  type: WidgetType.DATA_TABLE;
+}
+
+// Card grid
+{
+  type: WidgetType.DATA_CARDS;
+}
+
+// Search results
+{
+  type: WidgetType.LINK_LIST;
+}
+
+// Code with syntax highlighting
+{
+  type: WidgetType.CODE_OUTPUT;
+}
+
+// Markdown content
+{
+  type: WidgetType.MARKDOWN;
+}
+```
+
+Results automatically render beautifully in:
+
+- AI chat interface
+- CLI terminal (colored output)
+- React components
+- React Native apps
+
+## Permission System
+
+Control who can access your endpoints:
+
+```typescript
+allowedRoles: [UserRole.ADMIN]; // Only admins
+allowedRoles: [UserRole.CUSTOMER]; // Authenticated users
+allowedRoles: [UserRole.PUBLIC]; // Everyone
+allowedRoles: [UserRole.CLI_OFF]; // Disable CLI access
+allowedRoles: [UserRole.AI_TOOL_OFF]; // Disable AI access
+```
+
+Permissions enforced automatically everywhere.
+
+## Credit System
+
+Set credit costs for your endpoints:
+
+```typescript
+credits: 0; // Free
+credits: 0.65; // Web search (calculated from FEATURE_COSTS)
+credits: 0.52; // Text-to-speech per 1000 chars (calculated)
+credits: 10; // Expensive (e.g., GPT-4 message)
+```
+
+Credits automatically:
+
+- Checked before execution
+- Deducted after success
+- Logged in database
+- Displayed in UI
+
+## Type Safety
+
+Full TypeScript inference everywhere:
+
+```typescript
+// Types automatically inferred from definition
+export type RequestInput = typeof POST.types.RequestInput;
+export type ResponseOutput = typeof POST.types.ResponseOutput;
+
+// Use in your code with full autocomplete
+const result: ResponseOutput = await endpoint.mutate(input);
+```
+
+## i18n Support
+
+All user-facing text uses translation keys:
+
+```typescript
+title: "app.api.user.create.post.title";
+description: "app.api.user.create.post.description";
+```
+
+Automatically translated in:
+
+- AI tool descriptions
+- CLI help text
+- MCP tool descriptions
+- React UI labels
+- Error messages
+
+## Real-World Example: Web Search
+
+```typescript
+// brave-search/definition.ts
+const { GET } = createEndpoint({
+  method: Methods.GET,
+  path: ["agent", "web", "brave-search"],
+  credits: FEATURE_COSTS.BRAVE_SEARCH, // 0.65 credits per search
+
+  aiTool: {
+    displayName: "Search the Web",
+    icon: "search",
+    instructions: "Use this to find current information online",
+  },
+
+  fields: objectField(
+    { type: WidgetType.CONTAINER },
+    { request: "urlPathParams", response: true },
+    {
+      query: requestUrlParamField({ type: WidgetType.TEXT }, z.string().min(1)),
+      results: responseArrayField(
+        { type: WidgetType.LINK_LIST }, // Renders as clickable links!
+        objectField(
+          { type: WidgetType.LINK_CARD },
+          { response: true },
+          {
+            title: responseField({ type: WidgetType.TEXT }, z.string()),
+            url: responseField({ type: WidgetType.LINK }, z.string()),
+            snippet: responseField({ type: WidgetType.MARKDOWN }, z.string()),
+          },
+        ),
+      ),
+    },
+  ),
+});
+```
+
+**Result**: AI can search the web, and results display as beautiful, clickable link cards in the chat interface!
+
+## Best Practices
+
+### For Developers
+
+1. **Choose Appropriate Widget Types**
+   - Match widget to data type
+   - Use LINK for URLs
+   - Use DATA_TABLE for tabular data
+   - Use MARKDOWN for rich text
+
+2. **Set Reasonable Credit Costs**
+   - Free for simple operations
+   - 1-5 credits for API calls
+   - 10+ credits for expensive operations
+
+3. **Write Clear AI Instructions**
+   - Tell AI when to use your tool
+   - Provide examples
+   - Explain parameters
+
+4. **Use Semantic Aliases**
+   - Multiple ways to call same command
+   - User-friendly names
+   - Namespace related commands
+
+5. **Handle Errors Gracefully**
+   - Return clear error messages
+   - Suggest fixes
+   - Log for debugging
+
+## Troubleshooting
+
+**Tool not showing in AI chat**:
+
+- Check `allowedRoles` includes user's role
+- Verify `aiTool` metadata is defined
+- Check user has enough credits
+
+**CLI command not found**:
+
+- Check `aliases` are defined
+- Run `vibe list` to see all commands
+- Verify permissions
+
+**Widget not rendering**:
+
+- Check widget type is registered
+- Verify data structure matches widget
+- Check browser console for errors
+
+**Type errors**:
+
+- Run `npx vibe check` to validate
+- Check Zod schemas match data
+- Verify imports are correct
+
+## Learn More
+
+- **PLAN.md** - Implementation roadmap for contributors
+- **shared/widgets/** - Widget component documentation
+- **ai-tool/** - AI tool system details
+- **cli/** - CLI system details
+- **mcp/** - MCP integration details
+
+---
+
+**Status**: Production Ready
+**Version**: 1.0.0
+**Last Updated**: 2025-01-30

package/src/app/api/[locale]/system/unified-interface/cli/README.md

@@ -0,0 +1,349 @@
+# CLI System
+
+**Command-line interface for all API endpoints**
+
+## Overview
+
+The CLI System automatically converts your API endpoints into terminal commands. Uses the same endpoint registry as AI tools and MCP.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g vibe
+
+# Or use npx
+npx vibe <command>
+
+# Run a command
+vibe create-user --email=john@example.com --name="John Doe"
+
+# Use aliases
+vibe user:new --email=john@example.com
+vibe signup --email=john@example.com
+```
+
+## How It Works
+
+```
+1. Discovery
+   └─> Scans definition.ts files
+   └─> Extracts CLI metadata (aliases, params)
+
+2. Command Registration
+   └─> Registers commands with Commander.js
+   └─> Maps aliases to endpoints
+
+3. Execution
+   └─> Parses CLI arguments
+   └─> Validates parameters
+   └─> Calls endpoint via route handler
+   └─> Formats output (pretty or JSON)
+```
+
+## Command Naming
+
+Commands use path segments or aliases:
+
+```
+API Path: /user/create
+Command: vibe core:user:create
+
+Aliases: ["create-user", "user:new", "signup"]
+Commands: vibe create-user
+          vibe user:new
+          vibe signup
+```
+
+## Defining CLI Metadata
+
+```typescript
+// definition.ts
+const { POST } = createEndpoint({
+  method: Methods.POST,
+  path: ["user", "create"],
+  aliases: ["create-user", "user:new", "signup"],
+
+  cli: {
+    firstCliArgument: "email", // First positional arg
+    examples: [
+      {
+        command: "create-user john@example.com --name='John Doe'",
+        description: "Create a user with email and name",
+      },
+    ],
+  },
+
+  // ... rest of definition
+});
+```
+
+## CLI Arguments
+
+### Positional Arguments
+
+```bash
+# First argument is email (defined by firstCliArgument)
+vibe create-user john@example.com --name="John Doe"
+```
+
+### Named Arguments
+
+```bash
+# All fields can be named arguments
+vibe create-user --email=john@example.com --name="John Doe"
+```
+
+### Boolean Flags
+
+```bash
+# Boolean fields become flags
+vibe migrate --force
+vibe migrate --no-force
+```
+
+### Arrays
+
+```bash
+# Arrays use comma-separated values
+vibe send-email --to=john@example.com,jane@example.com
+```
+
+### JSON Objects
+
+```bash
+# Complex objects use JSON
+vibe create-user --metadata='{"source":"cli","version":"1.0"}'
+```
+
+## Output Formats
+
+### Pretty (Default)
+
+```bash
+vibe create-user --email=john@example.com
+
+✓ User created successfully
+  ID: 550e8400-e29b-41d4-a716-446655440000
+  Email: john@example.com
+  Name: John Doe
+  Created: 2024-01-15 10:30:00
+```
+
+### JSON
+
+```bash
+vibe create-user --email=john@example.com --output=json
+
+{
+  "success": true,
+  "data": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "email": "john@example.com",
+    "name": "John Doe",
+    "createdAt": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+## Authentication
+
+CLI authentication flow:
+
+1. Check `.vibe.session` file (from login/signup)
+2. If no session, check `VIBE_CLI_USER_EMAIL` env var and authenticate from DB
+3. If `VIBE_CLI_USER_EMAIL` is empty, create public user with new lead
+4. If email is set but user not found in DB, return error
+
+```bash
+# Use authenticated user from DB
+export VIBE_CLI_USER_EMAIL=admin@example.com
+vibe create-user --email=john@example.com
+
+# Use public user (no env var set)
+unset VIBE_CLI_USER_EMAIL
+vibe create-user --email=john@example.com
+```
+
+## Permission System
+
+Commands respect endpoint permissions:
+
+```typescript
+// definition.ts
+allowedRoles: [UserRole.ADMIN, UserRole.CLI_OFF];
+
+// user must have ADMIN; disabled for CLI 
+```
+
+Special role `WEB_OFF` and `AI_TOOL_OFF` for CLI-only operations:
+
+- Database migrations
+- System maintenance
+- Dangerous operations
+
+## Built-in Commands
+
+### Help
+
+```bash
+# List all commands
+vibe --help
+
+# Command-specific help
+vibe create-user --help
+```
+
+### Version
+
+```bash
+vibe --version
+```
+
+### Setup
+
+```bash
+# Install CLI globally
+vibe setup:install
+
+# Check installation
+vibe setup:status
+
+# Update CLI
+vibe setup:update
+
+# Uninstall CLI
+vibe setup:uninstall
+```
+
+### Vibe Check
+
+```bash
+# Check all files
+vibe check
+
+# Check specific path
+vibe check src/app/api/[locale]/user
+
+# Lint only
+vibe lint
+
+# Type check only
+vibe typecheck
+```
+
+## Configuration
+
+```typescript
+// config/platform-config.ts
+export const CLI_CONFIG: PlatformConfig = {
+  platform: Platform.CLI,
+  rootDir: "src/app/api/[locale]",
+  excludePaths: [], // CLI can access everything
+  cache: {
+    enabled: true,
+    ttl: 10 * 60 * 1000, // 10 minutes
+  },
+  rateLimit: {
+    enabled: false, // No rate limiting for CLI
+  },
+};
+```
+
+## Best Practices
+
+### 1. Use Semantic Aliases
+
+```typescript
+aliases: [
+  "create-user", // Imperative
+  "user:new", // Namespaced
+  "signup", // User-facing term
+];
+```
+
+### 2. Define First Argument
+
+```typescript
+cli: {
+  firstCliArgument: "email",  // Most common argument
+}
+```
+
+### 3. Provide Examples
+
+```typescript
+cli: {
+  examples: [
+    {
+      command: "create-user john@example.com --name='John Doe'",
+      description: "Create a user with email and name",
+    },
+    {
+      command: "create-user --email=john@example.com --role=ADMIN",
+      description: "Create an admin user",
+    },
+  ],
+}
+```
+
+### 4. Handle Errors Gracefully
+
+```typescript
+errorTypes: {
+  [EndpointErrorTypes.VALIDATION_FAILED]: {
+    title: "Invalid input",
+    description: "Please check that email is valid and name is not empty"
+  }
+}
+```
+
+## Scripting
+
+CLI is perfect for automation:
+
+```bash
+#!/bin/bash
+
+# Create multiple users
+for email in john@example.com jane@example.com; do
+  vibe create-user --email=$email --name="Test User"
+done
+
+# Check status
+if vibe db:ping --output=json | jq -r '.success' | grep -q 'true'; then
+  echo "Database is healthy"
+else
+  echo "Database is down"
+  exit 1
+fi
+```
+
+## Troubleshooting
+
+**"Command not found: vibe"**
+
+```bash
+npm install -g vibe
+# or use npx
+npx vibe <command>
+```
+
+**"Permission denied"**
+
+- Check CLI user's role in database
+- Verify endpoint's allowedRoles
+- Use correct VIBE_CLI_USER_EMAIL
+
+**"Invalid arguments"**
+
+- Check command help: `vibe <command> --help`
+- Verify argument names match definition
+- Use quotes for strings with spaces
+
+## Related
+
+- [Main README](../README.md)
+- [Shared README](../shared/README.md)
+- [AI Tool README](../ai-tool/README.md)
+- [MCP README](../mcp/README.md)