feat(cli): add safe SDK calls

[altaywtf]

Summary

Add a fail-closed escape hatch for JSON-compatible functions from the pinned put.io TypeScript SDK.

Closes #59.

Changed

• add sdk list with 134 callable paths and 37 reasoned exclusions from SDK v10.0.1
• add sdk call with positional JSON arguments through flags or raw --json
• require exactly one of --dry-run or explicit --execute
• execute through the existing selected/default/environment profile and shared SDK service
• support Effect-returning methods and pure JSON helpers; map void to null and reject non-JSON results
• restrict traversal to enumerable own data properties and reject accessors, prototype paths, cycles, and unknown methods
• exclude runtime-object, binary, auth/config, positional-password, and scalar-token operations that cannot be represented safely
• strictly redact supported keyed credentials and token-bearing scalar URLs in plans and results
• publish the surface through putio describe and refresh the consumer skill docs

Review aids

putio sdk list --output json
→ 134 supported operations, 37 unsupported operations with reasons

putio sdk call --operation files.get --args '[42]' --dry-run --output json
→ {"command":"sdk call","dryRun":true,"request":{"args":[42],"operation":"files.get"}}

PUTIO_CLI_TOKEN=dummy-profile-secret putio sdk call \
  --operation files.getApiDownloadUrl --args '[42]' --execute --output json
→ result URL contains oauth_token=[REDACTED]

flowchart LR
  A["operation + JSON args"] --> B["enumerable own-path resolver"]
  B --> C{"supported?"}
  C -- no --> D["structured rejection with reason"]
  C -- yes --> E{"dry-run or execute"}
  E -- dry-run --> F["strictly redacted plan"]
  E -- execute --> G["profile-authenticated SDK"]
  G --> H["JSON validation and strict redaction"]

Loading

Risks

The SDK does not expose runtime parameter schemas, so arguments remain positional and the SDK performs operation-specific validation during execution. The allow surface is derived from the pinned client, while known unsafe runtime and credential shapes are explicitly excluded; SDK upgrades should review that exclusion policy.

Verification

• pnpm exec vp run verify
• 27 test files, 268 tests passed
• packed CLI discovery: 134 supported / 37 unsupported / zero supported auth.*
• packed dry-run and prototype-path rejection
• packaged scalar URL redaction with dummy profile and explicit OAuth tokens
• autoreview: Codex gpt-5.6-sol, high reasoning, native isolation, web disabled; validated security/contract findings fixed, one scalar-URL claim disproved with runtime evidence, final rerun clean at 0.98 confidence

Complexity

Discovery is O(n) in the pinned SDK object graph. Invocation is O(d) in operation-path depth plus SDK request cost; payload redaction is O(p) in the JSON payload size.

---

Summary by cubic

Adds safe SDK invocation to the CLI with sdk list and sdk call using the pinned @putdotio/sdk. Enables controlled, JSON-only calls with strict dry-run planning, stronger credential redaction, and a correctly scoped operation catalog.

• New Features

  • sdk list: lists JSON-callable SDK functions and marks unsupported ones with reasons.
  • sdk call: runs a selected operation with positional JSON args via --args or --json.
  • Requires exactly one of --dry-run or --execute; treats all operations as potentially mutating; resolves auth from the selected/default profile.
  • Safety: traverses only enumerable own properties; blocks prototype paths, accessors, cycles, and unknown methods; excludes runtime-object, binary, auth/config, positional-password, and scalar-token operations.
  • Output: normalizes void to null; rejects non-JSON results; redacts credential-like fields (snake/camel case) and token-bearing URLs in plans/results.
  • Contract: exposed via putio describe; skill docs updated.

• Bug Fixes

  • Aligned the SDK operation catalog to only advertise enumerable own methods, reject accessors, and exclude secret-bearing namespaces and unsafe operations.

^{Written for commit d11b691. Summary will update on new commits.}

[Copilot]

Pull request overview

This PR adds a “safe SDK escape hatch” to the put.io CLI by introducing discoverable, fail-closed access to JSON-compatible operations from the pinned @putdotio/sdk (v10.0.1). It extends the CLI contract surface (putio describe) and documentation so consumers/agents can reliably list callable operations and invoke them with strict redaction and opt-in execution.

Changes:

• Add putio sdk list (catalogs supported/unsupported SDK operation paths) and putio sdk call (invokes an allowed operation with positional JSON args via flags or --json, requiring exactly one of --dry-run or --execute).
• Introduce safe operation-path resolution and invocation helpers with traversal restrictions (own enumerable data props only; reject prototype paths, accessors, cycles, unknown paths; reject non-JSON results).
• Tighten/extend structured redaction to cover SDK-shaped credential keys and token-bearing scalar URLs; update CLI metadata, tests, and skill/docs to publish the new surface.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/internal/sdk-operations.ts	Adds discovery, resolution, invocation, and JSON-normalization helpers for SDK operations with fail-closed traversal rules.
src/internal/sdk-operations.test.ts	Unit tests for SDK operation discovery, path validation, invocation, and JSON normalization.
src/internal/output.test.ts	Adds tests covering new redaction behavior relevant to SDK payloads and scalar URL redaction.
src/internal/output-service.ts	Expands sensitive-key detection (snake_case + camelCase) and adds strict redaction helper for SDK plans/results.
src/internal/metadata.test.ts	Ensures putio describe command list includes sdk list and sdk call.
src/internal/command-specs.ts	Extends JSON-shape metadata to allow a json item kind (used for positional SDK args).
src/internal/cli-contract.ts	Registers SDK command specs in the CLI contract catalog.
src/i18n/catalog/en.ts	Adds localized descriptions and loader text for SDK commands.
src/commands/sdk.ts	Implements sdk list and sdk call, including execution consent and redacted dry-run planning/output.
src/command-paths.test.ts	Integration tests for sdk call execution/dry-run behavior, consent enforcement, and redaction.
src/cli.ts	Wires the new sdk command into the top-level CLI.
src/cli.test.ts	Verifies argv parsing/contract JSON shape includes sdk call properties.
skills/putio-cli/SKILL.md	Updates consumer skill description to include generic TypeScript SDK tasks.
skills/putio-cli/references/writes.md	Documents sdk call dry-run and execute examples + guardrail reminder.
skills/putio-cli/references/guardrails.md	Adds an explicit guardrail note describing SDK operation-path restrictions and redaction behavior.
skills/putio-cli/references/discovery.md	Documents using sdk list/sdk call when no dedicated command exists.
README.md	Adds user-facing docs for SDK listing/calling, consent model, and safety/redaction behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[cubic-dev-ai]

All reported issues were addressed across 17 files

_{You’re at about 91% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[putio-releaser]

🎉 This PR is included in version 1.5.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