pandora-cli-skills 1.1.36 → 1.1.38

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pandora-cli-skills
 summary: Canonical skill and operator guide for Pandora CLI including mirror, polymarket, resolve, and LP flows.
-version: 1.1.36
+version: 1.1.37
 ---
 
 # Pandora CLI & Skills

package/cli/lib/command_executor_service.cjs

@@ -1,6 +1,11 @@
 const path = require('path');
 const { spawnSync } = require('child_process');
 
+/**
+ * Normalize unknown error-ish values into a loggable message string.
+ * @param {*} value
+ * @returns {string}
+ */
 function coerceErrorMessage(value) {
   if (typeof value === 'string') return value;
   if (value && typeof value.message === 'string') return value.message;
@@ -11,6 +16,12 @@ function coerceErrorMessage(value) {
   }
 }
 
+/**
+ * Parse a candidate JSON envelope from raw process output.
+ * Accepts only objects that include a boolean `ok` field.
+ * @param {string} text
+ * @returns {object|null}
+ */
 function parseEnvelopeCandidate(text) {
   const candidate = String(text || '').trim();
   if (!candidate) return null;
@@ -25,6 +36,12 @@ function parseEnvelopeCandidate(text) {
   return null;
 }
 
+/**
+ * Extract the last syntactically valid top-level JSON object from text.
+ * Useful when diagnostics/noise precede the structured CLI envelope.
+ * @param {string} text
+ * @returns {object|null}
+ */
 function extractLastJsonObject(text) {
   const source = String(text || '');
   if (!source) return null;
@@ -70,6 +87,12 @@ function extractLastJsonObject(text) {
   return parseEnvelopeCandidate(last);
 }
 
+/**
+ * Parse a CLI JSON envelope from stdout/stderr with robust fallbacks.
+ * @param {string} stdout
+ * @param {string} stderr
+ * @returns {object|null}
+ */
 function parseEnvelopeFromOutput(stdout, stderr) {
   const candidates = [stdout, stderr, `${stdout || ''}\n${stderr || ''}`];
   for (const candidate of candidates) {
@@ -81,10 +104,31 @@ function parseEnvelopeFromOutput(stdout, stderr) {
   return null;
 }
 
+/**
+ * @typedef {object} ExecutorEnvelope
+ * @property {boolean} ok
+ * @property {string} [command]
+ * @property {object} [data]
+ * @property {{code: string, message: string, details?: object}} [error]
+ */
+
+/**
+ * @typedef {object} ExecuteJsonCommandResult
+ * @property {boolean} ok
+ * @property {number} exitCode
+ * @property {string} stdout
+ * @property {string} stderr
+ * @property {ExecutorEnvelope} envelope
+ */
+
 /**
  * Build a child-process command executor for JSON-mode CLI invocations.
+ * The executor always prepends `--output json` and normalizes failures into an envelope shape.
  * @param {{cliPath?: string, defaultTimeoutMs?: number, env?: object}} [options]
- * @returns {{executeJsonCommand: (commandArgs: string[], runtime?: {timeoutMs?: number, env?: object}) => {ok: boolean, envelope: object, exitCode: number, stdout: string, stderr: string}}}
+ * @returns {{
+ *   executeJsonCommand: (commandArgs: string[], runtime?: {timeoutMs?: number, env?: object}) => ExecuteJsonCommandResult,
+ *   coerceErrorMessage: (value: *) => string
+ * }}
  */
 function createCommandExecutorService(options = {}) {
   const cliPath =
@@ -94,6 +138,12 @@ function createCommandExecutorService(options = {}) {
   const defaultTimeoutMs = Number.isFinite(options.defaultTimeoutMs) ? Math.max(1_000, Math.trunc(options.defaultTimeoutMs)) : 60_000;
   const baseEnv = options.env && typeof options.env === 'object' ? options.env : process.env;
 
+  /**
+   * Execute the CLI synchronously and parse the envelope from process output.
+   * @param {string[]} commandArgs
+   * @param {{timeoutMs?: number, env?: object}} [runtime]
+   * @returns {ExecuteJsonCommandResult}
+   */
   function executeJsonCommand(commandArgs, runtime = {}) {
     const timeoutMs = Number.isFinite(runtime.timeoutMs)
       ? Math.max(1_000, Math.trunc(runtime.timeoutMs))

package/cli/lib/error_recovery_service.cjs

@@ -39,6 +39,18 @@ function buildPolymarketPreflightCommand(cliName) {
   return `${cliName} polymarket preflight`;
 }
 
+function buildMirrorDeployRetryCommand(cliName) {
+  return `${cliName} mirror deploy --dry-run --plan-file <plan-file>`;
+}
+
+function buildMirrorSyncRetryCommand(cliName) {
+  return `${cliName} mirror sync once --paper --pandora-market-address <address> --polymarket-market-id <id>`;
+}
+
+function buildMcpRestartCommand(cliName) {
+  return `${cliName} mcp`;
+}
+
 /**
  * Build deterministic Next-Best-Action recovery hints for JSON errors.
  * @param {{cliName?: string}} [options]
@@ -83,6 +95,45 @@ function createErrorRecoveryService(options = {}) {
           command: buildPolymarketPreflightCommand(cliName),
           retryable: true,
         };
+      case 'MIRROR_DEPLOY_FAILED':
+      case 'MIRROR_GO_FAILED':
+      case 'MIRROR_GO_VERIFY_FAILED':
+      case 'MIRROR_GO_PREFLIGHT_FAILED':
+        return {
+          action: 'Re-run mirror deploy/verify in dry-run mode',
+          command: buildMirrorDeployRetryCommand(cliName),
+          retryable: true,
+        };
+      case 'MIRROR_SYNC_FAILED':
+      case 'MIRROR_GO_SYNC_FAILED':
+      case 'MIRROR_SYNC_PREFLIGHT_FAILED':
+      case 'MIRROR_SYNC_DAEMON_START_FAILED':
+      case 'MIRROR_SYNC_DAEMON_STOP_FAILED':
+      case 'MIRROR_SYNC_DAEMON_STATUS_FAILED':
+        return {
+          action: 'Run a bounded mirror sync iteration to isolate the failing gate',
+          command: buildMirrorSyncRetryCommand(cliName),
+          retryable: true,
+        };
+      case 'MCP_EXECUTE_INTENT_REQUIRED':
+        return {
+          action: 'Retry MCP tools/call with execute intent enabled',
+          command: buildMcpRestartCommand(cliName),
+          retryable: true,
+        };
+      case 'MCP_LONG_RUNNING_MODE_BLOCKED':
+        return {
+          action: 'Switch to a bounded command variant for MCP',
+          command: `${cliName} mirror sync once --help`,
+          retryable: true,
+        };
+      case 'MCP_TOOL_FAILED':
+      case 'UNKNOWN_TOOL':
+        return {
+          action: 'Inspect available MCP tools and retry with a supported tool name',
+          command: `${cliName} --output json schema`,
+          retryable: true,
+        };
       case 'MISSING_REQUIRED_FLAG':
       case 'MISSING_FLAG_VALUE':
       case 'INVALID_FLAG_VALUE':

package/cli/lib/mcp_tool_registry.cjs

@@ -1,3 +1,38 @@
+/**
+ * @typedef {string|number|boolean|null|undefined|Array<string|number|boolean>} FlagInputValue
+ */
+
+/**
+ * @typedef {{[flagName: string]: FlagInputValue}} ToolFlags
+ */
+
+/**
+ * @typedef {{
+ *   name: string,
+ *   command: string[],
+ *   description: string,
+ *   mutating?: boolean,
+ *   safeFlags?: string[],
+ *   executeFlags?: string[],
+ *   longRunningBlocked?: boolean
+ * }} ToolDefinition
+ */
+
+/**
+ * @typedef {{
+ *   positionals?: Array<string|number|boolean>,
+ *   flags?: ToolFlags,
+ *   intent?: { execute?: boolean }
+ * }} ToolInvocationArgs
+ */
+
+/**
+ * Normalize a flag token to a CLI-prefixed name.
+ * Leaves existing `--foo`/`-f` tokens unchanged and prefixes bare names.
+ *
+ * @param {string} name Raw flag key.
+ * @returns {string} Normalized CLI flag token or empty string.
+ */
 function normalizeFlagName(name) {
   const normalized = String(name || '').trim();
   if (!normalized) return '';
@@ -6,6 +41,13 @@ function normalizeFlagName(name) {
   return `--${normalized}`;
 }
 
+/**
+ * Convert a flag value (including nested arrays) into scalar CLI values.
+ * Booleans are preserved so callers can emit bare switch flags.
+ *
+ * @param {FlagInputValue} value Flag value candidate.
+ * @returns {Array<string|boolean>} Flattened scalar values.
+ */
 function flagValueToStrings(value) {
   if (value === null || value === undefined) return [];
   if (Array.isArray(value)) {
@@ -17,6 +59,13 @@ function flagValueToStrings(value) {
   return [String(value)];
 }
 
+/**
+ * Build argv segments from a JSON-style flags map.
+ * Truthy booleans produce bare switch flags; scalar values produce pairs.
+ *
+ * @param {ToolFlags} flags Flag map where keys may be with/without `--`.
+ * @returns {string[]} CLI argv segment for flags.
+ */
 function buildFlagArgv(flags) {
   if (!flags || typeof flags !== 'object') return [];
   const argv = [];
@@ -37,6 +86,13 @@ function buildFlagArgv(flags) {
   return argv;
 }
 
+/**
+ * Collect normalized flags that are meaningfully provided by the caller.
+ * Used by execution guardrails to detect safe/live mode intent flags.
+ *
+ * @param {ToolFlags} flags Candidate flags object.
+ * @returns {Set<string>} Set of normalized provided flag names.
+ */
 function providedFlagSet(flags) {
   const set = new Set();
   if (!flags || typeof flags !== 'object' || Array.isArray(flags)) return set;
@@ -53,6 +109,12 @@ function providedFlagSet(flags) {
   return set;
 }
 
+/**
+ * Convert a tool definition to MCP descriptor format.
+ *
+ * @param {ToolDefinition} definition Tool registration definition.
+ * @returns {{name: string, description: string, inputSchema: object}} MCP tool descriptor.
+ */
 function toToolDescriptor(definition) {
   return {
     name: definition.name,
@@ -104,6 +166,7 @@ function toToolDescriptor(definition) {
   };
 }
 
+/** @type {ToolDefinition[]} */
 const TOOL_DEFINITIONS = [
   { name: 'help', command: ['help'], description: 'Show top-level command help.' },
   { name: 'version', command: ['version'], description: 'Return the installed CLI version.' },
@@ -276,15 +339,33 @@ const TOOL_DEFINITIONS = [
 
 /**
  * Registry for MCP-exposed Pandora tools with execution guardrails.
- * @returns {{listTools: () => object[], prepareInvocation: (toolName: string, args?: object) => {argv: string[]}, hasTool: (toolName: string) => boolean}}
+ *
+ * @returns {{
+ *   listTools: () => object[],
+ *   prepareInvocation: (toolName: string, args?: ToolInvocationArgs) => {argv: string[]},
+ *   hasTool: (toolName: string) => boolean
+ * }} MCP tool registry API.
  */
 function createMcpToolRegistry() {
   const byName = new Map(TOOL_DEFINITIONS.map((definition) => [definition.name, definition]));
 
+  /**
+   * List all MCP-exposed Pandora tools and their shared JSON contract.
+   *
+   * @returns {object[]} Tool descriptors.
+   */
   function listTools() {
     return TOOL_DEFINITIONS.map((definition) => toToolDescriptor(definition));
   }
 
+  /**
+   * Validate and convert a tool invocation request into Pandora CLI argv.
+   * Applies guardrails for unknown/blocked tools and mutating intent rules.
+   *
+   * @param {string} toolName Registered MCP tool name.
+   * @param {ToolInvocationArgs} [args={}] Invocation payload from MCP client.
+   * @returns {{argv: string[]}} Prepared command argv (without binary prefix).
+   */
   function prepareInvocation(toolName, args = {}) {
     if (toolName === 'launch' || toolName === 'clone-bet') {
       const unsupported = new Error(