openkbs 0.0.65 → 0.0.67

package/README.md

@@ -1,7 +1,5 @@
 # OpenKBS · [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/open-kbs/openkbs-chat/blob/main/LICENSE) [![npm version](https://img.shields.io/badge/npm-v0.0.20-orange.svg)](https://www.npmjs.com/package/openkbs)
 
-
-
 OpenKBS is an extendable AI service designed to build,
 deploy and integrate AI agents and applications.
 

package/package.json

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

package/src/actions.js

@@ -611,20 +611,11 @@ async function downloadModifyAction() {
     });
 }
 
-async function updateKnowledgeAction(silent = false) {
+async function updateSkillsAction(silent = false) {
     try {
-        const knowledgeDir = path.join(process.cwd(), '.openkbs', 'knowledge');
-        const metadataPath = path.join(knowledgeDir, 'metadata.json');
-        const claudeMdPath = path.join(process.cwd(), 'CLAUDE.md');
-        
-        // Check if .openkbs/knowledge directory exists
-        if (!fs.existsSync(knowledgeDir)) {
-            if (!silent) {
-                console.red('Knowledge directory not found. Please ensure you are in an OpenKBS project directory.');
-            }
-            return;
-        }
-        
+        const skillsDir = path.join(process.cwd(), '.claude', 'skills', 'openkbs');
+        const metadataPath = path.join(skillsDir, 'metadata.json');
+
         // Get local metadata version
         let localVersion = null;
         if (fs.existsSync(metadataPath)) {
@@ -635,15 +626,14 @@ async function updateKnowledgeAction(silent = false) {
                 if (!silent) {
                     console.red('Error reading local metadata.json:', error.message);
                 }
-                return;
             }
         }
-        
+
         // Check remote version from S3
         const https = require('https');
         const bucket = 'openkbs-downloads';
-        const remoteMetadataKey = 'templates/.openkbs/knowledge/metadata.json';
-        
+        const remoteMetadataKey = 'templates/.claude/skills/openkbs/metadata.json';
+
         let remoteVersion = null;
         try {
             const fileUrl = `https://${bucket}.s3.amazonaws.com/${remoteMetadataKey}`;
@@ -654,7 +644,7 @@ async function updateKnowledgeAction(silent = false) {
                     res.on('end', () => resolve(data));
                 }).on('error', reject);
             });
-            
+
             const remoteMetadata = JSON.parse(remoteMetadataContent);
             remoteVersion = remoteMetadata.version;
         } catch (error) {
@@ -663,26 +653,23 @@ async function updateKnowledgeAction(silent = false) {
             }
             return;
         }
-        
+
         // Compare versions
         if (localVersion === remoteVersion) {
-            console.green('Knowledge base is already up to date.');
+            console.green('OpenKBS skill is already up to date.');
             return;
         }
-        
-        console.log(`Updating knowledge base from version ${localVersion || 'unknown'} to ${remoteVersion}...`);
-        
-        // Download updated knowledge files from S3
-        await downloadKnowledgeFromS3(knowledgeDir);
-        
-        // Download CLAUDE.md file from S3
-        await downloadClaudeMdFromS3(claudeMdPath);
-        
-        console.green('Knowledge base updated successfully!');
-        
+
+        console.log(`Updating OpenKBS skill from version ${localVersion || 'not installed'} to ${remoteVersion}...`);
+
+        // Download updated skill files from S3
+        await downloadSkillsFromS3(skillsDir);
+
+        console.green('OpenKBS skill updated successfully!');
+
     } catch (error) {
         if (!silent) {
-            console.red('Error updating knowledge base:', error.message);
+            console.red('Error updating skills:', error.message);
         }
     }
 }
@@ -744,8 +731,8 @@ async function updateCliAction() {
             console.red('Error fetching CLI version metadata:', error.message);
         }
 
