@descix/cli 1.0.0

package/templates/scaffolds/microservice/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@descix/service-starter",
+  "version": "1.0.0",
+  "description": "DeSciX Add-on Service Starter Template (MCP-Native)",
+  "main": "app.js",
+  "type": "module",
+  "scripts": {
+    "start": "node app.js",
+    "dev": "nodemon app.js",
+    "register": "node scripts/register.js",
+    "gen-jwt-secret": "node -e 'console.log(require(\"crypto\").randomBytes(32).toString(\"hex\"))'"
+  },
+  "dependencies": {
+    "@descix/cloud-core": "^1.0.0",
+    "@google-cloud/firestore": "^7.1.0",
+    "@google-cloud/secret-manager": "^5.0.1",
+    "@google-cloud/storage": "^7.7.0",
+    "axios": "^1.6.2",
+    "cors": "^2.8.5",
+    "dotenv": "^16.3.1",
+    "express": "^4.18.2",
+    "google-auth-library": "^9.4.1",
+    "@descix/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.2"
+  },
+  "license": "@Daita_DeSci_Community_License_v1/Daita_DeSci_Community_License_v1.pdf"
+}

package/templates/scaffolds/microservice/scripts/register.js

@@ -0,0 +1,55 @@
+/**
+ * Service Registration Script
+ * 
+ * Registers the service manifest with DeSciX Cloud.
+ * Usage: npm run register
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { Firestore } from '@google-cloud/firestore';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Load Manifest
+const manifestPath = path.resolve(__dirname, '../manifest.json');
+const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+
+async function register() {
+    console.log(`[Register] Registering service: ${manifest.service.name}`);
+    
+    // Connect to Firestore (uses ADC)
+    // Assumes we are running in a context with access to the Core project
+    // OR we might need to hit an admin API endpoint on Core if we don't have direct DB access.
+    // For this template, we'll assume direct DB access (common for internal services)
+    // or provide instructions to copy output to Core.
+
+    // OPTION: We could check if we have CREDENTIALS, if not, output the JSON 
+    // for the user to paste into the Core admin console.
+
+    try {
+        const firestore = new Firestore();
+        const docRef = firestore.collection('ServiceManifests').doc(manifest.service.name);
+        
+        await docRef.set({
+            ...manifest,
+            registeredAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            status: 'active'
+        });
+
+        console.log(`[Register] SUCCESS: Registered ${manifest.service.name}`);
+        console.log(`[Register] Domain: ${manifest.service.domain}`);
+        console.log(`[Register] Commands: ${Object.keys(manifest.commands).join(', ')}`);
+
+    } catch (error) {
+        console.error('[Register] FAILED:', error.message);
+        console.log('\n[Tip] If you don\'t have direct Firestore access, create a document in the "ServiceManifests" collection with this ID and content:');
+        console.log(`ID: ${manifest.service.name}`);
+        console.log(JSON.stringify(manifest, null, 2));
+    }
+}
+
+register();

package/templates/scaffolds/microservice/services/apiFront.js

@@ -0,0 +1,75 @@
+/**
+ * Service API Router
+ * 
+ * Routes incoming JSON commands to handlers.
+ * Expects `_descix` context injected by the Core Broker.
+ */
+
+import express from 'express';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+const apiRouter = express.Router();
+
+// Command Registry
+const commandRegistry = {
+    // Dynamic loading will happen in the handler
+    'sample_hello': 'sampleCommands.js',
+    'sample_analyze': 'sampleCommands.js'
+};
+
+class ServiceCommandHandler {
+    static async invoke(command, params) {
+        // 1. Check registry
+        const fileName = commandRegistry[command];
+        if (!fileName) {
+            throw new Error(`Unknown command: ${command}`);
+        }
+
+        // 2. Load module (simple dynamic import)
+        try {
+            const module = await import(`./commandHandlers/${fileName}`);
+            const handler = module.commands[command];
+            
+            if (!handler) {
+                throw new Error(`Handler not found for ${command} in ${fileName}`);
+            }
+
+            // 3. Execute
+            // We pass params directly. The handler is responsible for using _descix context.
+            return await handler(params);
+
+        } catch (error) {
+            console.error(`[CommandHandler] Error invoking ${command}:`, error);
+            throw error;
+        }
+    }
+}
+
+// Main Route
+apiRouter.post('/:command', async (req, res) => {
+    const { command } = req.params;
+    const params = req.body;
+
+    // The Core Broker injects this context
+    const context = params._descix;
+
+    if (!context) {
+        // In production, you might reject requests without context
+        // In dev, we might allow direct calls
+        console.warn(`[ApiFront] Warning: Request to ${command} missing _descix context`);
+    }
+
+    try {
+        console.log(`[ApiFront] Received command: ${command}`);
+        const result = await ServiceCommandHandler.invoke(command, params);
+        res.json(result);
+    } catch (error) {
+        res.status(500).json({
+            status: 'ERROR',
+            message: error.message
+        });
+    }
+});
+
+export default apiRouter;

