direct-cli 0.4.3__tar.gz → 0.5.1__tar.gz

{direct_cli-0.4.3 → direct_cli-0.5.1}/.github/workflows/quality.yml

@@ -30,4 +30,6 @@ jobs:
         run: mypy .
 
       - name: Run offline tests
-        run: pytest -m "not integration"
+        # Offline default comes from pyproject addopts (skips the live-network
+        # markers). integration_write stays in — it replays VCR cassettes offline.
+        run: pytest

{direct_cli-0.4.3 → direct_cli-0.5.1}/.gitignore

@@ -56,3 +56,6 @@ Thumbs.db
 *.log
 *.bak
 *.orig
+
+# Local measurement artifacts (regenerated via scripts/measure_criteria_limits.py)
+scripts/_criteria_limits_results.json

{direct_cli-0.4.3 → direct_cli-0.5.1}/CHANGELOG.md

@@ -1,7 +1,468 @@
 # Changelog
 
+## Unreleased
+
+**Added — `direct masters archive` (#633):**
+
+- New command that archives a Мастер кампаний. Live recon confirmed Yandex's
+  UI has **no separate "delete" action** for it — neither the campaigns
+  grid's row menu nor the overview page's own menu has a "Удалить" item,
+  only "Архивировать" (issue #633 comment documents the DOM structure
+  found live). This is the closest thing to delete Мастер кампаний has.
+- Clicks the overview page's "⋮" menu then "Архивировать" — both selected
+  via stable, confirmed-live `data-testid` attributes
+  (`CampaignHeader.MenuTrigger`/`CampaignHeader.Menu.archive`), unlike
+  `suspend`/`resume`'s best-effort text-matched candidate buttons.
+- Verifies success by re-reading the campaigns grid (`fetch_masters_list`)
+  and confirming the status actually became `ARCHIVED`, rather than
+  trusting the click alone. Idempotent: an already-archived campaign is a
+  no-op warning, not an error.
+- **Irreversible from this CLI** — there is no `masters unarchive`.
+  Classified `DANGEROUS` in `direct_cli/smoke_matrix.py` (same as
+  `suspend`/`resume`): Мастер кампаний has no API and thus no `--sandbox`
+  isolation, so any exercise of this command hits a real account.
+
+**Added — `direct masters update` (#631, Этап A):**
+
+- New command that edits a single Мастер кампаний's settings page
+  (`/wizard/campaigns/{id}/edit/`). This first stage covers exactly three
+  simple scalar fields: `--weekly-budget` (integer, Недельный бюджет),
+  `--promotion-goal` (`max-conversions`/`max-clicks`, Цель продвижения), and
+  `--directs-helps`/`--no-directs-helps` (Директ помогает — auto-apply
+  Yandex recommendations). At least one flag is required.
+- Live investigation (see `tests/fixtures/masters_wizard_edit_stage_a.html`)
+  found the edit page is a single form with one "Сохранить кампанию" button
+  — there is no per-section independent save. `update_master` therefore
+  submits the whole form on every call; fields not passed as flags are left
+  untouched (their current on-page value is preserved simply by never
+  filling/toggling their input).
+- New `direct_cli/browser/masters.py` functions: `update_master` plus
+  private `_set_weekly_budget`/`_set_directs_helps`/`_set_promotion_goal`
+  setters. Each field setter follows the module's existing "click, then
+  verify the change actually took effect" convention (`_suspend_or_resume`)
+  rather than trusting a click alone. `update_master` itself also verifies:
+  after clicking save it re-navigates to the edit page and re-reads every
+  requested field (`_verify_saved`), raising `BrowserSessionError` on any
+  mismatch instead of reporting a false success — so a click that doesn't
+  actually persist (rejected validation, session/redirect failure) is a
+  hard error, not a silent success.
+- `_click_save` and `_set_promotion_goal`'s option click use
+  `get_by_role(..., exact=True)`, not a substring `get_by_text` match — an
+  exact accessible-name match, scoped to the actual button/option role,
+  avoids clicking an ancestor container whose text merely contains the
+  target label.
+- Later Этап (B/C/D) fields — headline/text variant lists, sitelinks,
+  audience, Metrika counters/goals, budget adaptation, images/video — are
+  tracked separately in issue #631 and not implemented here.
+- No `--sandbox` equivalent exists for this browser-driven mutation (same
+  rationale as `masters suspend`/`resume`, #630) — classified `DANGEROUS` in
+  `direct_cli/smoke_matrix.py` and documented as manual-only in
+  `scripts/test_dangerous_commands.sh`.
+
+**Added — `direct masters add` (#632):**
+
+- New command that creates a brand-new "Конверсии и трафик" Мастер кампаний
+  by driving the same multi-field create wizard a human uses in the browser
+  (`https://direct.yandex.ru/wizard/campaigns/new/`) — Мастер кампаний has no
+  API surface at all, same as `list`/`get`/`suspend`/`resume`.
+- Live recon (issue #632 step 0, see
+  `tests/fixtures/masters_wizard_create.html`) found the create flow is NOT
+  the multi-page "Далее" wizard the issue originally assumed: it is one
+  micro-step (a landing-page URL field with client-side format validation)
+  followed by a single long form, terminating in two buttons — "Запустить
+  кампанию" (launch) and "Сохранить как черновик" (save as draft) — instead
+  of `masters update`'s one "Сохранить кампанию".
+- `--headline`/`--text`/`--region` are required (repeat the flag for
+  multiple values) even though Yandex's own wizard can auto-generate
+  headlines/texts by scanning the landing page — `add` refuses to silently
+  publish AI-written ad copy the caller never reviewed, given there is no
+  sandbox or rollback for Мастер кампаний mutations.
+- `--weekly-budget` is optional. `--draft`/`--launch` (default `--launch`)
+  selects which terminal button is clicked.
+- **NOT idempotent**: running this twice with the same arguments creates a
+  *second* campaign, not an update to the first — documented prominently in
+  the command's own `--help` and in the README, per the issue's explicit
+  "Риски" requirement.
+- Classified `DANGEROUS` in `direct_cli/smoke_matrix.py` and documented as
+  manual-only (verify with `--draft` first) in
+  `scripts/test_dangerous_commands.sh` — no `--sandbox` equivalent exists for
+  Мастер кампаний.
+- After clicking the terminal button, re-reads the headline/text/budget
+  fields to confirm the form actually reflects what was requested
+  (`_verify_created`) rather than trusting the click alone — ported from
+  `masters update`'s `_verify_saved` pattern (issue #631 review finding).
+  Dropdown/option clicks (`_fill_landing_url`'s "Далее", `_set_region`'s
+  suggestion, `_click_terminal_button`'s launch/draft button) use
+  `get_by_role(..., exact=True)`, not a substring `get_by_text` match — same
+  fix applied to `update_master`'s `_click_save`/`_set_promotion_goal`, to
+  avoid clicking an ancestor container whose text merely contains the
+  target label.
+- Not end-to-end live-verified: step 0 recon was deliberately read-only (no
+  campaign was created or saved during recon) — see the browser module's
+  docstring for what remains to be confirmed against a real account before
+  relying on this in production. In particular, `_verify_created` cannot
+  re-navigate and reload the way `_verify_saved` does (the post-click
+  destination URL is unconfirmed), so it only re-reads the current page
+  immediately after the click — a strictly weaker check pending a live
+  pass.
+
+**Added — `direct masters login` (#635):**
+
+- New interactive command that opens a visible browser window on a
+  persistent Chromium profile owned by the CLI
+  (`~/.direct-cli/chrome-profile/` by default, overridable with
+  `--profile-dir`). Log in by hand once via Yandex Passport; the command
+  polls until the session is confirmed authenticated (or times out after
+  `--timeout` seconds, default 300) and exits.
+- Independent of `direct playwright login`/the macOS Keychain entirely —
+  this never touches the user's real Chrome profile, so it works
+  identically on macOS/Linux/Windows at the cost of a one-time manual login
+  instead of a transparent cookie copy.
+- `direct masters` (`list`/`get`/`suspend`/`resume`) prefers this persistent
+  profile automatically whenever it exists, ahead of the saved
+  `playwright login` session — see the new tier 1.5 in
+  `direct_cli/commands/masters.py`'s session-resolution docstring.
+- Interactive by design (blocks waiting for a human); classified
+  `DANGEROUS` in `direct_cli/smoke_matrix.py` and documented as
+  manual-only in `scripts/test_dangerous_commands.sh` — it cannot run in
+  any automated smoke tier.
+- The profile directory is chmod'd `0700` (it holds a live Yandex session in
+  plaintext-readable cookies).
+- New `direct masters logout` deletes the profile — the only way to revoke
+  the on-disk session short of a manual `rm -rf`. A no-op with a warning
+  (not an error) if no profile exists. Also classified `DANGEROUS`
+  (local credential-store mutation, same category as `auth login`/`auth
+  use`).
+- `masters login` refuses to run without a terminal. It waits for a human,
+  so in CI or a script it now fails immediately with a clear message instead
+  of blocking for the full `--timeout` on a browser window nobody can see.
+- `masters login` polls for completion on a separate page instead of the
+  one the user is typing into. Previously the loop navigated the visible
+  Passport tab to the grid once a second, wiping a half-filled login form
+  or a pending 2FA prompt out from under the user.
+- `masters login` refuses a `--profile-dir` that already exists without the
+  CLI's own marker. Previously the marker was planted into whatever directory
+  was named — so `masters login --profile-dir ~` marked the home directory as
+  CLI-owned, and `masters logout` on the same path then accepted that marker
+  as authorization to `shutil.rmtree` it. A failed login armed it just the
+  same, since the marker was written before Chromium even launched.
+- `masters login --profile-dir X` is now honoured by the read commands. The
+  chosen directory is recorded, and `list`/`get`/`suspend`/`resume` resolve
+  the profile through that record. Previously tier 1.5 looked only at the
+  default location and passed no directory through, so a custom login path
+  reported "Login confirmed" and was then silently ignored by every read —
+  falling back to the Keychain the flag exists to avoid. `masters logout`
+  clears the record along with the profile.
+- The recorded profile path is stored and read as absolute. A relative value
+  would have been re-resolved against whatever directory a later command ran
+  from, so `masters logout` acted on a different profile depending on where
+  the user stood.
+- `masters` commands route through the persistent profile only when it holds
+  an actual browser session, not merely when the directory exists. An aborted
+  `masters login` leaves an empty profile behind; treating that as usable cost
+  a wasted browser launch on every later command and bypassed the user's
+  working saved session.
+- `masters logout` refuses to delete anything `masters login` did not
+  create. Every profile now carries a `.direct-cli-profile` marker file,
+  and `logout` rejects a target that lacks it, is a symlink, or is not a
+  directory. Without this a mistyped or shell-expanded `--profile-dir`
+  (`.`, `~`) went straight into `shutil.rmtree` and recursively deleted an
+  arbitrary tree.
+
+**Added — `direct masters suspend` / `direct masters resume` (#630):**
+
+- First mutating `masters` commands — stop/resume a Мастер кампаний by
+  clicking its overview page's action button, then re-reading the status to
+  confirm the change actually took effect (the click alone is never treated
+  as success). Both are idempotent: a campaign already in the target status
+  is a no-op with a warning, not an error. Neither has a `--sandbox`
+  equivalent — Мастер кампаний has no API surface at all, so there is no
+  isolated test copy; every mutation hits the real account (classified
+  `DANGEROUS` in `direct_cli/smoke_matrix.py`, manual-only per
+  `scripts/test_dangerous_commands.sh`).
+- **Not live-verified:** the resume button's text ("Возобновить кампанию")
+  is confirmed against a live account; the suspend/stop button's exact text
+  is not — `direct_cli/browser/masters.py` tries a short list of plausible
+  Russian labels and raises a clear error (suggesting `--headful`) if none
+  match, rather than clicking the wrong element.
+
+**BREAKING CHANGES — `direct masters` no longer accepts `--login` (#639):**
+
+- `direct masters list`/`get` dropped the `--login` option. Passing your own
+  login there built a `?ulogin=<login>` URL, but `ulogin` is Yandex's
+  *managed-client* (agency) parameter — passing your own login as the managed
+  client produced "Доступ ограничен" and HTTP 401 on the grid's data calls,
+  which is exactly why `masters list` found nothing. `direct masters` only
+  ever reads the logged-in browser session's own account now; there is no
+  agency/managed-client support and no replacement flag.
+
+**Fixed — `direct masters list` found no Мастера кампаний at all (#639):**
+
+- Three independent bugs, found via live diagnosis: (1) the `--login`/
+  `ulogin` issue above; (2) the DOM selector
+  (`a[href*='/wizard/campaigns/']`) never matched anything, because the
+  campaigns grid is a virtualized SPA that renders zero such anchors; (3) the
+  `status-filter` URL query parameter was silently ignored by the grid.
+  `list` now replays the grid's own JSON data call
+  (`POST /web-api/grid/api?operationName=GridCampaigns`) instead of scraping
+  the DOM, paginates past its 200-row page limit, and filters status on the
+  client side using `status.primaryStatus`.
+
+**Added — `direct masters list --status`:**
+
+- New `--status` option (`not-archived` default, plus `active`, `stopped`,
+  `archived`, `all`) lets you see only archived Мастера кампаний, or every
+  status at once — previously `list` had no status filtering at all.
+
+**New — `direct playwright login` / `direct playwright doctor`:**
+
+- `direct masters` previously re-decrypted Chrome's Yandex cookies via the
+  macOS Keychain on every single call. `direct playwright login` decrypts
+  once and persists the result as a Playwright `storage_state` session
+  (`~/.direct-cli/playwright/session.json`, `0600`) — `direct masters`
+  automatically prefers this saved session over a fresh Keychain round-trip,
+  falling back transparently when no session is saved, `--profile-dir`/
+  `--chrome-profile` was passed explicitly, or the saved session has expired.
+  Purely additive: `direct masters` continues to work with zero setup.
+- `direct playwright doctor` reports the health of the whole pipeline
+  (playwright/cryptography installed, chromium downloaded, Chrome profile
+  found, Keychain key derivable, cookies decryptable, saved session
+  present/fresh) without ever logging in, launching a browser, or writing to
+  disk.
+- Neither command requires a Yandex Direct API token/login.
+
+**Fixed — `direct masters` didn't work on macOS at all (#634):**
+
+- `direct masters list`/`get` previously copied `Cookies` + `Local State`
+  into a throwaway Chrome profile, assuming Chromium would decrypt the
+  cookies itself. On macOS this silently failed: the cookie AES key lives
+  only in the login Keychain (`Chrome Safe Storage`); `Local State`'s
+  `os_crypt.encrypted_key` is populated only on Windows. Every cookie was
+  discarded, producing an unauthenticated session that landed on Yandex's
+  login page and then timed out (`networkidle` never settles there, since
+  the login page holds long-poll connections).
+- `direct masters` now reads the Keychain password itself, derives Chrome's
+  AES-128-CBC key, decrypts only the Yandex Direct cookies it needs, and
+  injects them into a fresh bundled-Chromium context via `add_cookies()` —
+  no more temp-profile copying, and `channel="chrome"` (which required a
+  real Google Chrome install) is no longer needed.
+- Login-page and expired-session failures are now reported explicitly
+  (`BrowserAuthError`) instead of surfacing as an opaque 30s timeout.
+- New optional dependency in the `browser` extra: `cryptography>=41`.
+- Linux is supported (Chrome's basic/no-keyring password store only);
+  Windows is not yet.
+
+**New — `direct masters` (#628):**
+
+- Added `direct masters list` / `direct masters get <ids>` — read-only access
+  to Мастер кампаний (Campaign Wizard), which has **no Yandex Direct API
+  surface at all** (do not confuse with `UNIFIED_CAMPAIGN`, an unrelated v5
+  API campaign type already supported by `campaigns add/get --type
+  unified_campaign`). These commands drive a real Chrome session via
+  Playwright, decrypting and reusing the user's own Chrome cookies for
+  `yandex.ru` — no separate login flow (see the Fixed entry above for the
+  macOS Keychain decryption path added in #634). Requires the optional
+  `browser` extra: `pip install "direct-cli[browser]" && playwright install
+  chromium`. `direct masters` degrades gracefully (per-section warnings, not
+  a hard failure) when Yandex's page markup changes, since this data has no
+  API contract to rely on. See `direct_cli/browser/` for the scraping layer.
+
+**Internal — campaigns.py split, step 1 — CPM_BANNER (#613, part of #602):**
+
+- Extracted the `CPM_BANNER_CAMPAIGN` `add`/`update` subtype-block composition
+  (the former inline `elif campaign_type_norm == "CPM_BANNER_CAMPAIGN":`
+  branches) into a new sibling module
+  `direct_cli/commands/_campaigns_cpm_banner.py` (`build_add_block` /
+  `build_update_block`). Both commands now snapshot their CLI parameters once
+  (`p = dict(locals())`) and delegate. The CLI surface, every flag and every
+  `--dry-run` payload is byte-for-byte identical (28 `test_campaigns_*cpm*`
+  fixtures green).
+
+**Internal — campaigns.py split, step 3 (#615):**
+
+- Extracted the `SMART_CAMPAIGN` add/update subtype-block composition
+  (≈285 lines) into a new sibling module
+  `direct_cli/commands/_campaigns_smart.py`
+  (`build_add_block` / `build_update_block`). The `add` and `update`
+  commands now snapshot their CLI parameters once via `p = dict(locals())`
+  and delegate; the SmartCampaign builder pulls only the smart-relevant
+  flags from `p`. CLI surface, every flag and every `--dry-run` payload is
+  byte-for-byte identical (16 `test_campaigns_*smart*` fixtures green,
+  offline tier 2521 passed, WSDL parity + API coverage green).
+
+**Internal — campaigns.py split, step 1 (#602):**
+
+- Extracted all shared constants (`CAMPAIGNS_GET_CRITERIA_LIMITS`, `YES_NO`,
+  `ATTRIBUTION_MODELS`, …), typed-flag validators (`_validate_max_length`,
+  `_validate_sms_time`), payload builders (`_build_notification`,
+  `_build_time_targeting`, `_build_relevant_keywords`,
+  `_build_dynamic_placement_types`, `_build_frequency_cap`,
+  `_build_package_bidding_strategy`, `_build_smart_package_bidding_strategy`,
+  `_priority_goals_update_items`, `_route_cpa_flag`) and the reusable
+  TextCampaign strategy `click.option` groups (`_TEXT_*_STRATEGY_OPTIONS` and
+  their `*_UPDATE` variants) into a new sibling module
+  `direct_cli/commands/_campaigns_base.py`. `campaigns.py` re-imports every
+  name, so the CLI surface, every flag and every `--dry-run` payload is
+  byte-for-byte identical. First step of an incremental decomposition; the
+  per-campaign-type logic (`text`, `unified`, `dynamic`, `smart`,
+  `mobile_app`, `cpm_banner`) follows in subsequent PRs.
+
+**Internal — `make_get_command` covers the complex Group-4 `get`s (#588):**
+
+- `adgroups get`, `keywords get`, `creatives get`, `strategies get` and
+  `audiencetargets get` now register through the shared `make_get_command`
+  factory (net −345 lines). They reuse the existing `extra_options` /
+  `criteria_builder` / `criteria_limits` / `require_criteria_message` /
+  `nested_field_options` hooks — the `--status`/`--statuses` mutual-exclusion
+  guard (adgroups/keywords) lives in the per-module `criteria_builder`, not a
+  new factory flag. adgroups (8) and strategies (16) exercise the factory's
+  largest nested-`*FieldNames` sets to date.
+- Factory ordering fix: nested `*FieldNames` are now parsed (and their
+  provided-but-empty-CSV `UsageError` raised) *before* both the criteria-limit
+  enforcement and the empty-criteria `require_criteria_message` guard, matching
+  the order every hand-rolled command used. So a `--<nested> ""` combined with
+  either no filter at all or an over-limit array reports the nested error, not
+  the require/limit one (pinned by a new `test_dry_run` regression test). The
+  parsed dict is still merged after the common params, so payload key order is
+  unchanged, and this also restores the pre-factory nested-before-limits order
+  for the already-migrated `bidmodifiers get`. No module lacking both a nested
+  option and a `criteria_limits`/`require_criteria_message` is affected.
+- No CLI surface change: `--help` (option order, all nested-field options, the
+  `--is-archived` choice/default), `--dry-run` payloads, and the error-precedence
+  edge cases (empty-nested vs. no-filter and vs. over-limit) are byte-identical,
+  verified against 33 pre-migration baselines captured via CliRunner from the
+  pre-migration tree. As with every prior `make_get_command` migration, the
+  factory resolves the API client only on the live path, so these five `get`s
+  now honor `--dry-run` as a token-free test seam (no behavior change vs. the
+  other factory-backed commands).
+- Two Group-4 `get`s stay hand-rolled as documented carve-outs (see `_get.py`):
+  `ads get` (its `TextAdFieldNames` is always emitted with a per-field default,
+  like the carved-out `keywordbids`) and `campaigns get` (its `--fields` rejects
+  an explicitly empty CSV instead of falling back to the default `FieldNames`).
+
+**Internal — `make_get_command` covers the criteria-limit `get`s `bids` / `bidmodifiers` (completes #587):**
+
+- `bids get` (criteria-limit + require-at-least-one-filter, no `--ids`) and
+  `bidmodifiers get` (criteria-limit + 13 optional nested `*FieldNames`
+  projections + a defaulted `--levels` criteria) now register through the
+  shared `make_get_command` factory, reusing its existing `criteria_limits`,
+  `require_criteria_message` and `nested_field_options` hooks (no new factory
+  parameters). Net −230 lines.
+- No CLI surface change: `--help` (option order, the 13 nested-field options,
+  the `--levels` choice/default), `--dry-run` payloads (the criteria-limit
+  enforcement, the `bids get` require-filter `UsageError`, the always-present
+  `Levels` criteria and nested-field params) are byte-identical (verified
+  against pre-migration baselines).
+- This closes the migratable surface of #587. The three remaining `get`s stay
+  hand-rolled as documented carve-outs, each for a structural reason the shared
+  factory deliberately does not encode: `leads get` (`--datetime-from` /
+  `--datetime-to` sit between `--limit` and `--fetch-all` — a bespoke option
+  order), `keywordbids get` (its nested `SearchFieldNames` / `NetworkFieldNames`
+  carry their own per-field defaults and are always emitted, unlike the factory's
+  provided-only nested projections), and `reports get` (a custom non-RPC TSV
+  stream, not a JSON-RPC `get`).
+
+**Internal — `make_get_command` covers the no-`--ids` / wire-quirk `get`s (part of #587):**
+
+- `agencyclients get` (no `--ids`; filters by `--logins` / `--archived`) and
+  `adextensions get` now register through the shared `make_get_command` factory.
+  The factory gained two more optional parameters: `include_ids` (set `False`
+  for resources with no id filter — the command supplies a custom
+  `criteria_builder` from its own options) and `adextensions_wire_layout` (a
+  single-command flag that reproduces adextensions' exact recorded wire layout:
+  always emit `SelectionCriteria` even when empty, and order nested
+  `*FieldNames` before `Page`). The empty `SelectionCriteria` is a recorded API
+  contract — the `adextensions_get` read cassette replays it and the API accepts
+  it, unlike adgroups/ads/keywords.
+- No CLI surface change: `--help`, `--dry-run` payloads (incl. the empty-criteria
+  and nested-before-`Page` cases) and the read cassettes are byte-identical
+  (verified against pre-migration baselines). Remaining carve-out: `leads get`,
+  whose `--datetime-from` / `--datetime-to` options sit between `--limit` and
+  `--fetch-all` — a bespoke option order that doesn't fit the shared
+  `get_options` stack, so it stays hand-rolled.
+
+**Internal — `make_get_command` covers the nested-`*FieldNames` `get`s (part of #587):**
+
+- `adimages get`, `retargeting get`, `sitelinks get`, `feeds get` and
+  `clients get` now register through the shared `make_get_command` factory
+  (net −175 lines). The factory gained three optional, generic parameters:
+  `nested_field_options` (a tuple of `(flag, WSDL key, help)` for nested
+  `*FieldNames` projections, parsed via the existing `parse_nested_field_names`
+  and rendered between `--fields` and `--dry-run`), `ids_criteria_key` (the
+  SelectionCriteria key for `--ids`; `clients` uses `ClientIds`), and
+  `fields_help` (a resource-specific `--fields` wording, e.g. sitelinks'
+  "Comma-separated SitelinksSet FieldNames"). The shared `get_options` decorator
+  (`utils.py`) gained matching `nested_options` / `fields_help` hooks, both
+  defaulting to current behavior so its other callers are unchanged.
+- No CLI surface change: `--help` (option order, the nested-field option
+  position, the custom `--fields` help), `--dry-run` payloads (including the
+  `ClientIds` key and nested-field params), and the provided-but-empty
+  `*FieldNames` `UsageError` are byte-identical (verified against
+  pre-migration baselines). Deferred to a follow-up: `adextensions` (emits an
+  empty `SelectionCriteria` + Page-before-nested key order), and `leads` /
+  `agencyclients` (no `--ids`; bespoke required criteria).
+
+**Internal — `make_get_command` covers the criteria-limit ad-target `get`s (part of #587):**
+
+- `dynamicads get`, `smartadtargets get` and `dynamicfeedadtargets get` — three
+  byte-for-byte identical command bodies — now register through the shared
+  `make_get_command` factory (`direct_cli/commands/_get.py`) instead of hand-rolled
+  copies (net −131 lines). The factory gained two optional, generic parameters:
+  `criteria_limits` (forwarded to `enforce_criteria_array_limits`, command name
+  derived as `"<group> get"`) and `require_criteria_message` (the "provide at
+  least one filter" guard), plus a shared `ids_adgroup_campaign_states_criteria`
+  builder for the `Ids`/`AdGroupIds`/`CampaignIds`/`States` selection shape.
+- No CLI surface change: `--help`, `--dry-run` payloads, the over-limit and
+  empty-criteria errors, and module patchability are byte-identical (verified
+  against pre-migration baselines). Group 2 (nested `*FieldNames`) and the
+  no-`--ids` commands (`bids`, `keywordbids`, `bidmodifiers`) follow in a
+  separate PR.
+
+**Features — human-readable `text` output for reference commands (#578):**
+
+- Local reference commands now default to a human-readable `text` format instead
+  of raw JSON: `trackingparams` (dynamic tracking-parameter reference) and
+  `dictionaries list-names` (previously hardcoded JSON with no `--format`). Both
+  expose `--format {text,json,table,csv,tsv}` / `--output` via the new shared
+  `reference_output_options` decorator (sibling of `v4_output_options`, default
+  `text`). API-data commands keep their `json` default.
+- Global `output.py` fix: `--format table/csv/tsv` now render a list of scalar
+  values (e.g. dictionary names) as a single `Value` column instead of a Python
+  `repr` (`['Currencies', …]`) / empty output. Affects any caller that passes a
+  scalar list, not just the reference commands.
+
+**Features — preflight `SelectionCriteria` array caps on remaining read-get commands (#571):**
+
+- `ads`, `adgroups`, `bids`, `bidmodifiers`, `campaigns`, `keywords`,
+  `dynamicfeedadtargets`, `audiencetargets` `get` now reject over-long
+  `SelectionCriteria` arrays before the request and surface the array name and
+  ceiling instead of the opaque API `error_code=4001`. Extends the
+  `enforce_criteria_array_limits` discipline added in #555 to the rest of the
+  read-get surface. Per-filter caps were measured live against the Yandex Direct
+  sandbox on 2026-06-17 (see `scripts/measure_criteria_limits.py` and the
+  `*_GET_CRITERIA_LIMITS` constant in each command module for the exact
+  transcript).
+- Closes a downstream consistency gap: the MCP plugin
+  (`axisrow/yandex-direct-mcp-plugin#201`) can now drop its own batch-size
+  guard and forward the CLI error.
+
 ## 0.4.3
 
+**Fixes — known limitation: clearing a carousel AdImageHash (#574):**
+
+- `ads update --clear-image-hash` builds a valid scalar `AdImageHash: null`
+  (visible in `--dry-run`), but the live v5 API can reject it with `Error 5005`
+  (`adImageHash=<[<null>]>`). Root cause: the ad carries a **server-side
+  carousel image structure** that the documented `Ads.update` API does not
+  expose — `TextAd` has only a single `AdImageHash` (no `Carousel` field exists
+  anywhere in the v5 WSDL). Such a carousel image cannot be cleared through the
+  API; it can only be removed in the Direct web interface. The CLI now surfaces
+  a readable hint on `5005`/`AdImageHash` (explaining the carousel cause and the
+  workaround) instead of the opaque error. The request payload is unchanged —
+  the scalar null the CLI sends is correct; the rejection is the server's.
+  Workaround: replace the image with a single `--image-hash <other>`, which the
+  API accepts even on an active ad.
+
 **Features — batch `ads add` via `--from-file` / `--ads-json` (#562, #558 follow-up):**
 
 - `ads add` now accepts a batch of flag-form ad rows from a JSONL file

{direct_cli-0.4.3 → direct_cli-0.5.1}/CLAUDE.md

@@ -10,7 +10,8 @@ CLI for the Yandex Direct API, built with Python and Click. Installed via pip, p
 
 ```bash
 pip install -e ".[dev]"              # Install in dev mode
-pytest                               # Unit tests (no token needed)
+pytest                               # Offline tests, parallel via xdist (no token needed)
+pytest -n0                           # Same offline tests, sequential (for pdb / -s / debugging)
 pytest -m integration -v             # Integration tests (needs .env with token)
 pytest tests/test_cli.py::TestCLI::test_cli_help  # Single test
 pytest -k "campaigns"                # Pattern match
@@ -22,6 +23,8 @@ flake8 direct_cli tests              # Lint
 
 Click group-of-groups. Each Yandex Direct API resource = one file in `direct_cli/commands/` with a Click group and subcommands (`get`, `add`, `update`, `delete`, `suspend`, `resume`, etc.). All groups registered in `direct_cli/cli.py` via `cli.add_command()`.
 
+**Campaigns split (issue #602):** `campaigns.py` is being decomposed incrementally. Step 1 moved all shared constants, validators, payload builders and the reusable TextCampaign strategy option groups into a sibling `direct_cli/commands/_campaigns_base.py`; `campaigns.py` re-imports every name, so the CLI surface is unchanged. Subsequent steps will move per-campaign-type logic (`text`, `unified`, `dynamic`, `smart`, `mobile_app`, `cpm_banner`) into the same package — never edit shared helpers in `campaigns.py`, edit `_campaigns_base.py`.
+
 **Request flow:** `cli.py` → `auth.py` (resolves token/login) → `api.py` (`create_client`) → `tapi_yandex_direct.YandexDirect` → Yandex API → `output.py` (format/print).
 
 **Credentials priority (CLI):** explicit CLI flags (`--token`, `--login`, `--profile`) > base env/current working directory `.env` (`YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_LOGIN`) > active profile from `direct auth login` / `direct auth use` > 1Password/Bitwarden refs. Explicit `--profile` is isolated and does not fall back to base `.env` login. See `direct_cli/auth.py` (`get_credentials`) and README table for the full chain.
@@ -30,7 +33,9 @@ Click group-of-groups. Each Yandex Direct API resource = one file in `direct_cli
 
 **Shared utilities** (`utils.py`): `parse_ids`, `parse_json`, `build_selection_criteria`, `build_common_params`, `get_default_fields`, `COMMON_FIELDS` dict. All command modules import from here — don't duplicate.
 
-**Output** (`output.py`): `format_output()` supports json (default), table, csv, tsv. Colored helpers: `print_success`, `print_error`, `print_warning`, `print_info`.
+**Output** (`output.py`): `format_output()` supports json (default), table, csv, tsv, and `text` (human-readable plain blocks via `format_text`). Colored helpers: `print_success`, `print_error`, `print_warning`, `print_info`.
+
+**Reference commands** (local value lists / templates, e.g. `trackingparams`, `dictionaries list-names`) default to the human-readable `text` format and expose `--format {text,json,table,csv,tsv}` / `--output` via the shared `reference_output_options` decorator (`utils.py`, sibling of `v4_output_options`). API-data commands keep `json` default. New reference commands should use this decorator.
 
 ## Key Conventions
 
@@ -50,7 +55,7 @@ Click group-of-groups. Each Yandex Direct API resource = one file in `direct_cli
 - runtime-deprecated methods (see `RUNTIME_DEPRECATED_METHODS`);
 - v4 methods that have no v5 WSDL (covered by `direct_cli/v4_contracts.py`);
 - custom non-RPC endpoints (e.g. `reports.get` — TSV stream);
-- methods explicitly covered by `tests/test_dry_run.py::test_<service>_<op>_payload`.
+- methods explicitly covered by a `test_<service>_<op>_payload` test in the `tests/test_dry_run_*.py` module suite.
 
 A guard in `tests/test_api_coverage.py::test_dry_run_exclusions_have_no_helper_or_legacy_rationale` enforces this — any rationale outside those five categories that uses the banned phrasing is a mis-classification: write a `PAYLOAD_CASES` fixture instead. See post-mortem in issue #199.
 
@@ -78,6 +83,12 @@ Adding a new mutating command requires extending `COMMAND_WSDL_MAP` in `tests/te
 
 **Docs/cache freshness guard.** `direct_cli.reports_coverage.fetch_reports_spec` and `direct_cli.wsdl_coverage.fetch_wsdl` both refuse responses that look like a Yandex SmartCaptcha gate (markers `showcaptcha`, `smartcaptcha`, `<title>Captcha`) or are suspiciously short (<30 KB for HTML, <3 KB for WSDL). The matching tests `test_reports_cache_files_are_real_content` and `test_wsdl_cache_files_are_real_content` enforce the same invariant on committed cache files.
 
+**`direct masters` cookie decryption (#634).** On macOS, Chrome's cookie AES key lives *only* in the login Keychain (`Chrome Safe Storage`) — never in `Local State`, whose `os_crypt.encrypted_key` field is populated on Windows only. `direct_cli/browser/_chrome_crypto.py` reads the Keychain password itself, derives the AES-128-CBC key (PBKDF2-HMAC-SHA1, Chromium's `saltysalt`/1003-iteration constants), and decrypts only the Yandex Direct cookies it needs — it does not copy the user's Chrome profile or rely on a real Chrome to decrypt anything. `direct_cli/browser/session.py::open_chrome_session` injects the result via Playwright's `add_cookies()` into a bundled Chromium context. The same marker-registry pattern used for captchas (`_captcha.py`) covers Yandex's login-page markers (`session.py::assert_authenticated`), so an expired/wrong-account session is reported explicitly instead of surfacing as a `networkidle` timeout.
+
+**`direct playwright login`/`doctor` — persisted browser session.** `open_chrome_session` above decrypts from Chrome on every call; `direct playwright login` (`direct_cli/commands/browser_session.py`) instead decrypts once via `session.py::capture_storage_state` and persists the result as a Playwright `storage_state` file (`direct_cli/browser/store.py`, `~/.direct-cli/playwright/session.json`, `0600` inside `0700`, sibling of `auth.py`'s `AUTH_STORE_PATH`). `direct masters`' `_open_session` (`commands/masters.py`) then prefers this saved session (`session.py::open_saved_session`) over a fresh Keychain decrypt, falling back automatically when no session is saved, an explicit `--profile-dir`/`--chrome-profile` was passed, or the saved session turns out to be stale (`BrowserAuthError` triggers one retry via fresh decrypt). `direct playwright doctor` (`direct_cli/browser/diagnostics.py`) is a **read-only** diagnostic over the whole chain (playwright/cryptography installed, chromium downloaded, Chrome profile found, Keychain key derivable, cookies decryptable, saved session present/fresh) — it never logs in, never launches a browser of its own, and never writes to disk; that invariant is enforced by contract tests in `tests/test_playwright_session.py`.
+
+**`direct masters list` reads the grid's JSON API, not its DOM (#639).** Live diagnosis found the campaigns grid (`https://direct.yandex.ru/dna/grid/campaigns/`) is a virtualized SPA that never renders a `a[href*='/wizard/campaigns/']` anchor, so the original DOM-scraping approach could never have worked. `direct_cli/browser/masters.py::fetch_masters_list` instead intercepts the grid's own data call — `POST /web-api/grid/api?operationName=GridCampaigns` — via `page.on("response", ...)`, replays it through `page.request.post(...)` (with the captured headers) to paginate past its 200-row `GRID_PAGE_LIMIT`, and never hand-assembles the GraphQL query itself (it is several KB of fragments that would drift out of sync with Yandex's schema). Rows created via Мастер кампаний have no distinguishing `type`/`metaType`/`__typename` — the one field that does discriminate them, confirmed live, is `source == "UAC"` (`MASTERS_SOURCE`). `status.primaryStatus` is filtered client-side via `STATUS_FILTERS` (`masters list --status`, default `not-archived`) because the grid's `status-filter` URL query parameter is silently ignored server-side. `masters` has **no `--login`/agency support**: passing your own login as Yandex's managed-client `ulogin` parameter produces HTTP 401 "Доступ ограничен" on the grid's data calls (confirmed live) — both `list` and `get` build URLs without `ulogin`, and `masters` is in `cli.py`'s `_NO_CREDENTIALS_GROUPS`.
+
 ## PyPI Release
 
 Release is two-phase on purpose. Yandex frequently rate-limits the docs host with a SmartCaptcha gateway, which is an external rate-limit on our IP — not evidence that an URL is gone. Mixing docs-health checks into the publish path made releases non-deterministic, so they live in a separate preflight script.
@@ -105,6 +116,8 @@ Builds dist artifacts, runs twine checks, uploads to TestPyPI + PyPI. Does **not
 ## Tests
 
 - **Unit** (`test_cli.py`, `test_comprehensive.py`) — no API calls, no token needed.
+- **Dry-run payload tests** (`tests/test_dry_run_*.py`) — split by command type (issue #604): `test_dry_run.py` is the guard module (rationale + a `test_dry_run_module_is_importable` sanity check); `test_dry_run_shared.py` holds the `_dry_run`/`_read_dry_run`/`_rejected`/`_failing_run`/`_ids_csv`/`_write_jsonl` invocation helpers; `test_dry_run_<resource>.py` modules hold the per-service payload assertions. Add a new dry-run test to the owning module and import the helpers from `test_dry_run_shared`.
+- **Parallel by default:** `addopts` runs the offline tier with `-n auto` (pytest-xdist) across CPU cores; the suite is process-parallel-safe (env/cwd via `monkeypatch`, filesystem via `tmp_path`, the shared orphan store only in the excluded live tiers). Use `pytest -n0` to run sequentially for `pdb`/`-s`/debugging. The live tiers (`integration`/`v4_live_read`/`integration_live_write`) are **not** parallel-safe (real API + shared `~/.direct-cli` orphan store + ordered resource lifecycles); a `pytest_xdist_auto_num_workers` hook in `tests/conftest.py` auto-resolves `-n auto` to a single worker whenever a live marker is selected, so an explicit `pytest -m integration_live_write` stays serial.
 - **Integration** (`test_integration.py`, `@pytest.mark.integration`) — require `.env` with `YANDEX_DIRECT_TOKEN` and `YANDEX_DIRECT_LOGIN`. Auto-skip if absent.
 - **Credential resolution in tests:** env vars/current working directory `.env` first, then active `direct auth` profile, then skip. This matches the safe CLI default for base env vs. active profile: a developer machine with an active profile must not silently hit production on a plain `pytest`.