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
5 changes: 3 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -181,13 +181,14 @@ Key principles:

| File | Purpose |
|------------------------------------|------------------------------------|
| `src/vip/cli/` | CLI entry point, one module per command: `version.py`, `verify.py` (including `--basic` to skip `@slow`-tagged scenarios), `cleanup.py` (Connect content + orphaned Workbench sessions via `--workbench-url`), `install.py` (install, uninstall), `auth.py`, `report.py`, `status.py`, `scaffold.py`; `app.py` builds the parser and holds `main()` and the `--version` flag; `_common.py` holds helpers shared by several commands; `__init__.py` re-exports the names callers import from `vip.cli`, but a selftest must patch a helper on the submodule that calls it |
| `src/vip/cli/` | CLI entry point, one module per command: `version.py`, `verify.py` (including `--basic` to skip `@slow`-tagged scenarios), `cleanup.py` (Connect content + orphaned Workbench sessions via `--workbench-url`), `install.py` (install, uninstall), `auth.py`, `report.py`, `bundle.py`, `status.py`, `scaffold.py`; `app.py` builds the parser and holds `main()` and the `--version` flag; `_common.py` holds helpers shared by several commands; `__init__.py` re-exports the names callers import from `vip.cli`, but a selftest must patch a helper on the submodule that calls it |
| `src/vip/bundle/` | `vip bundle` internals: `summary.py` (allowlisted config summary and the secret list, with a selftest that fails on an unclassified config field), `archive.py` (allowlisted report files, encoded-form secret scan, atomic zip write), and `stamp.py` (the `_output/.vip-render.json` stamp that `vip report` writes, so that a bundle holds only rendered files made from its own `results.json`) |
| `src/vip/config.py` | TOML config loader and dataclasses (includes `[proxy]` → `ProxyConfig`) |
| `src/vip/proxy.py` | Single source of truth for outbound-proxy resolution. `ProxyConfig` + `build_proxy_map` (mirrors httpx's `get_environment_proxies`, incl. NO_PROXY formatting), `build_mounts` (per-scheme `HTTPTransport` mounts that keep `verify`), `proxy_for_url` (httpx-identical most-specific-pattern selection, used by non-httpx probes), `playwright_proxy` (renders a Playwright `launch(proxy=)` dict). Every HTTP egress path routes through this so VIP never diverges from httpx's own env-proxy behavior — see "Outbound proxy support" below |
| `src/vip/auth/` | Interactive and headless browser authentication for OIDC providers, split into `browser.py` (Chromium launch, `InteractiveAuthSession`), `cache.py`, `flows.py` (`start_interactive_auth`, `start_headless_auth`), `sso.py`, `workbench.py`, `scheme.py` (`resolve_url_scheme`) and `apikey.py` (Connect API-key minting); `__init__.py` re-exports the names callers import from `vip.auth`, but a selftest must patch a helper on the submodule that calls it; `authenticated_page` opens a headless page from a cached auth session for `vip cleanup --workbench-url`; `auth_cache_path()` is the single source of truth for the `.vip-auth-cache.json` location (both `plugin/auth.py` and `cli/cleanup.py` must use it), and `_load_cached_auth` probes Workbench before trusting a cached session; `refresh_auth_cache_from_storage_state` writes a live context's cookies back over a cache whose session has been invalidated (atomic, 0600, existing caches only); both cache writers drop Entra's long-lived `ESTSAUTHPERSISTENT` cookie (`_CACHE_DROPPED_COOKIES`) because Entra sets it even when "Stay signed in?" is answered No |
| `src/vip/idp.py` | IdP login form strategies for headless auth (Keycloak, Okta, Snowflake, Entra ID) |
| `src/vip/attest.py` | The two skip helpers (`not_applicable`, `unproven`) that record whether a skipped check was out of scope or simply never verified |
| `src/vip/errors.py` | The `VipError` exception hierarchy for user-facing CLI failures (`ConfigError`, `AuthError`, `ProductUnreachableError`, `InstallError`, `ReportError`, `AuthConfigError`, `AuthTimeoutError`), each carrying an `exit_code`; raise one instead of calling `sys.exit` from command code — see "Error handling" below |
| `src/vip/errors.py` | The `VipError` exception hierarchy for user-facing CLI failures (`ConfigError`, `AuthError`, `ProductUnreachableError`, `InstallError`, `ReportError`, `BundleError`, `AuthConfigError`, `AuthTimeoutError`), each carrying an `exit_code`; raise one instead of calling `sys.exit` from command code — see "Error handling" below |
| `src/vip/plugin/` | pytest plugin, split into `options.py` (`pytest_addoption`), `configure.py` (`pytest_configure`: markers, including `slow` used by `verify --basic`, and warning filters), `auth.py` (the `--interactive-auth`/`--headless-auth` login), `selection.py` (deselection and version auto-skip), `results.py` (JSON report output), `terminal.py` (concise display, heartbeat) and `state.py` (module-level mutable state; read and write it as `state.<name>`); `__init__.py` re-exports every hook, since pytest registers only the package module, plus the names callers import from `vip.plugin`, but a selftest must patch a helper on the submodule that calls it; `pytest_configure` also registers `vip.fixtures` as its own named plugin (`"vip-fixtures"`) so core fixtures resolve regardless of directory ancestry — see that module's docstring |
| `src/vip/fixtures.py` | VIP's core pytest fixtures and shared BDD "Given" steps (`vip_config`, `connect_client`, `browser_context_args`, etc.), registered by `vip.plugin.pytest_configure` rather than defined in a `conftest.py` — pytest scopes `conftest.py` fixtures by directory ancestry, which would hide them from extension directories |
| `src/vip/version.py` | `ProductVersion` parsing/comparison for `min_version` gating; `MINIMUM_SUPPORTED_POSIT_TEAM` support floor (powers `vip version`) |
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,7 @@ content from Connect.
| `vip status` | Quick health check for each configured product |
| `vip cleanup` | Delete VIP `_vip_test` content from Connect |
| `vip report` | Render the HTML report from test results (requires [Quarto CLI](https://quarto.org/docs/download/)) |
| `vip bundle` | Write a zip of the report output to share. It leaves out vip.toml and the auth cache, and checks each file for known credentials. |
| `vip auth` | Authentication tools (e.g. mint Connect API keys) |
| `vip version` | Print the vip version and the minimum supported Posit Team version |
| `vip --version` | Print the installed vip version |
Expand Down
Loading
Loading