perp-cli 0.12.14 → 0.12.17

package/README.md

@@ -218,16 +218,43 @@ Optional: add keys for trading and account data:
 
 ## AI Agent Skill
 
-Install as a skill for Claude Code, Cursor, Codex, Gemini CLI, etc.:
+Drop-in skill for Claude Code, Cursor, Codex, Gemini CLI, and other agent CLIs. Bundles a non-interactive command guide, ops playbook, strategy framework, and reusable shell scripts (preflight, arb monitor, validation) so your agent stops at the right confirmation points and never wedges on interactive wizards.
+
+### Install
 
 ```bash
-# Using npx (recommended)
+# Claude Code — slash command
+/install-skill hypurrquant/perp-cli
+
+# Cursor / Codex / generic agent CLIs — via npx
 npx skills add hypurrquant/perp-cli
 
-# Or via Claude Code slash command
-/install-skill hypurrquant/perp-cli
+# Manual install (any agent that reads a Skills directory)
+git clone https://github.com/hypurrquant/perp-cli.git
+cp -R perp-cli/skills/perp-cli ~/.claude/skills/        # or your CLI's skills dir
 ```
 
+The skill ships inside the npm package (`perp-cli/skills/perp-cli`), so a global install also makes it available locally:
+
+```bash
+npm install -g perp-cli@latest
+ls "$(npm root -g)/perp-cli/skills/perp-cli"
+```
+
+### What's in the skill
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Top-level agent guide — rules, workflows, examples |
+| `references/commands.md` | Full non-interactive command reference (every group) |
+| `references/agent-operations.md` | Setup flows, idempotency, error handling, common mistakes |
+| `references/strategies.md` | Funding-arb decision framework + risk management |
+| `scripts/preflight.sh` | Install + wallet + connectivity + risk readiness check |
+| `scripts/arb-monitor.sh` | Live monitor for open arb positions |
+| `scripts/spot-perp-scan.sh` | Scan spot+perp opportunities with balance context |
+| `scripts/funding-analysis.sh` | Cross-exchange funding overview / per-symbol drilldown |
+| `scripts/validate-arb.sh` | Pre-execution validation (price / balance / risk / dry-run) |
+
 See [`skills/perp-cli/SKILL.md`](skills/perp-cli/SKILL.md) for the full agent guide.
 
 ## Agent-First CLI Design

package/dist/commands/account.js

@@ -613,9 +613,21 @@ export function registerAccountCommands(program, getAdapter, isJson, getAdapterF
             p = pac(adapter);
         }
         catch (err) {
+            // pac() throws a generic "Market settings are only available on
+            // Pacifica" — replace with a TWAP-specific message so HL/LT/Aster
+            // users see what's actually unsupported. Codex QA matrix #1 fix.
+            const orig = err instanceof Error ? err.message : String(err);
+            const msg = orig.includes("only available on Pacifica")
+                ? "TWAP orders are a Pacifica-only feature."
+                : orig;
             if (isJson())
-                return printJson(jsonError("EXCHANGE_ERROR", err instanceof Error ? err.message : String(err)));
-            console.error(chalk.red(`\n  ${err instanceof Error ? err.message : String(err)}\n`));
+                return printJson(jsonError("NOT_SUPPORTED", msg, {
+                    details: { remediation: "Use 'perp -e pacifica account twap-orders'" },
+                }));
+            console.error(chalk.red(`\n  ${msg}\n`));
+            if (orig.includes("only available on Pacifica")) {
+                console.error(chalk.gray(`  Run: perp -e pacifica account twap-orders\n`));
+            }
             return;
         }
         const sdk = p.sdk;

package/dist/index.js

@@ -49,6 +49,7 @@ import { registerInitCommand } from "./commands/init.js";
 import { registerAlertCommands } from "./commands/alerts.js";
 import { loadSettings, saveSettings } from "./settings.js";
 import { setSharedApiNetwork } from "./shared-api.js";
+import { LANDING_EXCHANGES, asterAgentMissing as getAsterAgentMissing, renderLandingExchangeLine } from "./landing.js";
 const _require = createRequire(import.meta.url);
 const _pkg = _require("../package.json");
 const program = new Command();