-        // Also update knowledge base silently if it exists
-        await updateKnowledgeAction(true);
+        // Also update skills silently
+        await updateSkillsAction(true);
 
     } catch (error) {
         console.red('Error updating CLI:', error.message);
@@ -816,14 +803,17 @@ function compareVersions(version1, version2) {
 }
 
 
-async function downloadKnowledgeFromS3(targetDir) {
+async function downloadSkillsFromS3(targetDir) {
     const https = require('https');
     const bucket = 'openkbs-downloads';
-    const prefix = 'templates/.openkbs/knowledge/';
+    const prefix = 'templates/.claude/skills/openkbs/';
     const baseUrl = `https://${bucket}.s3.amazonaws.com`;
-    
+
     try {
-        // List all objects in knowledge folder
+        // Ensure directory exists
+        await fs.ensureDir(targetDir);
+
+        // List all objects in skills folder
         const listUrl = `${baseUrl}/?list-type=2&prefix=${prefix}`;
         const listXml = await new Promise((resolve, reject) => {
             https.get(listUrl, (res) => {
@@ -832,28 +822,28 @@ async function downloadKnowledgeFromS3(targetDir) {
                 res.on('end', () => resolve(data));
             }).on('error', reject);
         });
-        
+
         // Parse XML to extract object keys
         const keyMatches = listXml.match(/<Key>([^<]+)<\/Key>/g) || [];
         const keys = keyMatches.map(match => match.replace(/<\/?Key>/g, ''));
-        
+
         if (keys.length === 0) {
-            console.yellow('No knowledge files found in remote repository.');
+            console.yellow('No skill files found in remote repository.');
             return;
         }
-        
+
         // Download all files in parallel
         const downloadPromises = keys.map(async (key) => {
             const relativePath = key.substring(prefix.length);
-            
+
             // Skip if it's a directory marker
             if (relativePath.endsWith('/') || relativePath === '') return;
-            
+
             const localPath = path.join(targetDir, relativePath);
-            
+
             // Ensure directory exists
             await fs.ensureDir(path.dirname(localPath));
-            
+
             // Download file
             const fileUrl = `${baseUrl}/${key}`;
             const fileContent = await new Promise((resolve, reject) => {
@@ -864,49 +854,15 @@ async function downloadKnowledgeFromS3(targetDir) {
                 }).on('error', reject);
             });
             await fs.writeFile(localPath, fileContent);
-            
+
             console.log(`Downloaded: ${relativePath}`);
         });
-        
+
         await Promise.all(downloadPromises);
-        
-    } catch (error) {
-        console.red('Error downloading knowledge files from S3:', error.message);
-        throw error;
-    }
-}
 
-async function downloadClaudeMdFromS3(claudeMdPath) {
-    const https = require('https');
-    const bucket = 'openkbs-downloads';
-    const claudeMdKey = 'templates/CLAUDE.md';
-    
-    try {
-        // Download CLAUDE.md file from S3
-        const fileUrl = `https://${bucket}.s3.amazonaws.com/${claudeMdKey}`;
-        const fileContent = await new Promise((resolve, reject) => {
-            https.get(fileUrl, (res) => {
-                if (res.statusCode === 404) {
-                    reject(new Error('NoSuchKey'));
-                    return;
-                }
-                const chunks = [];
-                res.on('data', (chunk) => chunks.push(chunk));
-                res.on('end', () => resolve(Buffer.concat(chunks)));
-            }).on('error', reject);
-        });
-        
-        await fs.writeFile(claudeMdPath, fileContent);
-        
-        console.log('Downloaded: CLAUDE.md');
-        
     } catch (error) {
-        if (error.message === 'NoSuchKey') {
-            console.yellow('CLAUDE.md not found in remote repository, skipping...');
-        } else {
-            console.red('Error downloading CLAUDE.md:', error.message);
-            throw error;
-        }
+        console.red('Error downloading skill files from S3:', error.message);
+        throw error;
     }
 }
 
@@ -2457,6 +2413,14 @@ async function elasticStatusAction() {
  */
 async function stackAction(subCommand, args = []) {
     switch (subCommand) {
+        case 'create':
+            const stackName = args[0];
+            if (!stackName) {
+                console.red('Error: Stack name is required');
+                console.log('Usage: openkbs stack create <name>');
+                process.exit(1);
+            }
+            return await stackCreateAction(stackName);
         case 'deploy':
             return await elasticDeployAction();
         case 'destroy':
@@ -2469,10 +2433,54 @@ async function stackAction(subCommand, args = []) {
             console.log('Commands:');
             console.log('  deploy     Deploy all resources from openkbs.json');
             console.log('  destroy    Delete all resources (DANGEROUS)');
+            console.log('  create     Create new platform stack');
             console.log('  status     Show status of all resources');
     }
 }
 
+/**
+ * Create a new platform stack from template
+ */
+async function stackCreateAction(name) {
+    try {
+        // Download templates from S3 first
+        await downloadTemplates();
+
+        const platformTemplateDir = path.join(TEMPLATE_DIR, 'platform');
+        const targetDir = path.join(process.cwd(), name);
+
+        if (!fs.existsSync(platformTemplateDir)) {
+            console.red('Error: Platform template not found. Run "openkbs update" first.');
+            process.exit(1);
+        }
+
+        if (fs.existsSync(targetDir)) {
+            console.red(`Error: Directory ${name} already exists.`);
+            process.exit(1);
+        }
+
+        // Copy platform template
+        fs.copySync(platformTemplateDir, targetDir);
+
+        // Replace placeholders in all files
+        replacePlaceholderInFiles(targetDir, name);
+
+        console.green(`\nPlatform stack "${name}" created successfully!\n`);
+        console.log('Structure:');
+        console.log(`  ${name}/`);
+        console.log('  ├── agents/           # AI agents (each with app/ and src/)');
+        console.log('  ├── functions/        # Serverless Lambda functions');
+        console.log('  ├── site/             # Static site for whitelabel');
+        console.log('  └── openkbs.json      # Elastic services config\n');
+        console.log('Next steps:');
+        console.log(`  cd ${name}`);
+        console.log('  openkbs deploy        # Deploy elastic services');
+        console.log('  openkbs fn push api   # Deploy the API function');
+    } catch (error) {
+        console.red(`Error during stack create:`, error.message);
+    }
+}
+
 module.exports = {
     signAction,
     loginAction,
@@ -2490,7 +2498,7 @@ module.exports = {
     installFrontendPackageAction,
     modifyAction,
     downloadModifyAction,
-    updateKnowledgeAction,
+    updateSkillsAction,
     updateCliAction,
     publishAction,
     unpublishAction,

package/src/index.js

@@ -13,7 +13,7 @@ const {
     deleteFileAction,
     describeAction, deployAction, createByTemplateAction, initByTemplateAction,
     logoutAction, installFrontendPackageAction, modifyAction, downloadModifyAction,
-    updateKnowledgeAction, updateCliAction, publishAction, unpublishAction,
+    updateSkillsAction, updateCliAction, publishAction, unpublishAction,
     fnAction,
     siteAction,
     storageAction,
@@ -143,16 +143,18 @@ Reads openkbs.json and deletes:
 `);
 
 program
-    .command('stack <subcommand>')
-    .description('Manage stack resources (deploy, destroy, status)')
-    .action((subCommand) => stackAction(subCommand))
+    .command('stack <subcommand> [args...]')
+    .description('Manage stack resources (create, deploy, destroy, status)')
+    .action((subCommand, args) => stackAction(subCommand, args))
     .addHelpText('after', `
 Commands:
-  deploy     Deploy all resources from openkbs.json
-  destroy    Delete all resources (DANGEROUS)
-  status     Show status of all resources
+  create <name>  Create new platform stack from template
+  deploy         Deploy all resources from openkbs.json
+  destroy        Delete all resources (DANGEROUS)
+  status         Show status of all resources
 
 Examples:
+  $ openkbs stack create my-platform
   $ openkbs stack deploy
   $ openkbs stack status
   $ openkbs stack destroy
@@ -194,25 +196,24 @@ This file will be automatically included when you run the 'openkbs modify' comma
 
 program
     .command('update [target]')
-    .description('Update OpenKBS CLI or project components from remote repository')
+    .description('Update OpenKBS CLI or skills (default: CLI)')
     .action((target) => {
         if (!target) {
             updateCliAction();
-        } else if (target === 'knowledge') {
-            updateKnowledgeAction();
+        } else if (target === 'skills') {
+            updateSkillsAction();
         } else {
-            console.error(`Unknown update target: ${target}. Currently supported: knowledge`);
+            console.error(`Unknown update target: ${target}. Supported: skills`);
             process.exit(1);
         }
     })
     .addHelpText('after', `
 Examples:
   $ openkbs update
-  This will check for CLI updates and install them if available.
+  Check for CLI updates and install them.
 
-  $ openkbs update knowledge
-  This will check if your local .openkbs/knowledge directory is up to date with the remote repository
-  and update it if necessary.
+  $ openkbs update skills
+  Update .claude/skills/openkbs/ with latest OpenKBS skill files.
 `);
 
 program

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

@@ -0,0 +1,184 @@
+---
+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 a KB 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`. All agents share the platform's elastic services via the parent 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
+└── openkbs.json            # Elastic services config
+```
+
+### 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": "nodejs22.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
+```
+
+## 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
+
+- For backend SDK methods, see [reference/backend-sdk.md](reference/backend-sdk.md)
+- For frontend React patterns, see [reference/frontend-sdk.md](reference/frontend-sdk.md)
+- For XML command definitions, see [reference/commands.md](reference/commands.md)
+- For elastic services, see [reference/elastic-services.md](reference/elastic-services.md)
+- For complete examples, see [examples/](examples/)

package/templates/.claude/skills/openkbs/metadata.json

@@ -0,0 +1 @@
+{"version": "0.1.0"}