perp-cli 0.12.1 → 0.12.3

package/dist/commands/agent.js

@@ -1157,6 +1157,56 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
         }
     });
 }
+// ── Pre-venue rollback helpers ───────────────────────────────────────────────
+//
+// When `wallet agent approve <dex>` fails BEFORE the venue accepted the agent
+// (HTTP error, body-code rejection, parse error, network drop), the locally
+// generated `agent-<dex>-<master>` OWS wallet is orphaned in `~/.ows/wallets/`.
+// Retry collides with "wallet name already exists". These helpers auto-delete
+// the orphan and produce an actionable remediation string.
+//
+// Post-venue (persist-only) failures must NOT use these — those leave a
+// status:"partial" record so the user can still revoke venue-side state.
+/**
+ * Best-effort delete of an orphan local OWS wallet. Returns true on success,
+ * false on failure (also logs the failure to stderr per SSOT Rule #2: rollback
+ * failures must not silently mask the original error). The caller threads the
+ * boolean into the user-visible remediation.
+ */
+function tryDeleteOrphanWallet(ows, walletName) {
+    if (!walletName)
+        return false;
+    try {
+        ows.deleteWallet(walletName);
+        return true;
+    }
+    catch (cleanupErr) {
+        // Don't swallow — surface the rollback failure on stderr so the user can
+        // see exactly what's stuck. Original error still propagates from caller.
+        process.stderr.write(`[warn] failed to clean up orphan wallet "${walletName}": ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}\n`);
+        return false;
+    }
+}
+/**
+ * Build an actionable remediation message for pre-venue approve failures.
+ * On clean rollback: tells the user to deposit + retry the canonical
+ * `wallet agent approve <dex> --master <master>` command (no manual steps).
+ * On rollback failure: tells the user to manually delete the orphan wallet
+ * before retrying. The agent address is appended for diagnostic purposes
+ * (some users may need it for the venue UI).
+ */
+function buildPreVenueRemediation(opts) {
+    const { cleanupOk, dex, masterName, agentAddress, hint } = opts;
+    const retry = `perp wallet agent approve ${dex} --master ${masterName}`;
+    const head = cleanupOk
+        ? `Local agent wallet cleaned up. Deposit funds and retry: ${retry}`
+        : `Manual cleanup required — local agent wallet may still exist. Run: perp wallet remove agent-${dex === "hyperliquid" ? "hl" : dex === "pacifica" ? "pac" : "aster"}-${masterName}, then retry: ${retry}`;
+    const parts = [head];
+    if (hint)
+        parts.push(hint);
+    parts.push(`Agent address (diagnostic): ${agentAddress}`);
+    return parts.join(" | ");
+}
 /**
  * Core approve flow: Steps 2-12 (OWS wallet + policy + api-key + EIP-712 + Aster POST + persist).
  * Caller MUST hold the exchange lock before calling this function.
@@ -1233,13 +1283,15 @@ async function runApproveFlow(opts) {
         });
         if (!builderRes.ok) {
             const errText = await builderRes.text().catch(() => "");
-            // Aster builder POST failed — rollback api key (no Aster agent registered yet)
+            // Aster builder POST failed — pre-venue (no Aster agent registered yet).
+            // Rollback both: api key + orphan local OWS wallet.
             if (owsApiKeyId) {
                 try {
                     ows.revokeApiKey(owsApiKeyId);
                 }
                 catch { /* best effort */ }
             }
+            tryDeleteOrphanWallet(ows, agentWalletName);
             throw new PerpError("EXCHANGE_ERROR", `Aster approveBuilder failed (${builderRes.status}): ${errText.slice(0, 200)}`, {
                 remediation: "Check builder address and max-fee-rate parameters",
             });
@@ -1253,6 +1305,7 @@ async function runApproveFlow(opts) {
                 }
                 catch { /* best effort */ }
             }
