@lantos1618/better-ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lyndon Leong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# Better UI - AUI (Assistant-UI) System
+
+A concise and elegant tool system for Next.js that enables AI assistants to control both frontend and backend through a fluent API.
+
+## 🚀 Quick Start
+
+```tsx
+// Simple tool - just 2 methods
+const simpleTool = aui
+  .tool('weather')
+  .input(z.object({ city: z.string() }))
+  .execute(async ({ input }) => ({ temp: 72, city: input.city }))
+  .render(({ data }) => <div>{data.city}: {data.temp}°</div>);
+
+// Complex tool - adds client optimization
+const complexTool = aui
+  .tool('search')
+  .input(z.object({ query: z.string() }))
+  .execute(async ({ input }) => db.search(input.query))
+  .clientExecute(async ({ input, ctx }) => {
+    // Only when you need caching, offline, etc.
+    const cached = ctx.cache.get(input.query);
+    return cached || ctx.fetch('/api/tools/search', { body: input });
+  })
+  .render(({ data }) => <SearchResults results={data} />);
+```
+
+## ✨ Features
+
+- **Fluent API**: Chain methods for clean, readable tool definitions
+- **Type Safety**: Full TypeScript support with Zod schemas
+- **Minimal Boilerplate**: Only `input()` and `execute()` are required
+- **Dual Execution**: Server-side execution with optional client-side optimization
+- **React Integration**: Seamless rendering of tool results
+- **AI-Ready**: Designed for AI assistants to control UI/backend
+
+## 🏗️ Architecture
+
+```
+┌─────────────┐     ┌──────────────┐     ┌─────────────┐
+│   Client    │────▶│  AUI System  │────▶│   Server    │
+│  Component  │     │              │     │   Handler   │
+└─────────────┘     └──────────────┘     └─────────────┘
+       │                    │                     │
+       ▼                    ▼                     ▼
+  ToolRenderer     ClientExecutor         ToolExecutor
+                    (optional)            (server-side)
+```
+
+## 📦 Installation
+
+```bash
+npm install
+npm run dev
+```
+
+## 🛠️ API Reference
+
+### Tool Builder
+
+- `.tool(name)` - Create a new tool builder
+- `.input(schema)` - Define input validation with Zod
+- `.execute(handler)` - Server-side execution logic
+- `.clientExecute(handler)` - Optional client-side execution
+- `.render(component)` - React component for rendering results
+- `.description(text)` - Optional tool description
+- Returns a built tool object ready to use (no build step needed)
+
+### React Components
+
+```tsx
+import { ToolExecutorProvider, ToolRenderer, useToolExecutor } from '@/lib/aui/client';
+
+// Provider setup
+<ToolExecutorProvider tools={[weatherTool, searchTool]}>
+  <App />
+</ToolExecutorProvider>
+
+// Render a tool result
+<ToolRenderer toolCall={toolCall} tool={weatherTool} />
+
+// Hook usage
+const executor = useToolExecutor();
+const result = await executor.execute(toolCall);
+```
+
+## 🔧 Usage Examples
+
+### Basic Tool
+```tsx
+const weatherTool = aui
+  .tool('weather')
+  .input(z.object({ city: z.string() }))
+  .execute(async ({ input }) => {
+    const response = await fetch(`/api/weather?city=${input.city}`);
+    return response.json();
+  })
+  .render(({ data }) => (
+    <div className="weather-card">
+      <h3>{data.city}</h3>
+      <p>{data.temp}°F</p>
+    </div>
+  ));
+```
+
+### Tool with Client Optimization
+```tsx
+const searchTool = aui
+  .tool('search')
+  .input(z.object({ query: z.string() }))
+  .execute(async ({ input }) => {
+    return await database.search(input.query);
+  })
+  .clientExecute(async ({ input, ctx }) => {
+    // Client-side caching and offline support
+    const cached = ctx.cache.get(input.query);
+    if (cached) return cached;
+    
+    const result = await ctx.fetch('/api/aui', {
+      method: 'POST',
+      body: JSON.stringify({
+        toolCall: { toolName: 'search', input }
+      })
+    });
+    
+    ctx.cache.set(input.query, result);
+    return result;
+  })
+  .render(({ data }) => <SearchResults results={data} />);
+```
+
+## 🗂️ Project Structure
+
+```
+better-ui/
+├── app/                    # Next.js app directory
+│   ├── api/               # API routes
+│   └── aui-demo/          # Demo pages
+├── lib/aui/               # AUI system core
+│   ├── core/              # Core builder and registry
+│   ├── client/            # Client-side execution
+│   ├── server/            # Server-side execution
+│   ├── tools/             # Example tools
+│   └── types/             # TypeScript definitions
+├── examples/              # Usage examples
+└── agent/                 # Development metadata
+```
+
+## 🧪 Testing
+
+```bash
+npm test
+npm run type-check
+npm run lint
+```
+
+## 🚀 Development
+
+```bash
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
+
+# Start production server
+npm start
+```
+
+## 📚 Documentation
+
+- [AUI System Overview](AUI.md) - Detailed system documentation
+- [Examples](./examples/) - Complete usage examples
+- [API Reference](./lib/aui/README.md) - Core API documentation
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## 📄 License
+
+This project is private and proprietary.
+
+---
+
+Built with ❤️ using Next.js, TypeScript, and Zod.

