@descix/cli 1.0.1 → 1.0.4

package/bin/kb-deny-lint.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * kb-deny-lint.mjs — CLI-side runner for the Tier-P KB-publishing deny-class lint.
+ *
+ * Thin wrapper around the canonical @descix/cli CorpusDenyLint module (the ONE
+ * definition of the pattern set + doc_class taxonomy — this runner re-lists
+ * nothing). Used by the `.githooks/check_kb_deny_class.sh` pre-commit gate so a
+ * Tier-P manifest cannot be committed with a deny-class source, mirroring the
+ * sync-path gate in `corpus.js runCorpusSync`.
+ *
+ * Usage:  node kb-deny-lint.mjs <manifest.json> [<manifest.json> ...]
+ * Exit:   0 = clean (Tier-P manifests all pass, or none were Tier-P)
+ *         1 = at least one Tier-P manifest has a violation
+ *         2 = a manifest could not be read/parsed/validated
+ *
+ * Only manifests whose `publish_tier === "P"` are gated; others are skipped
+ * (current behavior unchanged, matching the sync path).
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { loadManifest } from '../lib/core/ManifestLoader.js';
+import { lintManifestForDenyClasses, assertNoViolations } from '../lib/core/CorpusDenyLint.js';
+
+/**
+ * Resolve the workspace root for a manifest by walking up to the nearest
+ * ancestor containing `.descix/workspace.json` (the same signal WorkspaceConfig
+ * uses). Falls back to the filesystem root's process.cwd() if none is found.
+ * Manifest source paths are workspace-relative, so this must match the workspace
+ * the sync command would resolve.
+ */
+async function resolveWorkspaceRoot(manifestPath) {
+  let dir = path.dirname(path.resolve(manifestPath));
+  const { root } = path.parse(dir);
+  while (true) {
+    try {
+      await fs.access(path.join(dir, '.descix', 'workspace.json'));
+      return dir;
+    } catch { /* keep walking */ }
+    if (dir === root) break;
+    dir = path.dirname(dir);
+  }
+  // No workspace.json ancestor — best effort (path/doc_class/license checks still fire).
+  return process.cwd();
+}
+
+async function main() {
+  const manifestPaths = process.argv.slice(2);
+  if (manifestPaths.length === 0) {
+    console.error('kb-deny-lint: no manifest paths given');
+    process.exit(2);
+  }
+
+  let anyViolation = false;
+  let anyLoadError = false;
+
+  for (const mfPath of manifestPaths) {
+    let manifest;
+    let workspaceRoot;
+    try {
+      workspaceRoot = await resolveWorkspaceRoot(mfPath);
+      manifest = await loadManifest(mfPath, workspaceRoot);
+    } catch (err) {
+      // A Tier-P manifest that fails schema validation (e.g. deny-class doc_class,
+      // missing doc_class) is itself a hard block — surface it as a violation.
+      console.error(`✗ ${mfPath}: ${err.message}`);
+      anyLoadError = true;
+      continue;
+    }
+
+    if (manifest.publish_tier !== 'P') continue; // only Tier-P manifests are gated
+
+    const report = await lintManifestForDenyClasses(manifest, workspaceRoot);
+    for (const ex of report.exemptions) console.log(`  ${ex.line}`);
+    for (const w of report.warnings) console.log(`  ${w.line}`);
+    try {
+      assertNoViolations(report);
+      console.log(`✓ ${mfPath}: Tier-P deny-class lint clean (${report.exemptions.length} exemption(s), ${report.warnings.length} warning(s)).`);
+    } catch (err) {
+      console.error(`✗ ${err.message}`);
+      anyViolation = true;
+    }
+  }
+
+  if (anyLoadError) process.exit(2);
+  process.exit(anyViolation ? 1 : 0);
+}
+
+main().catch(err => {
+  console.error(`kb-deny-lint: unexpected error: ${err.message}`);
+  process.exit(2);
+});

package/bin/mcp-server.js

