pandora-cli-skills 1.1.37 → 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/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(

package/cli/lib/stream_command_service.cjs

@@ -1,6 +1,12 @@
 const { createParseStreamFlags } = require('./parsers/stream_flags.cjs');
 const { graphqlRequest } = require('./indexer_client.cjs');
 
+/**
+ * Validate and return a required function dependency.
+ * @param {object} deps
+ * @param {string} name
+ * @returns {Function}
+ */
 function requireDep(deps, name) {
   if (!deps || typeof deps[name] !== 'function') {
     throw new Error(`createRunStreamCommand requires deps.${name}()`);
@@ -8,6 +14,11 @@ function requireDep(deps, name) {
   return deps[name];
 }
 
+/**
+ * Convert an HTTP(S) indexer URL to WS(S) for stream transport.
+ * @param {string} indexerUrl
+ * @returns {string|null}
+ */
 function toWsUrl(indexerUrl) {
   try {
     const parsed = new URL(String(indexerUrl || ''));
@@ -19,6 +30,11 @@ function toWsUrl(indexerUrl) {
   }
 }
 
+/**
+ * Emit one NDJSON line to stdout with backpressure awareness.
+ * @param {object} payload
+ * @returns {Promise<void>}
+ */
 function writeNdjson(payload) {
   const line = `${JSON.stringify(payload)}\n`;
   if (process.stdout.write(line)) {
@@ -29,6 +45,10 @@ function writeNdjson(payload) {
   });
 }
 
+/**
+ * Serialize stream writes so payloads are emitted in-order.
+ * @returns {(payload: object) => Promise<void>}
+ */
 function createQueuedWriter() {
   let chain = Promise.resolve();
   return (payload) => {
@@ -37,6 +57,14 @@ function createQueuedWriter() {
   };
 }
 
+/**
+ * Create stable stream event metadata shared by tick/diagnostic envelopes.
+ * @param {'prices'|'events'} channel
+ * @param {number} seq
+ * @param {'polling'|'websocket'} sourceTransport
+ * @param {string|null} sourceUrl
+ * @returns {object}
+ */
 function toTickBase(channel, seq, sourceTransport, sourceUrl) {
   return {
     type: 'stream.tick',
@@ -50,6 +78,13 @@ function toTickBase(channel, seq, sourceTransport, sourceUrl) {
   };
 }
 
+/**
+ * Query latest market rows used by the `prices` channel.
+ * @param {string} indexerUrl
+ * @param {{marketAddress?: string|null, chainId?: number|null, limit: number}} options
+ * @param {number} timeoutMs
+ * @returns {Promise<object[]>}
+ */
 async function fetchPriceRows(indexerUrl, options, timeoutMs) {
   const where = {};
   if (options.marketAddress) where.id = options.marketAddress;
@@ -75,6 +110,13 @@ async function fetchPriceRows(indexerUrl, options, timeoutMs) {
   return page;
 }
 
+/**
+ * Query latest liquidity event rows used by the `events` channel.
+ * @param {string} indexerUrl
+ * @param {{marketAddress?: string|null, chainId?: number|null, limit: number}} options
+ * @param {number} timeoutMs
+ * @returns {Promise<object[]>}
+ */
 async function fetchEventRows(indexerUrl, options, timeoutMs) {
   const where = {};
   if (options.marketAddress) where.marketAddress = options.marketAddress;
@@ -102,6 +144,16 @@ async function fetchEventRows(indexerUrl, options, timeoutMs) {
   return page;
 }
 
+/**
+ * Run polling-mode stream loop.
+ * Emits `stream.tick` records for fetched rows and `stream.diagnostic` on fetch failures.
+ * @param {string} indexerUrl
+ * @param {{channel: 'prices'|'events', intervalMs: number}} options
+ * @param {number} timeoutMs
+ * @param {(ms: number) => Promise<void>} sleepMs
+ * @param {(payload: object) => Promise<void>} emitNdjson
+ * @returns {Promise<never>}
+ */
 async function runPollingStream(indexerUrl, options, timeoutMs, sleepMs, emitNdjson) {
   let seq = 0;
   const channelFetcher = options.channel === 'prices' ? fetchPriceRows : fetchEventRows;
@@ -134,6 +186,14 @@ async function runPollingStream(indexerUrl, options, timeoutMs, sleepMs, emitNdj
   }
 }
 
+/**
+ * Attempt websocket streaming and return whether to continue with polling fallback.
+ * Resolves `false` on connection/setup failure or close, rejects on runtime WS errors after open.
+ * @param {string} wsUrl
+ * @param {{channel: 'prices'|'events'}} options
+ * @param {(payload: object) => Promise<void>} emitNdjson
+ * @returns {Promise<boolean>}
+ */
 async function tryWebSocketStream(wsUrl, options, emitNdjson) {
   const { WebSocket } = require('ws');
   let seq = 0;
@@ -202,6 +262,7 @@ async function tryWebSocketStream(wsUrl, options, emitNdjson) {
 
 /**
  * Create runner for `pandora stream`.
+ * In active mode this command emits NDJSON lines continuously, independent of `--output`.
  * @param {object} deps
  * @returns {{runStreamCommand: (args: string[], context: {outputMode: 'table'|'json'}) => Promise<void>}}
  */
@@ -227,6 +288,12 @@ function createRunStreamCommand(deps) {
     isSecureHttpUrlOrLocal,
   });
 
+  /**
+   * Dispatch `stream` subcommands and start websocket/polling event emission.
+   * @param {string[]} args
+   * @param {{outputMode: 'table'|'json'}} context
+   * @returns {Promise<void>}
+   */
   async function runStreamCommand(args, context) {
     const shared = parseIndexerSharedFlags(args);
     if (!shared.rest.length || includesHelpFlag(shared.rest)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pandora-cli-skills",
-  "version": "1.1.37",
+  "version": "1.1.38",
   "description": "Pandora CLI & Skills",
   "main": "cli/pandora.cjs",
   "bin": {