Metadata-Version: 2.4
Name: xiaokeer.agent.harness
Version: 0.1.0
Summary: Agent-first Python CLI harness for xiaokeer solution projects.
Author: xiaokeer
License-Expression: MIT
Keywords: agent,cli,harness,automation,xiaokeer
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# xiaokeer-agent-harness

`xiaokeer-agent-harness` is an agent-first Python CLI harness for building small, focused `xiaokeer` solution projects without rebuilding infrastructure every time.

It has no business domain. The included `workflow` commands are a generic, no-op state machine that demonstrates the reusable contracts: JSON output, `doctor`, plan/execute/resume, manifest persistence, explicit `--execute`, tests, packaging, GitHub CI, and PyPI publishing.

## Identity

| Item | Value |
| --- | --- |
| GitHub repository | `xiaokeer-agent-harness` |
| PyPI package | `xiaokeer.agent.harness` |
| Python import namespace | `xiaokeer.agent.harness` |
| CLI command | `xharness` |
| Initial version | `0.1.0` |
| License | MIT |

## What This Is

Use this repository as the base for future agent-friendly CLI solutions.

Examples:

- copy it to create an Excel processing solution
- copy it to create a small local file server
- copy it to create a file upload receiver
- copy it to create a device, cloud, or filesystem operation tool

The point is to keep future agents focused on business behavior instead of repeatedly designing CLI output, manifests, tests, packaging, and release flow.

## Non-Goals

This project is not a business solution, web framework, GUI, TUI, Excel processor, upload server, Android tool, or long-running service.

It does not prescribe which business domain a future project must implement.

## Install

After PyPI publication:

```bash
pip install xiaokeer.agent.harness
```

Recommended global CLI install:

```bash
pipx install xiaokeer.agent.harness
```

Local source install:

```bash
cd /Users/chongwen002/project/xiaokeer-agent-harness
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .
```

## Commands

```bash
xharness --version
xharness doctor
xharness workflow plan
xharness workflow inspect --manifest /path/to/manifest.json
xharness workflow execute --manifest /path/to/manifest.json --execute
xharness workflow resume --manifest /path/to/manifest.json --execute
```

## Agent Workflow

Check readiness:

```bash
xharness doctor
```

Create a no-business plan:

```bash
xharness workflow plan --label future-solution
```

Execute only the created manifest:

```bash
xharness workflow execute --manifest /path/to/manifest.json --execute
```

Resume safely:

```bash
xharness workflow resume --manifest /path/to/manifest.json --execute
```

Agents should read JSON output, exit codes, and manifest state. They should not parse human prose for workflow state.

## Default Output

Operational commands default to JSON.

Example `doctor` shape:

```json
{
  "ok": true,
  "tool": "xiaokeer.agent.harness",
  "tool_version": "0.1.0",
  "checks": [
    {
      "name": "python_version",
      "ok": true,
      "detail": "3.12.0"
    }
  ],
  "next_action": {
    "type": "run_workflow_plan"
  },
  "summary": "doctor_completed"
}
```

Example plan shape:

```json
{
  "ok": true,
  "tool": "xiaokeer.agent.harness",
  "tool_version": "0.1.0",
  "manifest_path": "/path/to/HarnessRun-20260605-120000/manifest.json",
  "run_dir": "/path/to/HarnessRun-20260605-120000",
  "summary": "plan_created",
  "next_action": {
    "type": "execute_workflow",
    "command": "xharness workflow execute --manifest /path/to/manifest.json --execute"
  }
}
```

## Exit Codes

| Code | Meaning |
| --- | --- |
| `0` | success |
| `1` | generic error |
| `2` | environment or external dependency unavailable |
| `3` | empty input, no matching items, or no-op plan |
| `4` | copy/write/create failure |
| `5` | verification or validation failure |
| `6` | destructive action failure |
| `7` | manifest or argument mismatch |
| `8` | required capability missing |

## Manifest

The manifest is a stable public contract and uses schema version `1`.

Generic run directory shape:

```text
HarnessRun-YYYYMMDD-HHMMSS/
  manifest.json
```

The current no-business workflow stores:

- `schema_version`
- `tool`
- `tool_version`
- `run_id`
- `created_at`
- `state`
- `selection`
- `destination`
- `items`
- `errors`
- `warnings`

Future solution projects may extend the manifest while preserving schema compatibility or explicitly introducing a new schema version.

## Development

```bash
cd /Users/chongwen002/project/xiaokeer-agent-harness
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip build twine
python -m pip install -e .
python -m unittest discover tests -v
python -m build
python -m twine check dist/*
```

Automated tests use fakeable boundaries and must not require real external systems.