@@ -20,14 +20,26 @@ import {
 import { WorkspaceConfig } from '../lib/workspace-config.js';
 import { DeSciXApiClient } from '../lib/api-client.js';
 import { WalletFileManager } from '../lib/wallet-file.js';
+import { CLI_VERSION } from '../lib/cli-version.js';
 import * as fs from 'fs/promises';
 import * as path from 'path';
+// WS-MCP-SSOT-TIER2 (audit §5.B-1): the curated HTTP-valid core tools are the SINGLE SOURCE
+// in @descix/platform-api/mcp-tools — shared with the Cloud HTTP MCP path (apiFront.js).
+// This stdio server imports them and CONCATENATES its CLI-LOCAL diagnostics (descix_doctor,
+// platform_health) which are NOT /apifront commands and are intentionally stdio-only.
+// The previously hand-duplicated curated literal in this file is GONE.
+import { toMcpToolList, NATIVE_MCP_TOOLS as SHARED_NATIVE_TOOLS, MCP_HANDSHAKE_INSTRUCTIONS, validateToolParams, toolAcceptsParam, VALIDATION_PHASE } from '@descix/platform-api/mcp-tools';
 
 // ---------------------------------------------------------------------------
-// Curated app-dev tool definitions (inline — no external tools.js dependency)
+// Tool definitions for the stdio MCP transport.
+//
+// CLI-LOCAL diagnostics (descix_doctor, platform_health) are defined here because they are
+// LOCAL CLI operations, not /apifront commands — they must never be advertised over the HTTP
+// path. Everything else comes from the shared SSOT (@descix/platform-api/mcp-tools), which is
+// the same source the Cloud HTTP MCP path advertises. ONE curated list, two transports.
 // ---------------------------------------------------------------------------
 
-const TOOLS = [
+const CLI_LOCAL_TOOLS = [
   {
     name: 'descix_doctor',
     description:
@@ -45,92 +57,32 @@ const TOOLS = [
     },
   },
   {
-    name: 'ask_question_to_app',
-    description: 'Ask an AI-powered question to an app\'s knowledge base using RAG',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        app_id: { type: 'string', description: 'App ID to query' },
-        knowledgebase_name: { type: 'string', description: 'KB name (default: General)' },
-        user_input: { type: 'string', description: 'The question to ask' },
-      },
-      required: ['app_id', 'user_input'],
-    },
-  },
-  {
-    name: 'query_knowledge_base',
-    description: 'Search a knowledge base using vector similarity (returns raw chunks)',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        app_id: { type: 'string', description: 'App ID' },
-        kb_id: { type: 'string', description: 'KB name (default: General)' },
-        query: { type: 'string', description: 'Search query' },
-        limit: { type: 'number', description: 'Max results (default: 5)' },
-      },
-      required: ['app_id', 'query'],
-    },
-  },
-  {
-    name: 'find_communities',
-    description: 'List available communities on the platform',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        filter: { type: 'string', description: 'Optional filter string' },
-      },
-    },
-  },
-  {
-    name: 'list_apps_for_community',
-    description: 'List apps in a community',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        community_id: { type: 'string', description: 'Community ID' },
-      },
-      required: ['community_id'],
-    },
-  },
-  {
-    name: 'tell_me_how',
+    name: 'platform_health',
     description:
-      'Discover platform tools and services by asking a natural language question. ' +
-      'Searches the entire service mesh for relevant capabilities. ' +
-      'If results are empty, try scope "discovery" or rephrase your question.',
+      'Check platform health. Returns structured pass/fail JSON for core platform (Cloud) and ' +
+      'an optional named microservice. The microservice is probed through the existing MCP proxy ' +
+      'infrastructure — no direct HTTP or curl. If this command responds, Cloud is healthy.',
     inputSchema: {
       type: 'object',
       properties: {
-        question: { type: 'string', description: 'What do you want to do?' },
-        scope: {
+        microservice: {
           type: 'string',
-          enum: ['project', 'entitlements', 'discovery'],
-          description: 'Search scope. "entitlements" = your purchased tools, "discovery" = all platform capabilities. Default: entitlements.',
+          description: 'Name of a registered microservice to check (e.g., "beast", "powch"). Omit to check core platform only.',
         },
       },
-      required: ['question'],
-    },
-  },
-  {
-    name: 'resolve_invite',
-    description:
-      'Resolve a DeSciX invite token into app configuration. Call this when .descix/app.json ' +
-      'contains an invite_token field. Returns app context, community info, and the agent_hint ' +
-      'authored by the app creator. The agent_hint tells you about the user\'s skill level and ' +
-      'goals — use it to adapt your approach.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        invite_token: {
-          type: 'string',
-          description: 'The invite token from .descix/app.json',
-        },
-      },
-      required: ['invite_token'],
     },
   },
 ];
 
