Metadata-Version: 2.4
Name: cli-anything-cvviewer
Version: 0.1.0
Summary: CLI-Anything harness for the CVViewer Qt desktop application.
Author: CVViewer maintainers
License: Proprietary
Keywords: cvviewer,cli-anything,automation,webapi,qt
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# cli-anything-cvviewer

Python Click CLI harness for the CVViewer Qt desktop application.

## Install

From PyPI, use `pipx` for an isolated command-line installation:

```powershell
pipx install cli-anything-cvviewer
```

Then verify the command:

```powershell
cli-anything-cvviewer --json contract check
```

For local development, install from `agent-harness`:

```powershell
python -m pip install -e .
```

If your current directory is `agent-harness\cli_anything\cvviewer`, the same
command is also supported:

```powershell
python -m pip install -e .
```

## Publish to PyPI

Release from `agent-harness` only:

```powershell
cd E:\QT\CVViewer\agent-harness
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
python -m twine upload --repository testpypi dist/*
python -m twine upload dist/*
```

Use `__token__` as the username when `twine upload` asks for credentials, and
paste the PyPI API token as the password. Bump the version in `setup.py` and
`cli_anything\cvviewer\__init__.py` before every new upload; PyPI rejects
reusing the same version.

The package includes the built-in scenario files under
`cli_anything\cvviewer\scenarios`. Runtime artifacts such as `runs`, `tasks`,
`dist`, and `*.egg-info` should not be uploaded or committed.

## Commands

```powershell
cli-anything-cvviewer --json info --source E:\QT\CVViewer
cli-anything-cvviewer --json project open E:\QT\CVViewer --role loader
cli-anything-cvviewer --json status --project E:\QT\CVViewer\.cvviewer-cli-session.json
cli-anything-cvviewer --json export --project E:\QT\CVViewer\.cvviewer-cli-session.json --format json --output E:\tmp\cvviewer-summary.json
cli-anything-cvviewer --json doctor env
cli-anything-cvviewer --json doctor cvviewer --source E:\QT\CVViewer
cli-anything-cvviewer --json doctor webapi
cli-anything-cvviewer --json webapi routes
cli-anything-cvviewer --json webapi health --host 127.0.0.1 --port 8090
cli-anything-cvviewer --json webapi version --host 127.0.0.1 --port 8090
cli-anything-cvviewer --json webapi protocol --host 127.0.0.1 --port 8090
cli-anything-cvviewer --json webapi errors --host 127.0.0.1 --port 8090
cli-anything-cvviewer --json webapi task-status --task-no T001 --host 127.0.0.1 --port 8090
cli-anything-cvviewer --json webapi task-events --task-no T001 --host 127.0.0.1 --port 8090
cli-anything-cvviewer --json webapi validate task-pack --file E:\tmp\task-pack.json
cli-anything-cvviewer --json webapi validate task-pack --file agent-harness\scenarios\pack-add-order.json
cli-anything-cvviewer --json webapi post task-pack --file E:\tmp\task-pack.json --host 127.0.0.1 --port 8090
cli-anything-cvviewer --json webapi smoke --role loader --host 127.0.0.1
cli-anything-cvviewer --json contract check
cli-anything-cvviewer --json contract export
cli-anything-cvviewer --json scenario list
cli-anything-cvviewer --json scenario show pack-add-order
cli-anything-cvviewer --json scenario validate pack-add-order
cli-anything-cvviewer --json scenario create-task pack-add-order --tasks-root agent-harness\tasks
cli-anything-cvviewer --json task create --route task-pack --file agent-harness\scenarios\pack-add-order.json --tasks-root agent-harness\tasks
cli-anything-cvviewer --json task create --route task-pack --file E:\tmp\task-pack.json --tasks-root agent-harness\tasks
cli-anything-cvviewer --json task submit agent-harness\tasks\T001.json --host 127.0.0.1 --port 8090 --run-root agent-harness\runs
cli-anything-cvviewer --json task start agent-harness\tasks\T001.json --host 127.0.0.1 --port 8090 --run-root agent-harness\runs
cli-anything-cvviewer --json task status agent-harness\tasks\T001.json --host 127.0.0.1 --port 8090 --events
cli-anything-cvviewer --json task replay agent-harness\tasks\T001.json
cli-anything-cvviewer --json task wait agent-harness\tasks\T001.json --host 127.0.0.1 --port 8090 --timeout 30
cli-anything-cvviewer --json webapi post task-pack --file E:\tmp\task-pack.json --host 127.0.0.1 --port 8090 --run-root agent-harness\runs
cli-anything-cvviewer --json run list --root agent-harness\runs
cli-anything-cvviewer --json analyze run agent-harness\runs\RUN_ID
cli-anything-cvviewer --json analyze runs --root agent-harness\runs
cli-anything-cvviewer --json diagnose run agent-harness\runs\RUN_ID
cli-anything-cvviewer report run agent-harness\runs\RUN_ID --format html --output E:\tmp\cvviewer-run-report.html
cli-anything-cvviewer --json report run agent-harness\runs\RUN_ID --format json --output E:\tmp\cvviewer-run-report.json
cli-anything-cvviewer --json report run agent-harness\runs\RUN_ID --format zip --output E:\tmp\cvviewer-run-report.zip
cli-anything-cvviewer --json workflow check-runtime --host 127.0.0.1 --port 8090 --role loader
cli-anything-cvviewer --json workflow inspect-task agent-harness\tasks\T001.json --host 127.0.0.1 --port 8090 --events
cli-anything-cvviewer --json workflow run-scenario pack-add-order --host 127.0.0.1 --port 8090 --tasks-root agent-harness\tasks --run-root agent-harness\runs --report E:\tmp\cvviewer-workflow-report.html
```

