Metadata-Version: 2.4
Name: vyspec
Version: 0.1.10
Summary: Vyspec command-line interface and local browser runner.
Author: Vyspec
Project-URL: Homepage, https://vyspec.com
Keywords: browser,ci,cli,qa,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: playwright==1.61.0
Requires-Dist: prompt-toolkit<4,>=3.0.52
Requires-Dist: pydantic>=2.8.0
Requires-Dist: pydantic-settings>=2.4.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich<15,>=14.1.0
Requires-Dist: sentry-sdk<3,>=2.67.1
Requires-Dist: structlog>=24.4.0
Provides-Extra: dev
Requires-Dist: build>=1.3.0; extra == "dev"
Requires-Dist: mypy>=1.11.0; extra == "dev"
Requires-Dist: pytest>=8.3.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: twine>=6.2.0; extra == "dev"

# Vyspec CLI

The Vyspec CLI is a thin, customer-operated browser executor. It runs on a developer or CI
machine, opens the customer’s local application, captures bounded browser observations, and executes
typed actions returned by the Vyspec API.

The runner does **not** contain the model provider key, private agent prompts, QA orchestration, or
licensing authority. Those remain in the Vyspec API. Treat the runner as inspectable and tamperable because
it runs on the customer’s machine.

## Local setup

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

Set the local application port in the repository's ignored `.env`:

```dotenv
VSY_APP_PORT=3000
```

Then connect that Git repository to an existing Vyspec Project:

```bash
vsy init
```

`vsy init` checks for the Chromium build required by the installed CLI and offers to download it
when it is missing. You may defer that download and run `vsy install-browser` later. CI should keep
installing the browser explicitly before `vsy run`.

The CLI opens Vyspec in the browser and asks the signed-in user to select and authorize one Project.
When `origin` points to GitHub, GitLab, or Bitbucket, Vyspec detects the provider and continues that
same browser tab directly into the repository connection flow. Repositories without a supported
remote keep the normal local authorization flow. The CLI then adds an owner-readable Project API
key to that `.env`:

```dotenv
VSY_PROJECT_API_KEY=revocable-project-api-key
VSY_HEADLESS=false
```

The Project API key is the only Vyspec credential accepted by the runner. Never put an OpenAI, Browserbase,
AWS, or private Vyspec model credential in this file.

Running `vsy init` again reuses a valid connection. Use `vsy init --reauthorize` to replace it.
Then run the agent from that repository with `vsy run --profile <run-profile-id>`.

## Commands

```bash
vsy --version
vsy install-browser
vsy init
vsy connect
vsy doctor
vsy run
vsy run --profile <run-profile-id>
vsy run --profile <run-profile-id> --headless
```

Interactive local runs ask whether to use a visible or headless browser. Pass `--headless` to skip
that choice and keep it hidden. CI always uses a headless browser.

In a terminal, `vsy run` finds the nearest `.env` inside the current Git repository, authenticates
its Project API key, displays that Project and directory, and lists only the active Run Profiles
belonging to that Project. Local runs use `VSY_APP_PORT` from that repository's `.env`.
Supplying `--profile` skips profile selection.

For ad hoc QA without creating a saved Profile, supply instructions directly:

```bash
vsy run --instructions "Verify the corrected checkout total"
vsy run --instructions-file qa.md
vsy run --instructions-file qa.md \
  --session-profile <session-profile-id> \
  --start-path /account/records/42
```

Direct Runs start at `/` in a fresh desktop Chrome session with balanced execution defaults. If
the page or record belongs to a signed-in user, pass an automatic-login Session Profile and the
origin-relative page to open after login. Select the Session Profile under the Project's
Configuration area; its ID is the final segment of that Profile's page URL. Add that Session
Profile's required `VSY_...` credential variables to the repository `.env` for local runs or the
provider's secret store for CI. Credential values stay on the runner machine and are never sent to
the Vyspec API or model.

`vsy connect` keeps the initialized repository visible to the Vyspec web application while that
terminal remains open. It authenticates with the repository's Project API key, reports whether the
configured loopback application is reachable, and disconnects cleanly on Ctrl+C. This presence
command does not start a Run by itself.