+// Final stdio tool list: CLI-local diagnostics + the shared curated core tools (protocol shape).
+const TOOLS = [...CLI_LOCAL_TOOLS, ...toMcpToolList(SHARED_NATIVE_TOOLS)];
+
+// Live tool surface as last returned by tools/list (permission-filtered by the backend).
+// Seeded with the static curated SSOT so the very first tools/call is schema-aware even if
+// no tools/list preceded it. Consumed by tools/call for schema-aware context injection and
+// local param pre-validation (ws-mcp-surface-basics).
+let knownTools = TOOLS;
+
 // ---------------------------------------------------------------------------
 // Server bootstrap
 // ---------------------------------------------------------------------------
@@ -150,10 +102,26 @@ try {
     console.error('[MCP] No workspace config found — using defaults');
   }
 
-  // Create HTTP-only API client
+  // Create HTTP-only API client.
+  //
+  // serviceMode: true — THIS SERVER IS HEADLESS AND MUST DECLARE IT. Without it, a session
+  // whose token has expired falls through api-client.js's refresh handling into the INTERACTIVE
+  // device-login branch (:482-486): it logs to stdout and then `await`s `loginDevice`, opening a
+  // browser and blocking — inside a JSON-RPC request, on a transport with no human attached. The
+  // correct headless behaviour already existed one branch earlier at :474, which throws an error
+  // naming the fix; this server simply never opted into it. Measured 2026-08-30: the branch is
+  // reachable from here, and `serviceMode` was false because this construction site never set it.
+  //
+  // NO baseUrl HERE — and its absence is the fix, not an omission. This site used to pass
+  // `baseUrl: workspaceConfig?.apiUrl || null`, reading the LEGACY top-level workspace key. That
+  // is a second derivation of the origin, and worse than a preference: api-client.js:60 resolves
+  // through the origin owner ONLY `if (!this.baseUrl)`, so supplying one here PREVENTED the owner
+  // from ever running — no precedence, no DESCIX_API_URL, and no printed env line. Passing
+  // nothing lets the one owner resolve and announce it. (Contract rev 9: ruled a defect against
+  // I1 and folded into A1.)
   const apiClient = new DeSciXApiClient({
     projectRoot: workspaceRoot,
-    baseUrl: workspaceConfig?.apiUrl || null,
+    serviceMode: true,
   });
 
   // Load wallet credentials
