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
2 changes: 1 addition & 1 deletion docs/en/how-to/script-the-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ stopped at 100 of 752; go on with: ycli tracker issues search 'Queue: DE' --next
$ ycli tracker issues search 'Queue: DE' --limit 100 --next eyJ2IjoxLCJvZiI6… > second.json
```

A token carries its listing: with `--next`, give nothing but the limit and what the command cannot be called without, and that as it was: an argument that differs from the token's is refused by its name, never passed over. A token of a Tracker issue search by a scroll (`--scroll-type`) works once; any other token works again. A listing that can no longer go on exits with `9`: start it again without the token. A run that asks more pages than `YCLI__HTTP__MAX_PAGES` stops there and says so the same way, with a token to go on from. A small first `--limit` sets the size of the pages for every piece after it, so take the first piece as large as the ones you mean to go on with.
A token carries its listing: with `--next`, give nothing but the limit and what the command cannot be called without, and that as it was: an argument that differs from the token's is refused by its name, never passed over. A token of a Tracker issue search by a scroll (`--scroll-type`) works once; any other token works again. It also holds the scroll's own token, so `ycli tracker issues scroll-clear --next TOKEN` releases the scroll before it expires; that token is of no use without your credentials and dies with the scroll. A token goes on only in the organization it was returned in: under another account it is refused, not run. A listing that can no longer go on exits with `9`: start it again without the token. A run that asks more pages than `YCLI__HTTP__MAX_PAGES` stops there and says so the same way, with a token to go on from. A small first `--limit` sets the size of the pages for every piece after it, so take the first piece as large as the ones you mean to go on with.

## Delete without a prompt

Expand Down
9 changes: 5 additions & 4 deletions docs/en/reference/cli/tracker.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,7 @@ $ ycli tracker issues [OPTIONS] COMMAND [ARGS]...
* `update`: Update issue ISSUE_KEY (PATCH...
* `move`: Move issue ISSUE_KEY to another QUEUE...
* `suggest`: Suggest issues whose summary contains...
* `scroll-clear`: Release search-scroll resources (POST...
* `scroll-clear`: Release the scroll of a search before it...
* `update-bulk`: Mass-edit issues (POST /bulkchange/_update).
* `move-bulk`: Mass-move issues to another QUEUE (POST...
* `transition-bulk`: Mass status transition (POST...
Expand Down Expand Up @@ -395,9 +395,10 @@ $ ycli tracker issues suggest [OPTIONS] INPUT

### `ycli tracker issues scroll-clear`

Release search-scroll resources (POST /system/search/scroll/_clear).
Release the scroll of a search before it expires (POST /system/search/scroll/_clear).

Pass each ``--pair scrollId=scrollToken`` from a scrolled ``issues search``.
Only ``issues search --scroll-type`` has something to release; after this its token goes
on nowhere.

**Usage**:

Expand All @@ -407,7 +408,7 @@ $ ycli tracker issues scroll-clear [OPTIONS]

**Options**:

* `--pair TEXT`: scrollId=scrollToken pair to release (repeatable).
* `--next TOKEN`: The token a search by a scroll printed: it names the scroll to release. [required]
* `-o, --format [auto|json|yaml|pretty|csv|markdown|ndjson|name]`: Output format (auto = pretty on a TTY, JSON when piped).
* `-y, --yes`: Do not ask before an operation that deletes data.
* `--dry-run`: Do not send a write: print the request it would send instead. Reads still run, and only the first write of a command is shown. A secret in the body (a password, a token) is printed as ***.
Expand Down
8 changes: 4 additions & 4 deletions docs/en/reference/mcp/tracker.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,14 +148,14 @@ dropped. Returns the moved issue with its new key.

*Clear Tracker search scroll* · idempotent write

Release the server resources of a scrolled issue search (harmless housekeeping).
Release the scroll of an issue search before it expires (harmless housekeeping).

``body`` maps each ``X-Scroll-Id`` to its ``X-Scroll-Token`` from a scrolled
``issues.search`` response. Returns an acknowledgement on success.
Only a search by a scroll (`scroll_type`) has something to release; after this its
`next` goes on nowhere. Returns an acknowledgement on success.

| Parameter | Type | Required | Description |
|---|---|:---:|---|
| `body` | object | yes | A bare ``{scrollId: scrollToken}`` mapping — body for ``POST …/scroll/_clear``. Each entry releases the server resources of one scrolled ``issues.search`` response. |
| `next` | string | yes | The `next` a search by a scroll returned: it names the scroll. |

## `tracker_issues_update_bulk`

Expand Down
2 changes: 1 addition & 1 deletion docs/ru/how-to/script-the-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ stopped at 100 of 752; go on with: ycli tracker issues search 'Queue: DE' --next
$ ycli tracker issues search 'Queue: DE' --limit 100 --next eyJ2IjoxLCJvZiI6… > second.json
```