+            tryDeleteOrphanWallet(ows, agentWalletName);
             const errMsg = builderResp.msg ?? builderResp.message ?? String(builderResp.code);
             throw new PerpError("EXCHANGE_ERROR", `Aster approveBuilder failed: ${errMsg}`, {
                 remediation: "Check builder address and max-fee-rate parameters",
@@ -1307,30 +1360,37 @@ async function runApproveFlow(opts) {
             asterPostSucceeded = true;
         }
         else {
-            // Aster POST body indicated failure — rollback api key (Aster did not register)
+            // Aster POST body indicated failure — pre-venue (Aster did not register).
+            // Rollback both api key + orphan local OWS wallet.
             if (owsApiKeyId) {
                 try {
                     ows.revokeApiKey(owsApiKeyId);
                 }
                 catch { /* best effort */ }
             }
+            const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
             const errMsg = resp.msg ?? resp.message ?? String(resp.code);
             throw new PerpError("APPROVE_PARTIAL", `Aster approveAgent failed: ${errMsg}`, {
-                remediation: `Agent address for cleanup: ${agentEvmAddress}`,
+                remediation: buildPreVenueRemediation({
+                    cleanupOk, dex: "aster", masterName, agentAddress: agentEvmAddress,
+                }),
             });
         }
     }
     else {
-        // HTTP error — rollback api key (Aster did not register)
+        // HTTP error — pre-venue (Aster did not register). Rollback both.
         if (owsApiKeyId) {
             try {
                 ows.revokeApiKey(owsApiKeyId);
             }
             catch { /* best effort */ }
         }
+        const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
         const errText = await agentRes.text().catch(() => "");
         throw new PerpError("APPROVE_PARTIAL", `Aster approveAgent failed (${agentRes.status}): ${errText.slice(0, 200)}`, {
-            remediation: `Agent address for cleanup: ${agentEvmAddress}`,
+            remediation: buildPreVenueRemediation({
+                cleanupOk, dex: "aster", masterName, agentAddress: agentEvmAddress,
+            }),
         });
     }
     // Step 12: Persist agent meta
@@ -1551,13 +1611,26 @@ async function runHlApproveFlow(opts) {
         resp = JSON.parse(text);
     }
     catch {
+        // Pre-venue parse failure — Hyperliquid did NOT register the agent.
+        // Roll back the orphan local OWS wallet so retry doesn't collide with
+        // "wallet name already exists". Errors during cleanup must NOT mask the
+        // original network/parse error (SSOT Rule #2).
+        const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
         throw new PerpError("EXCHANGE_ERROR", `HL exchange API parse error (${agentRes.status}): ${text.slice(0, 200)}`, {
-            remediation: "Check Hyperliquid API status",
+            remediation: buildPreVenueRemediation({
+                cleanupOk, dex: "hyperliquid", masterName, agentAddress: agentEvmAddress,
+                hint: "Check Hyperliquid API status",
+            }),
         });
     }
     if (resp?.status === "err") {
+        // Pre-venue rejection — Hyperliquid did NOT register the agent. Roll
+        // back the orphan local OWS wallet so retry can proceed cleanly.
+        const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
         throw new PerpError("APPROVE_PARTIAL", `HL approveAgent failed: ${typeof resp.response === "string" ? resp.response : JSON.stringify(resp)}`, {
-            remediation: `Agent address for cleanup: ${agentEvmAddress}`,
+            remediation: buildPreVenueRemediation({
+                cleanupOk, dex: "hyperliquid", masterName, agentAddress: agentEvmAddress,
+            }),
         });
     }
     // Step 6: Persist
@@ -1682,24 +1755,36 @@ async function runPacApproveFlow(opts) {
             // Pacifica REST envelope: success === true OR explicit data field
             if (resp.success === false || resp.error) {
                 const errMsg = typeof resp.error === "string" ? resp.error : JSON.stringify(resp);
+                // Pre-venue rejection — Pacifica did NOT register the agent.
+                const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
                 throw new PerpError("APPROVE_PARTIAL", `Pacifica bind_agent_wallet failed: ${errMsg}`, {
-                    remediation: `Agent address for cleanup: ${agentSolanaAddress}`,
+                    remediation: buildPreVenueRemediation({
+                        cleanupOk, dex: "pacifica", masterName, agentAddress: agentSolanaAddress,
+                    }),
                 });
             }
             pacPostSucceeded = true;
         }
         else {
             const errText = await httpRes.text().catch(() => "");
+            // Pre-venue rejection — Pacifica did NOT register the agent.
+            const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
             throw new PerpError("APPROVE_PARTIAL", `Pacifica bind_agent_wallet failed (${httpRes.status}): ${errText.slice(0, 200)}`, {
-                remediation: `Agent address for cleanup: ${agentSolanaAddress}`,
+                remediation: buildPreVenueRemediation({
+                    cleanupOk, dex: "pacifica", masterName, agentAddress: agentSolanaAddress,
+                }),
             });
         }
     }
     catch (httpErr) {
         if (httpErr instanceof PerpError)
             throw httpErr;
+        // Network-level failure — Pacifica did NOT register the agent.
+        const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
         throw new PerpError("APPROVE_PARTIAL", `Pacifica bind_agent_wallet network error: ${httpErr instanceof Error ? httpErr.message : String(httpErr)}`, {
-            remediation: `Agent address for cleanup: ${agentSolanaAddress}`,
+            remediation: buildPreVenueRemediation({
+                cleanupOk, dex: "pacifica", masterName, agentAddress: agentSolanaAddress,
+            }),
         });
     }
     // Step 5: Persist

