@perpscope/percolator-adapter 0.9.0 → 1.0.1

package/README.md

@@ -1,11 +1,18 @@
 # @perpscope/percolator-adapter
 
-Read-only adapter helpers for Solana perps terminals that want PerpScope DTOs without adopting the cockpit UI.
+Read-only CLI and adapter helpers for Solana perps terminals that want PerpScope compatibility checks and DTOs without adopting the cockpit UI.
 
 ```bash
 npm install @perpscope/percolator-adapter
+npx perpscope init perpscope.capture.json
+npx perpscope compat doctor perpscope.capture.json --strict
+npx perpscope compat badge perpscope.capture.json
 ```
 
+`perpscope init` creates a sanitized starter capture. `compat doctor` tells you whether required fields pass and what to map next. `compat badge` gives you a tiny Markdown/JSON summary for READMEs, PRs, and issue handoffs.
+
+Doctor exit codes are CI-ready: `0` means required fields pass, `1` means rejected or required fields missing, and `2` means strict mode found useful-field gaps, unknown fields, or alias suggestions.
+
 ```js
 import {
   buildPercolatorCompatibilityReport,
@@ -72,12 +79,15 @@ The full field-level contract is documented in `../../docs/field-compatibility-m
 ## CLI
 
 ```bash
+perpscope init perpscope.capture.json
 perpscope compat report capture.json
 perpscope compat diff previous.json current.json
-perpscope compat doctor capture.json
+perpscope compat doctor capture.json --strict
 perpscope compat badge capture.json --json
 ```
 