@@ -615,11 +616,16 @@ if (rawArgs.length === 0 || (!hasSubcommand && !rawArgs.includes("-h") && !rawAr
             }
             else {
                 // Configured — show exchange status + balance
-                const EX_NAMES = ["pacifica", "hyperliquid", "lighter", "aster"];
-                const exLabel = (e) => e === "pacifica" ? "Pacifica" : e === "hyperliquid" ? "Hyperliquid" : e === "lighter" ? "Lighter" : "Aster";
                 // Ping + balance in parallel (with 5s timeout to keep landing fast)
                 const withTimeout = (p, ms) => Promise.race([p, new Promise((_, rej) => setTimeout(() => rej(new Error("timeout")), ms))]);
-                const statusResults = await Promise.allSettled(EX_NAMES.map(async (ex) => {
+                // Aster venue ships only signed account endpoints — no public
+                // address-based balance query exists (HL/PAC/LT all do). So when
+                // a user has an env-PK but no Aster agent, every getBalance()
+                // call throws NOT_SUPPORTED at venue. Detect that case here so
+                // landing can surface a clear "agent required" hint instead of
+                // a generic dash.
+                const asterAgentMissing = getAsterAgentMissing();
+                const statusResults = await Promise.allSettled(LANDING_EXCHANGES.map(async (ex) => {
                     try {
                         const adapter = await withTimeout(getAdapterForExchange(ex), 5000);
                         const [balance, positions] = await withTimeout(Promise.all([adapter.getBalance(), adapter.getPositions()]), 5000);
@@ -668,10 +674,7 @@ if (rawArgs.length === 0 || (!hasSubcommand && !rawArgs.includes("-h") && !rawAr
                     if (r.status !== "fulfilled")
                         continue;
                     const s = r.value;
-                    const icon = s.ok ? chalk.green("●") : chalk.red("○");
-                    const eq = s.ok ? chalk.white(`$${Number(s.equity).toLocaleString("en", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`) : chalk.gray("—");
-                    const pos = s.ok && s.positions > 0 ? chalk.yellow(` ${s.positions} pos`) : "";
-                    console.log(`    ${icon} ${chalk.cyan(exLabel(s.exchange).padEnd(14))} ${eq}${pos}`);
+                    console.log(renderLandingExchangeLine(s, asterAgentMissing));
                     if (s.ok) {
                         totalEquity += s.equity;
                         totalPositions += s.positions;
@@ -705,7 +708,21 @@ else {
         const msg = err instanceof Error ? err.message : String(err);
         if (isJson()) {
             const { jsonError } = await import("./utils.js");
-            console.log(JSON.stringify(jsonError("FATAL", msg)));
+            const { PerpError } = await import("./errors.js");
+            // Preserve typed PerpError code + remediation through the top-level
+            // catch (Rule #2: stay loud, keep semantic envelope).
+            if (err instanceof PerpError) {
+                const s = err.structured;
+                console.log(JSON.stringify(jsonError(s.code, s.message, {
+                    status: s.status,
+                    retryable: s.retryable,
+                    retryAfterMs: s.retryAfterMs,
+                    remediation: s.remediation,
+                })));
+            }
+            else {
+                console.log(JSON.stringify(jsonError("FATAL", msg)));
+            }
         }
         else {
             console.error(chalk.red(msg));

package/dist/landing.d.ts

@@ -0,0 +1,9 @@
+export declare const LANDING_EXCHANGES: readonly ["pacifica", "hyperliquid", "lighter", "aster"];
+export type LandingExchangeStatus = {
+    exchange: typeof LANDING_EXCHANGES[number];
+    ok: boolean;
+    equity: number;
+    positions: number;
+};
+export declare function asterAgentMissing(): boolean;
+export declare function renderLandingExchangeLine(status: LandingExchangeStatus, asterAgentMissing: boolean): string;

package/dist/landing.js

@@ -0,0 +1,20 @@
+import chalk from "chalk";
+import { listAgents } from "./agent-wallet/store.js";
+export const LANDING_EXCHANGES = ["pacifica", "hyperliquid", "lighter", "aster"];
+function exchangeLabel(exchange) {
+    return exchange === "pacifica" ? "Pacifica" : exchange === "hyperliquid" ? "Hyperliquid" : exchange === "lighter" ? "Lighter" : "Aster";
+}
+export function asterAgentMissing() {
+    return listAgents("aster").length === 0;
+}
+export function renderLandingExchangeLine(status, asterAgentMissing) {
+    if (!status.ok && status.exchange === "aster" && asterAgentMissing) {
+        return `    ${chalk.yellow("⚙")} ${chalk.cyan(exchangeLabel(status.exchange).padEnd(14))} ${chalk.yellow("agent required")} ${chalk.gray("→ perp wallet agent approve aster")}`;
+    }
+    const icon = status.ok ? chalk.green("●") : chalk.red("○");
+    const equity = status.ok
+        ? chalk.white(`$${Number(status.equity).toLocaleString("en", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`)
+        : chalk.gray("—");
+    const positions = status.ok && status.positions > 0 ? chalk.yellow(` ${status.positions} pos`) : "";
+    return `    ${icon} ${chalk.cyan(exchangeLabel(status.exchange).padEnd(14))} ${equity}${positions}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.12.14",
+  "version": "0.12.17",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter, Aster",
   "bin": {
     "perp": "dist/index.js",