fix(cli): validate cache TTL values

[Kewe63]

Summary

Fixes #591.

--cache-ttl was parsed with parseInt() and accepted negative, fractional, missing, non-finite, and unsafe-integer inputs. The option was also absent from the global command schema.

Changes

• parse the complete cache-TTL value instead of accepting numeric prefixes
• require a non-negative safe integer
• reject a valueless --cache-ttl option
• validate malformed TTL values even when --no-cache disables effective cache reads
• return a structured INVALID_PARAMS error before API construction or network activity
• add the option's integer/minimum/maximum/default contract to schema.json
• update cache help text with the numeric contract
• add invalid, missing, conflicting-option, and boundary regressions
• add a patch changeset

This PR intentionally covers only --cache-ttl; the separate --retries fix is tracked in #590.

Regression proof

The final cache-TTL tests applied to current main before the fix:

Test Files  1 failed (1)
Tests       13 failed | 2 passed | 475 skipped (490)

The valid 0 and Number.MAX_SAFE_INTEGER boundaries passed; malformed-value, valueless, --no-cache conflict, and schema assertions failed.

With this fix:

Test Files  1 passed (1)
Tests       16 passed | 475 skipped (491)

Real CLI verification:

$ nansen research smart-money netflow --cache --cache-ttl Infinity
{"success":false,"error":"--cache-ttl must be a non-negative safe integer; received: Infinity","code":"INVALID_PARAMS","status":null}
exit=1

The command ran with a fake API key, temporary HOME, and external network access disabled; no API client/network path was entered.

Full suite, run without the competing parallel suite that had caused unrelated trading-test timeouts:

Test Files  66 passed (66)
Tests       2693 passed | 16 skipped (2709)

Additional checks:

• npm run lint — passed
• git diff --check — passed
• npm pack --ignore-scripts --dry-run — passed; 85 package files, no tests included

Compatibility and risk

• valid existing TTL values retain their behavior
• 0 continues to disable cache reads
• Number.MAX_SAFE_INTEGER is accepted exactly
• malformed values that were previously truncated, defaulted, or allowed now fail early
• no command or API method changes; the schema now documents the option already accepted by the CLI

Checklist

• Tests pass (npm test)
• src/schema.json updated for the corrected global option contract
• README.md updated if new top-level commands or categories were added — none added
• Changeset added (.changeset/validate-cli-cache-ttl.md)

[nansen-pr-reviewer]

pr-reviewer Summary for #1daac2c

✅ No issues found

The code review completed successfully with no findings.

Review effort: 2/5 (Simple)

Summary

This PR is a clean, well-scoped fix for --cache-ttl input validation. The implementation is correct and safe — no findings.

Overall assessment: The new parseNonNegativeSafeIntegerOption function correctly handles every edge case: valueless flags, arrays from repeated options, empty/whitespace strings, negative values, non-integers, unsafe integers, and Infinity/NaN. The check order (flags before options) is consistent with how parseArgs routes a bare --cache-ttl at end-of-args to the flags object, so both the "one valued + one bare" orderings produce the right error message. The schema.json update is accurate, the changeset is correctly typed as a patch for a bug fix, and test coverage is thorough with good boundary and conflict cases. The --retries parseInt path (line 2077) is a pre-existing issue that the PR intentionally defers to #590 — not introduced here.

---

Token usage: 803 input, 3,236 output, 323,689 cache read, 25,530 cache write | Usage Guide

New pushes are reviewed automatically with a 10-minute cooldown between reviews. To request a review at any time, comment @nansen-pr-reviewer re-review.

[nansen-pr-reviewer]

Auto-approved

This PR was automatically approved because:

• Claude recommends approval
• Claude assessed this as a moderate effort change
• The effort level is within the auto-approval threshold of 2
• No high or critical issues were detected
• Review comment contains non-blocking feedback

If you have any concerns, please request a manual review.

[nansen-pr-reviewer]

Auto-approved

This PR was automatically approved because:

• Claude recommends approval
• Claude assessed this as a moderate effort change
• The effort level is within the auto-approval threshold of 2
• No high or critical issues were detected

If you have any concerns, please request a manual review.