feat(cli): add local file upload

[altaywtf]

Summary

Add a safe, profile-aware files upload command backed by the TypeScript SDK.

Closes #54.

Changed

• accept a readable local regular-file path plus optional parent ID and remote filename
• stream the file through Node's file-backed Blob into sdk.files.upload
• support flags, raw JSON input, structured output, and mutation-free dry-runs
• reject unreadable/non-file paths, invalid parent IDs, blank names, and traversal-like remote names before SDK invocation
• expose the command through putio describe and document agent guardrails

Review aids

putio files upload --path README.md --parent-id 42 --dry-run --output json

{
  "command": "files upload",
  "dryRun": true,
  "request": {
    "file_name": "README.md",
    "parent_id": 42,
    "path": "README.md",
    "size": 4740
  }
}

flowchart LR
  A["flags or JSON"] --> B["validate path and destination"]
  B --> C["resolve regular readable file"]
  C --> D{"dry-run?"}
  D -- yes --> E["emit request plan"]
  D -- no --> F["shared authenticated SDK"]
  F --> G["files.upload with file-backed Blob"]

Loading

Risks

The file contents are consumed lazily by the SDK request. The command resolves the path and checks regular-file/read access first, but a file changed after validation can still fail at upload time and is reported through the existing SDK error boundary.

Verification

• pnpm exec vp run verify
• 26 test files, 258 tests passed
• packed binary dry-run against README.md
• packed binary directory rejection with structured error output
• autoreview: Codex gpt-5.6-sol, high reasoning, native isolation, web disabled; two boundary findings fixed, rerun clean at 0.86 confidence

Complexity

O(1) CLI memory for file content; the SDK consumes a file-backed Blob instead of eagerly buffering the file.

---

Summary by cubic

Add putio files upload to send a readable local file to put.io with an optional parent folder and remote filename. Supports dry-run and JSON input, validates inputs up front, and streams via a file-backed Blob to keep memory use low.

• New Features

  • New command: putio files upload
    • Flags: --path, --parent-id, --file-name, --json, --dry-run, --output
  • Validates a readable regular file; rejects directories, unreadable paths, blank names, traversal-like names, and negative parent-id before calling sdk.files.upload
  • Dry-run prints a request plan with file size and does not mutate state
  • Streams the file into sdk.files.upload; adds clear loader and terminal feedback for direct file or queued transfer results
  • Updated README, describe metadata (JSON input schema), i18n strings, and guardrails/writes references

• Bug Fixes

  • Hardened upload validation tests for directories, unreadable files, blank names, invalid parent-id, and SDK failure propagation

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

[Copilot]

Pull request overview

Adds a new write-path to the put.io CLI for uploading a readable local regular file into put.io, with profile-aware auth, input validation, dry-run planning, and describe/agent documentation updates.

Changes:

• Introduces putio files upload (flags + raw JSON input) that validates local path + optional parent ID + optional remote filename, and uploads via sdk.files.upload.
• Adds local upload preparation helper (prepareLocalUpload) plus new input validator (validateLocalPathInput), i18n strings, and terminal rendering for upload results.
• Extends command metadata/describe coverage, command-path mocks, and adds command-path + renderer tests; updates README + skills guardrails/references.

Reviewed changes

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

Show a summary per file

File	Description
src/test-support/command-path-mocks.ts	Adds files.upload SDK mock and reset behavior for command-path tests.
src/internal/metadata.test.ts	Ensures files upload appears in the describe/metadata command list.
src/internal/local-upload.ts	New helper to resolve/validate a local regular file and create a Blob for upload.
src/internal/command.ts	Adds validateLocalPathInput for local path safety checks.
src/i18n/catalog/en.ts	Adds upload-related loader + terminal strings and metadata description.
src/commands/files.ts	Implements files upload, dry-run plan output, upload invocation, and command specs entry.
src/commands/files.test.ts	Tests terminal rendering for upload responses (file vs queued transfer).
src/command-paths.test.ts	Adds end-to-end command-path tests for upload, dry-run, and validation failures.
src/cli.test.ts	Validates describe exposes the expected JSON schema properties for files upload.
skills/putio-cli/references/writes.md	Documents upload usage patterns for write commands and dry-run.
skills/putio-cli/references/guardrails.md	Updates guardrails to mention local upload path validation expectations.
README.md	Adds a user-facing example for putio files upload.

---

💡 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 12 files

_{You’re at about 90% 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.4.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