@descix/cli 1.0.0

package/templates/scaffolds/microservice/templates/SERVICE_README_TEMPLATE.md

@@ -0,0 +1,143 @@
+# {Service Name} Service
+
+## Overview
+
+{One paragraph description of what this service does and when to use it.
+Include the key use cases, benefits, and target users.
+This section is critical for tell_me_how discovery - be descriptive about WHEN to use this service.}
+
+## Prerequisites
+
+- {Any setup requirements}
+- {Required permissions or app purchases}
+- {Environment configuration}
+
+## Available Commands
+
+### {command_name}
+
+**Description:** {Detailed description of what this command does}
+
+**Use when:** {Specific scenarios when this command should be used. This helps tell_me_how match user questions to the right tool.}
+
+**Prerequisites:**
+- {What must be true before calling this command}
+- {Required prior steps or configurations}
+
+**Parameters:**
+- `param1` (required, string): {Description of this parameter}
+- `param2` (optional, number): {Description with default value if any}
+- `param3` (optional, object): {Description of nested structure}
+
+**Example Request:**
+```json
+{
+  "command": "{command_name}",
+  "params": {
+    "param1": "example_value",
+    "param2": 42
+  }
+}
+```
+
+**Example Response:**
+```json
+{
+  "status": "OK",
+  "message": {
+    "result_field": "value",
+    "another_field": 123
+  }
+}
+```
+
+**Errors:**
+- `{ERROR_CODE}`: {When this error occurs and how to fix it}
+
+---
+
+### {another_command_name}
+
+**Description:** {Description}
+
+**Use when:** {Scenarios}
+
+**Prerequisites:**
+- {Requirements}
+
+**Parameters:**
+- `param1` (required, string): {Description}
+
+**Example Request:**
+```json
+{
+  "command": "{another_command_name}",
+  "params": {
+    "param1": "value"
+  }
+}
+```
+
+---
+
+## Common Workflows
+
+### Workflow: {Workflow Name}
+
+{Description of a common multi-step process using this service's commands}
+
+1. **Step 1:** Call `{first_command}` to {action}
+2. **Step 2:** Call `{second_command}` to {action}
+3. **Step 3:** Verify with `{third_command}`
+
+**Example:**
+```bash
+# Using the CLI
+descix service call {command_name} --param1 value
+
+# Or via tell_me_how
+tell_me_how("I want to {describe the workflow goal}")
+```
+
+## Integration with Other Services
+
+{Describe how this service works with other DeSciX services}
+
+- **RAG Integration:** {If this service uses knowledge bases}
+- **Token Economy:** {If this service interacts with tokenomics}
+- **Other Services:** {Any service-to-service communication}
+
+## Troubleshooting
+
+### Common Errors
+
+**Error: `{Error message}`**
+- **Cause:** {Why this happens}
+- **Solution:** {How to fix it}
+
+**Error: `{Another error}`**
+- **Cause:** {Why this happens}
+- **Solution:** {How to fix it}
+
+### Getting Help
+
+If you encounter issues:
+1. Use `tell_me_how` to find related documentation
+2. Check the app's knowledge base for detailed guides
+3. Contact community support
+
+---
+
+## Service Metadata
+
+| Field | Value |
+|-------|-------|
+| Service Name | {service_name} |
+| Version | {version} |
+| Community | {community_id} |
+| App | {app_id} |
+| Commands | {command_count} |
+
+---
+
+*This README is vectorized for `tell_me_how` discovery. Keep it up to date with your service's capabilities.*

package/templates/scaffolds/site/DeSciXAppSDK.js

@@ -0,0 +1,62 @@
+/**
+ * DeSciXAppSDK.js (V2 - App Shell Edition)
+ * 
+ * A thin wrapper for CodeSites and ChatWidgets running within the DeSciX PWA.
+ * Leverages Same-Origin interframe scripting to provide direct access to
+ * PWA helpers and the backend API.
+ */
+
+window.DeSciX = (() => {
+    const isEmbedded = window.top !== window;
+    
+    // Check for same-origin access
+    const hasParentAccess = () => {
+        try {
+            return isEmbedded && !!window.top.DeSciX;
+        } catch (e) {
+            return false;
+        }
+    };
+
+    if (!hasParentAccess()) {
+        console.warn('[DeSciX SDK] Running in standalone mode or cross-origin. Direct PWA helpers unavailable.');
+        return {
+            mode: 'standalone',
+            call: async (command, params) => {
+                throw new Error('SDK not initialized in PWA App Shell mode.');
+            }
+        };
+    }
+
+    console.log('[DeSciX SDK] Initialized in App Shell mode.');
+
+    // Proxy to the PWA's global DeSciX object
+    return {
+        mode: 'shell',
+        
+        /**
+         * Access to global application data (Communities, Apps, User Profile)
+         */
+        get AppData() { return window.top.DeSciX.AppData; },
+
+        /**
+         * Access to the PWA state machine and navigation
+         */
+        get AppContext() { return window.top.DeSciX.AppContext; },
+
+        /**
+         * Direct API call helper (proxied through PWA session)
+         */
+        call: (command, params) => window.top.DeSciX.call(command, params),
+
+        /**
+         * Chat interaction helpers
+         */
+        Chat: {
+            suggestPrompt: (text) => {
+                // Future: trigger text injection into ChatWidget
+                console.log('[DeSciX SDK] Suggesting prompt:', text);
+            }
+        }
+    };
+})();

package/templates/scaffolds/site/README.md

@@ -0,0 +1,51 @@
+# Site Folder
+
+This folder contains your app's static site files that are deployed to the web.
+
+## Structure
+
+```
+site/
+├── index.html    # Main entry point
+├── styles.css    # Stylesheet
+├── app.js        # Client-side JavaScript
+└── README.md     # This file
+```
+
+## Deployment
+
+Your site is deployed when you run:
+
+```bash
+descix site upload
+```
+
+The site files are uploaded to Google Cloud Storage and served within the DeSciX PWA.
+
+## Using the DeSciX SDK
+
+The DeSciX SDK is automatically injected into your CodeSite when running within the PWA App Shell. You can access it via the global `DeSciX` object.
+
+```javascript
+// 1. Access global application data
+const stats = await DeSciX.AppData.getCommunityStats();
+
+// 2. Call DeSciX API (uses parent PWA session)
+const result = await DeSciX.call('ask_question_to_app', {
+  community_id: 'egpt',
+  app_id: 'agent',
+  user_input: 'Explain the platform architecture'
+});
+```
+
+## Adding More Files
+
+Add any static assets (images, fonts, additional JS/CSS) to this folder. All files in `site/` are deployed together.
+
+## Local Development
+
+To test your site within the DeSciX PWA, use the `servelocal` command:
+
+```bash
+descix site servelocal 3000
+```

package/templates/scaffolds/site/app.js

@@ -0,0 +1,22 @@
+/**
+ * {{APP_NAME}} - Site JavaScript
+ * 
+ * Add your client-side logic here.
+ * 
+ * For DeSciX SDK integration, use the global DeSciX object:
+ * 
+ * Example:
+ * const stats = await DeSciX.AppData.getCommunityStats();
+ * console.log('My Community Stats:', stats);
+ * 
+ * // Call backend API directly
+ * const result = await DeSciX.call('get_app', { app_id: 'myapp' });
+ */
+
+document.addEventListener('DOMContentLoaded', async () => {
+    console.log('{{APP_NAME}} site loaded');
+    
+    if (window.DeSciX) {
+        console.log('[App] DeSciX SDK detected. Mode:', window.DeSciX.mode);
+    }
+});

package/templates/scaffolds/site/index.html

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{APP_NAME}}</title>
+    <link rel="stylesheet" href="styles.css">
+</head>
+<body>
+    <div class="container">
+        <header>
+            <h1>{{APP_NAME}}</h1>
+            <p class="tagline">Your DeSciX App</p>
+        </header>
+        
+        <main>
+            <section class="hero">
+                <h2>Welcome</h2>
+                <p>This is your app's static site. Edit this page to create your user interface.</p>
+            </section>
+            
+            <section class="features">
+                <h3>Getting Started</h3>
+                <ul>
+                    <li>Edit <code>index.html</code> to customize your page</li>
+                    <li>Add styles in <code>styles.css</code></li>
+                    <li>Add JavaScript in <code>app.js</code></li>
+                    <li>Deploy with <code>descix kb sync</code></li>
+                </ul>
+            </section>
+        </main>
+        
+        <footer>
+            <p>Powered by <a href="https://descix.net">DeSciX</a></p>
+        </footer>
+    </div>
+    
+    <!-- DeSciX App SDK -->
+    <script src="DeSciXAppSDK.js"></script>
+    <script src="app.js"></script>
+</body>
+</html>