package/dist/commands/init.d.ts

@@ -14,3 +14,22 @@ export declare function validateKey(chain: "solana" | "evm" | "apikey", key: str
     address: string;
 }>;
 export declare function registerInitCommand(program: Command): void;
+/**
+ * Drive `perp setup` end-to-end without TTY. Required:
+ *   - --passphrase or OWS_PASSPHRASE env (3-path resolver)
+ * Optional:
+ *   - --wallet-name (default: "main")
+ *   - --default-exchange (must be one of pacifica/hyperliquid/lighter/aster)
+ *
+ * Side effects:
+ *   1. Creates an OWS wallet via createWallet(name, passphrase)
+ *   2. Sets settings.owsActiveWallet (if unset) + settings.defaultExchange (if provided)
+ *
+ * Errors are returned as INVALID_PARAMS / PASSPHRASE_REQUIRED — never via
+ * readline. JSON envelope is emitted on stdout when --json is present.
+ */
+export declare function runNonInteractiveSetup(opts: {
+    walletName?: string;
+    passphrase?: string;
+    defaultExchange?: string;
+}): Promise<void>;

package/dist/commands/init.js

@@ -3,6 +3,10 @@ import { createInterface } from "readline";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { resolve } from "path";
 import { loadSettings, saveSettings } from "../settings.js";
+import { PerpError } from "../errors.js";
+import { jsonOk, jsonError, printJson } from "../utils.js";
+import { resolvePassphrase } from "../agent-wallet/passphrase.js";
+import { loadOws } from "../signer/ows-loader.js";
 const PERP_DIR = resolve(process.env.HOME || "~", ".perp");
 const ENV_FILE = resolve(PERP_DIR, ".env");
 // ── .env helpers ──────────────────────────────────────────────
