@descix/cli 1.0.1 → 1.0.3

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

@@ -1,78 +1,68 @@
 /**
- * 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).
+ * DeSciX service api-client — the CLI's REST api-client running in THIS microservice.
+ *
+ * AUTH MODEL — the microservice IS the CLI's api-client running in the cloud
+ * (CEO-D-2026-06-02-APP-MICROSERVICE-IS-CLI-CLIENT-WALLET-SIG):
+ *   This service authenticates to /apifront EXACTLY like the CLI: it holds the DEVELOPER'S OWN
+ *   durable credential (wallet_address + signature, from the developer's .descix/wallet.json),
+ *   presents it to `reconnect_by_wallet` to mint a session access_token, and calls /apifront AS
+ *   THE DEVELOPER. There is NO SA-OIDC, NO delegate signature, NO X-NFT-ID, NO SERVICE_KEY, NO
+ *   Signer. The packaged `@descix/cli` `createServiceApiClient` does all of this.
+ *
+ * CREDENTIAL PLACEMENT (org rule — no checked-in credentials):
+ *   The developer copies their wallet `signature` + `wallet_address` into the service config as
+ *   `DEVELOPER_SIGNATURE` / `DEVELOPER_WALLET_ADDRESS`, in the GITIGNORED dev-overrides.json (dev)
+ *   / a SECRET (prod) — NEVER the checked-in defaults-config.json (the signature is a credential).
+ *   We HARD-FAIL (no fallback) if either is absent.
  */
 
-import axios from 'axios';
+import { createServiceApiClient } from '@descix/cli/service-api-client';
 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);
-        }
+let _service = null;
+
+/**
+ * Build (once) the developer-authed service api-client for this microservice.
+ * Reads the developer credential from config and HARD-FAILS if absent (no fallback).
+ */
+function getService() {
+    if (_service) return _service;
+    if (!utils.CORE_API_URL) {
+        throw new Error('CORE_API_URL not configured.');
     }
+    if (!utils.DEVELOPER_WALLET_ADDRESS || !utils.DEVELOPER_SIGNATURE) {
+        throw new Error(
+            'Developer credential missing: set DEVELOPER_WALLET_ADDRESS + DEVELOPER_SIGNATURE in the ' +
+            'GITIGNORED dev-overrides.json (dev) / a secret (prod) — never defaults-config.json. ' +
+            'These are the developer\'s own wallet_address + signature (from .descix/wallet.json). No fallback.'
+        );
+    }
+    _service = createServiceApiClient({
+        baseUrl: utils.CORE_API_URL,
+        walletAddress: utils.DEVELOPER_WALLET_ADDRESS,
+        signature: utils.DEVELOPER_SIGNATURE,
+    });
+    return _service;
+}
 
+class McpClient {
     /**
-     * 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
+     * Call a Core command via /apifront, authenticated AS the developer.
+     * @param {string} command - Command name (e.g. 'app_records_put', 'get_app_asset')
+     * @param {Object} args    - Command params
+     * @returns {Promise<any>} - Core's `message` payload on success
      */
-    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;
-        }
+    async callTool(command, args = {}) {
+        return getService().invoke(command, args);
     }
 }
 
 export const mcpClient = new McpClient();
+
+/**
+ * The raw `invoke(command, params) => Promise<message>` — the exact shape `fetchAppAsset`
+ * (from `@descix/sdk`) and other mesh helpers expect. Prefer this for new code.
+ */
+export function getInvoke() {
+    return getService().invoke;
+}

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

@@ -1,247 +1,29 @@
 /**
- * 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)
+ * Service Configuration — Thin wrapper over @descix/cloud-core
+ *
+ * Uses @descix/cloud-core for shared bootstrap logic:
+ * - Layered config: Env -> .env -> workspace.json
+ * - Secret Manager integration
+ * - Auto-port detection in dev
+ *
+ * This is the ONLY path to config values. Never use process.env directly.
+ * Never add fallback values to utils.CONFIG_VALUE — nulls surface misconfigurations.
  */
 
 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';
+import {
+    createCloudConfig,
+    getCloudConfig,
+    initializeCloudConfig,
+} from '@descix/cloud-core';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const require = createRequire(import.meta.url);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootPath = path.resolve(__dirname, '..');
 
-class ServiceConfig {
-    constructor() {
-        if (ServiceConfig.instance) return ServiceConfig.instance;
+// Initialize CloudConfig with service root
+createCloudConfig({ rootPath });
 
-        this.__appDir = path.resolve(__dirname, '../');
+const utils = getCloudConfig();
 
-        // 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 };
+export { initializeCloudConfig as initializeServiceConfig, utils };

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

@@ -6,6 +6,30 @@
 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.}
 
+## Onboarding — Canonical Mesh Microservice Setup
+
+Run this sequence ONCE to stand up a microservice that can call the mesh
+(Core Tools like `query_knowledge_base`, or other services' tools) over the
+`/apifront` broker:
+
+```bash
+descix app create   -c {community} -a {app}     # create the app (or hydrate an existing one)
+descix app init      -a {community}-{app}        # scaffold site/ kb/ microservice/
+descix app set-port  -a {community}-{app} -p {port}   # assign the microservice's loopback port in workspace.json
+descix microservice register                     # register the service manifest with the Core gateway
+# then: cp dev-overrides.example.json dev-overrides.json  and fill in the developer credential
+```
+
+> **Calling /apifront — the microservice IS the CLI's api-client in the cloud**
+> (CEO-D-2026-06-02-APP-MICROSERVICE-IS-CLI-CLIENT-WALLET-SIG). The scaffold
+> `mcpClient` authenticates AS the developer: it reads `DEVELOPER_WALLET_ADDRESS`
+> + `DEVELOPER_SIGNATURE` (the developer's own wallet credential, from
+> `.descix/wallet.json`) and calls `reconnect_by_wallet` to mint a session —
+> exactly like the CLI. Put the credential in the GITIGNORED `dev-overrides.json`
+> (dev) / a secret (prod), NEVER `defaults-config.json`. There is NO
+> `register-delegate`, NO `SERVICE_KEY`, NO service account for the data plane.
+> **HTTP 401?** The developer credential is missing or wrong — check those two keys.
+
 ## Prerequisites
 
 - {Any setup requirements}