package/templates/scaffolds/site/styles.css

@@ -0,0 +1,123 @@
+/* DeSciX App Styles */
+
+:root {
+    --primary-color: #6366f1;
+    --background-color: #f8fafc;
+    --text-color: #1e293b;
+    --text-muted: #64748b;
+    --border-color: #e2e8f0;
+    --card-background: #ffffff;
+}
+
+* {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+}
+
+body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
+    background-color: var(--background-color);
+    color: var(--text-color);
+    line-height: 1.6;
+}
+
+.container {
+    max-width: 800px;
+    margin: 0 auto;
+    padding: 2rem;
+}
+
+header {
+    text-align: center;
+    margin-bottom: 3rem;
+}
+
+header h1 {
+    font-size: 2.5rem;
+    color: var(--primary-color);
+    margin-bottom: 0.5rem;
+}
+
+.tagline {
+    color: var(--text-muted);
+    font-size: 1.1rem;
+}
+
+main {
+    background: var(--card-background);
+    border-radius: 12px;
+    padding: 2rem;
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+}
+
+section {
+    margin-bottom: 2rem;
+}
+
+section:last-child {
+    margin-bottom: 0;
+}
+
+h2 {
+    font-size: 1.5rem;
+    margin-bottom: 1rem;
+}
+
+h3 {
+    font-size: 1.2rem;
+    margin-bottom: 0.75rem;
+    color: var(--text-muted);
+}
+
+ul {
+    list-style: none;
+    padding: 0;
+}
+
+li {
+    padding: 0.5rem 0;
+    border-bottom: 1px solid var(--border-color);
+}
+
+li:last-child {
+    border-bottom: none;
+}
+
+code {
+    background: var(--background-color);
+    padding: 0.2rem 0.4rem;
+    border-radius: 4px;
+    font-family: 'Monaco', 'Menlo', monospace;
+    font-size: 0.9em;
+}
+
+footer {
+    text-align: center;
+    margin-top: 3rem;
+    color: var(--text-muted);
+}
+
+footer a {
+    color: var(--primary-color);
+    text-decoration: none;
+}
+
+footer a:hover {
+    text-decoration: underline;
+}
+
+/* Responsive */
+@media (max-width: 600px) {
+    .container {
+        padding: 1rem;
+    }
+    
+    header h1 {
+        font-size: 2rem;
+    }
+    
+    main {
+        padding: 1.5rem;
+    }
+}