package/templates/scaffolds/microservice/services/commandHandlers/sampleCommands.js

@@ -0,0 +1,57 @@
+import { mcpClient } from '../mcpClient.js';
+
+export const commands = {
+    /**
+     * Simple echo command
+     */
+    sample_hello: async (params) => {
+        const { message, _descix } = params;
+        
+        return {
+            status: 'OK',
+            message: `Echo: ${message}`,
+            user: _descix?.user?.email || 'Guest'
+        };
+    },
+
+    /**
+     * Demonstrates Loopback:
+     * 1. Receives a query
+     * 2. Calls Core Tool (query_knowledge_base) via MCP Client
+     * 3. Returns combined result
+     */
+    sample_analyze: async (params) => {
+        const { query, _descix } = params;
+
+        if (!_descix?.user) {
+            throw new Error('Authentication required for analysis');
+        }
+
+        console.log(`[SampleService] Analyzing '${query}' for user ${_descix.user.id}`);
+
+        try {
+            // CALL CORE TOOL: query_knowledge_base
+            // This goes Service -> Cloud -> Vector DB -> Cloud -> Service
+            const ragResult = await mcpClient.callTool('query_knowledge_base', {
+                community_id: 'descix',
+                app_id: 'docs',
+                kb_id: 'sdk',
+                query: query
+            }, _descix);
+
+            return {
+                status: 'OK',
+                analysis: `Analyzed query: ${query}`,
+                rag_findings: ragResult || 'No results found',
+                timestamp: new Date().toISOString()
+            };
+        } catch (error) {
+            console.error('[SampleService] RAG lookup failed:', error);
+            return {
+                status: 'ERROR',
+                message: 'Analysis failed due to upstream error',
+                details: error.message
+            };
+        }
+    }
+};

package/templates/scaffolds/microservice/services/mcpClient.js