+Doctor exit codes are CI-ready: `0` means required fields pass, `1` means rejected or required fields missing, and `2` means strict mode found useful-field gaps, unknown fields, or alias suggestions.
+
 Try it locally with:
 
 ```bash

package/bin/perpscope.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import {
   buildCompatibilityBadge,
   buildCompatibilityDoctor,
@@ -13,19 +13,104 @@ import {
 } from "../index.js";
 
 const [, , ...args] = process.argv;
+const CAPTURE_TEMPLATE = {
+  label: "My terminal read-only capture",
+  cluster: "mainnet-beta",
+  market: {
+    symbol: "SOL-PERP",
+    base: "SOL",
+    quote: "USDC",
+    slab: "PERCOLAT_SOL_...",
+    program: "Perco1ator111111111111111111111111111111111"
+  },
+  oracle: {
+    priceUsd: 181.61,
+    ageSecs: 2
+  },
+  engine: {
+    currentSlot: 346892118,
+    lastMarketSlot: 346892090,
+    fundingRateBpsPerHour: 0.82,
+    openInterestUsd: 2430000,
+    longOpenInterestUsd: 1320000,
+    shortOpenInterestUsd: 1110000,
+    insuranceUsd: 148000,
+    stressConsumedBps: 118,
+    stressLimitBps: 500
+  },
+  execution: {
+    bestBid: 181.52,
+    bestAsk: 181.71,
+    receipts: [
+      {
+        label: "latest fill",
+        sourceTimestamp: "2026-06-20T13:24:12Z",
+        spreadBps: 10.5,
+        impactBps: 8.4,
+        markout1mBps: 4.2,
+        markout5mBps: -1.7,
+        routeLatencyMs: 132,
+        priorityFeeMicrolamports: 2200
+      }
+    ]
+  },
+  account: {
+    side: "long",
+    positionSize: 420,
+    positionNotionalUsd: 76276.2,
+    collateralUsd: 8400,
+    unrealizedPnlUsd: 3067.2,
+    liquidationPrice: 162.94
+  },
+  history: {
+    fundingSkew: [
+      {
+        sourceTimestamp: "2026-06-20T13:24:00Z",
+        slot: 346892086,
+        fundingBpsPerHour: 0.82,
+        longOpenInterestUsd: 1320000,
+        shortOpenInterestUsd: 1110000,
+        stressConsumedBps: 118,
+        stressLimitBps: 500,
+        oracleAgeSec: 2.1
+      }
+    ]
+  }
+};
 
 function usage() {
   return [
     "Usage:",
+    "  perpscope init [output.json] [--force]",
     "  perpscope compat report <capture.json>",
     "  perpscope compat diff <previous.json> <current.json>",
-    "  perpscope compat doctor <capture.json>",
+    "  perpscope compat doctor <capture.json> [--strict|--json]",
     "  perpscope compat badge <capture.json> [--json|--markdown]",
     "",
     "Read-only only: the adapter rejects wallet, signer, transaction, instruction, order, private key, seed, mnemonic, and API key fields."
   ].join("\n");
 }
 
+function initMessage(path) {
+  return [
+    `Created ${path}`,
+    "",
+    "Next:",
+    `  perpscope compat doctor ${path}`,
+    `  perpscope compat badge ${path}`,
+    "",
+    "Edit the capture with sanitized read-only decoded state before sharing it."
+  ].join("\n");
+}
+
+function initCapture(path = "perpscope.capture.json", options = {}) {
+  if (existsSync(path) && !options.force) {
+    throw new Error(`${path} already exists. Use --force to overwrite.`);
+  }
+  writeFileSync(path, `${JSON.stringify(CAPTURE_TEMPLATE, null, 2)}\n`);
+  return path;
+}
+
 function readCapture(path) {
   if (!path) throw new Error("Missing capture path.");
   return parsePercolatorJson(readFileSync(path, "utf8"));
@@ -56,12 +141,28 @@ function formatDoctor(doctor) {
   return lines.join("\n");
 }
 
+function doctorExitCode(doctor, options = {}) {
+  if (doctor.status === "rejected" || doctor.required.mapped < doctor.required.total) return 1;
+  if (options.strict && (
+    doctor.useful.mapped < doctor.useful.total ||
+    doctor.unknownFields.length ||
+    doctor.aliasSuggestions.length
+  )) return 2;
+  return 0;
+}
+
 function main() {
   const [scope, command, ...rest] = args;
   if (!scope || scope === "--help" || scope === "-h") {
     console.log(usage());
     return;
   }
+  if (scope === "init") {
+    const output = command && !command.startsWith("--") ? command : "perpscope.capture.json";
+    const flags = [command, ...rest].filter(Boolean);
+    console.log(initMessage(initCapture(output, { force: flags.includes("--force") })));
+    return;
+  }
   if (scope !== "compat") throw new Error(`Unknown scope: ${scope}`);
   if (command === "report") {
     const input = readCapture(rest[0]);
@@ -76,7 +177,9 @@ function main() {
   }
   if (command === "doctor") {
     const input = readCapture(rest[0]);
-    console.log(formatDoctor(buildCompatibilityDoctor(buildReport(input), { input })));
+    const doctor = buildCompatibilityDoctor(buildReport(input), { input });
+    console.log(rest.includes("--json") ? JSON.stringify(doctor, null, 2) : formatDoctor(doctor));
+    process.exitCode = doctorExitCode(doctor, { strict: rest.includes("--strict") });
     return;
   }
   if (command === "badge") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perpscope/percolator-adapter",
-  "version": "0.9.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "Read-only Percolator adapter helpers for Solana perps terminals.",
   "main": "./index.js",

package/src/lib/percolator-adapter.js

@@ -1,6 +1,6 @@
 import { normalizeFundingSkewHistory } from "./funding-history.js";
 
-export const PERPSCOPE_ADAPTER_VERSION = "0.9.0";
+export const PERPSCOPE_ADAPTER_VERSION = "1.0.1";
 
 const KEYPAIR_FIELD_PATTERN = /(^|_)(secret|private|keypair|mnemonic|seed|walletPath|wallet)(_|$)/i;
 const HISTORY_COMMAND_KEYS = new Set([