@descix/cli 2.0.2 → 2.0.3

package/agent-assets/guides/microservice-pattern.md

@@ -116,7 +116,9 @@ descix kb corpus sync -c <community> -a <app>
 
 **What registration is, and is not.** It publishes your `manifest.json` — the command list —
 and vectorizes the README you pass with `-r`, so `tell_me_how` can discover your tools.
-`scripts/register.js` writes that manifest and logs the commands it published. There is no
+`scripts/register.js` writes that manifest and logs the commands it published. It targets a RUNNING
+service: it first calls the service's own `/api` unsigned and registers only if the mesh guard
+answers 401, so start the service (`npm run dev`), then run `npm run register`. There is no
 separate developer-facing vectorize step — `descix microservice vectorize` exists but is an
 admin-only utility (for re-vectorizing without re-registering), not part of the normal flow.
 It is a DISCOVERY step.

package/bin/descix.js

@@ -442,11 +442,9 @@ const airdropCommand = program
 
 airdropCommand
   .command('execute-queue')
-  .description('Manually trigger airdrop_execute_queue on the target env (admin-only)')
-  .option('--community <slug>', 'Community slug for per-community batch scoping (REQUIRED for --apply)')
-  .option('--dry-run', 'Read-only preview: encode calldata, estimate gas, validate net-zero invariant. No PK, no tx, no state mutation.')
-  .option('--apply', 'Live execution: requires --signer-pk-file or interactive prompt-password. Mutually exclusive with --dry-run.')
-  .option('--signer-pk-file <path>', 'Path to file containing admin signer PK (0x + 64 hex). Required for --apply unless prompted interactively.')
+  .description('DRY-RUN ONLY preview of the airdrop migration queue (admin-only). Execution lives in daita-sam (act plan + the role holder\'s own wallet) — the apply leg is removed.')
+  .option('--community <slug>', 'Community slug for per-community batch scoping')
+  .option('--dry-run', 'Read-only preview: encode calldata, estimate gas, validate net-zero invariant. No PK, no tx, no state mutation. (The default; the flag is accepted for scripts.)')
   .option('--batch-size <n>', 'Cap on users processed this run (server caps at AIRDROP_MAX_RUN_USERS)')
   .action(async (options) => {
     try {

package/lib/commands/airdrop.js

@@ -1,149 +1,47 @@
 /**
- * Airdrop Commands
+ * Airdrop Commands — DRY-RUN ONLY.
  *
- * Admin-facing CLI commands for WS-ADMIN-B1 airdrop migration operations.
- * Per CEO-D-MANUAL-TRIGGER-NO-CRON (2026-04-20), Cloud Scheduler cron was dropped
- * from Round B in favor of operator-invoked manual triggers via this CLI.
+ *   descix airdrop execute-queue [--community <slug>] [--dry-run] [--batch-size <n>]
  *
- * Per CEO-D-B1-FIX-DESIGN-LOCK (2026-04-28), the CLI signature is:
- *   descix airdrop execute-queue --community <slug> [--dry-run | --signer-pk-file <path> --apply]
+ * The apply leg (an admin PK forwarded through the server to Powch's broadcast) is REMOVED,
+ * CLI and server both (CEO 2026-10-10, daita-sam M2 envelope constraint 6): migration batches
+ * execute in daita-sam — act plan + typed confirm + the role holder's own wallet, client-signed.
  *
- *   --community <slug>      REQUIRED for --apply mode (per-community batch scoping). Optional
- *                           in --dry-run mode (returns aggregate-across-communities preview).
- *   --dry-run               Read-only preview path. No PK prompt. No tx. No state mutation.
- *   --apply                 Live execution path. Requires --signer-pk-file or interactive
- *                           prompt-password. Mutually exclusive with --dry-run.
- *   --signer-pk-file <path> File containing the admin's per-invocation signer PK (0x + 64 hex,
- *                           one line). Inline --signer-pk and env vars REJECTED on security
- *                           grounds (process listing leak).
- *
- * Access: requires admin session (platform-admin group membership enforced server-side
- * in `airdrop_execute_queue` via `isPlatformAdmin(user)`). CLI-side, we require an
- * authenticated session (`requireAuth`). The server rejects non-admin users.
- *
- * Safety: the `BATCH_UPDATE_BALANCES_BROADCAST_ENABLED` flag gates the actual on-chain
- * broadcast in Powch. While that flag is false, `airdrop_execute_queue --apply` will assemble
- * batches but Powch returns `stopped_at_broadcast_boundary` — useful for verifying queue
- * assembly without spending MATIC.
+ * Access: requires an authenticated session (`requireAuth`); the server additionally requires
+ * platform admin for the preview.
  */
 
-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';
 import { requireAuth } from '../auth-guard.js';
 
-const PK_REGEX = /^0x[a-fA-F0-9]{64}$/;
-
 /**
- * Read a signer PK from a file. Validates 0x + 64-hex format. Trims trailing whitespace
- * and a trailing newline only — does NOT mutate any other formatting.
- *
- * @param {string} path - Filesystem path to the PK file.
- * @returns {string} Validated PK in `0x` + 64 hex form.
- * @throws {Error} If the file is missing or contents are malformed.
- */
-export function readSignerPkFromFile(path) {
-    let raw;
-    try {
-        raw = fs.readFileSync(path, 'utf8');
-    } catch (e) {
-        throw new Error(`--signer-pk-file: cannot read ${path}: ${e.message}`);
-    }
-    const trimmed = raw.trim();
-    if (!PK_REGEX.test(trimmed)) {
-        // CRITICAL: do not echo the contents (even partial) into the error message.
-        throw new Error(`--signer-pk-file: contents do not match expected 0x + 64 hex format`);
-    }
-    return trimmed;
-}
-
-/**
- * Interactive password prompt (no echo). Reads a line of stdin with terminal echo disabled
- * so the typed PK never appears on screen. Validates 0x + 64-hex format.
- *
- * @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.
-        const originalWrite = stdout.write.bind(stdout);
-        stdout.write = (str, ...rest) => {
-            // Suppress only the echoed characters during the prompt; allow our prompt to render.
-            if (typeof str === 'string' && str.length === 1) return true;
-            return originalWrite(str, ...rest);
-        };
-        stdout.write('Enter signer PK (0x + 64 hex, will not be echoed): ');
-        rl.question('', (answer) => {
-            stdout.write = originalWrite;
-            stdout.write('\n');
-            rl.close();
-            const trimmed = (answer || '').trim();
-            if (!PK_REGEX.test(trimmed)) {
-                reject(new Error('prompt-password: input does not match expected 0x + 64 hex format'));
-                return;
-            }
-            resolve(trimmed);
-        });
-    });
-}
-
-/**
- * Execute the airdrop migration batch queue on the target environment.
+ * Preview (dry-run) the airdrop migration batch queue on the target environment.
  *
  * @param {Object} options
- * @param {string} [options.community] - Community slug for per-community batch scoping.
- *   REQUIRED for --apply mode; optional for --dry-run mode (omitted = aggregate preview).
- * @param {boolean} [options.dryRun] - If true, read-only preview path. Mutually exclusive with --apply.
- * @param {boolean} [options.apply] - If true, live execution path. Requires --signer-pk-file or
- *   interactive prompt-password. Mutually exclusive with --dry-run.
- * @param {string} [options.signerPkFile] - Path to file containing the admin's signer PK.
+ * @param {string} [options.community] - Community slug scoping the preview (omitted = aggregate).
+ * @param {boolean} [options.dryRun] - Accepted for scripts; dry-run is the only mode.
  * @param {number} [options.batchSize] - Optional cap on number of users processed this run.
  * @param {Object} [options.apiClient] - Optional injected API client (for tests).
- * @param {Function} [options.promptFn] - Optional injected interactive PK prompt (for tests).
  */
 export async function executeQueue(options) {
-    const apiClient = options.apiClient || new DeSciXApiClient();
-    await requireAuth(apiClient);
-
-    // Mode resolution: --dry-run and --apply are mutually exclusive. Default is dry-run when
-    // no --apply is provided (read-only is the safer default per CEO-D-B1-FIX-DESIGN-LOCK §4.A).
-    if (options.dryRun && options.apply) {
-        throw new Error('--dry-run and --apply are mutually exclusive (CEO-D-B1-FIX-DESIGN-LOCK Decision 1).');
-    }
-    const isDryRun = options.dryRun === true || (!options.apply && options.dryRun !== false);
-    const isApply = options.apply === true;
-
-    if (isApply && !options.community) {
-        throw new Error('--community <slug> is required for --apply mode (per-community batch scoping per CEO-D-B1-FIX-DESIGN-LOCK Decision 3).');
+    // THE APPLY LEG IS STRUCK — refused before auth, before any network touch (CEO 2026-10-10, daita-sam M2 envelope constraint 6; the server
+    // refuses it too): migration batches execute in daita-sam — act plan + the role holder's own
+    // wallet signs, client-side. No PK ever transits this CLI again.
+    if (options.apply || options.signerPkFile) {
+        throw new Error(
+            'airdrop execute-queue is DRY-RUN ONLY: the apply leg (admin PK forwarded through the ' +
+            'server) is removed. Execute migration batches in daita-sam (act plan + your own wallet).'
+        );
     }
+    const isDryRun = true;
 
-    // Resolve signer PK for --apply mode: --signer-pk-file (default) or interactive prompt fallback.
-    let signerPkHex = null;
-    if (isApply) {
-        if (options.signerPkFile) {
-            signerPkHex = readSignerPkFromFile(options.signerPkFile);
-        } else {
-            const promptFn = options.promptFn || promptSignerPkInteractive;
-            signerPkHex = await promptFn();
-        }
-    }
+    const apiClient = options.apiClient || new DeSciXApiClient();
+    await requireAuth(apiClient);
 
     const params = {};
     if (options.community) params.community = options.community;
-    params.mode = isApply ? 'apply' : 'dry-run';
-    if (signerPkHex) params.signer_pk_hex = signerPkHex;
+    params.mode = 'dry-run';
     if (options.batchSize !== undefined && options.batchSize !== null) {
         const bs = Number(options.batchSize);
         if (!Number.isFinite(bs) || bs <= 0) {
@@ -157,18 +55,13 @@ export async function executeQueue(options) {
     }
 
     const envLabel = process.env.DESCIX_API_URL || '(workspace default)';
-    const mode = isApply ? chalk.green('APPLY') : chalk.yellow('DRY-RUN');
-    console.log(chalk.cyan(`\nairdrop execute-queue [${mode}] target=${envLabel}`));
+    console.log(chalk.cyan(`\nairdrop execute-queue [${chalk.yellow('DRY-RUN')}] target=${envLabel}`));
     if (options.community) {
         console.log(chalk.gray(`  community:        ${options.community}`));
     }
     if (params.batch_size) {
         console.log(chalk.gray(`  batch_size:       ${params.batch_size}`));
     }
-    if (signerPkHex) {
-        // Just confirm a PK is loaded; never echo any portion of it.
-        console.log(chalk.gray(`  signer_pk:        loaded (0x${signerPkHex.slice(2,6)}…${signerPkHex.slice(-4)})`));
-    }
     console.log('');
 
     let response;
@@ -184,12 +77,6 @@ export async function executeQueue(options) {
             console.error(chalk.gray('  Verify your membership in the DESCIX_ADMIN_GROUP Google Group.\n'));
         }
         throw error;
-    } finally {
-        // Belt-and-suspenders: clear local PK var after the single use. We deliberately
-        // do NOT mutate `params.signer_pk_hex` here because the api-client/axios layer may
-        // still be serializing the body, and modern axios keeps no reference after the
-        // request resolves anyway. The local var nulling is the meaningful action.
-        signerPkHex = null;
     }
 
     const result = response?.message || response;
@@ -212,7 +99,7 @@ export async function executeQueue(options) {
         const nzLabel = nz.passes ? chalk.green('PASS') : chalk.red('FAIL');
         console.log(`  net_zero_assertion:       ${nzLabel} (Σ=${nz.sum})`);
         const pbc = result.pre_batch_checks || {};
-        console.log(`  pre_batch_checks:         ${pbc.passes ? chalk.green('PASS') : chalk.red('FAIL — --apply would refuse')}`);
+        console.log(`  pre_batch_checks:         ${pbc.passes ? chalk.green('PASS') : chalk.red('FAIL — an execute would refuse')}`);
         for (const r of (pbc.refusals || [])) {
             console.log(chalk.red(`    ${r.kind} ${r.wallet} (${r.community_id}) holds ${r.held}, needs ${r.required} base units — rows ${(r.pending_ids || []).join(', ')}`));
         }
@@ -226,8 +113,8 @@ export async function executeQueue(options) {
             }
         }
         console.log('');
-        console.log(chalk.gray('No PK supplied. No tx submitted. No DB rows mutated.'));
-        console.log(chalk.gray('Re-run with --apply --signer-pk-file <path> to commit.'));
+        console.log(chalk.gray('No tx submitted. No DB rows mutated.'));
+        console.log(chalk.gray('To execute migration batches: daita-sam (act plan + your own wallet).'));
         console.log('');
         return result;
     }
@@ -254,13 +141,9 @@ export async function executeQueue(options) {
     }
 
     console.log('');
-    if (isApply) {
-        console.log(chalk.gray('Apply complete. See on_chain_log for the trigger audit row.'));
-    } else {
-        console.log(chalk.gray('Dry-run complete. No broadcast attempted. No on_chain_log broadcast row written.'));
-    }
+    console.log(chalk.gray('Dry-run complete. No broadcast attempted. No on_chain_log broadcast row written.'));
     console.log('');
     return result;
 }
 
-export default { executeQueue, readSignerPkFromFile, promptSignerPkInteractive };
+export default { executeQueue };

package/lib/commands/config.js

@@ -34,10 +34,24 @@ export async function show() {
       console.log(chalk.yellow(`   ⚠ This workspace pins ${normalizeOrigin(pinned)} (${environmentNameFor(pinned)}), but ${effective.source} overrides it for this shell.`));
     }
 
-    // v3 single-app: the one app this workspace holds
-    const appId = workspaceConfig.env?.app?.appId;
-    if (appId) {
-      console.log(chalk.white(`   App:           ${appId}`));
+    // v3 single-app: the one app this workspace holds. Every fact a verb can set is shown here,
+    // so the verb's effect is verifiable without hand-reading workspace.json (field, 2026-10-10:
+    // neither the adopted kbId nor env.gateway.port was printed by anything).
+    const app = workspaceConfig.env?.app;
+    if (app?.appId) {
+      console.log(chalk.white(`   App:           ${app.appId}`));
+      if (app.kbId) {
+        console.log(chalk.white(`   KB:            ${app.kbId}`));
+      }
+      if (app.site?.static) {
+        console.log(chalk.white(`   Site:          static ${app.site.static}`));
+      } else if (app.site?.port) {
+        console.log(chalk.white(`   Site:          dev server on port ${app.site.port} (${app.site.protocol || 'https'})`));
+      }
+    }
+    const gatewayPort = workspaceConfig.env?.gateway?.port;
+    if (gatewayPort) {
+      console.log(chalk.white(`   Gateway port:  ${gatewayPort}`));
     }
 
     console.log('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/cli",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "DeSciX CLI and MCP Server - Unified command-line interface for DeSciX platform",
   "repository": {
     "type": "git",

package/templates/scaffolds/microservice/package.json

@@ -11,7 +11,7 @@
     "gen-jwt-secret": "node -e 'console.log(require(\"crypto\").randomBytes(32).toString(\"hex\"))'"
   },
   "dependencies": {
-    "@descix/cloud-core": "^1.2.0",
+    "@descix/cloud-core": "^2.0.0",
     "@descix/platform-api": "^2.0.0",
     "@google-cloud/secret-manager": "^5.0.1",
     "@google-cloud/storage": "^7.7.0",

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

@@ -23,6 +23,11 @@
  * (audience = CORE_API_URL). On Cloud Run that works with no setup. Under local developer ADC,
  * ID-token minting is unsupported without impersonation and this reports a named failure — it
  * does not fall back to anything.
+ *
+ * REGISTRATION TARGETS A RUNNING SERVICE. Before it registers, the bootstrap calls this service's
+ * own /api UNSIGNED and registers only if the mesh guard answers 401 (the mesh startup self-test).
+ * The origin it calls is derived from utils.PORT — the same config value app.js binds — so start
+ * the service (npm run dev) first, in the same checkout, then run this script.
  */
 
 import fs from 'fs';
@@ -51,12 +56,17 @@ async function register() {
         // Used ONLY to name the derived domain in a message. The platform, not this script,
         // owns the derivation.
         siteDomain: utils.SITE_DOMAIN,
+        // The running service's own listener, from the config owner app.js binds (utils.PORT).
+        meshSelfUrl: `http://127.0.0.1:${utils.PORT}`,
     });
 
     const result = await bootstrap.register();
 
     if (result.status !== 'ok') {
         console.error(`[Register] ${manifest.service.name}: registration ${result.status} — ${result.error || result.reason}`);
+        if (String(result.error || result.reason).includes('mesh self-test FAILED')) {
+            console.error('[Register] REMEDY: start the service (npm run dev), then re-run npm run register');
+        }
         process.exit(1);
     }
     console.log(`[Register] SUCCESS: ${manifest.service.name} registered via register_service`);