package/lib/aui/README.md

@@ -0,0 +1,136 @@
+# AUI (Assistant-UI) System
+
+A concise, type-safe tool system for AI assistants to control frontend and backend operations in Next.js/Vercel applications.
+
+## Quick Start
+
+```tsx
+import aui from '@/lib/aui';
+import { z } from 'zod';
+
+// Simple tool - just 2 methods
+const simpleTool = aui
+  .tool('weather')
+  .input(z.object({ city: z.string() }))
+  .execute(async ({ input }) => ({ temp: 72, city: input.city }))
+  .render(({ data }) => <div>{data.city}: {data.temp}°</div>);
+
+// Complex tool - adds client optimization
+const complexTool = aui
+  .tool('search')
+  .input(z.object({ query: z.string() }))
+  .execute(async ({ input }) => db.search(input.query))
+  .clientExecute(async ({ input, ctx }) => {
+    // Only when you need caching, offline, etc.
+    const cached = ctx.cache.get(input.query);
+    return cached || ctx.fetch('/api/tools/search', { body: input });
+  })
+  .render(({ data }) => <SearchResults results={data} />);
+```
+
+## Core Features
+
+- **Concise API**: Define tools in 2-4 method calls
+- **Type Safety**: Full TypeScript support with Zod validation
+- **Dual Execution**: Run on server (default) or client (optimized)
+- **React Integration**: Built-in rendering and hooks
+- **Context Management**: Caching, sessions, and state
+- **AI-Ready**: Designed for AI assistant control
+
+## API Methods
+
+### Core Methods
+- `.tool(name)` - Create a new tool
+- `.input(schema)` - Define input validation with Zod
+- `.execute(handler)` - Server-side execution logic
+- `.render(component)` - React component for rendering results
+
+### Optional Methods
+- `.clientExecute(handler)` - Client-side execution with caching
+- `.middleware(fn)` - Add middleware for auth, logging, etc.
+- `.describe(text)` - Add description for documentation
+- `.tag(...tags)` - Add tags for organization
+
+## Examples
+
+See `/lib/aui/examples/` for complete examples including:
+- Weather tool (simple)
+- Search tool (with caching)
+- Calculator tool (with validation)
+- Form tool (with middleware)
+- Analytics tool (complex visualization)
+
+## Using Tools in React
+
+```tsx
+import { useAUITool, AUIProvider } from '@/lib/aui';
+
+function MyComponent() {
+  const { execute, data, loading, error } = useAUITool(weatherTool);
+  
+  return (
+    <div>
+      <button onClick={() => execute({ city: 'NYC' })}>
+        Get Weather
+      </button>
+      {loading && <div>Loading...</div>}
+      {data && weatherTool.renderer({ data })}
+    </div>
+  );
+}
+
+// Wrap your app with AUIProvider
+export default function App() {
+  return (
+    <AUIProvider>
+      <MyComponent />
+    </AUIProvider>
+  );
+}
+```
+
+## AI Control Example
+
+Enable AI assistants to control both frontend and backend:
+
+```tsx
+const databaseTool = aui
+  .tool('database')
+  .input(z.object({
+    table: z.string(),
+    operation: z.enum(['select', 'insert', 'update', 'delete']),
+    conditions: z.record(z.any()).optional()
+  }))
+  .execute(async ({ input }) => {
+    // Server-side database operations
+    return await db[input.operation](input.table, input.conditions);
+  })
+  .clientExecute(async ({ input, ctx }) => {
+    // Client-side optimistic updates
+    if (input.operation === 'select') {
+      const cached = ctx.cache.get(`${input.table}:${input.operation}`);
+      if (cached) return cached;
+    }
+    return ctx.fetch('/api/database', { body: input });
+  });
+```
+
+## AI Control Examples
+
+The system includes comprehensive examples for AI control in `/lib/aui/examples/ai-control-full.tsx`:
+
+- **Database Operations**: Query and manipulate data
+- **UI Control**: Manage modals, navigation, themes
+- **File System**: Read/write files (server-side)
+- **API Integration**: Call external APIs with CORS proxy
+- **Real-time Streams**: WebSocket/SSE connections
+- **Form Generation**: Dynamic form creation
+- **Analytics**: Event tracking and analysis
+
+## Testing
+
+```bash
+npm test -- --testPathPattern=aui
+```
+
+All 63 tests passing ✅