@@ -0,0 +1,78 @@
+/**
+ * DeSciX MCP Loopback Client
+ * 
+ * Enables the service to call Core Tools (e.g. RAG, Purchase) or other Service Tools
+ * via the Federated MCP Broker (DeSciX_Cloud).
+ */
+
+import axios from 'axios';
+import { utils } from './utils.js';
+import { Signer } from '@descix/sdk'; // Assuming descix-sdk is available in the container
+
+class McpClient {
+    constructor() {
+        // Initialize signer if key is available
+        if (utils.SERVICE_KEY) {
+            this.signer = new Signer(utils.SERVICE_KEY.privateKey, utils.SERVICE_KEY.slotId);
+        }
+    }
+
+    /**
+     * Call a tool via the Core Broker
+     * @param {string} toolName - Name of the tool to call (e.g., 'query_knowledge_base')
+     * @param {Object} args - Tool arguments
+     * @param {Object} context - User context object (from _descix) to pass identity
+     * @returns {Promise<any>} - Tool result
+     */
+    async callTool(toolName, args, context) {
+        if (!utils.CORE_API_URL) {
+            throw new Error('CORE_API_URL not configured');
+        }
+
+        // Construct the payload simulating a PWA or internal request
+        const payload = {
+            command: toolName,
+            params: {
+                ...args,
+                // Critical: Pass the original user context back to Core
+                // The Core trusts this service (authenticated via Service Secret or VPC)
+                // In this simplified template, we pass the user ID we received
+                user_id: context?.user?.id || utils.OWNER_USER_ID,
+                // If we have owner credentials, use them as fallback for auth
+                wallet_address: utils.OWNER_WALLET_ADDRESS,
+                signature: utils.OWNER_SIGNATURE
+            }
+        };
+
+        try {
+            console.log(`[McpClient] Calling ${toolName} on ${utils.CORE_API_URL}`);
+            
+            // Get headers (Signature or Legacy Secret)
+            const headers = {
+                'Content-Type': 'application/json'
+            };
+
+            if (this.signer) {
+                // Sign the payload string
+                const signatureHeaders = this.signer.getHeaders(JSON.stringify(payload));
+                Object.assign(headers, signatureHeaders);
+            } else if (utils.SERVICE_SECRET) {
+                // Fallback to legacy secret
+                headers['Authorization'] = `Bearer ${utils.SERVICE_SECRET}`;
+            }
+            
+            const response = await axios.post(utils.CORE_API_URL, payload, { headers });
+
+            if (response.data?.status === 'OK') {
+                return response.data.message;
+            } else {
+                throw new Error(response.data?.message || 'Unknown error from Core');
+            }
+        } catch (error) {
+            console.error(`[McpClient] Error calling ${toolName}:`, error.message);
+            throw error;
+        }
+    }
+}
+
+export const mcpClient = new McpClient();

package/templates/scaffolds/microservice/services/utils.js

