openkbs 0.0.76 → 0.0.78

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openkbs",
-  "version": "0.0.76",
+  "version": "0.0.78",
   "description": "OpenKBS - Command Line Interface",
   "main": "src/index.js",
   "scripts": {

package/src/actions.js

@@ -800,6 +800,35 @@ async function updateSkillsAction(silent = false) {
             return;
         }
 
+        // Always download the root CLAUDE.md file (even if skills are up to date)
+        const claudeDir = path.join(process.cwd(), '.claude');
+        await fs.ensureDir(claudeDir);
+
+        const claudeMdKey = 'templates/.claude/CLAUDE.md';
+        const claudeMdUrl = `https://${bucket}.s3.amazonaws.com/${claudeMdKey}`;
+
+        try {
+            const claudeMdContent = await new Promise((resolve, reject) => {
+                https.get(claudeMdUrl, (res) => {
+                    if (res.statusCode === 404) {
+                        reject(new Error('CLAUDE.md not found'));
+                        return;
+                    }
+                    const chunks = [];
+                    res.on('data', (chunk) => chunks.push(chunk));
+                    res.on('end', () => resolve(Buffer.concat(chunks)));
+                }).on('error', reject);
+            });
+            await fs.writeFile(path.join(claudeDir, 'CLAUDE.md'), claudeMdContent);
+            if (!silent) {
+                console.log('Downloaded: CLAUDE.md');
+            }
+        } catch (error) {
+            if (!silent) {
+                console.yellow('Could not download CLAUDE.md:', error.message);
+            }
+        }
+
         // Compare versions
         if (localVersion === remoteVersion) {
             console.green('OpenKBS skill is already up to date.');

package/templates/.claude/CLAUDE.md

@@ -1,6 +1,6 @@
 # OpenKBS Platform Project
 
-First update skills: `openkbs update skills`
+First update CLI and skills: `openkbs update`
 
 Then load the openkbs skill: `/openkbs`
 

package/templates/.claude/skills/openkbs/SKILL.md

@@ -121,6 +121,7 @@ openkbs postgres shell   # Connect to Postgres
 openkbs storage ls       # List S3 objects
 openkbs pulse status     # WebSocket status
 openkbs site push        # Deploy static site
+openkbs site spa /app/index.html  # Enable SPA routing
 ```
 
 ### Image Generation Service

package/templates/.claude/skills/openkbs/reference/elastic-services.md

@@ -240,6 +240,102 @@ channel.presence.subscribe((members) => {
 
 ---
 
+## SPA (Single Page Application) Support
+
+Host React, Vue, or Angular apps on your whitelabel domain with client-side routing.
+
+### Enable SPA Mode
+
+```bash
+openkbs site spa /app/index.html    # Enable SPA fallback
+openkbs site spa --disable          # Disable SPA mode
+```
+
+### How It Works
+
+When SPA mode is enabled, CloudFront catches 403/404 errors and serves your fallback file with HTTP 200. This allows client-side routing to handle all `/app/*` paths.
+
+```
+yourdomain.com/              → serves /index.html (landing page)
+yourdomain.com/app/          → serves /app/index.html (SPA)
+yourdomain.com/app/dashboard → serves /app/index.html (SPA handles route)
+yourdomain.com/app/profile   → serves /app/index.html (SPA handles route)
+```
+
+### Project Structure
+
+```
+my-platform/
+├── site/
+│   ├── index.html           # Static landing page
+│   └── app/                  # Built React app (copied from spa/dist)
+│       ├── index.html
+│       └── assets/
+├── spa/                      # React source (not deployed)
+│   ├── package.json
+│   ├── vite.config.js
+│   └── src/
+│       ├── main.jsx
+│       └── App.jsx
+└── openkbs.json
+```
+
+### Example: React + Vite SPA
+
+**1. Create React app:**
+
+```bash
+npm create vite@latest spa -- --template react
+cd spa
+npm install react-router-dom
+```
+
+**2. Configure Vite for /app base path:**
+
+```javascript
+// spa/vite.config.js
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  base: '/app/'
+})
+```
+
+**3. Add routing:**
+
+```jsx
+// spa/src/App.jsx
+import { BrowserRouter, Routes, Route, Link } from 'react-router-dom'
+
+function App() {
+  return (
+    <BrowserRouter basename="/app">
+      <nav>
+        <Link to="/">Home</Link>
+        <Link to="/dashboard">Dashboard</Link>
+      </nav>
+      <Routes>
+        <Route path="/" element={<Home />} />
+        <Route path="/dashboard" element={<Dashboard />} />
+      </Routes>
+    </BrowserRouter>
+  )
+}
+```
+
+**4. Build and deploy:**
+
+```bash
+cd spa && npm run build
+cp -r dist/* ../site/app/
+cd .. && openkbs site push
+openkbs site spa /app/index.html
+```
+
+---
+
 ## Full-Stack Example
 
 Complete Node.js application with all services:

package/version.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.76",
-  "releaseDate": "2026-01-14",
-  "releaseNotes": "OpenKBS CLI version 0.0.76"
+  "version": "0.0.78",
+  "releaseDate": "2026-01-16",
+  "releaseNotes": "OpenKBS CLI version 0.0.78"
 }

package/.claude/skills/openkbs/SKILL.md

@@ -1,250 +0,0 @@
----
-name: openkbs
-description: OpenKBS AI agent development framework. Use when creating, modifying, or deploying AI agents with backend handlers (onRequest, onResponse, actions.js), frontend components (contentRender.js), or elastic services (functions, postgres, storage, pulse). Trigger keywords: openkbs, kb, agent, handler, contentRender, elastic, memory, scheduled task.
----
-
-# OpenKBS Development
-
-OpenKBS is a framework for building AI-powered applications - from simple agents to full-stack platforms.
-
-## Two Usage Modes
-
-### 1. Agent-Only Mode
-Build a single conversational AI agent with backend handlers and custom UI.
-```
-openkbs create my-agent
-openkbs push
-```
-Simplest way to get started - just an agent with memory, commands, and custom frontend.
-
-### 2. Platform Mode (Full-Stack)
-Build complete SaaS platforms that **include agents** plus additional infrastructure.
-```
-openkbs deploy          # Deploy from openkbs.json
-openkbs stack status    # View deployed resources
-```
-
-Platform mode extends agent capabilities with:
-- **Multiple Agents**: Run several agents on one platform (in `agents/` folder)
-- **Elastic Functions**: Serverless Lambda (Node.js, Python, Java)
-- **Elastic Postgres**: Managed PostgreSQL (Neon) for relational data
-- **Elastic Storage**: S3 buckets + CloudFront CDN for files
-- **Elastic Pulse**: Real-time WebSocket pub/sub
-- **Whitelabel**: Custom domains (`example.com`) with static site (`site/` folder)
-
-**Architecture Note**: The whitelabel itself is an app with its own `kbId` (a service agent, not user-facing). This "parent" kbId is used throughout the stack for elastic services. Each agent in `agents/` has its own separate `kbId`.
-
-## Project Structure
-
-### Agent Structure
-```
-my-agent/
-├── app/
-│   ├── settings.json       # Agent configuration (model, itemTypes, MCP)
-│   └── instructions.txt    # System prompt for LLM
-├── src/
-│   ├── Events/
-│   │   ├── onRequest.js    # Pre-process user messages
-│   │   ├── onResponse.js   # Parse LLM output, execute commands
-│   │   ├── actions.js      # Command implementations
-│   │   ├── onCronjob.js    # Scheduled periodic tasks
-│   │   └── onPublicAPIRequest.js  # Webhook handler
-│   └── Frontend/
-│       ├── contentRender.js    # Custom React UI
-│       └── contentRender.json  # Frontend dependencies
-│
-```
-
-### Platform Structure
-```
-my-platform/
-├── agents/                        # Multiple AI agents
-│   ├── marketing-assistant/       # Each agent has full structure
-│   │   ├── app/
-│   │   │   ├── settings.json
-│   │   │   └── instructions.txt
-│   │   └── src/
-│   │       ├── Events/
-│   │       │   ├── onRequest.js
-│   │       │   ├── onResponse.js
-│   │       │   └── actions.js
-│   │       └── Frontend/
-│   │           └── contentRender.js
-│   └── support-agent/             # Another agent
-│       ├── app/
-│       └── src/
-├── functions/                     # Serverless Lambda functions
-│   └── api/
-│       └── index.mjs
-├── site/                          # Static site for whitelabel domain
-│   └── index.html
-└── openkbs.json                   # Elastic services config
-```
-
-### openkbs.json
-```json
-{
-  "elastic": {
-    "postgres": true,
-    "storage": true,
-    "pulse": true,
-    "functions": {
-      "api": { "runtime": "nodejs24.x", "memory": 512 }
-    }
-  }
-}
-```
-
-## Quick Commands
-
-### Agent Commands
-```bash
-openkbs create <name>    # Create new agent
-openkbs push             # Deploy to cloud
-openkbs pull             # Download from cloud
-openkbs update skills    # Update this skill
-```
-
-### Platform Commands
-```bash
-openkbs deploy           # Deploy all elastic services
-openkbs stack status     # Show deployed resources
-openkbs destroy          # Remove all resources (DANGEROUS)
-```
-
-### Elastic Services
-```bash
-openkbs fn list          # List Lambda functions
-openkbs fn push api      # Deploy function
-openkbs fn logs api      # View function logs
-openkbs postgres shell   # Connect to Postgres
-openkbs storage ls       # List S3 objects
-openkbs pulse status     # WebSocket status
-openkbs site push        # Deploy static site
-```
-
-### Image Generation Service
-Generate images directly from CLI using OpenKBS AI services:
-
-```bash
-# Generate with GPT
-openkbs service -m gpt-image -d '{"action":"createImage","prompt":"a logo"}' -o logo.png
-
-# Generate with Gemini
-openkbs service -m gemini-image -d '{"action":"createImage","prompt":"hero image"}' -o hero.png
-
-# Edit existing image
-openkbs service -m gpt-image -d '{"action":"createImage","prompt":"make it blue","imageUrls":["https://..."]}' -o edited.png
-```
-
-**Available models:**
-- `gpt-image` - OpenAI GPT Image (gpt-image-1.5)
-- `gemini-image` - Google Gemini Flash (gemini-2.5-flash-image)
-
-**Options for gpt-image:**
-| Option | Values | Default |
-|--------|--------|---------|
-| prompt | (required) | - |
-| size | "1024x1024", "1024x1536", "1536x1024", "auto" | "auto" |
-| quality | "low", "medium", "high", "auto" | "auto" |
-| n | Number of images | 1 |
-| output_format | "png", "jpg", "webp" | "png" |
-| background | "transparent", "opaque", "auto" | "auto" |
-| output_compression | 0-100 | 100 |
-| imageUrls | Array of URLs for editing | - |
-
-**Options for gemini-image:**
-| Option | Values | Default |
-|--------|--------|---------|
-| prompt | (required) | - |
-| aspect_ratio | "1:1", "16:9", "9:16", "4:3", "3:4" | "1:1" |
-| imageUrls | Array of URLs for reference | - |
-
-## Backend Handler Pattern
-
-Commands are XML tags with JSON content that the LLM outputs:
-
-```xml
-<commandName>{"param": "value"}</commandName>
-```
-
-The `handler.js` parses these tags, matches regex patterns in `actions.js`, and executes async functions:
-
-```javascript
-// actions.js pattern
-[/<googleSearch>([\s\S]*?)<\/googleSearch>/s, async (match) => {
-    const data = JSON.parse(match[1].trim());
-    const results = await openkbs.googleSearch(data.query);
-    return {
-        type: 'SEARCH_RESULTS',
-        data: results,
-        _meta_actions: ["REQUEST_CHAT_MODEL"]  // Loop back to LLM
-    };
-}]
-```
-
-## Meta Actions
-
-Control flow after command execution:
-
-- `["REQUEST_CHAT_MODEL"]` - Send result back to LLM for processing
-- `[]` - Display result to user, stop conversation
-
-## Memory System
-
-Configure in `settings.json`:
-
-```json
-{
-  "itemTypes": {
-    "memory": {
-      "attributes": [
-        { "attrName": "itemId", "attrType": "itemId", "encrypted": false },
-        { "attrName": "body", "attrType": "body", "encrypted": true }
-      ]
-    }
-  },
-  "options": {
-    "priorityItems": [{ "prefix": "memory_", "limit": 100 }]
-  }
-}
-```
-
-Priority items are auto-injected into LLM context.
-
-## Additional Resources
-
-### Reference Documentation
-- [reference/backend-sdk.md](reference/backend-sdk.md) - Backend SDK methods (openkbs.*)
-- [reference/frontend-sdk.md](reference/frontend-sdk.md) - Frontend React patterns
-- [reference/commands.md](reference/commands.md) - XML command definitions
-- [reference/elastic-services.md](reference/elastic-services.md) - Functions, Postgres, Storage, Pulse
-
-### Ready-to-Use Patterns
-Production-tested code blocks for common tasks:
-
-**Content & Media:**
-- [patterns/image-generation.md](patterns/image-generation.md) - AI image generation with upload
-- [patterns/video-generation.md](patterns/video-generation.md) - Async video generation with polling
-- [patterns/file-upload.md](patterns/file-upload.md) - Presigned URL file uploads
-- [patterns/web-publishing.md](patterns/web-publishing.md) - HTML page publishing
-
-**Memory & Storage:**
-- [patterns/memory-system.md](patterns/memory-system.md) - Memory CRUD with settings.json config
-- [patterns/vectordb-archive.md](patterns/vectordb-archive.md) - Long-term archive with semantic search
-
-**Scheduling & Automation:**
-- [patterns/scheduled-tasks.md](patterns/scheduled-tasks.md) - Task scheduling (one-time & recurring)
-- [patterns/cronjob-batch-processing.md](patterns/cronjob-batch-processing.md) - Batch file processing with state
-- [patterns/cronjob-monitoring.md](patterns/cronjob-monitoring.md) - Continuous monitoring with pulse control
-
-**External Integrations:**
-- [patterns/telegram.md](patterns/telegram.md) - Telegram bot commands (send messages)
-- [patterns/telegram-webhook.md](patterns/telegram-webhook.md) - Telegram webhook (receive messages)
-- [patterns/public-api-item-proxy.md](patterns/public-api-item-proxy.md) - Public API with geolocation
-
-### Complete Examples
-- [examples/ai-copywriter-agent/](examples/ai-copywriter-agent/) - Content generation agent
-- [examples/ai-marketing-agent/](examples/ai-marketing-agent/) - Marketing automation agent
-- [examples/monitoring-bot/](examples/monitoring-bot/) - Cronjob + Telegram monitoring agent
-- [examples/nodejs-demo/](examples/nodejs-demo/) - Platform with elastic functions

package/.claude/skills/openkbs/examples/ai-copywriter-agent/app/instructions.txt

@@ -1,96 +0,0 @@
-You are an autonomous agent for crafting intelligent, creative, and consistent content:
-
-Job:
-- Find and open at least one site that have correct, reliable and detailed information about the product
-- paraphrase and enrich it and generate a SEO friendly product description
-- Always search the official website of the manufacturer (Brand) and find information about the product from there.
-- If you see additional instructions in PROCESS_PRODUCT, execute them.
-- When you have obtained all the necessary information, output JOB_COMPLETED response.
-
-Important Guidelines:
-- use webpageToText command to read websites content in details
-- Always output one command per response and wait for the response before continuing
-- If an API call fails, so that you can't extract a required data, retry with different website or search query
-- When searching for product information, use the format: Product Name + Product Code.
-- Once all necessary information is obtained, deliver the final result using the following JSON format
-
-Output Format Success:
-{
-  "type": "JOB_COMPLETED",
-  "productID": "[productID]",
-  "productDescription": "[short plain text description]",
-  "metaDescription": "...",
-  "images": [{"url": "...", "title": "..."}, ...],
-  "attributes": {"size": "L", ...},
-  "videos": [
-    {"url": "[video1_url]", "title": "[video1_title]"},
-    {"url": "[video2_url]", "title": "[video2_title]"}
-  ]
-}
-
-Description: """
-Use this JSON format to output the final job response
-"""
-
-Output Format Failed:
-{"type": "JOB_FAILED", "reason": "fail reason summary"}
-Description: """
-Output this JSON format if you can't extract the required data
-"""
-
-LIST OF AVAILABLE COMMANDS:
-To execute a command, output it as text and wait for system response.
-
-<googleSearch>
-{
-  "query": "search query"
-}
-</googleSearch>
-Description: """
-Get results from Google Search API.
-"""
-
-<youtubeSearch>
-{
-  "query": "search query"
-}
-</youtubeSearch>
-Description: """
-Get results from YouTube Search API.
-"""
-
-<googleImageSearch>
-{
-  "query": "search query"
-}
-</googleImageSearch>
-Description: """
-Get results from Google Image Search.
-"""
-
-<webpageToText>
-{
-  "url": "https://example.com/page"
-}
-</webpageToText>
-Description: """
-Use this API to open/read web pages like product pages.
-"""
-
-<documentToText>
-{
-  "url": "https://example.com/document.pdf"
-}
-</documentToText>
-Description: """
-Extract text from documents (PDF, DOC, etc.).
-"""
-
-<imageToText>
-{
-  "url": "https://example.com/image.png"
-}
-</imageToText>
-Description: """
-OCR - Extract text from images.
-"""

package/.claude/skills/openkbs/examples/ai-copywriter-agent/app/settings.json

@@ -1,6 +0,0 @@
-{
-  "chatVendor": "anthropic",
-  "kbDescription": "An autonomous AI powerhouse for content generation",
-  "kbTitle": "Copywriter",
-  "model": "claude-sonnet-4-20250514"
-}

package/.claude/skills/openkbs/examples/ai-copywriter-agent/src/Events/actions.js

@@ -1,132 +0,0 @@
-const extractJSONFromText = (text) => {
-    let braceCount = 0, startIndex = text.indexOf('{');
-    if (startIndex === -1) return null;
-
-    for (let i = startIndex; i < text.length; i++) {
-        if (text[i] === '{') braceCount++;
-        if (text[i] === '}' && --braceCount === 0) {
-            try {
-                return JSON.parse(text.slice(startIndex, i + 1));
-            } catch {
-                return null;
-            }
-        }
-    }
-    return null;
-}
-
-export const getActions = (meta) => [
-    // IMPORTANT: Actions returning JOB_COMPLETED or JOB_FAILED stop agent execution and return final result
-    [/[\s\S]*"type"\s*:\s*"JOB_COMPLETED"[\s\S]*/, async (match, event) => {
-        const parsedData = extractJSONFromText(match[0]);
-        if (parsedData && parsedData.type === "JOB_COMPLETED") {
-            await openkbs.chats({
-                action: "updateChat",
-                title: await openkbs.encrypt(parsedData?.name),
-                chatIcon: '🟢',
-                chatId: event?.payload?.chatId
-            })
-
-            return parsedData;
-        }
-    }],
-
-    [/[\s\S]*"type"\s*:\s*"JOB_FAILED"[\s\S]*/, async (match, event) => {
-        const parsedData = extractJSONFromText(match[0]);
-        if (parsedData && parsedData.type === "JOB_FAILED") {
-            await openkbs.chats({
-                action: "updateChat",
-                title: await openkbs.encrypt(parsedData.reason),
-                chatIcon: '🔴',
-                chatId: event?.payload?.chatId
-            })
-            return parsedData;
-        }
-    }],
-
-    // Google Search with XML+JSON format
-    [/<googleSearch>([\s\S]*?)<\/googleSearch>/s, async (match) => {
-        try {
-            const data = JSON.parse(match[1].trim());
-            const response = await openkbs.googleSearch(data.query);
-            const results = response?.map(({ title, link, snippet, pagemap }) => ({
-                title, link, snippet, image: pagemap?.metatags?.[0]?.["og:image"]
-            }));
-            return { data: results, ...meta };
-        } catch (e) {
-            return { error: e.message, ...meta };
-        }
-    }],
-
-    // YouTube Search with XML+JSON format
-    [/<youtubeSearch>([\s\S]*?)<\/youtubeSearch>/s, async (match) => {
-        try {
-            const data = JSON.parse(match[1].trim());
-            const response = await openkbs.googleSearch(data.query + ' site:youtube.com', { videoOnly: true });
-            const results = response?.map(({ title, link, snippet, pagemap }) => ({
-                title,
-                link: link.replace('www.youtube.com/watch?v=', 'youtu.be/'),
-                snippet,
-                thumbnail: pagemap?.videoobject?.[0]?.thumbnailurl || pagemap?.metatags?.[0]?.["og:image"],
-                duration: pagemap?.videoobject?.[0]?.duration,
-                channel: pagemap?.metatags?.[0]?.["og:site_name"],
-            })).filter(item => item.link.includes('youtu'));
-            return { data: results, ...meta };
-        } catch (e) {
-            return { error: e.message, ...meta };
-        }
-    }],
-
-    // Google Image Search with XML+JSON format
-    [/<googleImageSearch>([\s\S]*?)<\/googleImageSearch>/s, async (match) => {
-        try {
-            const data = JSON.parse(match[1].trim());
-            const response = await openkbs.googleSearch(data.query, { searchType: 'image' });
-            const results = response?.map(({ title, link, snippet, pagemap }) => {
-                const imageObj = pagemap?.cse_image?.[0];
-                const thumbnail = imageObj?.src || pagemap?.metatags?.[0]?.["og:image"] || link;
-                return { title, link, snippet, image: thumbnail };
-            });
-            return { data: results, ...meta };
-        } catch (e) {
-            return { error: e.message, ...meta };
-        }
-    }],
-
-    // Webpage to Text with XML+JSON format
-    [/<webpageToText>([\s\S]*?)<\/webpageToText>/s, async (match) => {
-        try {
-            const data = JSON.parse(match[1].trim());
-            let response = await openkbs.webpageToText(data.url);
-            if (!response?.url) return { data: { error: "Unable to read website" }, ...meta };
-            return { data: response, ...meta };
-        } catch (e) {
-            return { error: e.response?.data || e.message, ...meta };
-        }
-    }],
-
-    // Document to Text with XML+JSON format
-    [/<documentToText>([\s\S]*?)<\/documentToText>/s, async (match) => {
-        try {
-            const data = JSON.parse(match[1].trim());
-            let response = await openkbs.documentToText(data.url);
-            return { data: response, ...meta };
-        } catch (e) {
-            return { error: e.response?.data || e.message, ...meta };
-        }
-    }],
-
-    // Image to Text (OCR) with XML+JSON format
-    [/<imageToText>([\s\S]*?)<\/imageToText>/s, async (match) => {
-        try {
-            const data = JSON.parse(match[1].trim());
-            let response = await openkbs.imageToText(data.url);
-            if (response?.detections?.[0]?.txt) {
-                response = { detections: response?.detections?.[0]?.txt };
-            }
-            return { data: response, ...meta };
-        } catch (e) {
-            return { error: e.response?.data || e.message, ...meta };
-        }
-    }],
-];