pandora-cli-skills 1.1.30 → 1.1.32

package/cli/lib/cli_output_service.cjs

@@ -1,3 +1,8 @@
+/**
+ * Create CLI output helpers for success/error envelopes and table output.
+ * @param {{defaultSchemaVersion?: string, CliError: Function}} [options]
+ * @returns {{emitFailure: (outputMode: 'table'|'json', error: any) => void, emitSuccess: (outputMode: 'table'|'json', command: string, data: any, tableRenderer?: Function) => void}}
+ */
 function createCliOutputService(options = {}) {
   const defaultSchemaVersion =
     typeof options.defaultSchemaVersion === 'string' && options.defaultSchemaVersion.trim()
@@ -120,6 +125,7 @@ function createCliOutputService(options = {}) {
   };
 }
 
+/** Public CLI output service factory export. */
 module.exports = {
   createCliOutputService,
 };

package/cli/lib/command_router.cjs

@@ -1,3 +1,9 @@
+/**
+ * Build the top-level command dispatcher for `pandora`.
+ * The returned function routes parsed command/args/context to subcommand handlers.
+ * @param {object} deps
+ * @returns {(command: string|undefined, args: string[], context: {outputMode: 'table'|'json'}) => Promise<void>}
+ */
 function createCommandRouter(deps = {}) {
   const {
     CliError,
@@ -156,7 +162,7 @@ function createCommandRouter(deps = {}) {
   };
 }
 
+/** Public command-router factory export. */
 module.exports = {
   createCommandRouter,
 };
-

package/cli/lib/history_service.cjs

@@ -1,24 +1,17 @@
 const { createIndexerClient } = require('./indexer_client.cjs');
-const { round } = require('./shared/utils.cjs');
+const { round, toOptionalNumber } = require('./shared/utils.cjs');
 
 const USDC_DECIMALS = 6;
 const HISTORY_SCHEMA_VERSION = '1.0.0';
 
-function toNumber(value) {
-  if (value === null || value === undefined || value === '') return null;
-  const numeric = Number(value);
-  if (!Number.isFinite(numeric)) return null;
-  return numeric;
-}
-
 function toUsdc(raw) {
-  const numeric = toNumber(raw);
+  const numeric = toOptionalNumber(raw);
   if (numeric === null) return null;
   return round(numeric / 10 ** USDC_DECIMALS, 6);
 }
 
 function normalizeProbabilityFromYesChance(rawYesChance) {
-  const raw = toNumber(rawYesChance);
+  const raw = toOptionalNumber(rawYesChance);
   if (raw === null) return null;
   if (raw >= 0 && raw <= 1) return raw;
   if (raw > 1 && raw <= 100) return raw / 100;
@@ -29,8 +22,8 @@ function computeYesProbabilityFromMarket(market) {
   const yesChanceProb = normalizeProbabilityFromYesChance(market && market.yesChance);
   if (yesChanceProb !== null && yesChanceProb >= 0 && yesChanceProb <= 1) return yesChanceProb;
 
-  const reserveYes = toNumber(market && market.reserveYes);
-  const reserveNo = toNumber(market && market.reserveNo);
+  const reserveYes = toOptionalNumber(market && market.reserveYes);
+  const reserveNo = toOptionalNumber(market && market.reserveNo);
   if (reserveYes === null || reserveNo === null) return null;
   const total = reserveYes + reserveNo;
   if (!Number.isFinite(total) || total <= 0) return null;
@@ -112,21 +105,21 @@ function buildSummary(items) {
   };
 
   for (const item of items) {
-    const collateral = toNumber(item.collateralAmountUsdc) || 0;
+    const collateral = toOptionalNumber(item.collateralAmountUsdc) || 0;
     summary.grossVolumeUsdc += collateral;
 
     if (item.status === 'open') {
       summary.openCount += 1;
-      summary.unrealizedPnlApproxUsdc += toNumber(item.pnlUnrealizedApproxUsdc) || 0;
+      summary.unrealizedPnlApproxUsdc += toOptionalNumber(item.pnlUnrealizedApproxUsdc) || 0;
     } else if (item.status === 'won') {
       summary.wonCount += 1;
-      summary.realizedPnlApproxUsdc += toNumber(item.pnlRealizedApproxUsdc) || 0;
+      summary.realizedPnlApproxUsdc += toOptionalNumber(item.pnlRealizedApproxUsdc) || 0;
     } else if (item.status === 'lost') {
       summary.lostCount += 1;
-      summary.realizedPnlApproxUsdc += toNumber(item.pnlRealizedApproxUsdc) || 0;
+      summary.realizedPnlApproxUsdc += toOptionalNumber(item.pnlRealizedApproxUsdc) || 0;
     } else {
       summary.closedOtherCount += 1;
-      summary.realizedPnlApproxUsdc += toNumber(item.pnlRealizedApproxUsdc) || 0;
+      summary.realizedPnlApproxUsdc += toOptionalNumber(item.pnlRealizedApproxUsdc) || 0;
     }
   }
 
@@ -141,15 +134,15 @@ function sortHistoryItems(items, orderBy, orderDirection) {
   const dir = String(orderDirection || 'desc').toLowerCase() === 'asc' ? 1 : -1;
   const pick = (item) => {
     if (orderBy === 'pnl') {
-      return toNumber(item.pnlRealizedApproxUsdc) ?? toNumber(item.pnlUnrealizedApproxUsdc) ?? -Infinity;
+      return toOptionalNumber(item.pnlRealizedApproxUsdc) ?? toOptionalNumber(item.pnlUnrealizedApproxUsdc) ?? -Infinity;
     }
     if (orderBy === 'entry-price') {
-      return toNumber(item.entryPriceUsdcPerToken) ?? -Infinity;
+      return toOptionalNumber(item.entryPriceUsdcPerToken) ?? -Infinity;
     }
     if (orderBy === 'mark-price') {
-      return toNumber(item.markPriceUsdcPerToken) ?? -Infinity;
+      return toOptionalNumber(item.markPriceUsdcPerToken) ?? -Infinity;
     }
-    return toNumber(item.timestamp) ?? 0;
+    return toOptionalNumber(item.timestamp) ?? 0;
   };
 
   items.sort((a, b) => {

package/cli/lib/mirror_command_service.cjs

@@ -1,12 +1,27 @@
+/**
+ * Canonical usage string for `mirror go`.
+ * Exported for CLI help rendering and integration tests.
+ * @type {string}
+ */
 const MIRROR_GO_USAGE =
   'pandora [--output table|json] mirror go --polymarket-market-id <id>|--polymarket-slug <slug> [--liquidity-usdc <n>] [--fee-tier 500|3000|10000] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--paper|--dry-run|--execute-live|--execute] [--auto-sync] [--sync-once] [--sync-interval-ms <ms>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--funder <address>] [--usdc <address>] [--oracle <address>] [--factory <address>] [--sources <url...>] [--manifest-file <path>] [--trust-deploy] [--skip-gate] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--with-rules] [--include-similarity] [--min-close-lead-seconds <n>]';
 
+/**
+ * Canonical usage string for `mirror sync`.
+ * Exported for CLI help rendering and integration tests.
+ * @type {string}
+ */
 const MIRROR_SYNC_USAGE =
   'pandora [--output table|json] mirror sync run|once|start --pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--paper|--dry-run|--execute-live|--execute] [--private-key <hex>] [--funder <address>] [--usdc <address>] [--trust-deploy] [--manifest-file <path>] [--skip-gate] [--daemon] [--stream|--no-stream] [--interval-ms <ms>] [--drift-trigger-bps <n>] [--hedge-trigger-usdc <n>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--depth-slippage-bps <n>] [--min-time-to-close-sec <n>] [--iterations <n>] [--state-file <path>] [--kill-switch-file <path>] [--chain-id <id>] [--rpc-url <url>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--webhook-url <url>] [--telegram-bot-token <token>] [--telegram-chat-id <id>] [--discord-webhook-url <url>]';
 
 const INVALID_SUBCOMMAND_MESSAGE =
   'mirror requires subcommand: browse|plan|deploy|verify|lp-explain|hedge-calc|simulate|go|sync|status|close';
 
+/**
+ * Build the `mirror` subcommand dispatcher with lazy-loaded action handlers.
+ * @param {object} deps
+ * @returns {(args: string[], context: {outputMode: 'table'|'json'}) => Promise<any>}
+ */
 function createRunMirrorCommand(deps) {
   const {
     CliError,
@@ -126,6 +141,7 @@ function createRunMirrorCommand(deps) {
   };
 }
 
+/** Public mirror command service exports. */
 module.exports = {
   MIRROR_GO_USAGE,
   MIRROR_SYNC_USAGE,

package/cli/lib/mirror_econ_service.cjs

@@ -1,5 +1,5 @@
 const { computeDistributionHint, normalizeProbability } = require('./mirror_sizing_service.cjs');
-const { round, clamp } = require('./shared/utils.cjs');
+const { round, clamp, toOptionalNumber } = require('./shared/utils.cjs');
 
 const MIRROR_LP_EXPLAIN_SCHEMA_VERSION = '1.0.0';
 const MIRROR_HEDGE_CALC_SCHEMA_VERSION = '1.0.0';
@@ -7,15 +7,8 @@ const MIRROR_SIMULATE_SCHEMA_VERSION = '1.0.0';
 const USDC_DECIMALS = 6;
 const USDC_SCALE = 10 ** USDC_DECIMALS;
 
-function toNumber(value) {
-  if (value === null || value === undefined || value === '') return null;
-  const numeric = Number(value);
-  if (!Number.isFinite(numeric)) return null;
-  return numeric;
-}
-
 function toRawUsdc(usdc) {
-  const numeric = toNumber(usdc);
+  const numeric = toOptionalNumber(usdc);
   if (numeric === null) return null;
   return BigInt(Math.round(numeric * USDC_SCALE));
 }
@@ -26,7 +19,7 @@ function rawUsdcToNumber(rawValue) {
 }
 
 function toPercent(value) {
-  const numeric = toNumber(value);
+  const numeric = toOptionalNumber(value);
   if (numeric === null) return null;
   if (numeric >= 0 && numeric <= 100) return round(numeric, 6);
   return null;
@@ -42,8 +35,8 @@ function resolveDistribution(options = {}) {
   const diagnostics = [];
   const sourceYesPct = toPercent(options.sourceYesPct);
 
-  const explicitYes = toNumber(options.distributionYes);
-  const explicitNo = toNumber(options.distributionNo);
+  const explicitYes = toOptionalNumber(options.distributionYes);
+  const explicitNo = toOptionalNumber(options.distributionNo);
   if (explicitYes !== null || explicitNo !== null) {
     if (explicitYes === null || explicitNo === null) {
       throw new Error('distributionYes and distributionNo must both be provided together.');
@@ -85,8 +78,8 @@ function resolveDistribution(options = {}) {
 }
 
 function deriveYesPctFromReserves(reserveYesUsdc, reserveNoUsdc) {
-  const yesReserve = toNumber(reserveYesUsdc);
-  const noReserve = toNumber(reserveNoUsdc);
+  const yesReserve = toOptionalNumber(reserveYesUsdc);
+  const noReserve = toOptionalNumber(reserveNoUsdc);
   if (yesReserve === null || noReserve === null) return null;
   const total = yesReserve + noReserve;
   if (!Number.isFinite(total) || total <= 0) return null;
@@ -99,8 +92,8 @@ function computeCompleteSetAllocation(options = {}) {
     throw new Error('liquidityUsdc must be a positive number.');
   }
 
-  const distributionYes = toNumber(options.distributionYes);
-  const distributionNo = toNumber(options.distributionNo);
+  const distributionYes = toOptionalNumber(options.distributionYes);
+  const distributionNo = toOptionalNumber(options.distributionNo);
   if (!Number.isInteger(distributionYes) || !Number.isInteger(distributionNo)) {
     throw new Error('distributionYes and distributionNo must be integers.');
   }
@@ -154,9 +147,9 @@ function computeCompleteSetAllocation(options = {}) {
 }
 
 function simulateDirectionalSwap(options = {}) {
-  const reserveYes = Math.max(0, toNumber(options.reserveYesUsdc) || 0);
-  const reserveNo = Math.max(0, toNumber(options.reserveNoUsdc) || 0);
-  const volumeUsdc = Math.max(0, toNumber(options.volumeUsdc) || 0);
+  const reserveYes = Math.max(0, toOptionalNumber(options.reserveYesUsdc) || 0);
+  const reserveNo = Math.max(0, toOptionalNumber(options.reserveNoUsdc) || 0);
+  const volumeUsdc = Math.max(0, toOptionalNumber(options.volumeUsdc) || 0);
   const feeTier = Number.isFinite(Number(options.feeTier)) ? Number(options.feeTier) : 3000;
   const feeRate = clamp(feeTier / 1_000_000, 0, 0.1);
   const side = String(options.side || 'none').toLowerCase();
@@ -215,8 +208,8 @@ function simulateDirectionalSwap(options = {}) {
 
 function solveVolumeForTargetYesPct(options = {}) {
   const targetYesPct = toPercent(options.targetYesPct);
-  const reserveYesUsdc = toNumber(options.reserveYesUsdc);
-  const reserveNoUsdc = toNumber(options.reserveNoUsdc);
+  const reserveYesUsdc = toOptionalNumber(options.reserveYesUsdc);
+  const reserveNoUsdc = toOptionalNumber(options.reserveNoUsdc);
   const feeTier = Number.isFinite(Number(options.feeTier)) ? Number(options.feeTier) : 3000;
 
   if (targetYesPct === null || reserveYesUsdc === null || reserveNoUsdc === null) {
@@ -267,7 +260,7 @@ function solveVolumeForTargetYesPct(options = {}) {
 
 function normalizeVolumeScenarios(value, liquidityUsdc) {
   const fallback = () => {
-    const liq = Math.max(1, toNumber(liquidityUsdc) || 0);
+    const liq = Math.max(1, toOptionalNumber(liquidityUsdc) || 0);
     return [
       round(liq * 0.25, 6),
       round(liq * 0.5, 6),
@@ -277,7 +270,7 @@ function normalizeVolumeScenarios(value, liquidityUsdc) {
   };
 
   if (Array.isArray(value)) {
-    const parsed = value.map((item) => toNumber(item)).filter((item) => Number.isFinite(item) && item >= 0).map((item) => round(item, 6));
+    const parsed = value.map((item) => toOptionalNumber(item)).filter((item) => Number.isFinite(item) && item >= 0).map((item) => round(item, 6));
     return parsed.length ? parsed : fallback();
   }
 
@@ -285,7 +278,7 @@ function normalizeVolumeScenarios(value, liquidityUsdc) {
   if (raw) {
     const parsed = raw
       .split(',')
-      .map((entry) => toNumber(entry.trim()))
+      .map((entry) => toOptionalNumber(entry.trim()))
       .filter((entry) => Number.isFinite(entry) && entry >= 0)
       .map((entry) => round(entry, 6));
     return parsed.length ? parsed : fallback();
@@ -295,13 +288,13 @@ function normalizeVolumeScenarios(value, liquidityUsdc) {
 }
 
 function computeHedgeMetrics(options = {}) {
-  const reserveYesUsdc = toNumber(options.reserveYesUsdc) || 0;
-  const reserveNoUsdc = toNumber(options.reserveNoUsdc) || 0;
-  const excessYesUsdc = toNumber(options.excessYesUsdc) || 0;
-  const excessNoUsdc = toNumber(options.excessNoUsdc) || 0;
-  const hedgeRatio = clamp(toNumber(options.hedgeRatio) || 1, 0, 5);
+  const reserveYesUsdc = toOptionalNumber(options.reserveYesUsdc) || 0;
+  const reserveNoUsdc = toOptionalNumber(options.reserveNoUsdc) || 0;
+  const excessYesUsdc = toOptionalNumber(options.excessYesUsdc) || 0;
+  const excessNoUsdc = toOptionalNumber(options.excessNoUsdc) || 0;
+  const hedgeRatio = clamp(toOptionalNumber(options.hedgeRatio) || 1, 0, 5);
   const polymarketYesPct = toPercent(options.polymarketYesPct);
-  const hedgeCostBps = Math.max(0, toNumber(options.hedgeCostBps) || 35);
+  const hedgeCostBps = Math.max(0, toOptionalNumber(options.hedgeCostBps) || 35);
   const feeTier = Number.isFinite(Number(options.feeTier)) ? Number(options.feeTier) : 3000;
   const feeRate = clamp(feeTier / 1_000_000, 0, 0.1);
 
@@ -444,8 +437,8 @@ function buildMirrorSimulate(options = {}) {
           : 'none';
 
   const feeTier = Number.isFinite(Number(options.feeTier)) ? Number(options.feeTier) : 3000;
-  const hedgeRatio = clamp(toNumber(options.hedgeRatio) || 1, 0, 5);
-  const hedgeCostBps = Math.max(0, toNumber(options.hedgeCostBps) || 35);
+  const hedgeRatio = clamp(toOptionalNumber(options.hedgeRatio) || 1, 0, 5);
+  const hedgeCostBps = Math.max(0, toOptionalNumber(options.hedgeCostBps) || 35);
   const polymarketYesPct = toPercent(
     options.polymarketYesPct !== undefined ? options.polymarketYesPct : (targetYesPct !== null ? targetYesPct : 50),
   );

package/cli/lib/mirror_handlers/browse.cjs

@@ -1,3 +1,9 @@
+/**
+ * Handle `mirror browse` command execution.
+ * Emits help or filtered mirror browse results through CLI output services.
+ * @param {{shared: object, context: object, deps: object}} params
+ * @returns {Promise<void>}
+ */
 module.exports = async function handleMirrorBrowse({ shared, context, deps }) {
   const {
     includesHelpFlag,

package/cli/lib/mirror_handlers/close.cjs

@@ -1,3 +1,9 @@
+/**
+ * Handle `mirror close` command execution.
+ * Builds and emits a close plan payload for dry-run/operator workflows.
+ * @param {{shared: object, context: object, deps: object}} params
+ * @returns {Promise<void>}
+ */
 module.exports = async function handleMirrorClose({ shared, context, deps }) {
   const {
     includesHelpFlag,

package/cli/lib/mirror_handlers/deploy.cjs

@@ -1,3 +1,9 @@
+/**
+ * Handle `mirror deploy` command execution.
+ * Parses deploy flags, invokes deploy service, and emits deploy payloads.
+ * @param {{shared: object, context: object, deps: object}} params
+ * @returns {Promise<void>}
+ */
 module.exports = async function handleMirrorDeploy({ shared, context, deps }) {
   const {
     includesHelpFlag,

package/cli/lib/mirror_handlers/go.cjs

@@ -1,3 +1,9 @@
+/**
+ * Handle `mirror go` command execution.
+ * Orchestrates plan -> deploy -> verify -> optional sync/trade flow and emits a combined payload.
+ * @param {{shared: object, context: object, deps: object, mirrorGoUsage: string}} params
+ * @returns {Promise<void>}
+ */
 module.exports = async function handleMirrorGo({ shared, context, deps, mirrorGoUsage }) {
   const {
     CliError,

package/cli/lib/mirror_handlers/hedge_calc.cjs

@@ -1,3 +1,9 @@
+/**
+ * Handle `mirror hedge-calc` command execution.
+ * Resolves optional market context and emits hedge sizing diagnostics.
+ * @param {{shared: object, context: object, deps: object}} params
+ * @returns {Promise<void>}
+ */
 module.exports = async function handleMirrorHedgeCalc({ shared, context, deps }) {
   const {
     CliError,

package/cli/lib/mirror_handlers/lp_explain.cjs

@@ -1,3 +1,9 @@
+/**
+ * Handle `mirror lp-explain` command execution.
+ * Produces and emits LP inventory/price-balance explanation payloads.
+ * @param {{shared: object, context: object, deps: object}} params
+ * @returns {Promise<void>}
+ */
 module.exports = async function handleMirrorLpExplain({ shared, context, deps }) {
   const {
     includesHelpFlag,

package/cli/lib/mirror_handlers/plan.cjs

@@ -1,3 +1,9 @@
+/**
+ * Handle `mirror plan` command execution.
+ * Resolves source market inputs and emits mirror plan payloads.
+ * @param {{shared: object, context: object, deps: object}} params
+ * @returns {Promise<void>}
+ */
 module.exports = async function handleMirrorPlan({ shared, context, deps }) {
   const {
     includesHelpFlag,

package/cli/lib/mirror_handlers/simulate.cjs

@@ -1,3 +1,9 @@
+/**
+ * Handle `mirror simulate` command execution.
+ * Computes scenario projections and emits simulation payloads.
+ * @param {{shared: object, context: object, deps: object}} params
+ * @returns {Promise<void>}
+ */
 module.exports = async function handleMirrorSimulate({ shared, context, deps }) {
   const {
     includesHelpFlag,

package/cli/lib/mirror_handlers/status.cjs

@@ -1,5 +1,11 @@
 const path = require('path');
 
+/**
+ * Handle `mirror status` command execution.
+ * Reads sync state and optionally enriches with live verification/position diagnostics.
+ * @param {{actionArgs: string[], shared: object, context: object, deps: object}} params
+ * @returns {Promise<void>}
+ */
 module.exports = async function handleMirrorStatus({ actionArgs, shared, context, deps }) {
   const {
     CliError,

package/cli/lib/mirror_handlers/sync.cjs

@@ -1,3 +1,9 @@
+/**
+ * Handle `mirror sync` command execution (`run|once|start|stop|status`).
+ * Orchestrates sync runtime, daemon lifecycle, and structured output emission.
+ * @param {{shared: object, context: object, deps: object, mirrorSyncUsage: string}} params
+ * @returns {Promise<void>}
+ */
 module.exports = async function handleMirrorSync({ shared, context, deps, mirrorSyncUsage }) {
   const {
     CliError,

package/cli/lib/mirror_handlers/verify.cjs

@@ -1,3 +1,9 @@
+/**
+ * Handle `mirror verify` command execution.
+ * Runs pair verification and emits similarity/rules/gate diagnostics.
+ * @param {{shared: object, context: object, deps: object}} params
+ * @returns {Promise<void>}
+ */
 module.exports = async function handleMirrorVerify({ shared, context, deps }) {
   const {
     includesHelpFlag,

package/cli/lib/mirror_service.cjs

@@ -6,16 +6,12 @@ const { resolvePolymarketMarket, fetchDepthForMarket, browsePolymarketMarkets }
 const { findBestPandoraMatch, fetchPandoraMarketContext, verifyMirrorPair, hashRules } = require('./mirror_verify_service.cjs');
 const { deployPandoraAmmMarket } = require('./pandora_deploy_service.cjs');
 const { defaultManifestFile, upsertPair } = require('./mirror_manifest_store.cjs');
-const { round: roundFinite } = require('./shared/utils.cjs');
+const { round } = require('./shared/utils.cjs');
 
 const MIRROR_PLAN_SCHEMA_VERSION = '1.0.0';
 const MIRROR_DEPLOY_SCHEMA_VERSION = '1.0.0';
 const MIRROR_BROWSE_SCHEMA_VERSION = '1.0.0';
 
-function round(value, decimals = 6) {
-  return roundFinite(Number(value), decimals);
-}
-
 function createServiceError(code, message, details = undefined) {
   const err = new Error(message);
   err.code = code;