@descix/cli 1.0.6 → 1.0.8

package/lib/api-client.js

@@ -13,6 +13,35 @@ import { resolveOrigin } from './origin.js';
 import { reportEnvironment, EXPLICIT_ORIGIN_SOURCE } from './environment-report.js';
 import { diag } from './diagnostic-log.js';
 
+/**
+ * THE effective API origin for this invocation, with the source that chose it: the environment
+ * variable (which the --api-url / --env flags fold into), then the workspace's env.apiUrl, then
+ * ~/.descix/config.json, then the declared default. Every surface that SHOWS or USES the origin
+ * consumes this — `config show` used to print the workspace file's value while every command
+ * used the environment variable's, so an inherited DESCIX_API_URL silently pointed commands at
+ * production while `config show` said dev (JARVIS-FRAQTL, 2026-09-16).
+ *
+ * Never returns null and never throws for an ABSENT configuration (nothing configured is the
+ * declared default, carrying `source: default`, which the caller prints). Throws
+ * OriginInvalidError when a source named an origin that cannot be used.
+ *
+ * @param {string|null|undefined} workspaceEnvApiUrl - the loaded workspace's env.apiUrl
+ * @returns {Promise<{origin: string, source: string, isDefault: boolean}>}
+ */
+export async function resolveEffectiveOrigin(workspaceEnvApiUrl) {
+  let globalApiUrl = null;
+  try {
+    const { GlobalConfig } = await import('./global-config.js');
+    const gc = await GlobalConfig.load();
+    globalApiUrl = gc.api_url || null;
+  } catch {}
+  return resolveOrigin({
+    envVar: process.env.DESCIX_API_URL,
+    workspaceEnvApiUrl,
+    globalApiUrl,
+  });
+}
+
 export class DeSciXApiClient {
   constructor(options = {}) {
     this.baseUrl = options.baseUrl || null; // Will be loaded async
@@ -93,28 +122,7 @@ export class DeSciXApiClient {
    * @returns {Promise<{origin: string, source: string, isDefault: boolean}>}
    */
   async detectApiUrl() {
-    // Every branch of this function used to be able to yield the production origin without the
-    // developer having chosen it, and the `!== PRODUCTION_URL` comparisons made it WORSE than a
-    // plain fallback: a workspace that had deliberately set prod was treated as if it had set
-    // nothing and skipped, so "chosen" and "unconfigured" were provably indistinguishable. The
-    // precedence and the fail-loud now live in the one origin owner.
-    let globalApiUrl = null;
-    try {
-      const { GlobalConfig } = await import('./global-config.js');
-      const gc = await GlobalConfig.load();
-      globalApiUrl = gc.api_url || null;
-    } catch {}
-
-    // Never returns null and never throws for an ABSENT configuration: nothing configured is
-    // the declared default (PROD), carrying `source: default`, which the caller prints. It DOES
-    // throw OriginInvalidError when a source named an origin that cannot be used — silently
-    // discarding what the developer typed is the same defect from the other direction.
-    return resolveOrigin({
-      envVar: process.env.DESCIX_API_URL,
-      workspaceEnvApiUrl: this._workspaceConfig?.env?.apiUrl,
-      legacyApiUrl: this._workspaceConfig?.apiUrl,
-      globalApiUrl,
-    });
+    return resolveEffectiveOrigin(this._workspaceConfig?.env?.apiUrl);
   }
 
   /**

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/airdrop.js

@@ -28,6 +28,8 @@
  */
 
 import fs from 'fs';
+// "May I prompt?" has ONE OWNER. This site holds no TTY check of its own.
+import { requireInteractive } from '../interactive.js';
 import readline from 'readline';
 import chalk from 'chalk';
 import { DeSciXApiClient } from '../api-client.js';
@@ -65,6 +67,14 @@ export function readSignerPkFromFile(path) {
  * @returns {Promise<string>} Validated PK in `0x` + 64 hex form.
  */
 export async function promptSignerPkInteractive({ stdin = process.stdin, stdout = process.stdout } = {}) {
+    // Gate FIRST: a non-TTY here previously hung forever holding a secret prompt open. This site
+    // keeps its own readline because it must disable terminal echo so the PK is never displayed;
+    // the DECISION of whether prompting is allowed is still the owner's alone.
+    requireInteractive({
+        what: 'descix airdrop',
+        question: 'signer private key',
+        nonInteractiveForm: ['descix airdrop --signer-pk-file <path>   # reads the key from a file, never echoed']
+    });
     return await new Promise((resolve, reject) => {
         const rl = readline.createInterface({ input: stdin, output: stdout, terminal: true });
         // Disable echo so the PK isn't visible while typing.

package/lib/commands/auth.js

@@ -264,7 +264,19 @@ export async function loginDevice(options = {}) {
     }
 
     const walletPath = WalletFileManager.getProjectWalletPath(workspaceRoot);
-    await WalletFileManager.saveWalletFile(walletPath, walletData);
+    try {
+      await WalletFileManager.saveWalletFile(walletPath, walletData);
+    } catch (saveErr) {
+      spinner.fail(chalk.red('Login did not complete'));
+      // The browser ceremony succeeded, but the platform returned no usable CLI credential for this
+      // account (e.g. an empty wallet signature). Say so plainly: nothing was written, and this
+      // workspace is NOT logged in on this environment.
+      throw Object.assign(new Error(
+        `The platform completed the browser sign-in but returned an unusable CLI credential (${saveErr.message}). ` +
+        `Nothing was saved and you are NOT logged in on ${apiClient.baseUrl}. ` +
+        `This is a platform defect, not something you can fix locally; report it with this message.`
+      ), { code: 'UNUSABLE_CLI_CREDENTIAL' });
+    }
 
     spinner.succeed(chalk.green('Login successful!'));
     if (walletData.oauth) {
@@ -319,7 +331,9 @@ export async function loginDevice(options = {}) {
     spinner.fail(chalk.red('Login failed'));
     console.error(chalk.red(error.message));
     
-    if (error.message.includes('expired')) {
+    if (error.code === 'UNUSABLE_CLI_CREDENTIAL') {
+      // The message above is the whole diagnosis; connectivity tips would misdirect.
+    } else if (error.message.includes('expired')) {
       diag(chalk.yellow('💡 Tip: Device codes expire after 15 minutes.'));
       diag(chalk.yellow('   Run the login command again to get a new code.\n'));
     } else {

package/lib/commands/config.js

@@ -9,6 +9,8 @@ import chalk from 'chalk';
 import * as path from 'path';
 import { WorkspaceConfig } from '../workspace-config.js';
 import { environmentNameFor } from '../environment-report.js';
+import { resolveEffectiveOrigin } from '../api-client.js';
+import { normalizeOrigin } from '../origin.js';
 
 /**
  * Show current configuration
@@ -20,15 +22,17 @@ export async function show() {
 
     console.log(chalk.cyan('\n📋 DeSciX Workspace Configuration:\n'));
     console.log(chalk.white(`   Workspace:     ${workspaceRoot}`));
-    // Under (A', contract rev 2) getApiUrl() ALWAYS yields an origin — a workspace that named
-    // none resolves to the declared default. The "(not configured)" branch is therefore
-    // unreachable and was DELETED, not fenced.
-    const configuredOrigin = workspaceConfig.getApiUrl();
-    console.log(chalk.white(`   API URL:       ${configuredOrigin}`));
-    // The environment NAME comes from the ONE owner that derives it from the origin. It used to
-    // read a separate `env.environment` key and fall back to the literal 'production' — a second
-    // derivation of the same fact, which could disagree with the origin printed one line above.
-    console.log(chalk.white(`   Environment:   ${environmentNameFor(configuredOrigin)}`));
+    // The origin every command in this shell will USE, and who chose it — not the file's value
+    // alone. An inherited DESCIX_API_URL outranks the workspace pin; showing only the pin made
+    // `config show` say dev while commands ran against production.
+    const effective = await resolveEffectiveOrigin(workspaceConfig.env?.apiUrl);
+    console.log(chalk.white(`   API URL:       ${effective.origin}`));
+    console.log(chalk.white(`   Environment:   ${environmentNameFor(effective.origin)}`));
+    console.log(chalk.white(`   Chosen by:     ${effective.source}`));
+    const pinned = workspaceConfig.env?.apiUrl;
+    if (pinned && normalizeOrigin(pinned) !== effective.origin) {
+      console.log(chalk.yellow(`   ⚠ This workspace pins ${normalizeOrigin(pinned)} (${environmentNameFor(pinned)}), but ${effective.source} overrides it for this shell.`));
+    }
 
     // Show mapped apps (v2.1 env.products)
     const platform = workspaceConfig.env?.platform;
@@ -49,28 +53,6 @@ export async function show() {
   }
 }
 
-/**
- * Set API URL
- */
-export async function setUrl(url, options = {}) {
-  try {
-    const workspaceConfig = await WorkspaceConfig.load();
-    const workspaceRoot = workspaceConfig.getWorkspaceRoot();
-
-    workspaceConfig.apiUrl = url;
-    workspaceConfig.environment = url.includes('localhost') ? 'development' : 'production';
-    const configPath = await workspaceConfig.save(workspaceRoot);
-
-    console.log(chalk.green('\n✅ Configuration updated!\n'));
-    console.log(chalk.white(`   API URL: ${url}`));
-    console.log(chalk.gray(`   Saved to: ${configPath}\n`));
-
-  } catch (error) {
-    console.error(chalk.red('Error updating config:', error.message));
-    throw error;
-  }
-}
-
 /**
  * Initialize config for environment
  */