package/lib/aui/__tests__/aui-complete.test.ts

@@ -0,0 +1,251 @@
+import { describe, it, expect, beforeEach } from '@jest/globals';
+import aui, { z } from '../index';
+import { AIControlledTool, createAITool, aiControlSystem } from '../ai-control';
+import { clientControlSystem } from '../client-control';
+
+describe('AUI Complete System Tests', () => {
+  beforeEach(() => {
+    aui.clear();
+    aiControlSystem.clear();
+  });
+
+  describe('Simple Tool Pattern', () => {
+    it('should create a simple tool with execute and render', async () => {
+      const simpleTool = aui
+        .tool('weather')
+        .input(z.object({ city: z.string() }))
+        .execute(async ({ input }) => ({ temp: 72, city: input.city }))
+        .render(({ data }) => `${data.city}: ${data.temp}°` as any);
+
+      expect(simpleTool.name).toBe('weather');
+      
+      const result = await simpleTool.run({ city: 'New York' });
+      expect(result).toEqual({ temp: 72, city: 'New York' });
+    });
+
+    it('should validate input schema', async () => {
+      const tool = aui
+        .tool('validated')
+        .input(z.object({ 
+          required: z.string(),
+          optional: z.number().optional() 
+        }))
+        .execute(async ({ input }) => input);
+
+      await expect(tool.run({ required: 'test' })).resolves.toEqual({ required: 'test' });
+      await expect(tool.run({ missing: 'field' } as any)).rejects.toThrow();
+    });
+  });
+
+  describe('Complex Tool Pattern', () => {
+    it('should support client and server execution', async () => {
+      const complexTool = aui
+        .tool('search')
+        .input(z.object({ query: z.string() }))
+        .execute(async ({ input }) => ({ 
+          results: [`server: ${input.query}`] 
+        }))
+        .clientExecute(async ({ input, ctx }) => {
+          const cached = ctx.cache.get(input.query);
+          if (cached) return cached;
+          
+          const result = { results: [`client: ${input.query}`] };
+          ctx.cache.set(input.query, result);
+          return result;
+        });
+
+      // Server execution
+      const serverResult = await complexTool.run(
+        { query: 'test' }, 
+        { isServer: true, cache: new Map(), fetch: fetch }
+      );
+      expect(serverResult.results[0]).toContain('server');
+
+      // Client execution
+      const clientResult = await complexTool.run(
+        { query: 'test' }, 
+        { isServer: false, cache: new Map(), fetch: fetch }
+      );
+      expect(clientResult.results[0]).toContain('client');
+    });
+
+    it('should support middleware', async () => {
+      const middlewareTool = aui
+        .tool('with-middleware')
+        .input(z.object({ value: z.number() }))
+        .execute(async ({ input }) => ({ result: input.value }))
+        .middleware(async ({ input, next }) => {
+          input.value = input.value * 2;
+          const result = await next();
+          result.result = result.result + 10;
+          return result;
+        });
+
+      const result = await middlewareTool.run({ value: 5 });
+      expect(result).toEqual({ result: 20 }); // (5 * 2) + 10
+    });
+  });
+
+  describe('AI Control System', () => {
+    it('should create AI-controlled tools with permissions', () => {
+      const aiTool = createAITool('ai-tool', {
+        permissions: {
+          allowClientExecution: true,
+          allowServerExecution: false
+        }
+      })
+        .input(z.object({ action: z.string() }))
+        .execute(async ({ input }) => ({ executed: input.action }));
+
+      expect(aiTool).toBeInstanceOf(AIControlledTool);
+      expect(aiTool.name).toBe('ai-tool');
+    });
+
+    it('should enforce rate limiting', async () => {
+      const rateLimitedTool = createAITool('rate-limited', {
+        rateLimit: {
+          requestsPerMinute: 2
+        },
+        audit: true  // Enable audit to track execution for rate limiting
+      })
+        .input(z.object({ id: z.number() }))
+        .execute(async ({ input }) => ({ id: input.id }));
+
+      // First two requests should succeed
+      await expect(rateLimitedTool.run({ id: 1 })).resolves.toEqual({ id: 1 });
+      await expect(rateLimitedTool.run({ id: 2 })).resolves.toEqual({ id: 2 });
+      
+      // Third request should fail
+      await expect(rateLimitedTool.run({ id: 3 })).rejects.toThrow('Rate limit exceeded');
+    });
+
+    it('should track execution with audit', async () => {
+      const auditedTool = createAITool('audited', { audit: true })
+        .input(z.object({ action: z.string() }))
+        .execute(async ({ input }) => ({ result: input.action }));
+
+      await auditedTool.run({ action: 'test1' });
+      await auditedTool.run({ action: 'test2' });
+
+      const log = auditedTool.getExecutionLog();
+      expect(log).toHaveLength(2);
+      expect(log[0].input).toEqual({ action: 'test1' });
+      expect(log[1].input).toEqual({ action: 'test2' });
+    });
+  });
+
+  describe('Tool Registry', () => {
+    it('should register and retrieve tools', () => {
+      const tool1 = aui.tool('tool1')
+        .input(z.object({ x: z.number() }))
+        .execute(async ({ input }) => input);
+
+      const tool2 = aui.tool('tool2')
+        .input(z.object({ y: z.string() }))
+        .execute(async ({ input }) => input);
+
+      expect(aui.has('tool1')).toBe(true);
+      expect(aui.has('tool2')).toBe(true);
+      expect(aui.getToolNames()).toEqual(['tool1', 'tool2']);
+    });
+
+    it('should support tool tags and discovery', () => {
+      const apiTool = aui.tool('api')
+        .tag('backend', 'api', 'rest')
+        .execute(async () => ({ success: true }));
+
+      const uiTool = aui.tool('ui')
+        .tag('frontend', 'ui', 'dom')
+        .execute(async () => ({ rendered: true }));
+
+      expect(aui.findByTag('backend')).toContain(apiTool);
+      expect(aui.findByTag('frontend')).toContain(uiTool);
+      expect(aui.findByTags('backend', 'api')).toContain(apiTool);
+    });
+  });
+
+  describe('Tool Execution', () => {
+    it('should execute tools through AUI instance', async () => {
+      aui.tool('executor')
+        .input(z.object({ value: z.number() }))
+        .execute(async ({ input }) => ({ doubled: input.value * 2 }));
+
+      const result = await aui.execute('executor', { value: 5 });
+      expect(result).toEqual({ doubled: 10 });
+    });
+
+    it('should handle execution errors', async () => {
+      aui.tool('error-tool')
+        .execute(async () => {
+          throw new Error('Execution failed');
+        });
+
+      await expect(aui.execute('error-tool', {})).rejects.toThrow('Execution failed');
+    });
+  });
+
+  describe('Client Control System', () => {
+    it('should list available client tools', () => {
+      const tools = clientControlSystem.listClientTools();
+      
+      expect(tools).toContainEqual(
+        expect.objectContaining({
+          name: 'client-dom',
+          description: 'Manipulate DOM elements on the client'
+        })
+      );
+      
+      expect(tools).toContainEqual(
+        expect.objectContaining({
+          name: 'client-forms',
+          description: 'Control and interact with forms'
+        })
+      );
+    });
+  });
+
+  describe('Tool Serialization', () => {
+    it('should serialize tool configuration', () => {
+      const tool = aui.tool('serializable')
+        .describe('A test tool')
+        .tag('test', 'demo')
+        .input(z.object({ x: z.number() }))
+        .execute(async ({ input }) => input)
+        .clientExecute(async ({ input }) => input)
+        .render(() => null as any);
+
+      const json = tool.toJSON();
+      
+      expect(json).toEqual({
+        name: 'serializable',
+        description: 'A test tool',
+        tags: ['test', 'demo'],
+        hasInput: true,
+        hasExecute: true,
+        hasClientExecute: true,
+        hasRender: true,
+        hasMiddleware: false
+      });
+    });
+  });
+
+  describe('Context Management', () => {
+    it('should create and use context correctly', async () => {
+      const contextTool = aui.tool('context-test')
+        .execute(async ({ ctx }) => ({
+          isServer: ctx?.isServer,
+          hasCache: ctx?.cache instanceof Map,
+          hasFetch: typeof ctx?.fetch === 'function'
+        }));
+
+      const result = await contextTool.run({}, aui.createContext({ 
+        isServer: true,
+        user: { id: 1 }
+      }));
+
+      expect(result.isServer).toBe(true);
+      expect(result.hasCache).toBe(true);
+      expect(result.hasFetch).toBe(true);
+    });
+  });
+});