## CI contract

The CLI enters CI mode when `CI`, `GITHUB_ACTIONS`, or `GITLAB_CI` is explicitly set to
`true`, `1`, `yes`, or `on`. Values such as `CI=false` do not enable CI behavior.
Bitbucket Pipelines is detected from its numeric `BITBUCKET_BUILD_NUMBER` variable.

CI execution has one deterministic contract:

- `VSY_PROJECT_API_KEY` must contain the Project API key supplied through the CI secret store.
- `vsy run` must receive either `--profile <run-profile-id>`, `--instructions`, or
  `--instructions-file`; saved Profile IDs must belong to the connected Project.
- Session Profile credential names must exist in the CI environment when a saved or direct Run
  selects an automatic-login Session Profile.
- The customer application must listen on loopback port `3000`; `VSY_APP_PORT` is ignored in CI.
- The browser is always headless, profile selection is never interactive, and `vsy init` is rejected.
- Every Run creates a new isolated browser context. Automatic-login Profiles require credentials
  from the repository or CI environment, and the runner executes the configured login flow before QA.

The GitHub Action owns CLI installation, the hosted API endpoint, and invocation. Customers
provide only their Project API key, selected Run Profile, application process, and profile-specific
test credentials.

The supported wrapper is published separately as the public
[`vyspec-action`](https://github.com/Vyspec/vyspec-action) repository. Invoke its released
major version after the application has been started in an earlier workflow step:

```yaml
- name: Run Vyspec QA
  uses: Vyspec/vyspec-action@v1
  with:
    github-token: ${{ github.token }}
    project-api-key: ${{ secrets.VSY_PROJECT_API_KEY }}
    run-profile-id: 123e4567-e89b-42d3-a456-426614174000
```

The action currently targets GitHub-hosted Ubuntu runners. It installs Python 3.12, its pinned public
CLI release, and the CLI-pinned Playwright Chromium build. It waits up to 120 seconds for the
application on port `3000`, preserves the CLI's original operational and cancellation status, and
creates or updates one pull-request report.

The runner always connects to `http://127.0.0.1:<port>`. It does not accept an arbitrary target
hostname, so QA can only operate against an application running on the same developer or CI machine.

`vsy run` exits with `0` whenever execution completes and produces a definitive `passed` or `failed`
QA verdict. A failed QA verdict is reported in the terminal, result file, and pull-request comment; it
is not an operational process failure. Exit `2` means execution could not produce a definitive result.
User or CI cancellation exits with `130`. `SIGTERM` is normalized
to the same cancellation path so the runner closes the browser and makes a best-effort failure update
before exiting.

The project token starts a run and is immediately exchanged for a short-lived credential scoped to
that exact run attempt. The server returns the saved run profile's start URL, host allowlist, browser
preset, and step limit. For each observation the runner requests a short-lived upload grant, uploads
the PNG directly to storage, and sends only the artifact reference to:

```text
POST /api/v1/runner/runs/{runId}/turn
```

The server returns a bounded batch of native computer actions. The runner executes only supported
actions, refuses navigation outside the configured loopback host, caps screenshots, and never
executes arbitrary JavaScript returned by the server.

## Trust boundary

```text
Customer machine                         Vyspec API
────────────────                         ──────────────
Chromium + local app
Screenshots only          ────────────►  License/auth checks
Native computer actions   ◄────────────  Private prompts + Luna
Loopback host enforcement                 Run state and workflow
```

The runner intentionally has no SQS, ECS, AWS, Browserbase, Cloudflare, or direct OpenAI integration.
Each model turn is a short authenticated API request; there is no hosted worker process to manage.

## Operational error reporting

The CLI reports operational crashes to Vyspec's Sentry project so broken releases and recurring
runner failures can be diagnosed. Reports include the CLI version, command name, CI/local source,
exception type, and sanitized stack locations. They exclude command arguments, environment values,
credentials, emails, prompts, screenshots, browser contents, request bodies, URLs, and local paths.

Set `VSY_TELEMETRY_DISABLED=1` to disable CLI error reporting.