Токен несёт свой список: с `--next` задают только лимит и то, без чего команду не вызвать, причём таким же, как было: аргумент, который расходится с токеном, получает отказ с его именем, а не отбрасывается молча. Токен поиска задач Трекера с прокруткой (`--scroll-type`) работает один раз; любой другой токен можно использовать повторно. Список, который уже нельзя продолжить, завершается кодом `9`: начните его заново без токена. Запуск, которому нужно больше страниц, чем `YCLI__HTTP__MAX_PAGES`, останавливается на этом пределе и говорит об этом так же, с токеном для продолжения. Маленький первый `--limit` задаёт размер страниц для всех следующих частей, поэтому берите первую часть такой же величины, какими собираетесь продолжать.
Токен несёт свой список: с `--next` задают только лимит и то, без чего команду не вызвать, причём таким же, как было: аргумент, который расходится с токеном, получает отказ с его именем, а не отбрасывается молча. Токен поиска задач Трекера с прокруткой (`--scroll-type`) работает один раз; любой другой токен можно использовать повторно. В нём лежит и собственный токен прокрутки, поэтому `ycli tracker issues scroll-clear --next TOKEN` освобождает прокрутку до истечения её срока; этот токен бесполезен без ваших учётных данных и перестаёт действовать вместе с прокруткой. Токен продолжает список только в той организации, где он получен: под другой учётной записью будет отказ, а не запуск. Список, который уже нельзя продолжить, завершается кодом `9`: начните его заново без токена. Запуск, которому нужно больше страниц, чем `YCLI__HTTP__MAX_PAGES`, останавливается на этом пределе и говорит об этом так же, с токеном для продолжения. Маленький первый `--limit` задаёт размер страниц для всех следующих частей, поэтому берите первую часть такой же величины, какими собираетесь продолжать.

## Удаление без запроса подтверждения

Expand Down
1 change: 1 addition & 0 deletions e2e/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ A log of the CI job is public. When a step fails, the runner prints its command
| `name`, `smoke` | test id; `smoke: true` also runs on pull requests |
| `permanent` | `true` for a scenario that makes what the API cannot delete: it is skipped unless the run is given `--permanent` |
| `steps[].run` | arguments after `ycli -o json --yes`; `${RUN}`, `${TAG}` (the four hex digits of the run's name, for a key that takes no dash), `${QUEUE}`, `${FILES}` (the directory `e2e/files`) and saved names are substituted |
| `steps[].exits` | the exit code the command must end with (default `0`); for a step whose point is a refusal, such as `9` for a listing that can no longer go on. Nothing of its output is read |
| `steps[].output` | `json` (default; a listing is read as its items); `listing` for a listing as it is printed, `{items, truncated, next, total}`; `text` for a command that prints raw text, such as `wiki pages get`; `bytes` for one that prints a file: `expect` then sees `size` and `head`, the first 16 bytes in hex (`"starts_with(head, '89504e47')": true` for a PNG) |
| `steps[].expect` | JMESPath expression → expected value; `unique(array)` is added for duplicate checks |
| `steps[].save` | name → JMESPath expression; later steps use `${name}` |
Expand Down
15 changes: 15 additions & 0 deletions e2e/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -53,9 +53,24 @@ class Step(BaseModel):
"markdown). bytes: it prints a file; `expect` sees `size` and `head` (the first 16 "
"bytes, in hex).",
)
exits: int = Field(
default=0,
description="The exit code the command must end with. Not 0: the refusal is the point "
"of the step (9: a listing that cannot go on), and nothing of its output is read.",
)
expect: dict[str, Any] = Field(default_factory=dict)
save: dict[str, str] = Field(default_factory=dict)
cleanup: str | None = None

@model_validator(mode="after")
def _a_refusal_has_no_output(self) -> Self:
if self.exits and (self.expect or self.save):
raise ValueError(
f"step {self.id}: `exits: {self.exits}` reads nothing of the output, so "
"`expect` and `save` beside it would be passed over"
)
return self

disarms: tuple[str, ...] = ()
reads: tuple[str, ...] = ()
needs: tuple[str, ...] = ()
Expand Down
7 changes: 5 additions & 2 deletions e2e/runner.py
Original file line number Diff line number Diff line change
Expand Up @@ -280,13 +280,16 @@ def _run_step(
outcome = "passed" if completed.exit_code == 0 else "failed"
count = "1 retry" if retries == 1 else f"{retries} retries"
retried.append(f"{scenario.name}/{step.id}: {outcome} after {count} ({step.retry.when})")
if completed.exit_code != 0:
if completed.exit_code != step.exits:
after = f" (after {retries} retries)" if retries else ""
shown = shlex.join(render_command(step.run, named(variables)))
wanted = f", not {step.exits}" if step.exits else ""
raise ScenarioError(
f"{where} `ycli {shown}` exited {completed.exit_code}{after}: "
f"{where} `ycli {shown}` exited {completed.exit_code}{wanted}{after}: "
f"{hidden(completed.stderr or completed.stdout, variables)}"
)
if step.exits:
return # the refusal was the point: there is no output to read
document = _parse(where, step, completed)
for expression, wanted in step.expect.items():
query = render(expression, variables)
Expand Down
16 changes: 16 additions & 0 deletions e2e/scenarios/tracker/issue_options.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,22 @@ steps:
expect:
"length(@)": 1
"[0].key": ${key}
# A scroll taken in pieces, released by its own token, and gone after that. Measured
# 2026-10-10: the clear answers 204 and the next page of a released scroll 403, which the
# CLI tells as a listing that cannot go on (exit 9).
- id: scroll-in-pieces
run: 'tracker issues search "Queue: ${QUEUE}" --scroll-type unsorted --per-scroll 1 --limit 1'
output: listing
expect:
"length(items)": 1
truncated: true
save:
scrolled: next
- id: scroll-clear
run: tracker issues scroll-clear --next ${scrolled}
- id: scroll-released
run: 'tracker issues search "Queue: ${QUEUE}" --next ${scrolled}'
exits: 9
- id: suggest
run: tracker issues suggest "${RUN}" --queue ${QUEUE} --full --fields summary
- id: priorities
Expand Down
Loading
Loading