@@ -250,6 +218,14 @@ try {
         '1. **Objective:** "Do you want to explore existing apps, or build something new?"',
         '2. **Community/App:** Use find_communities + list_apps_for_community, then ask: "Which community and app should this project target?"',
         '3. **Environment:** "Should this run against local dev backend (localhost:4000) or hosted API (descix.net)?"',
+        '4. **Cloud Brain:** "Which knowledge bases should I always consult when helping you?"',
+        '   Use the available_kbs field from this doctor report to show apps the user has access to.',
+        '   Present each with its app_id and community.',
+        '   User selects which ones to align to.',
+        '   Write their selections to .descix/alignment.json:',
+        '   { "version": "1.0", "apps": [{ "app_id": "...", "kb": "General", "role": "user\'s description" }],',
+        '     "defaults": { "level": 3, "thinking": -1, "tokens": true } }',
+        '   If user wants an app they don\'t have: guide them to join the community via find_communities.',
         '',
         '## Canonical setup commands (run in terminal)',
         '```',
@@ -288,6 +264,43 @@ try {
       report.warnings.push('No agent instruction files found. Run "descix quickstart" to generate them.');
     }
 
+    // Cloud brain alignment — read local alignment config
+    const alignmentPath = path.join(checkRoot, '.descix', 'alignment.json');
+    try {
+      const raw = await fs.readFile(alignmentPath, 'utf-8');
+      report.alignment = JSON.parse(raw);
+    } catch {
+      report.alignment = null;
+    }
+
+    // Detect Claude Code environment
+    try {
+      await fs.access(path.join(checkRoot, '.claude'));
+      report.claude_code_detected = true;
+    } catch {
+      report.claude_code_detected = false;
+    }
+
+    // Discover available KBs when authenticated and alignment is needed
+    if (walletInfo && (report.setup_needed || !report.alignment)) {
+      try {
+        const purchasesResult = await apiClient.invoke(
+          'fetch_my_purchases',
+          { product_type: 'APP' },
+          { allowGuest: false }
+        );
+        const purchasedApps = purchasesResult?.message?.apps || [];
+        const kbApps = purchasedApps.map(app => ({
+          app_id: app.app_id || app.appId || app.id,
+          community_id: app.community_id || app.communityId,
+          name: app.name || app.app_id || app.appId || app.id,
+        })).filter(a => a.app_id);
+        report.available_kbs = kbApps;
+      } catch {
+        report.available_kbs = null;
+      }
+    }
+
     // Remote verification (if requested, authenticated, and workspace configured)
     if (verifyRemote && walletInfo && freshContext?.appId) {
       try {
@@ -309,6 +322,15 @@ try {
       }
     }
 
+    // Suggest cloud brain alignment when workspace is configured but alignment is missing
+    if (!report.alignment && report.workspace?.configured) {
+      report.suggestions = report.suggestions || [];
+      report.suggestions.push(
+        'Cloud brain alignment not configured. Ask the user which knowledge bases to always consult. ' +
+        'Write selections to .descix/alignment.json.'
+      );
+    }
+
     if (report.warnings.length === 0) {
       report.status = 'healthy';
     } else {
@@ -320,14 +342,40 @@ try {
 
   // Create MCP server
   const server = new Server(
-    { name: 'DeSciX MCP Server', version: '1.0.0' },
-    { capabilities: { tools: {} } },
+    { name: 'DeSciX MCP Server', version: CLI_VERSION },
+    // WS-MVP-FIRSTCONTACT F1: the external-consumer operating manual rides the MCP
+    // `initialize` result on BOTH transports. SSOT: @descix/platform-api/mcp-tools
+    // handshake.js — do not hand-author a second copy here.
+    { capabilities: { tools: {} }, instructions: MCP_HANDSHAKE_INSTRUCTIONS },
   );
 
-  // tools/list — return curated tool definitions
+  // tools/list — PERMISSION-FILTERED surface (WS-MCP-SURFACE-SPLIT §10.2).
+  //
+  // The describe IS the permission gate. Rather than advertise a static curated list, the
+  // stdio server asks the BACKEND's /mcp tools/list (authenticated with this operator's
+  // credentials) so the advertised surface is filtered by the SAME server-side
+  // checkCommandPermission gate as the HTTP transport — ONE filter, no parallel taxonomy.
+  // `--admin` is simply the local operator's wallet carrying admin entitlements (cred-gated,
+  // §9.1): a platform-admin wallet sees admin tools; a public wallet sees public-only.
+  //
+  // CLI-LOCAL diagnostics (descix_doctor, platform_health) are ALWAYS concatenated — they are
+  // local CLI operations, never /apifront commands, so the backend never advertises them.
+  //
+  // Fallback: if the backend is unreachable, advertise the static curated SSOT core
+  // (CLI_LOCAL_TOOLS + NATIVE_MCP_TOOLS) so the operator is never left with an empty toolbox.
   server.setRequestHandler(ListToolsRequestSchema, async () => {
-    console.error(`[MCP] tools/list — returning ${TOOLS.length} tools`);
-    return { tools: TOOLS };
+    try {
+      const backendTools = await apiClient.mcpListTools();
+      const tools = [...CLI_LOCAL_TOOLS, ...backendTools];
+      // Remember the live, permission-filtered surface: tools/call uses it to decide which
+      // workspace defaults a tool actually ACCEPTS, and to pre-validate params locally.
+      knownTools = tools;
+      console.error(`[MCP] tools/list — ${backendTools.length} permission-filtered backend tools + ${CLI_LOCAL_TOOLS.length} CLI-local = ${tools.length}`);
+      return { tools };
+    } catch (err) {
+      console.error(`[MCP] tools/list — backend unreachable (${err.message}); falling back to static curated core (${TOOLS.length} tools)`);
+      return { tools: TOOLS };
+    }
   });
 
   // tools/call — dispatch to backend via HTTP (except doctor which is local)
@@ -344,16 +392,44 @@ try {
         };
       }
 
-      // Merge default context for convenience (caller can override).
-      // Only auto-fill when workspace is configured — prevents silently
-      // targeting wrong app/community.
+      // Merge default context for convenience (caller can override). Only auto-fill when the
+      // workspace is configured — prevents silently targeting the wrong app/community.
+      //
+      // ws-mcp-surface-basics — SCHEMA-AWARE injection. This block used to inject blindly into
+      // EVERY tool, which had two failure modes: it pushed app_id into tools that declare no
+      // app_id (find_communities), and it MANUFACTURED `kb_id: 'General'` — a param
+      // ask_question_to_app does not accept — so the stdio path itself created the
+      // silently-ignored parameter that this workstream exists to kill. A default is now only
+      // filled in when the TARGET TOOL DECLARES that parameter. The hardcoded 'General'
+      // fallback is DELETED (anti-pattern #7): when the workspace names no KB we send none and
+      // let the server apply its own configured default.
       const params = { ...args };
       if (defaultContext) {
-        if (!params.app_id && defaultContext.appId) params.app_id = defaultContext.appId;
-        if (!params.kb_id && (defaultContext.kbId || 'General')) params.kb_id = params.kb_id || defaultContext.kbId || 'General';
-        if (!params.community_id && defaultContext.communityId) params.community_id = defaultContext.communityId;
+        const accepts = (p) => toolAcceptsParam(knownTools, name, p);
+        if (!params.app_id && defaultContext.appId && accepts('app_id')) params.app_id = defaultContext.appId;
+        if (!params.community_id && defaultContext.communityId && accepts('community_id')) params.community_id = defaultContext.communityId;
+        if (!params.kb_id && defaultContext.kbId && accepts('kb_id')) params.kb_id = defaultContext.kbId;
+        // The ask-family names the same concept knowledgebase_name; honor the workspace default
+        // under the name the target tool actually publishes rather than under kb_id.
+        if (!params.knowledgebase_name && defaultContext.kbId && accepts('knowledgebase_name')) {
+          params.knowledgebase_name = defaultContext.kbId;
+        }
       }
 
+      // Fail loud LOCALLY on an unknown/missing param, before spending a round trip. The
+      // backend re-validates at its own boundary — this is a fast mirror of the same SSOT
+      // validator, never a second contract.
+      //
+      // PRE-INJECTION, measured: `args` is authored by the local MCP client and the only keys this
+      // block adds are ones the TARGET TOOL DECLARES (toolAcceptsParam). Nothing platform-injected
+      // has been written yet — apiFront's envelope/identity/context writes all happen server-side,
+      // after apiClient.invoke leaves this process — so the strict view is the honest one and a
+      // client-authored `_descix` is refused here, one round trip early.
+      validateToolParams(knownTools, name, params, {
+        surface: 'CLI stdio MCP tools/call',
+        phase: VALIDATION_PHASE.PRE_INJECTION,
+      });
+
       const result = await apiClient.invoke(name, params);
       return {
         content: [{
@@ -363,8 +439,16 @@ try {
       };
     } catch (error) {
       console.error(`[MCP] Tool error: ${error.message}`);
+      // WS-HEADLESS-MVP-A3: when the backend attached structured error fields (code +
+      // data — e.g. CREDITS_REQUIRED with its machine-readable purchasable action), ferry
+      // them as JSON after the prose so an MCP client can render the action (balance
+      // check via `get_credit_balance`, buy via `descix credits buy` / the
+      // create_stripe_checkout_session command) instead of parsing the message string.
+      const structured = (error.code || error.data)
+        ? `\n${JSON.stringify({ code: error.code, data: error.data }, null, 2)}`
+        : '';
       return {
-        content: [{ type: 'text', text: `Error: ${error.message}` }],
+        content: [{ type: 'text', text: `Error: ${error.message}${structured}` }],
         isError: true,
       };
     }

package/lib/agent-files.js

@@ -10,6 +10,7 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
+import { readIdentity, isIdentityNamed } from './workspace-identity.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -30,35 +31,46 @@ const AGENT_FILES = [
  */
 async function loadContext(workspaceRoot) {
   const wsPath = path.join(workspaceRoot, '.descix', 'workspace.json');
+
+  // A workspace.json that cannot be read or parsed is a HARD failure, not a cue to invent an
+  // identity. This used to return `{appId: <dirname>, communityId: 'daita', apiUrl: <prod>}` —
+  // three fabricated facts written into four files the developer's coding agent then treats as
+  // authoritative. 'daita' is the DeSciX root community; handing it to an unrelated developer
+  // was the worst of the three.
+  let config;
   try {
-    const raw = await fs.readFile(wsPath, 'utf-8');
-    const config = JSON.parse(raw);
-
-    // Derive from v2.1 format or legacy
-    const platform = config.env?.platform || {};
-    const appId = platform.appId || config.defaultContext?.appId || 'my-app';
-    const communityId = platform.communityId || config.defaultContext?.communityId || config.primaryCommunity || 'descix';
-
-    // Derive API URL
-    let apiUrl = config.apiUrl || null;
-    if (!apiUrl && platform.microservice?.port) {
-      apiUrl = `https://localhost:${platform.microservice.port}`;
-    }
-    apiUrl = apiUrl || 'https://descix.net';
+    config = JSON.parse(await fs.readFile(wsPath, 'utf-8'));
+  } catch (err) {
+    throw new Error(
+      `Cannot generate agent instruction files: ${wsPath} could not be read (${err.code || err.message}). ` +
+      `Run \`descix init -c <community> -a <app>\` first — the app, community and origin these ` +
+      `files state must come from your workspace, and there is no default that would be true.`
+    );
+  }
 
-    // Friendly name: capitalize app_id or use as-is
-    const appName = appId.charAt(0).toUpperCase() + appId.slice(1);
+  // ONE reader, over the keys registerApp() actually writes. See lib/workspace-identity.js.
+  const { appId, communityId, apiUrl, originSource } = readIdentity(config);
 
-    return { appId, communityId, apiUrl, appName };
-  } catch {
-    // No workspace.json — use defaults
-    return {
-      appId: path.basename(workspaceRoot),
-      communityId: 'descix',
-      apiUrl: 'https://descix.net',
-      appName: path.basename(workspaceRoot),
-    };
+  if (!isIdentityNamed({ appId, communityId })) {
+    const missing = [!appId && 'app id', !communityId && 'community id'].filter(Boolean).join(' and ');
+    throw new Error(
+      `Cannot generate agent instruction files: ${wsPath} names no ${missing}. ` +
+      `Run \`descix init -c <community> -a <app>\` to register it. ` +
+      `(Refusing to write files that would state an app or community you did not choose.)`
+    );
   }
+
+  // Under (A', contract rev 2) the origin is NEVER absent: a workspace that named none resolves
+  // to the declared default, carrying `source: default`. The "(not configured)" branch that
+  // stood here is therefore unreachable and was DELETED rather than fenced — an unreachable
+  // branch kept "just in case" is the compat fence CEO-D-2026-07-26 forbids. Which origin this
+  // is, and who chose it, is declared by the env line every network-bound command prints.
+  const originLine = apiUrl;
+
+  // Friendly name: capitalize app_id or use as-is
+  const appName = appId.charAt(0).toUpperCase() + appId.slice(1);
+
+  return { appId, communityId, apiUrl: originLine, appName, originSource };
 }
 
 /**