@descix/cli 1.0.7 → 1.0.8

package/lib/command-visibility.js

@@ -0,0 +1,213 @@
+/**
+ * Command Visibility — the PUBLIC-vs-admin CLI help listing.
+ *
+ * CEO ruling (verbatim): "The microservice manifest consumed by DeSciX core should determine
+ * what gets exposed via MCP (and therefore CLI listing should be easily exposed there too for
+ * the core itself) - shouldn't we reuse that surface." And: "It's not a worry that admin
+ * commands can be discovered by normal users but rather we are trying to avoid the flood of
+ * noise so it is acceptable to have two lists that can be derived from the same manifest."
+ *
+ * THE CLASS COMES FROM THE SERVER AT RUNTIME (`get_command_surface`, guest-allowed) — there is
+ * NO committed class table in this repo. The only thing committed here is
+ * lib/verb-invokes.generated.json, a CLI-owned fact ("this verb invokes these commands"),
+ * regenerated by scripts/generate-verb-invokes.mjs from bin/descix.js + lib/** itself.
+ *
+ * A verb is hidden from the default listing when it invokes at least one command AND every
+ * command it invokes is classified 'admin' by the server. A verb with no recorded invokes
+ * (local-only, or a verb whose only invoke call sites are dynamic — see
+ * scripts/lib/verb-invoke-graph.mjs) stays visible: absence of information is not evidence of
+ * admin-only-ness. A GROUP (a command with children and no action of its own) is hidden when
+ * every one of its children ends up hidden — hiding is transitive up the tree, computed
+ * bottom-up from the LIVE commander tree (never a second, hand-kept tree).
+ *
+ * Hiding is LISTING ONLY. A hidden verb still EXECUTES normally when typed; the server's own
+ * permission gate (checkCommandPermission) is the actual enforcement, unchanged by this file.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import VERB_INVOKES from './verb-invokes.generated.json' with { type: 'json' };
+
+const CACHE_PATH = path.join(os.homedir(), '.descix', 'command-surface-cache.json');
+/** Short TTL: this is a LISTING convenience cache, not a security boundary — a stale read only
+ * ever risks showing (or hiding) a help row for a few minutes, never changes what executes. */
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+/**
+ * ONE explicit, CLI-owned declaration: Drive content authoring (`descix drive pull/push`) needs
+ * infrastructure admin credentials (Google ADC / a Drive service account) that `get_command_surface`
+ * has no visibility into — it is not gated by any COMMAND_PERMISSIONS entry the server classifies
+ * 'admin', so it can never be derived from the manifest. Per the CEO's ruling these stay OUT of
+ * the public CLI listing (internal Drive authoring still uses them — hidden, never deleted). The
+ * `drive` group itself is included for clarity; it would also be hidden automatically once both
+ * of its children are (see applyVisibility's group rule), but naming it here keeps this ONE set
+ * the single place that answers "why is drive hidden" rather than splitting the answer across a
+ * declaration and an inference.
+ */
+export const INFRA_ADMIN_HIDDEN_PATHS = new Set(['drive', 'drive pull', 'drive push']);
+
+/** @returns {Record<string,string[]>} the committed, generated verb -> invoked-commands map. */
+export function getVerbInvokeMap() {
+  return VERB_INVOKES;
+}
+
+/**
+ * Fetch the server's per-command visibility surface as a guest (no login needed).
+ * @param {import('./api-client.js').DeSciXApiClient} apiClient
+ * @returns {Promise<{ service: string, manifest_hash: string, commands: Record<string,'public'|'admin'> }>}
+ */
+export async function fetchCommandSurface(apiClient) {
+  const resp = await apiClient.invoke('get_command_surface', {}, { allowGuest: true });
+  const msg = resp?.message || resp;
+  if (!msg || typeof msg.commands !== 'object' || msg.commands === null) {
+    throw new Error(`get_command_surface returned an unexpected shape: ${JSON.stringify(resp)}`);
+  }
+  return msg;
+}
+
+async function readCache() {
+  try {
+    const raw = await fs.readFile(CACHE_PATH, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+async function writeCache(cache) {
+  try {
+    await fs.mkdir(path.dirname(CACHE_PATH), { recursive: true });
+    await fs.writeFile(CACHE_PATH, JSON.stringify(cache, null, 2), 'utf8');
+  } catch {
+    // Best-effort. A cache write failure must never break help output — the caller already has
+    // the freshly-fetched surface in hand and can render with it regardless.
+  }
+}
+
+/**
+ * The server surface for `origin`, from the user-level cache (keyed by origin, short TTL) when
+ * fresh, else fetched live and cached. Throws if the fetch fails (network down, old server
+ * without the command, etc.) — the caller decides what "help shows everything" means.
+ *
+ * @param {string} origin
+ * @param {import('./api-client.js').DeSciXApiClient} apiClient
+ * @returns {Promise<{ commands: Record<string,'public'|'admin'>, fromCache: boolean }>}
+ */
+export async function getCommandSurface(origin, apiClient) {
+  const cache = await readCache();
+  const entry = cache[origin];
+  if (entry && typeof entry.fetchedAt === 'number' && (Date.now() - entry.fetchedAt) < CACHE_TTL_MS) {
+    return { commands: entry.surface.commands, fromCache: true };
+  }
+  const surface = await fetchCommandSurface(apiClient);
+  cache[origin] = { surface, fetchedAt: Date.now() };
+  await writeCache(cache);
+  return { commands: surface.commands, fromCache: false };
+}
+
+/**
+ * Should a single LEAF verb (identified by its full space-joined path, e.g. "kb corpus sync") be
+ * hidden from the default listing, given the server's command->visibility surface?
+ *
+ * @param {string} verbPath
+ * @param {Record<string,'public'|'admin'>} surfaceCommands
+ * @returns {boolean}
+ */
+export function shouldHideLeaf(verbPath, surfaceCommands) {
+  if (INFRA_ADMIN_HIDDEN_PATHS.has(verbPath)) return true;
+  const invokes = VERB_INVOKES[verbPath];
+  if (!invokes || invokes.length === 0) return false; // no recorded invokes -> stays visible
+  return invokes.every((cmd) => surfaceCommands[cmd] === 'admin');
+}
+
+/**
+ * Apply hide/show to the LIVE commander tree rooted at `program`, bottom-up. Never reads or
+ * builds a second command tree — `cmd.commands` / `cmd._actionHandler` (commander's own runtime
+ * state) is the only source of "what verbs exist and how they nest", so this can never drift
+ * from the tree `--help` actually renders.
+ *
+ * @param {import('commander').Command} program
+ * @param {Record<string,'public'|'admin'>} surfaceCommands
+ */
+export function applyVisibility(program, surfaceCommands) {
+  function visit(cmd, pathTokens) {
+    const verbPath = pathTokens.join(' ');
+    const hasChildren = Array.isArray(cmd.commands) && cmd.commands.length > 0;
+    // ADDITIVE ONLY. Some commands are registered `{ hidden: true }` by the CLI itself for
+    // reasons that have nothing to do with server admin-gating — see the retired-surface
+    // registrations in lib/commands/retired-kb-sync.js, each a deliberate loud-refusal stub kept
+    // out of the default listing so it doesn't clutter it, while still working and refusing
+    // clearly when typed. This layer may HIDE a visible command; it must never REVEAL a command
+    // the CLI already chose to hide. MEASURED: an early version unconditionally overwrote
+    // `_hidden`, which un-hid a retired-surface stub the moment its verb had no generated-map
+    // entry (it invokes no /apifront command at all, so its invoke list is empty).
+    const alreadyHidden = !!cmd._hidden;
+
+    if (hasChildren) {
+      let allChildrenHidden = true;
+      for (const child of cmd.commands) {
+        const childHidden = visit(child, [...pathTokens, child.name()]);
+        if (!childHidden) allChildrenHidden = false;
+      }
+      if (pathTokens.length === 0) return false; // never hide the root program
+      if (cmd._actionHandler) {
+        // A command that is BOTH a group and its own runnable leaf (not used in this CLI today,
+        // but commander allows it) is judged as a leaf: its own invokes decide it, independent
+        // of its children.
+        const hidden = alreadyHidden || shouldHideLeaf(verbPath, surfaceCommands);
+        cmd._hidden = hidden;
+        return hidden;
+      }
+      cmd._hidden = alreadyHidden || allChildrenHidden;
+      return cmd._hidden;
+    }
+
+    if (pathTokens.length === 0) return false; // the root has no children in practice, but guard anyway
+    const hidden = alreadyHidden || shouldHideLeaf(verbPath, surfaceCommands);
+    cmd._hidden = hidden;
+    return hidden;
+  }
+  visit(program, []);
+}
+
+/**
+ * Is this invocation one that will render `--help` output? Only these fetch the network — every
+ * other invocation must stay fast and offline-safe.
+ *
+ * Recognizes: `-h` / `--help` anywhere, `help` in subcommand position, a bare invocation (no positional tokens once
+ * global flags are stripped), and a "bare group" invocation (the resolved command has children
+ * but no action handler of its own — e.g. `descix app` with no subcommand, which commander
+ * renders as help even though the CLI never called outputHelp() itself).
+ *
+ * @param {import('commander').Command} program
+ * @param {string[]} argv - process.argv.slice(2)
+ * @param {{ valueFlags?: string[], booleanFlags?: string[] }} [globalFlags]
+ * @returns {boolean}
+ */
+export function isHelpInvocation(program, argv, globalFlags = {}) {
+  if (argv.length === 0) return true;
+  if (argv.includes('-h') || argv.includes('--help')) return true;
+  if (argv.includes('-V') || argv.includes('--version')) return false; // prints a version, renders no listing
+
+  const valueFlags = new Set(globalFlags.valueFlags || []);
+  const booleanFlags = new Set(globalFlags.booleanFlags || []);
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (valueFlags.has(tok)) { i++; continue; }
+    if (booleanFlags.has(tok)) continue;
+    if (tok.startsWith('-')) continue; // an option belonging to whatever command it turns out to be
+    positional.push(tok);
+  }
+  if (positional.length === 0) return true;
+
+  let cmd = program;
+  for (const tok of positional) {
+    if (cmd._actionHandler) break; // reached a leaf; remaining tokens are ITS args, not subcommands
+    if (tok === 'help') return true; // commander's help subcommand, only in subcommand position
+    const next = (cmd.commands || []).find((c) => c.name() === tok || (c.aliases && c.aliases().includes(tok)));
+    if (!next) return false; // unresolvable path — commander's own error path, not ours to fetch for
+    cmd = next;
+  }
+  return !cmd._actionHandler;
+}

package/lib/commands/corpus.js

@@ -452,16 +452,13 @@ export async function runCorpusSync(apiClient, options) {
     const missingKbNames = requestedKbNames.filter(name => !registeredKbNames.has(name));
     if (missingKbNames.length > 0) {
       // Hard-fail: every KB we are about to sync into must already be registered in Firestore.
-      // No hardcoded fallback. `app init` is the verb that actually creates a KB on a
-      // git-mode app (init_git_mode_kb, bin/descix.js:1163). `kb create` is Drive-mode
-      // wired (create_skeleton_kb, :2087) and fails here — filed as its own defect.
+      // No hardcoded fallback. `app init --kb` is the verb that creates a KB (init_git_mode_kb).
       spinner.fail(`Unregistered KB(s) for app "${appId}"`);
       throw new Error(
         `KnowledgeBase document(s) missing in Firestore for app "${appId}": ${missingKbNames.join(', ')}.\n` +
         `Registered KBs for this app: ${[...registeredKbNames].join(', ') || '(none)'}.\n` +
         `Syncing vectors into Pinecone without a matching KB doc would orphan them (chat queries hard-fail).\n` +
-        `Fix: run \`descix app init -a ${appId}\` — it creates the KB via init_git_mode_kb and needs no Drive folder.\n` +
-        `(\`descix kb create\` currently routes through create_skeleton_kb and FAILS on a git-mode app.)`
+        `Fix: run \`descix app init -a ${appId} --kb <kb_name>\` for each missing KB — it creates the KB and needs no Drive folder.`
       );
     }
 

package/lib/commands/kb.js

@@ -179,9 +179,9 @@ export async function runKbPush(apiClient, options) {
     const onConflictPrompt = options.interactive ? async (fileName, fileInfo) => {
       spinner.stop();
       requireInteractive({
-        what: 'descix kb push --interactive',
+        what: 'descix drive push --interactive',
         question: `File "${fileName}" exists in Drive. Overwrite or skip?`,
-        nonInteractiveForm: ['descix kb push   # without --interactive, conflicts resolve without a prompt']
+        nonInteractiveForm: ['descix drive push   # without --interactive, conflicts resolve without a prompt']
       });
       const { action } = await inquirer.prompt([{
         type: 'list',

package/lib/commands/retired-kb-sync.js

@@ -19,20 +19,17 @@
 export const CANONICAL_KB_SYNC = 'descix kb corpus sync';
 
 /** The verb that creates a KB — `kb corpus sync`'s dependency (I4). */
-export const CANONICAL_KB_CREATE = 'descix kb create';
+export const CANONICAL_KB_CREATE = 'descix app init --kb <kb_name>';
 
 /**
  * Every KB-sync surface retired by ws-devplane-cli-kb-surface-single-canonical-sync.
  * `invocation` is what a user types; `parent` is the commander parent it hung off.
  */
 export const RETIRED_KB_SYNC_SURFACES = [
-  { id: 'sync',      parent: 'program', name: 'sync',  invocation: 'descix sync',      registered: true  },
-  { id: 'sync.kb',   parent: 'sync',    name: 'kb',    invocation: 'descix sync kb',   registered: true  },
-  { id: 'kb.chunk',  parent: 'kb',      name: 'chunk', invocation: 'descix kb chunk',  registered: true  },
-  { id: 'kb.sync',   parent: 'kb',      name: 'sync',  invocation: 'descix kb sync',   registered: true  },
-  // registered:false -- `update` survives for app/site, so this one is a dispatcher branch
-  // inside the live `update` command rather than a commander registration of its own.
-  { id: 'update.kb', parent: 'update',  name: 'kb',    invocation: 'descix update kb', registered: false },
+  { id: 'sync',      parent: 'program', name: 'sync',  invocation: 'descix sync' },
+  { id: 'sync.kb',   parent: 'sync',    name: 'kb',    invocation: 'descix sync kb' },
+  { id: 'kb.chunk',  parent: 'kb',      name: 'chunk', invocation: 'descix kb chunk' },
+  { id: 'kb.sync',   parent: 'kb',      name: 'sync',  invocation: 'descix kb sync' },
 ];
 
 /** Implementations deleted with those surfaces. No exported symbol survives without a caller (I3). */
@@ -61,24 +58,6 @@ export function retiredKbSyncMessage(invocation) {
   );
 }
 
-/**
- * Refuse a retired invocation LOUDLY and exit non-zero.
- *
- * MEASURED, not assumed: a `throw` from updateAuto is NOT swallowed — updateAuto's own catch
- * prints the message before rethrowing, so both forms reach the user and exit 1. This exists
- * for two smaller, real reasons: (1) ONE owner for the refusal, so the dispatcher branch and
- * updateAuto's kb branch cannot drift into different wording or different exit codes; and
- * (2) a deliberate retirement is not a crash, so it should not be framed as "✖ Update failed".
- *
- * @param {string} invocation - the retired invocation, e.g. 'descix update kb'
- * @param {(s:string)=>string} red - chalk.red or equivalent
- * @returns {never}
- */
-export function refuseRetiredKbSync(invocation, red) {
-  console.error(red(`\n❌ ${retiredKbSyncMessage(invocation)}\n`));
-  process.exit(1);
-}
-
 /**
  * Register a retired invocation so it exits NON-ZERO naming the canonical surface.
  * Accepts and ignores any args/options the old surface took, so an old script fails with
@@ -120,7 +99,6 @@ export function registerRetiredKbSync(parent, name, invocation, red) {
 export function registerAllRetiredKbSync(roots, red) {
   const byId = { ...roots };
   for (const s of RETIRED_KB_SYNC_SURFACES) {
-    if (!s.registered) continue;
     const parent = byId[s.parent];
     if (!parent) {
       throw new Error(

package/lib/commands/status.js

@@ -206,15 +206,6 @@ export async function runStatus(options = {}) {
     console.log(`Service Key:        ${chalk.gray('None')} (dev-overrides.json)`);
   }
 
-  // Check for MCP rules
-  const rulesPath = path.join(checkDir, '.cursor', 'rules', 'descix_mcp.mdc');
-  try {
-    await fs.access(rulesPath);
-    console.log(`MCP Rules:          ${chalk.green('Deployed')} (.cursor/rules/descix_mcp.mdc)`);
-  } catch {
-    console.log(`MCP Rules:          ${chalk.gray('Not Deployed')}`);
-  }
-
   // Check gcloud
   const gcloudStatus = await checkGcloud();
   if (gcloudStatus.installed) {

package/lib/sdk-assets.js

@@ -0,0 +1,28 @@
+/**
+ * The SDK's agent assets (instructions, guides, reference) ship inside this package at
+ * agent-assets/. `pullSdkAssets` copies them into a workspace at .descix/sdk-assets/ so a local AI
+ * agent can read them. A missing source is a broken install and throws; it is never skipped.
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+
+/** agent-assets/ at the package root, one level above lib/. */
+export const SDK_ASSETS_SOURCE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'agent-assets');
+
+/**
+ * Copy the package's agent-assets/ to <workspaceRoot>/.descix/sdk-assets/.
+ * @param {string} workspaceRoot
+ * @returns {Promise<string>} the target directory
+ * @throws when the package's agent-assets/ is absent or the copy fails
+ */
+export async function pullSdkAssets(workspaceRoot) {
+  const target = path.join(workspaceRoot, '.descix', 'sdk-assets');
+  try {
+    await fs.access(SDK_ASSETS_SOURCE);
+  } catch {
+    throw new Error(`SDK agent assets are missing from this install (${SDK_ASSETS_SOURCE}). Reinstall @descix/cli.`);
+  }
+  await fs.cp(SDK_ASSETS_SOURCE, target, { recursive: true });
+  return target;
+}

package/lib/verb-invokes.generated.json

@@ -0,0 +1,233 @@
+{
+  "admin-login": [
+    "admin_bootstrap_login"
+  ],
+  "airdrop execute-queue": [
+    "airdrop_execute_queue"
+  ],
+  "app delete": [
+    "delete_app"
+  ],
+  "app init": [
+    "create_app_for_community",
+    "get_product_context",
+    "init_git_mode_kb"
+  ],
+  "app invite": [
+    "create_app_invite"
+  ],
+  "app list": [
+    "fetch_my_purchases"
+  ],
+  "app media-upload": [
+    "get_asset_upload_token"
+  ],
+  "app open": [],
+  "app set-api-url": [
+    "update_app_metadata"
+  ],
+  "app set-default-model": [
+    "clear_app_default_model",
+    "set_app_default_model"
+  ],
+  "app set-listed": [
+    "update_app"
+  ],
+  "app set-localpath": [],
+  "app set-name": [
+    "update_app"
+  ],
+  "app set-port": [],
+  "app set-price": [
+    "update_app_metadata"
+  ],
+  "app set-repo": [
+    "set_app_repo"
+  ],
+  "app set-site": [],
+  "app sync-assets": [
+    "sync_app_assets"
+  ],
+  "app unmap": [],
+  "buy chains": [],
+  "buy poll": [
+    "get_quote_status"
+  ],
+  "buy quote": [
+    "create_crypto_quote"
+  ],
+  "buy status": [
+    "get_quote_status"
+  ],
+  "chat": [
+    "ask_multiple_apps",
+    "ask_question_to_app"
+  ],
+  "clone": [
+    "get_repo_credentials"
+  ],
+  "community check-token": [
+    "check_token_symbol_available"
+  ],
+  "community contract": [
+    "get_contract_details"
+  ],
+  "community create": [
+    "create_community_skeleton"
+  ],
+  "community delete": [
+    "delete_community"
+  ],
+  "community deploy-token": [
+    "deploy_contract"
+  ],
+  "community info": [
+    "get_community"
+  ],
+  "community link-token": [
+    "link_contract_to_community"
+  ],
+  "community list": [
+    "find_communities"
+  ],
+  "community rename": [
+    "rename_community"
+  ],
+  "config init": [],
+  "config set-dev-certs": [],
+  "config set-env": [],
+  "config set-gateway-port": [],
+  "config set-powch-url": [],
+  "config set-site-url": [],
+  "config set-url": [],
+  "config show": [],
+  "credits balance": [
+    "get_credit_balance"
+  ],
+  "credits buy": [
+    "create_stripe_checkout_session"
+  ],
+  "credits grant": [
+    "grant_credits"
+  ],
+  "credits history": [
+    "get_credit_history"
+  ],
+  "credits refund": [
+    "refund_credits"
+  ],
+  "doctor": [],
+  "drive pull": [],
+  "drive push": [],
+  "health": [],
+  "init": [
+    "find_communities",
+    "resolve_invite"
+  ],
+  "kb clear-override-model": [
+    "clear_kb_model_override"
+  ],
+  "kb corpus status": [],
+  "kb corpus sync": [
+    "get_kb_rag_status",
+    "get_product_context",
+    "kb_delete_chunks",
+    "kb_list_file_ids",
+    "kb_sync_chunks",
+    "list_knowledge_bases"
+  ],
+  "kb delete": [
+    "delete_knowledge_base"
+  ],
+  "kb doctor": [
+    "get_kb_rag_status"
+  ],
+  "kb list": [
+    "list_knowledge_bases"
+  ],
+  "kb set-override-model": [
+    "set_kb_model_override"
+  ],
+  "login": [
+    "device_check_status",
+    "device_request_login",
+    "sync_auto_purchases"
+  ],
+  "logout": [],
+  "mcp execute": [],
+  "mcp-serve": [],
+  "microservice health": [
+    "service_health_check"
+  ],
+  "microservice init": [],
+  "microservice list": [
+    "list_services"
+  ],
+  "microservice register": [
+    "register_service"
+  ],
+  "microservice register-delegate": [
+    "fetch_my_purchases",
+    "register_delegate"
+  ],
+  "microservice reload": [
+    "reload_service_manifests"
+  ],
+  "microservice restart": [],
+  "microservice vectorize": [
+    "vectorize_service_readme"
+  ],
+  "new-chat": [],
+  "purchases": [
+    "fetch_my_purchases"
+  ],
+  "quickstart": [
+    "device_check_status",
+    "device_request_login",
+    "find_communities",
+    "resolve_invite",
+    "sync_auto_purchases"
+  ],
+  "reconnect": [
+    "reconnect_by_wallet"
+  ],
+  "referral create": [
+    "generate_referral_code"
+  ],
+  "role create": [
+    "create_role"
+  ],
+  "serve": [],
+  "site delete": [
+    "delete_site_files"
+  ],
+  "site init": [],
+  "site list": [
+    "list_site_files"
+  ],
+  "site status": [
+    "get_site_manifest"
+  ],
+  "site upload": [
+    "confirm_site_deploy",
+    "get_site_build_config",
+    "get_site_deploy_token"
+  ],
+  "stats": [
+    "get_user_community_stats"
+  ],
+  "status": [],
+  "store generate-summary": [
+    "generate_entity_summary"
+  ],
+  "store search": [
+    "search_store"
+  ],
+  "tell-me-how": [
+    "tell_me_how"
+  ],
+  "whoami": [
+    "fetch_my_purchases",
+    "validate_session"
+  ]
+}