@@ -109,12 +113,23 @@ export async function validateKey(chain, key) {
 }
 // ── Commands ──────────────────────────────────────────────────
 export function registerInitCommand(program) {
-    // ── perp setup (interactive) ──
+    // ── perp setup (interactive + non-interactive) ──
     program
         .command("setup")
         .alias("init")
-        .description("Interactive setup wizard — configure keys & default exchange")
-        .action(async () => {
+        .description("Setup wizard — interactive by default, scriptable with --non-interactive")
+        .option("--non-interactive", "Run without prompts; requires --passphrase or OWS_PASSPHRASE env")
+        .option("--wallet-name <name>", "OWS wallet alias to create (default: 'main')")
+        .option("--passphrase <pp>", "OWS vault passphrase (fallback: OWS_PASSPHRASE env / stdin)")
+        .option("--default-exchange <name>", "Default exchange (pacifica/hyperliquid/lighter/aster)")
+        .action(async (opts) => {
+        // Non-interactive mode: skip all readline prompts, drive everything from
+        // flags + OWS_PASSPHRASE env. This is the agent-friendly onboarding path
+        // (CI / Docker / scripted init) — see plan v3.0 "agent-friendly five
+        // guarantees" P1 (no-prompt) and P3 (passphrase 3-path).
+        if (opts.nonInteractive) {
+            return runNonInteractiveSetup(opts);
+        }
         const rl = createInterface({ input: process.stdin, output: process.stdout });
         try {
             console.log(chalk.cyan.bold("\n  perp-cli Setup Wizard\n"));
@@ -304,3 +319,109 @@ function parseExchangeChoice(input) {
     }
     return [...new Set(exchanges)];
 }
+// ── Non-interactive setup (agent / CI / Docker) ──────────────────────────────
+const VALID_EXCHANGES = ["pacifica", "hyperliquid", "lighter", "aster"];
+/**
+ * Test seam: emit JSON envelopes when the global --json flag is present.
+ * Mirrors the inline pattern used elsewhere (see src/index.ts:87) instead of
+ * wiring isJson() through registerInitCommand for one call site.
+ */
+function setupIsJson() {
+    return process.argv.includes("--json");
+}
+/**
+ * Drive `perp setup` end-to-end without TTY. Required:
+ *   - --passphrase or OWS_PASSPHRASE env (3-path resolver)
+ * Optional:
+ *   - --wallet-name (default: "main")
+ *   - --default-exchange (must be one of pacifica/hyperliquid/lighter/aster)
+ *
+ * Side effects:
+ *   1. Creates an OWS wallet via createWallet(name, passphrase)
+ *   2. Sets settings.owsActiveWallet (if unset) + settings.defaultExchange (if provided)
+ *
+ * Errors are returned as INVALID_PARAMS / PASSPHRASE_REQUIRED — never via
+ * readline. JSON envelope is emitted on stdout when --json is present.
+ */
+export async function runNonInteractiveSetup(opts) {
+    const isJson = setupIsJson();
+    try {
+        // Validate --default-exchange shape early so users hit a precise error
+        // before passphrase resolution.
+        if (opts.defaultExchange !== undefined &&
+            !VALID_EXCHANGES.includes(opts.defaultExchange)) {
+            throw new PerpError("INVALID_PARAMS", `Invalid --default-exchange "${opts.defaultExchange}"`, {
+                remediation: `Use one of: ${VALID_EXCHANGES.join(", ")}`,
+            });
+        }
+        // Resolve passphrase. resolvePassphrase already throws PASSPHRASE_REQUIRED
+        // when stdin is non-TTY and nothing was provided. In TTY mode it returns
+        // null — non-interactive mode must NOT fall back to a prompt.
+        const resolved = await resolvePassphrase({ flag: opts.passphrase });
+        if (resolved === null) {
+            throw new PerpError("PASSPHRASE_REQUIRED", "Non-interactive setup requires a passphrase", {
+                remediation: "Provide --passphrase <pp> or set OWS_PASSPHRASE env var",
+            });
+        }
+        const pp = resolved;
+        const walletName = opts.walletName ?? "main";
+        // Create OWS wallet
+        const ows = loadOws();
+        const w = ows.createWallet(walletName, pp);
+        // Update settings
+        const settings = loadSettings();
+        if (!settings.owsActiveWallet) {
+            settings.owsActiveWallet = walletName;
+        }
+        if (opts.defaultExchange) {
+            settings.defaultExchange = opts.defaultExchange;
+        }
+        saveSettings(settings);
+        if (isJson) {
+            printJson(jsonOk({
+                walletName: w.name,
+                walletId: w.id,
+                accounts: w.accounts,
+                owsActiveWallet: settings.owsActiveWallet,
+                defaultExchange: settings.defaultExchange ?? null,
+                mode: "non-interactive",
+            }));
+            return;
+        }
+        console.log(chalk.cyan.bold("\n  perp-cli Setup (non-interactive) — Done\n"));
+        console.log(`  Wallet:           ${chalk.white.bold(w.name)}`);
+        console.log(`  Active wallet:    ${chalk.cyan(settings.owsActiveWallet)}`);
+        if (settings.defaultExchange) {
+            console.log(`  Default exchange: ${chalk.cyan(settings.defaultExchange)}`);
+        }
+        console.log(chalk.gray(`\n  Vault: ~/.ows/ (AES-256-GCM encrypted)\n`));
+    }
+    catch (err) {
+        if (isJson) {
+            if (err instanceof PerpError) {
+                printJson(jsonError(err.structured.code, err.structured.message, {
+                    ...(err.structured.remediation
+                        ? { details: { remediation: err.structured.remediation } }
+                        : {}),
+                }));
+            }
+            else {
+                const msg = err instanceof Error ? err.message : String(err);
+                printJson(jsonError("UNKNOWN", msg));
+            }
+            process.exitCode = 1;
+            return;
+        }
+        if (err instanceof PerpError) {
+            console.error(chalk.red(`\n  Error [${err.structured.code}]: ${err.structured.message}`));
+            if (err.structured.remediation) {
+                console.error(chalk.gray(`  Remediation: ${err.structured.remediation}\n`));
+            }
+        }
+        else {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(chalk.red(`\n  Error: ${msg}\n`));
+        }
+        process.exitCode = 1;
+    }
+}

package/dist/commands/wallet.js

@@ -324,6 +324,7 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         .description("Generate a new wallet (OWS encrypted vault, multi-chain)")
         .option("--words <count>", "Mnemonic word count (12 or 24)", "12")
         .option("--show-mnemonic", "Display the mnemonic phrase (CAUTION)")
+        .option("--passphrase <pp>", "Master OWS passphrase (fallback: OWS_PASSPHRASE env / stdin)")
         .option("--legacy <chain>", "Legacy mode: generate solana or evm key (unencrypted)")
         .action(async (name, opts) => {
         // Legacy mode for backward compat
@@ -332,8 +333,14 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         }
         const walletName = name || "default";
         try {
+            // Resolve vault passphrase via the standard 3-path resolver (--passphrase
+            // > OWS_PASSPHRASE env > stdin pipe). When stdin is a TTY and nothing was
+            // provided, the resolver returns null; fall back to "" to preserve the
+            // historical "no passphrase" default for interactive use.
+            const { resolvePassphrase } = await import("../agent-wallet/passphrase.js");
+            const pp = (await resolvePassphrase({ flag: opts.passphrase })) ?? "";
             const ows = loadOws();
-            const w = ows.createWallet(walletName, "", parseInt(opts.words));
+            const w = ows.createWallet(walletName, pp, parseInt(opts.words));
             // Set as active wallet
             const { loadSettings: ls, saveSettings: ss } = await import("../settings.js");
             const settings = ls();
@@ -393,7 +400,7 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         .option("--evm <hex>", "EVM (secp256k1) private key — use with --solana to import both curves")
         .option("--solana <key>", "Solana (ed25519) private key — accepts hex (64), base58 (Phantom export), or JSON byte array. Use with --evm to import both curves")
         .option("--mnemonic", "Import as mnemonic phrase instead of private key")
-        .option("--passphrase <pp>", "OWS vault encryption passphrase (default: empty / OWS_PASSPHRASE env)")
+        .option("--passphrase <pp>", "Master OWS passphrase (fallback: OWS_PASSPHRASE env / stdin)")
         .option("--legacy <chain>", "Legacy mode: import to wallets.json (solana or evm)")
         .action(async (privateKey, opts) => {
         // Legacy mode (positional only)
@@ -475,9 +482,12 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
                     throw new Error(`Invalid Solana key — expected hex (64 chars), base58 (Phantom export), or JSON byte array. Inner: ${msg}`);
                 }
             };
-            // Resolve vault passphrase (precedence: --passphrase > OWS_PASSPHRASE env > "")
-            const pp = opts.passphrase
-                ?? (("OWS_PASSPHRASE" in process.env) ? (process.env["OWS_PASSPHRASE"] ?? "") : "");
+            // Resolve vault passphrase via the standard 3-path resolver (--passphrase
+            // > OWS_PASSPHRASE env > stdin pipe). When stdin is a TTY and nothing was
+            // provided, the resolver returns null; fall back to "" to preserve the
+            // historical "no passphrase" default for interactive use.
+            const { resolvePassphrase } = await import("../agent-wallet/passphrase.js");
+            const pp = (await resolvePassphrase({ flag: opts.passphrase })) ?? "";
             let w;
             if (opts.mnemonic) {
                 w = ows.importWalletMnemonic(opts.name, privateKey, pp);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter, Aster",
   "bin": {
     "perp": "dist/index.js",
@@ -59,7 +59,7 @@
     "ink": "^6.8.0",
     "ink-spinner": "^5.0.0",
     "ink-table": "^3.1.0",
-    "lighter-ts-sdk": "^1.0.10",
+    "lighter-ts-sdk": "1.0.10",
     "react": "^19.2.4",
     "tweetnacl": "^1.0.3",
     "ws": "^8.19.0",