## Scope

This harness inspects project metadata and can probe CVViewer's existing Web API
when `loader.exe` or `unloader.exe` is already running. It does not modify Qt C++
source and does not run CMake, npm, or pnpm.

Future algorithm commands should call a real CVViewer C++ backend executable
rather than reimplementing PCL, Modbus, ZeroMQ, or cargo-placement logic in
Python.

## Web API Routes

Known route names:

- `start-pack`: `/api/vision/startPack`, loader default port `8090`
- `task-pack`: `/api/vision/taskPack`, loader default port `8090`
- `start-unpack`: `/api/vision/startUnPack`, unloader default port `8092`
- `task-unpack`: `/api/vision/taskUnPack`, unloader default port `8092`
- `vision-data`: `/webapi/visionData`, default port `8090`
- `health`: `GET /api/vision/health`
- `version`: `GET /api/vision/version`
- `protocol`: `GET /api/vision/protocol`
- `error-codes`: `GET /api/vision/errorCodes`
- `task-status`: `GET /api/vision/taskStatus?taskNo=...`
- `task-events`: `GET /api/vision/taskEvents?taskNo=...`

`webapi validate` checks required fields locally before sending. `webapi post`
sends the JSON payload to the running CVViewer process. `webapi smoke` sends a
minimal `startPack` or `startUnPack` request for connectivity probing.
The read-only commands query a running CVViewer process without emitting Qt
signals or sending task mutation payloads.

## Automation Workflow

The expanded CLI-side workflow keeps CVViewer as the source of truth while
making interface test evidence repeatable:

- `contract check/export`: inspect the static CLI-side protocol contract.
- `doctor env/cvviewer/webapi`: run read-only checks for Python/Click/CLI
  installation, CVViewer source layout, and static Web API assumptions.
- `webapi post --run-root`: send a request and persist `meta.json`,
  `request.json`, and `response.json` under a run directory.
- `scenario list/show/validate/create-task`: discover standard payloads,
  inspect them, validate them against a Web API route, and turn them into local
  task records.
- `task create`: create a local task record from a payload file.
- `task submit`: send the task payload to its configured route and optionally
  save run evidence.
- `task start`: send `startPack` or `startUnPack` with `taskNo` and optionally
  save run evidence.
- `task status/replay/wait`: inspect the local task record, print the payload
  for replay, and optionally query/wait on CVViewer's read-only task status API.
- `run list/show`: inspect saved run records.
- `analyze run/runs`: normalize raw run evidence into stable facts and summarize
  pass/fail categories across a run root.
- `diagnose run`: classify deterministic failures such as connection refused,
  timeout, missing required fields, HTTP errors, and known CVViewer response
  codes.
- `report run`: generate Markdown, HTML, JSON, or ZIP reports from a run
  directory. ZIP reports include rendered report files plus raw artifacts.
- `workflow check-runtime`: call read-only runtime APIs and surface protocol
  completeness warnings.
- `workflow inspect-task`: combine a local task record with optional runtime
  `taskStatus/taskEvents`.
- `workflow run-scenario`: validate a standard scenario, create a local task,
  submit/start it, collect status/events, analyze evidence, diagnose failures,
  and optionally export a report.

## Scenarios

`agent-harness/scenarios/pack-add-order.json` is the repository copy of a small
standard `task-pack` payload for装车加单 workflows. PyPI installations also
ship the same built-in payload under `cli_anything/cvviewer/scenarios`, so
`scenario list`, `scenario show`, `scenario validate`, and
`workflow run-scenario` work without a source checkout.

Recommended standard flow:

```powershell
cli-anything-cvviewer --json scenario list
cli-anything-cvviewer --json scenario validate pack-add-order
cli-anything-cvviewer --json scenario create-task pack-add-order --tasks-root agent-harness\tasks
cli-anything-cvviewer --json task submit agent-harness\tasks\pack-add-order-demo.json --host 127.0.0.1 --port 8090 --run-root agent-harness\runs
cli-anything-cvviewer --json task start agent-harness\tasks\pack-add-order-demo.json --host 127.0.0.1 --port 8090 --run-root agent-harness\runs
cli-anything-cvviewer --json analyze runs --root agent-harness\runs
cli-anything-cvviewer --json workflow run-scenario pack-add-order --host 127.0.0.1 --port 8090 --tasks-root agent-harness\tasks --run-root agent-harness\runs
```

CVViewer-side read-only APIs such as `/api/vision/health`,
`/api/vision/version`, `/api/vision/protocol`, `/api/vision/errorCodes`,
`/api/vision/taskStatus`, and `/api/vision/taskEvents` can be queried through
the `webapi` command group when `loader.exe` or `unloader.exe` is running.

## Task Management Limits

`task` commands are intentionally CLI-side orchestration helpers. They do not
delete or mutate CVViewer internal state, and they do not invent a completion
status that CVViewer has not reported. Without `--host`, `task status` reports
local CLI evidence only. With `--host`, `task status` and `task wait` query the
running CVViewer read-only task APIs.
