feat(cli): add device approval and watch positions

[altaywtf]

Summary

• add authenticated device-code approval with positional and raw JSON input
• add read, set, and reset commands for file watch positions
• preserve agent-first discovery, dry-run, field selection, redaction, and consumer guidance

Closes #53
Closes #55

Changed

• auth approve <code> maps to the SDK auth.linkDevice operation
• files start-from get|set|reset map to the existing SDK watch-position operations
• write commands support --json and --dry-run; the read supports --fields
• README, describe metadata, translations, tests, and the packaged consumer skill stay aligned

Review aids

Flow	Example	Result
Approve plan	putio auth approve PUTIO1 --dry-run --output json	{"command":"auth approve","dryRun":true,"request":{"code":"PUTIO1"}}
Set position plan	putio files start-from set 42 95 --dry-run --output json	{"command":"files start-from set","dryRun":true,"request":{"file_id":42,"time":95}}
Read contract	putio files start-from get 42 --fields start_from --output json	Returns only start_from

Risks

• live authenticated mutations were not run; SDK endpoint behavior is covered by the pinned SDK contract and CLI command-path tests
• file ids must be positive integers and watch positions must be non-negative whole seconds

Verification

• pnpm exec vp run verify
• packaged dist/bin.mjs describe contract inspection
• packaged positional and raw-JSON dry-runs for approve, set, and reset
• autoreview: Codex gpt-5.6-sol, high effort, native isolation, web disabled; clean with no findings

Complexity

• focused command adapters and schemas over existing SDK operations; no dependency or architecture changes

---

Summary by cubic

Adds auth approve to link a device code with the authenticated account and files start-from get|set|reset to read and manage saved watch positions. Supports positional args or raw --json, with dry-run previews and field selection on reads.

• New Features
  • auth approve <code> calls SDK auth.linkDevice; trims whitespace and rejects codes containing ? or #.
  • files start-from get <file-id> returns { file_id, start_from }; supports --fields.
  • files start-from set <file-id> <seconds> and files start-from reset <file-id> map to SDK watch-position ops; support --json and --dry-run.
  • Input validation: file_id must be a positive integer; seconds must be a non-negative integer.
  • Docs, describe metadata, i18n, and tests updated to match.

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

[Copilot]

Pull request overview

Adds new CLI surfaces to support agent-driven device-code approval and file watch-position (“start-from”) workflows, integrating them with the existing Effect-based command infrastructure, output contracts, and consumer-facing guidance.

Changes:

• Introduce auth approve <code> with --json and --dry-run, mapping to the SDK auth.linkDevice.
• Add files start-from get|set|reset commands with field selection on reads and dry-run + raw JSON input on writes.
• Update command metadata, i18n strings, tests, and consumer reference docs/README to reflect the new command surface.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/commands/auth.ts	Adds auth approve command with schema validation, dry-run planning, and SDK call wiring.
src/commands/files.ts	Adds `files start-from get
src/internal/command-specs.ts	Adds integerArgument helper for command metadata.
src/i18n/catalog/en.ts	Adds terminal messages and metadata descriptions for new commands.
src/internal/metadata.test.ts	Updates describe/metadata expectations to include the new commands.
src/command-paths.test.ts	Adds command-path tests for approval and start-from read/write flows.
src/test-support/command-path-mocks.ts	Extends SDK mock surface for linkDevice and start-from operations.
src/cli.test.ts	Verifies JSON metadata shape includes the new command inputs.
skills/putio-cli/references/auth.md	Documents the new auth approve flow for consumers/agents.
skills/putio-cli/references/reads.md	Documents files start-from get and its field/output contract.
skills/putio-cli/references/writes.md	Documents dry-run/write examples for start-from and approve.
README.md	Adds user-facing examples for device approval and watch-position commands.

---

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

[cubic-dev-ai]

No issues found across 12 files

_{Re-trigger cubic}

[putio-releaser]

🎉 This PR is included in version 1.3.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