package/test-hydration.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * Test Drive Hydration
+ */
+
+import { google } from 'googleapis';
+import GoogleStorage from './lib/google-storage-adc.js';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DRIVE_FOLDER_MIME = 'application/vnd.google-apps.folder';
+
+async function getAuth() {
+  return new google.auth.GoogleAuth({
+    scopes: ['https://www.googleapis.com/auth/drive', 'https://www.googleapis.com/auth/drive.file']
+  });
+}
+
+async function main() {
+  console.log('=== Drive Hydration Test ===\n');
+  
+  // Step 1: Verify ADC
+  console.log('1. Verifying ADC authentication...');
+  const user = await GoogleStorage.verifyDriveAuth();
+  console.log(`   ✓ Authenticated as: ${user.emailAddress}\n`);
+  
+  // Step 2: Find DeSciX base folder
+  console.log('2. Looking for DeSciX base folder...');
+  const auth = await getAuth();
+  const drive = google.drive({ version: 'v3', auth });
+  
+  const possibleNames = ['DeSciX', 'DeSciX_Apps', 'descix-apps', 'descix'];
+  let baseFolder = null;
+  
+  for (const name of possibleNames) {
+    const res = await drive.files.list({
+      q: `name='${name}' and mimeType='${DRIVE_FOLDER_MIME}' and trashed=false`,
+      fields: 'files(id, name)'
+    });
+    if (res.data.files?.length) {
+      baseFolder = res.data.files[0];
+      console.log(`   ✓ Found base folder: "${name}" (ID: ${baseFolder.id})\n`);
+      break;
+    }
+  }
+  
+  if (!baseFolder) {
+    console.log('   ✗ Could not find DeSciX base folder');
+    const rootRes = await drive.files.list({
+      q: `'root' in parents and mimeType='${DRIVE_FOLDER_MIME}' and trashed=false`,
+      fields: 'files(id, name)',
+      pageSize: 20
+    });
+    console.log('   Root folders:');
+    for (const f of rootRes.data.files || []) {
+      console.log(`     - ${f.name} (${f.id})`);
+    }
+    return;
+  }
+  
+  // Step 3: Find descix/agent
+  console.log('3. Locating descix/agent folder...');
+  const agentFolderId = await GoogleStorage.findFolderByPath(baseFolder.id, 'descix/agent');
+  
+  if (!agentFolderId) {
+    console.log('   ✗ Could not find descix/agent folder');
+    console.log('   Contents of base folder:');
+    const contents = await GoogleStorage.listFolderWithMeta(baseFolder.id);
+    for (const f of contents) {
+      console.log(`     - ${f.name} (${f.mimeType === DRIVE_FOLDER_MIME ? 'folder' : 'file'})`);
+    }
+    return;
+  }
+  
+  console.log(`   ✓ Found descix/agent folder (ID: ${agentFolderId})\n`);
+  
+  // Step 4: List contents
+  console.log('4. Contents of descix/agent in Drive:');
+  const agentContents = await GoogleStorage.listFolderWithMeta(agentFolderId);
+  for (const f of agentContents) {
+    const type = f.mimeType === DRIVE_FOLDER_MIME ? '📁' : '📄';
+    console.log(`   ${type} ${f.name}`);
+    
+    // List subfolders
+    if (f.mimeType === DRIVE_FOLDER_MIME) {
+      const subContents = await GoogleStorage.listFolderWithMeta(f.id);
+      for (const sf of subContents) {
+        const subType = sf.mimeType === DRIVE_FOLDER_MIME ? '📁' : '📄';
+        console.log(`     ${subType} ${sf.name}`);
+      }
+    }
+  }
+  console.log('');
+  
+  // Step 5: Pull content using the new downloadFileFromDrive function
+  const targetDir = '/Users/essam/Documents/Code/DaitaERC20/descix/agent';
+  console.log(`5. Pulling content to ${targetDir}...`);
+  
+  const pullRecursive = async (localPath, folderId, indent = '  ') => {
+    await fs.mkdir(localPath, { recursive: true });
+    const files = await GoogleStorage.listFolderWithMeta(folderId);
+    let count = 0;
+    
+    for (const file of files) {
+      const targetPath = path.join(localPath, file.name);
+      
+      if (file.mimeType === DRIVE_FOLDER_MIME) {
+        console.log(`${indent}📁 ${file.name}/`);
+        count += await pullRecursive(targetPath, file.id, indent + '  ');
+      } else {
+        console.log(`${indent}📄 Downloading: ${file.name}`);
+        await GoogleStorage.downloadFileFromDrive(file.id, targetPath);
+        count++;
+      }
+    }
+    return count;
+  };
+  
+  const downloaded = await pullRecursive(targetDir, agentFolderId);
+  console.log(`\n   ✓ Downloaded ${downloaded} files\n`);
+  
+  // Step 6: Verify
+  console.log('6. Verifying local content:');
+  const verifyDir = async (dir, indent = '') => {
+    try {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      for (const e of entries) {
+        const type = e.isDirectory() ? '📁' : '📄';
+        console.log(`   ${indent}${type} ${e.name}`);
+        if (e.isDirectory()) {
+          await verifyDir(path.join(dir, e.name), indent + '  ');
+        }
+      }
+    } catch {
+      console.log(`   ${indent}(empty)`);
+    }
+  };
+  await verifyDir(targetDir);
+  
+  console.log('\n=== Test Complete ===');
+  console.log(`\nBase folder ID for workspace.json: ${baseFolder.id}`);
+}
+
+main().catch(err => {
+  console.error('Error:', err.message);
+  console.error(err.stack);
+  process.exit(1);
+});