@@ -0,0 +1,247 @@
+/**
+ * Service Configuration Bootstrap
+ * 
+ * STANDARD BOOTSTRAP PATTERN:
+ * - .env: Only bootstrap keys (CONFIG_SECRET_NAME, CONFIG_SECRET_VERSION, DEPLOY_ENV)
+ * - defaults-config.json: Instance defaults (checked in)
+ * - Secret Manager: Global config
+ * - dev-overrides.json: Local dev overrides (gitignored)
+ */
+
+import { fileURLToPath } from 'url';
+import { GoogleAuth } from 'google-auth-library';
+import { SecretManagerServiceClient } from '@google-cloud/secret-manager';
+import dotenv from 'dotenv';
+import path from 'path';
+import fs from 'fs';
+import { createRequire } from 'module';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+
+class ServiceConfig {
+    constructor() {
+        if (ServiceConfig.instance) return ServiceConfig.instance;
+
+        this.__appDir = path.resolve(__dirname, '../');
+
+        // 1. Load Bootstrap .env
+        if (process.env.DEPLOY_ENV !== 'production') {
+            dotenv.config({ path: path.resolve(this.__appDir, '.env') });
+        }
+        
+        this.CONFIG_SECRET_NAME = process.env.CONFIG_SECRET_NAME || null;
+        this.CONFIG_SECRET_VERSION = process.env.CONFIG_SECRET_VERSION || null;
+        this.DEPLOY_ENV = process.env.DEPLOY_ENV || null;
+
+        // 2. Initialize Config Keys (All NULL - no hardcoded defaults)
+        this.DEBUG_LOCAL = null;
+        this.LOCAL_PORT = null;
+        this.CORE_API_URL = null; // URL for DeSciX Core (for loopback)
+        this.SERVICE_SECRET = null; // Secret for authenticating loopback calls (Legacy)
+        this.SERVICE_KEY = null; // Service Delegate Key (New)
+        
+        // Owner Credentials (for loopback API calls)
+        this.OWNER_WALLET_ADDRESS = null;
+        this.OWNER_SIGNATURE = null;
+        this.OWNER_USER_ID = null;
+
+        this.GOOGLE_PROJECT_ID = null;
+        this.secretClient = null;
+        this.PORT = process.env.PORT || null;
+
+        // Load instance defaults immediately
+        this._loadDefaults();
+
+        ServiceConfig.instance = this;
+    }
+
+    _mergeConfig(config) {
+        for (const [key, value] of Object.entries(config)) {
+            if (key.startsWith('_')) continue;
+            // Allow dynamic expansion (undefined) or overwrite (null/value)
+            this[key] = value;
+        }
+    }
+
+    _loadDefaults() {
+        const defaultsPath = path.resolve(this.__appDir, 'defaults-config.json');
+        if (fs.existsSync(defaultsPath)) {
+            try {
+                this._mergeConfig(require(defaultsPath));
+                console.log('[Config] Loaded defaults-config.json');
+            } catch (e) {
+                console.error('[Config] Error loading defaults-config.json:', e.message);
+            }
+        }
+    }
+
+    _loadDevOverrides() {
+        if (this.DEPLOY_ENV !== 'dev') return;
+        const overridesPath = path.resolve(this.__appDir, 'dev-overrides.json');
+        if (fs.existsSync(overridesPath)) {
+            try {
+                this._mergeConfig(require(overridesPath));
+                console.log('[Config] Loaded dev-overrides.json');
+            } catch (e) {
+                console.error('[Config] Error loading dev-overrides.json:', e.message);
+            }
+        }
+    }
+
+    async accessSecretVersion(secretName, version) {
+        if (!version) throw new Error('[Config] CRITICAL: CONFIG_SECRET_VERSION not set');
+        if (!this.secretClient) this.secretClient = new SecretManagerServiceClient();
+        
+        const name = `projects/${this.GOOGLE_PROJECT_ID}/secrets/${secretName}/versions/${version}`;
+        const [response] = await this.secretClient.accessSecretVersion({ name });
+        return response.payload.data.toString('utf8');
+    }
+
+    async _registerWithWorkspace() {
+        if (this.DEPLOY_ENV !== 'dev' && !this.DEBUG_LOCAL) return;
+
+        if (this.DEBUG_LOCAL) {
+            process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+        }
+
+        let communityId = null;
+        let appId = null;
+        let workspacePath = null;
+
+        // Walk up from the service directory to find .descix/workspace.json
+        let searchDir = this.__appDir;
+        for (let i = 0; i < 10; i++) {
+            const candidate = path.resolve(searchDir, '.descix/workspace.json');
+            if (fs.existsSync(candidate)) {
+                workspacePath = candidate;
+                break;
+            }
+            const parent = path.dirname(searchDir);
+            if (parent === searchDir) break;
+            searchDir = parent;
+        }
+
+        // Detect context from manifest.json
+        try {
+            const manifestPath = path.resolve(this.__appDir, 'manifest.json');
+            if (fs.existsSync(manifestPath)) {
+                const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                communityId = manifest.service?.community_id || manifest.community_id;
+                appId = manifest.service?.app_id || manifest.app_id;
+            }
+        } catch (e) {
+            console.warn('[Config] Failed to detect app context from manifest:', e.message);
+        }
+
+        if (!communityId || !appId) {
+            console.log('[Config] No communityId/appId — skipping workspace registration');
+            return;
+        }
+
+        if (!workspacePath) {
+            console.log('[Config] No .descix/workspace.json found — skipping workspace registration');
+            return;
+        }
+
+        // Write service port into workspace.json for descix-serve to pick up
+        try {
+            const workspace = JSON.parse(fs.readFileSync(workspacePath, 'utf-8'));
+            if (!workspace.communities) workspace.communities = {};
+            if (!workspace.communities[communityId]) workspace.communities[communityId] = { apps: {} };
+            if (!workspace.communities[communityId].apps) workspace.communities[communityId].apps = {};
+            if (!workspace.communities[communityId].apps[appId]) workspace.communities[communityId].apps[appId] = {};
+
+            const appEntry = workspace.communities[communityId].apps[appId];
+            if (!appEntry.service) appEntry.service = {};
+            appEntry.service.port = parseInt(this.PORT, 10);
+
+            fs.writeFileSync(workspacePath, JSON.stringify(workspace, null, 2), 'utf-8');
+            console.log(`[Config] Registered ${communityId}/${appId} service port ${this.PORT} in workspace.json`);
+
+            this._workspacePath = workspacePath;
+            this._registeredCommunityId = communityId;
+            this._registeredAppId = appId;
+        } catch (e) {
+            console.warn('[Config] Failed to write workspace.json:', e.message);
+        }
+    }
+
+    cleanupWorkspaceRegistration() {
+        if (!this._workspacePath || !this._registeredCommunityId || !this._registeredAppId) return;
+        try {
+            const workspace = JSON.parse(fs.readFileSync(this._workspacePath, 'utf-8'));
+            const appEntry = workspace.communities?.[this._registeredCommunityId]?.apps?.[this._registeredAppId];
+            if (appEntry?.service) {
+                delete appEntry.service.port;
+            }
+            fs.writeFileSync(this._workspacePath, JSON.stringify(workspace, null, 2), 'utf-8');
+            console.log(`[Config] Cleaned up workspace registration for ${this._registeredCommunityId}/${this._registeredAppId}`);
+        } catch {
+            // Best-effort cleanup on shutdown
+        }
+    }
+
+    async initialize() {
+        // 1. Get Project ID
+        const auth = new GoogleAuth();
+        this.GOOGLE_PROJECT_ID = await auth.getProjectId();
+
+        // 2. Load from Secret Manager
+        if (this.CONFIG_SECRET_NAME) {
+            try {
+                const payload = await this.accessSecretVersion(
+                    this.CONFIG_SECRET_NAME, 
+                    this.CONFIG_SECRET_VERSION
+                );
+                this._mergeConfig(JSON.parse(payload));
+                console.log(`[Config] Loaded from Secret Manager: ${this.CONFIG_SECRET_NAME}`);
+            } catch (error) {
+                console.warn(`[Config] Secret Manager unavailable:`, error.message);
+            }
+        }
+
+        // 3. Apply Dev Overrides
+        this._loadDevOverrides();
+
+        // 4. Validate Port (Allow 'auto' or 0)
+        if (!this.PORT && this.PORT !== 0) {
+            if (this.DEBUG_LOCAL && this.LOCAL_PORT) {
+                this.PORT = this.LOCAL_PORT;
+            } else {
+                // If dev, default to auto-assign
+                if (this.DEPLOY_ENV === 'dev' || this.DEBUG_LOCAL) {
+                    this.PORT = 'auto';
+                } else {
+                    throw new Error('[Config] CRITICAL: PORT not configured');
+                }
+            }
+        }
+        
+        // 5. Default Core API URL if not set
+        if (!this.CORE_API_URL) {
+            this.CORE_API_URL = this.DEBUG_LOCAL 
+                ? 'https://localhost:4000/apifront' 
+                : 'https://descix-cloud.descix.net/apifront';
+        }
+
+        // 6. Register service port in workspace.json for descix-serve gateway
+        await this._registerWithWorkspace();
+
+        // Clean up registration on shutdown
+        process.on('SIGINT', () => this.cleanupWorkspaceRegistration());
+        process.on('SIGTERM', () => this.cleanupWorkspaceRegistration());
+
+        console.log(`[Config] Final: port=${this.PORT}, core=${this.CORE_API_URL}`);
+    }
+}
+
+const serviceConfig = new ServiceConfig();
+
+async function initializeServiceConfig() {
+    await serviceConfig.initialize();
+    return serviceConfig;
+}
+
+export { initializeServiceConfig, serviceConfig as utils };

package/templates/scaffolds/microservice/setup-schema.json

@@ -0,0 +1,18 @@
+{
+  "serviceName": "sample-service",
+  "description": "DeSciX Add-on Service",
+  "configChecks": [
+    {
+      "key": "CONFIG_SECRET_NAME",
+      "source": ".env",
+      "required": true,
+      "description": "Secret Manager secret name"
+    },
+    {
+        "key": "CONFIG_SECRET_VERSION",
+        "source": ".env",
+        "required": true,
+        "description": "Secret Manager version"
+    }
+  ]
+}