Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .agents/skills/verify-putio-cli/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,5 +48,5 @@ Report the run id, the revision from `run.txt`, and the step directories that ca

- The fixture's device poll counter lives for the whole run: the second device login in one run gets the token on its first poll.
- Never press `o` during device login and never pass `--open`: both call the OS browser opener (on a loopback URL, but still a real window on the user's desktop).
- The sandbox proves CLI behavior against put.io's contract as the fixture models it, not against the live API. Say so when you report.
- tmux sessions are 120×40; terminal boxes wider than that wrap in captures.
- The sandbox proves CLI behavior against the fixture's model of put.io's contract; the live API stays unproven. Say so when you report.
- tmux sessions are 120×40; terminal boxes wider than that wrap in captures, so match on labels.
29 changes: 6 additions & 23 deletions .agents/skills/verify-putio-cli/features/README.md
Original file line number Diff line number Diff line change
@@ -1,34 +1,17 @@
# putio-cli verification map

The maintained source for proving user-facing behavior of the `putio` binary. Read this index, then use the matching feature file as the recipe.
Each feature file is a recipe for [SKILL.md](../SKILL.md)'s `verify.sh`: `.agents/skills/verify-putio-cli/scripts/verify.sh`, run from the repo root. Every recipe starts from a fresh run: `pnpm exec vp run build` after the last source change, `verify.sh start`, and `verify.sh doctor` printing only `ok` lines.

## Baseline preconditions

- `pnpm exec vp run build` ran after the last source change.
- `verify.sh start` created the run and `verify.sh doctor` prints only `ok` lines.
- The scratch config is empty unless a recipe's preconditions say otherwise.
- `verify.sh` means `.agents/skills/verify-putio-cli/scripts/verify.sh`, run from the repo root.

## Driving conventions

- Pipes (`verify.sh cli`) are the agent path; JSON is the default there. The PTY (`verify.sh pty`) is the human path.
- Name each step after the sub-feature ID, so evidence directories map back to this file.
- Commands are literal. Keep flags and quoting unchanged.

## Proof and skip reporting

- Pipe proof: `command.txt`, `stdout.txt`, `stderr.txt`, `exit.txt` from the step directory.
- PTY proof: `screen-<label>.txt` before and after the action, and `pane.txt`.
- Mutation proof: `verify.sh config` or `verify.sh requests`, a second view of the state.
- An unreachable path is reported with its command and the unmet precondition, never as verified through another path.

## Feature entry contract

Each feature file starts with an H1 and one paragraph of user-visible behavior, then exactly four H2s in order: `Sub-features`, `How to get to it (user POV)`, `Driving it with verify.sh`, `Gotchas`.
- A step's name, such as `login-stdin`, names its evidence directory.
- A mutation needs a second view of the state: `verify.sh config` or `verify.sh requests`.
- Report an unreachable path with its command and the unmet precondition.

## Features

- [Auth login](./auth-login.md): token from stdin, hidden prompt, device link, profiles, rejected tokens.
- [Account reads](./account-reads.md): `whoami`, `auth status`, and `files list` with saved or missing auth.
- [SDK call](./sdk-call.md): `sdk call` argument validation, dry run, and execution.
- [Transfers watch](./transfers-watch.md): `transfers watch` until a transfer finishes or the deadline passes.

A new feature file has an H1, one paragraph of user-visible behavior, then `Driving it with verify.sh` and `Gotchas`.
16 changes: 1 addition & 15 deletions .agents/skills/verify-putio-cli/features/account-reads.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,6 @@

A user checks who they are signed in as, where the auth comes from, and lists files. Without auth, each read fails with a structured error that tells the user how to sign in.

## Sub-features

- `whoami-anon` fails with the sign-in hint when no token is configured.
- `whoami` returns account info and the auth source.
- `whoami-fields` narrows output with `--fields`.
- `auth-status` reports the profile, auth method, and config path.
- `files-list` lists the root folder.

## How to get to it (user POV)

- `putio whoami`, optionally `--fields auth`.
- `putio auth status`, optionally `--profile <name>`.
- `putio files list`.

## Driving it with verify.sh

Preconditions: a fresh run. For signed-in steps, first `printf fixture-token | verify.sh cli login-stdin -- auth login --token-stdin --output json`.
Expand All @@ -29,5 +15,5 @@ Preconditions: a fresh run. For signed-in steps, first `printf fixture-token | v

## Gotchas

- The fixture answers `401` to any token but `fixture-token`; a `401` here means the saved token is wrong, not that the CLI is.
- The fixture answers `401` to any token but `fixture-token`; a `401` here means the saved token is wrong.
- `files list` is a streaming read; `--output ndjson` changes the shape, so assert per mode.
19 changes: 0 additions & 19 deletions .agents/skills/verify-putio-cli/features/auth-login.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,6 @@

A user saves put.io credentials as the default auth or a named profile: by piping an existing token, typing it into a hidden prompt, or approving a device code in the browser. The CLI validates a supplied token before saving it and writes the config with mode `600`.

## Sub-features

- `login-stdin` saves a piped token after validating it.
- `login-prompt` reads a token from a hidden prompt in a terminal.
- `login-device` shows an activation code and link, polls, then saves the token.
- `login-profile` saves under `--profile <name>` and keeps other profiles.
- `login-rejected` refuses an invalid token and leaves the config untouched.
- `login-inline-token` refuses a token value on the command line.

## How to get to it (user POV)

- `putio auth login --token-stdin` with the token on stdin.
- `putio auth login --token` in a terminal.
- `putio auth login`, then open the printed link.
- Any of the above with `--profile <name>`.

## Driving it with verify.sh

Preconditions: a fresh run, no config file (`verify.sh config` prints `no config file`).
Expand All @@ -32,6 +16,3 @@ Preconditions: a fresh run, no config file (`verify.sh config` prints `no config
## Gotchas

- `--token` without a TTY fails by design; drive it only through `pty`.
- Never press `o` or pass `--open` during device login: it opens a real browser window.
- The device poll counter is per run; the second device login in a run succeeds on its first poll.
- Some terminal boxes wrap at 120 columns in captures; match on labels, not layout.
11 changes: 0 additions & 11 deletions .agents/skills/verify-putio-cli/features/sdk-call.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,6 @@

`putio sdk call` runs any SDK operation with JSON arguments. It validates the arguments against the operation's input schema before a dry run or a request, so a wrong shape fails locally with the operation and issue named.

## Sub-features

- `sdk-call` executes a read operation and prints its result.
- `sdk-call-dry-run` previews the call without a request.
- `sdk-call-invalid` rejects arguments that do not match the schema, before any request.

## How to get to it (user POV)

- `putio sdk call --operation <name> --args '<json array>'`, with exactly one of `--dry-run` or `--execute`.
- `putio sdk operations` lists the names.

## Driving it with verify.sh

Preconditions: a fresh run, signed in with `printf fixture-token | verify.sh cli login-stdin -- auth login --token-stdin --output json`.
Expand Down
10 changes: 0 additions & 10 deletions .agents/skills/verify-putio-cli/features/transfers-watch.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,6 @@

`putio transfers watch` polls one transfer until it reaches a finished status or the deadline passes, then prints the last transfer it saw and whether it timed out.

## Sub-features

- `watch-finished` returns at once for a finished transfer.
- `watch-deadline` stops at `--timeout-seconds`, even when `--interval-seconds` is longer.
- `watch-ndjson` streams one line per poll.

## How to get to it (user POV)

- `putio transfers watch --id <id>`, optionally `--timeout-seconds` and `--interval-seconds`.

## Driving it with verify.sh

Preconditions: a fresh run, signed in with `printf fixture-token | verify.sh cli login-stdin -- auth login --token-stdin --output json`. The fixture serves transfer `7` as always `DOWNLOADING` and transfer `8` as `COMPLETED`.
Expand Down