cybervisor 0.1.0__tar.gz

cybervisor-0.1.0/PKG-INFO

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: cybervisor
+Version: 0.1.0
+Summary: Autonomous CLI supervisor for staged AI workflows
+Author: crzidea
+Project-URL: Homepage, https://github.com/crzidea/cybervisor
+Project-URL: Repository, https://github.com/crzidea/cybervisor
+Project-URL: Issues, https://github.com/crzidea/cybervisor/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: setproctitle>=1.3.4; platform_system != "Windows"
+
+# cybervisor
+
+`cybervisor` is an autonomous CLI supervisor for development runs. It executes a default 5-stage pipeline with Gemini CLI, Claude Code, or a mock agent, supports customizing stages in YAML config, installs runtime hooks for non-interactive execution, enforces optional stage-result contracts, and keeps audit logs in JSONL.
+
+## What it does
+
+- Runs the default five ordered stages: `Spec`, `Review Spec`, `Implement`, `Review Code`, `Verify`
+- Allows custom stage lists in `cybervisor.yaml`
+- Supports optional structured stage-result contracts and artifact-driven routing
+- Fails fast when the selected agent CLI or hook verifier credentials are missing
+- Writes non-secret hook runtime metadata and settings snapshots under `.cybervisor/hooks/` for non-mock runs
+- Keeps verifier credentials in inherited `CYBERVISOR_LLM_*` env vars instead of persisting them under `.cybervisor/hooks/`
+- Snapshots `.gemini/settings.json` or `.claude/settings.json` and restores the exact pre-run content on exit
+- Streams live agent output to stderr and persists per-stage logs under `.cybervisor/`
+- Exits with `130` on `SIGINT` or `SIGTERM` after cleanup
+
+## Requirements
+
+- Python 3.11+
+- [`uv`](https://docs.astral.sh/uv/)
+- One of:
+  - `gemini` on `PATH`
+  - `claude` on `PATH`
+  - `mock` mode for local deterministic runs
+- `CYBERVISOR_LLM_API_KEY` for non-mock runs
+
+Optional local env loading is supported from `.env` in the working directory. `cybervisor` reads only `CYBERVISOR_LLM_BASE_URL`, `CYBERVISOR_LLM_API_KEY`, and `CYBERVISOR_LLM_MODEL`, and does not override variables already exported in the shell.
+
+## Install
+
+Install the CLI onto your `PATH`:
+
+```bash
+uv tool install -e .
+```
+
+After installation, verify:
+
+```bash
+cybervisor --version
+```
+
+Developer fallback if you do not want to install the CLI globally:
+
+```bash
+uv run cybervisor --version
+```
+
+## Setup
+
+```bash
+uv sync
+cp .env.example .env
+```
+
+Set at least:
+
+```bash
+CYBERVISOR_LLM_API_KEY=...
+# Optional overrides
+# CYBERVISOR_LLM_BASE_URL=https://api.openai.com/v1
+# CYBERVISOR_LLM_MODEL=auto
+```
+
+## Usage
+
+Minimal run:
+
+```bash
+cybervisor "Create a 360 feedback system" --config cybervisor.yaml
+```
+
+Start from a specific stage:
+
+```bash
+cybervisor "Create a 360 feedback system" --start-stage "Implement"
+```
+
+Version and help:
+
+```bash
+cybervisor --version
+cybervisor --help
+```
+
+Minimal config:
+
+```yaml
+pipeline:
+  agent_tool: gemini
+
+stages:
+  - name: Spec
+  - name: Review Spec
+  - name: Implement
+  - name: Review Code
+  - name: Verify
+```
+
+Notes:
+
+- `hook:` values are sourced from `CYBERVISOR_LLM_*` env vars, not from config file literals
+- If a stage omits `prompt_template`, the default template is used
+- If `stages:` is omitted, the default five-stage pipeline is used
+- If `stages:` is provided, `cybervisor` runs the stages exactly as configured
+- Stages may optionally declare a `contract` for required result artifacts and a `next_stage` for explicit success-path routing
+- When a review stage can route `changes_requested` to a correction stage, set that review stage's `next_stage` explicitly for the `approved` path instead of relying on linear order
+- Use `--start-stage STAGE_NAME` to skip earlier stages and begin execution at the named stage
+
+Review/fix loop example:
+
+```yaml
+pipeline:
+  agent_tool: claude
+
+stages:
+  - name: Implement
+
+  - name: Review Code
+    next_stage: Verify
+    prompt_template: |
+      Review the implementation.
+      Write the final result to .cybervisor/contracts/artifacts/Review Code.yaml.
+    contract:
+      allowed_statuses: [approved, changes_requested]
+      routes:
+        changes_requested:
+          next_stage: Fix Code
+          injections: [summary, details, actions]
+
+  - name: Fix Code
+    next_stage: Review Code
+    prompt_template: |
+      Fix the issues described by the latest review.
+      Full contract:
+      {latest_contract_yaml}
+      Summary:
+      {latest_contract_summary}
+      Details:
+      {latest_contract_details_yaml}
+      Actions:
+      {latest_contract_actions_yaml}
+
+  - name: Verify
+```
+
+In this pattern:
+
+- `Review Code` with `status: approved` goes to `Verify`
+- `Review Code` with `status: changes_requested` goes to `Fix Code`
+- `Fix Code` loops back to `Review Code`
+- If `Review Code` omitted `next_stage: Verify`, a linear stage list would otherwise fall through to `Fix Code`
+- Contract prompt guides live at `.cybervisor/contracts/prompts/[Stage Name].md`
+
+## Runtime behavior
+
+For `gemini` and `claude` runs, `cybervisor`:
+
+1. Performs preflight checks.
+2. Writes shared hook runtime metadata into `.cybervisor/hooks/`.
+3. Persists an exact settings snapshot in `.cybervisor/hooks/`.
+4. Patches the active tool settings file so the selected agent invokes the packaged `cybervisor-agent-hook` entry point.
+5. Starts the agent in a dedicated process group when supported.
+6. Uses the runtime hook to classify autonomy decisions as `approve` or `block`, then adapts those into the selected tool's native hook output so the agent continues autonomously.
+7. If the active stage declares a contract, uses the same hook runtime to block completion until the required artifact exists and is structurally valid.
+8. Streams agent output into stderr and the stage log file.
+9. Re-validates contract artifacts after agent exit, then routes by contract status or explicit `next_stage` when configured.
+10. Restores settings and removes runtime files on success, failure, or interrupt.
+
+Generated artifacts:
+
+- `.cybervisor/logs/cybervisor.log.jsonl`: structured run log
+- `.cybervisor/logs/stages/<stage_name>.jsonl`: captured transcript per stage
+- `.cybervisor/contracts/artifacts/*.yaml`: optional stage-result artifacts for contract-enabled stages
+- `.cybervisor/contracts/prompts/*.md`: authored contract prompt guides for contract-enabled stages
+
+## Development
+
+Validation commands used by this repo:
+
+```bash
+uv run mypy --strict src
+uv run pytest
+```
+
+Useful focused runs:
+
+```bash
+uv run pytest tests/integration/test_pipeline_e2e.py
+uv run pytest tests/unit/test_hooks.py tests/unit/test_pipeline.py tests/unit/test_signals.py
+```
+
+## Publish
+
+Build distributions:
+
+```bash
+uv build
+```
+
+Check the generated artifacts locally:
+
+```bash
+python -m zipfile -l dist/*.whl
+tar -tf dist/*.tar.gz
+```
+
+Upload to PyPI with a token:
+
+```bash
+export UV_PUBLISH_TOKEN=your-pypi-token
+uv publish
+```
+
+Optional dry run against TestPyPI:
+
+```bash
+export UV_PUBLISH_TOKEN=your-testpypi-token
+uv publish --index testpypi
+```
+
+If the version already exists on PyPI, bump `version` in `pyproject.toml` and `src/cybervisor/__init__.py` before rebuilding.
+
+## Manual demo workflow
+
+The repository includes a demo bootstrap helper:
+
+```bash
+scripts/e2e-demo-project.sh
+```
+
+That script:
+
+- creates a fresh demo workspace with `scripts/init-demo-project.sh`
+- supports `--agent-tool claude|gemini` and defaults to `claude`
+- optionally starts a local deterministic hook verifier stub when run with `--with-local-api`
+- copies `templates/demo/.env` into the demo workspace as `.env`
+- prints the exact `cd` and `cybervisor` command to run manually in your shell
+- reminds you to install the CLI first if `cybervisor` is not yet on your `PATH`
+
+## Specs Directory
+
+Feature folders under `specs/` are archival implementation artifacts after delivery. The current source of truth for runtime behavior is the checked-in code plus the main project docs and constitution.
+
+## Repository layout
+
+```text
+src/cybervisor/        Core CLI package
+assets/hooks/          Standalone runtime hook source
+scripts/               Demo bootstrap and end-to-end scripts
+templates/demo/        Demo project scaffold
+tests/                 Unit and integration coverage
+specs/                 Speckit feature artifacts
+.specify/              Constitution, templates, and repo scripts
+AGENTS.md              Symlink to .specify/memory/constitution.md
+GEMINI.md              Symlink to AGENTS.md
+CLAUDE.md              Symlink to AGENTS.md
+```
+
+## Agent docs
+
+The agent mandate files are symlinked by design:
+
+- `AGENTS.md` -> `.specify/memory/constitution.md`
+- `GEMINI.md` -> `AGENTS.md`
+- `CLAUDE.md` -> `AGENTS.md`
+
+If mandate content needs to change, update `.specify/memory/constitution.md`, not the symlinks.

cybervisor-0.1.0/README.md

@@ -0,0 +1,268 @@
+# cybervisor
+
+`cybervisor` is an autonomous CLI supervisor for development runs. It executes a default 5-stage pipeline with Gemini CLI, Claude Code, or a mock agent, supports customizing stages in YAML config, installs runtime hooks for non-interactive execution, enforces optional stage-result contracts, and keeps audit logs in JSONL.
+
+## What it does
+
+- Runs the default five ordered stages: `Spec`, `Review Spec`, `Implement`, `Review Code`, `Verify`
+- Allows custom stage lists in `cybervisor.yaml`
+- Supports optional structured stage-result contracts and artifact-driven routing
+- Fails fast when the selected agent CLI or hook verifier credentials are missing
+- Writes non-secret hook runtime metadata and settings snapshots under `.cybervisor/hooks/` for non-mock runs
+- Keeps verifier credentials in inherited `CYBERVISOR_LLM_*` env vars instead of persisting them under `.cybervisor/hooks/`
+- Snapshots `.gemini/settings.json` or `.claude/settings.json` and restores the exact pre-run content on exit
+- Streams live agent output to stderr and persists per-stage logs under `.cybervisor/`
+- Exits with `130` on `SIGINT` or `SIGTERM` after cleanup
+
+## Requirements
+
+- Python 3.11+
+- [`uv`](https://docs.astral.sh/uv/)
+- One of:
+  - `gemini` on `PATH`
+  - `claude` on `PATH`
+  - `mock` mode for local deterministic runs
+- `CYBERVISOR_LLM_API_KEY` for non-mock runs
+
+Optional local env loading is supported from `.env` in the working directory. `cybervisor` reads only `CYBERVISOR_LLM_BASE_URL`, `CYBERVISOR_LLM_API_KEY`, and `CYBERVISOR_LLM_MODEL`, and does not override variables already exported in the shell.
+
+## Install
+
+Install the CLI onto your `PATH`:
+
+```bash
+uv tool install -e .
+```
+
+After installation, verify:
+
+```bash
+cybervisor --version
+```
+
+Developer fallback if you do not want to install the CLI globally:
+
+```bash
+uv run cybervisor --version
+```
+
+## Setup
+
+```bash
+uv sync
+cp .env.example .env
+```
+
+Set at least:
+
+```bash
+CYBERVISOR_LLM_API_KEY=...
+# Optional overrides
+# CYBERVISOR_LLM_BASE_URL=https://api.openai.com/v1
+# CYBERVISOR_LLM_MODEL=auto
+```
+
+## Usage
+
+Minimal run:
+
+```bash
+cybervisor "Create a 360 feedback system" --config cybervisor.yaml
+```
+
+Start from a specific stage:
+
+```bash
+cybervisor "Create a 360 feedback system" --start-stage "Implement"
+```
+
+Version and help:
+
+```bash
+cybervisor --version
+cybervisor --help
+```
+
+Minimal config:
+
+```yaml
+pipeline:
+  agent_tool: gemini
+
+stages:
+  - name: Spec
+  - name: Review Spec
+  - name: Implement
+  - name: Review Code
+  - name: Verify
+```
+
+Notes:
+
+- `hook:` values are sourced from `CYBERVISOR_LLM_*` env vars, not from config file literals
+- If a stage omits `prompt_template`, the default template is used
+- If `stages:` is omitted, the default five-stage pipeline is used
+- If `stages:` is provided, `cybervisor` runs the stages exactly as configured
+- Stages may optionally declare a `contract` for required result artifacts and a `next_stage` for explicit success-path routing
+- When a review stage can route `changes_requested` to a correction stage, set that review stage's `next_stage` explicitly for the `approved` path instead of relying on linear order
+- Use `--start-stage STAGE_NAME` to skip earlier stages and begin execution at the named stage
+
+Review/fix loop example:
+
+```yaml
+pipeline:
+  agent_tool: claude
+
+stages:
+  - name: Implement
+
+  - name: Review Code
+    next_stage: Verify
+    prompt_template: |
+      Review the implementation.
+      Write the final result to .cybervisor/contracts/artifacts/Review Code.yaml.
+    contract:
+      allowed_statuses: [approved, changes_requested]
+      routes:
+        changes_requested:
+          next_stage: Fix Code
+          injections: [summary, details, actions]
+
+  - name: Fix Code
+    next_stage: Review Code
+    prompt_template: |
+      Fix the issues described by the latest review.
+      Full contract:
+      {latest_contract_yaml}
+      Summary:
+      {latest_contract_summary}
+      Details:
+      {latest_contract_details_yaml}
+      Actions:
+      {latest_contract_actions_yaml}
+
+  - name: Verify
+```
+
+In this pattern:
+
+- `Review Code` with `status: approved` goes to `Verify`
+- `Review Code` with `status: changes_requested` goes to `Fix Code`
+- `Fix Code` loops back to `Review Code`
+- If `Review Code` omitted `next_stage: Verify`, a linear stage list would otherwise fall through to `Fix Code`
+- Contract prompt guides live at `.cybervisor/contracts/prompts/[Stage Name].md`
+
+## Runtime behavior
+
+For `gemini` and `claude` runs, `cybervisor`:
+
+1. Performs preflight checks.
+2. Writes shared hook runtime metadata into `.cybervisor/hooks/`.
+3. Persists an exact settings snapshot in `.cybervisor/hooks/`.
+4. Patches the active tool settings file so the selected agent invokes the packaged `cybervisor-agent-hook` entry point.
+5. Starts the agent in a dedicated process group when supported.
+6. Uses the runtime hook to classify autonomy decisions as `approve` or `block`, then adapts those into the selected tool's native hook output so the agent continues autonomously.
+7. If the active stage declares a contract, uses the same hook runtime to block completion until the required artifact exists and is structurally valid.
+8. Streams agent output into stderr and the stage log file.
+9. Re-validates contract artifacts after agent exit, then routes by contract status or explicit `next_stage` when configured.
+10. Restores settings and removes runtime files on success, failure, or interrupt.
+
+Generated artifacts:
+
+- `.cybervisor/logs/cybervisor.log.jsonl`: structured run log
+- `.cybervisor/logs/stages/<stage_name>.jsonl`: captured transcript per stage
+- `.cybervisor/contracts/artifacts/*.yaml`: optional stage-result artifacts for contract-enabled stages
+- `.cybervisor/contracts/prompts/*.md`: authored contract prompt guides for contract-enabled stages
+
+## Development
+
+Validation commands used by this repo:
+
+```bash
+uv run mypy --strict src
+uv run pytest
+```
+
+Useful focused runs:
+
+```bash
+uv run pytest tests/integration/test_pipeline_e2e.py
+uv run pytest tests/unit/test_hooks.py tests/unit/test_pipeline.py tests/unit/test_signals.py
+```
+
+## Publish
+
+Build distributions:
+
+```bash
+uv build
+```
+
+Check the generated artifacts locally:
+
+```bash
+python -m zipfile -l dist/*.whl
+tar -tf dist/*.tar.gz
+```
+
+Upload to PyPI with a token:
+
+```bash
+export UV_PUBLISH_TOKEN=your-pypi-token
+uv publish
+```
+
+Optional dry run against TestPyPI:
+
+```bash
+export UV_PUBLISH_TOKEN=your-testpypi-token
+uv publish --index testpypi
+```
+
+If the version already exists on PyPI, bump `version` in `pyproject.toml` and `src/cybervisor/__init__.py` before rebuilding.
+
+## Manual demo workflow
+
+The repository includes a demo bootstrap helper:
+
+```bash
+scripts/e2e-demo-project.sh
+```
+
+That script:
+
+- creates a fresh demo workspace with `scripts/init-demo-project.sh`
+- supports `--agent-tool claude|gemini` and defaults to `claude`
+- optionally starts a local deterministic hook verifier stub when run with `--with-local-api`
+- copies `templates/demo/.env` into the demo workspace as `.env`
+- prints the exact `cd` and `cybervisor` command to run manually in your shell
+- reminds you to install the CLI first if `cybervisor` is not yet on your `PATH`
+
+## Specs Directory
+
+Feature folders under `specs/` are archival implementation artifacts after delivery. The current source of truth for runtime behavior is the checked-in code plus the main project docs and constitution.
+
+## Repository layout
+
+```text
+src/cybervisor/        Core CLI package
+assets/hooks/          Standalone runtime hook source
+scripts/               Demo bootstrap and end-to-end scripts
+templates/demo/        Demo project scaffold
+tests/                 Unit and integration coverage
+specs/                 Speckit feature artifacts
+.specify/              Constitution, templates, and repo scripts
+AGENTS.md              Symlink to .specify/memory/constitution.md
+GEMINI.md              Symlink to AGENTS.md
+CLAUDE.md              Symlink to AGENTS.md
+```
+
+## Agent docs
+
+The agent mandate files are symlinked by design:
+
+- `AGENTS.md` -> `.specify/memory/constitution.md`
+- `GEMINI.md` -> `AGENTS.md`
+- `CLAUDE.md` -> `AGENTS.md`
+
+If mandate content needs to change, update `.specify/memory/constitution.md`, not the symlinks.

cybervisor-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "cybervisor"
+version = "0.1.0"
+description = "Autonomous CLI supervisor for staged AI workflows"
+readme = {file = "README.md", content-type = "text/markdown"}
+requires-python = ">=3.11"
+authors = [
+  {name = "crzidea"},
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27.0",
+  "pyyaml>=6.0.3",
+  "setproctitle>=1.3.4; platform_system != 'Windows'",
+]
+
+[project.urls]
+Homepage = "https://github.com/crzidea/cybervisor"
+Repository = "https://github.com/crzidea/cybervisor"
+Issues = "https://github.com/crzidea/cybervisor/issues"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.0.0",
+  "playwright>=1.50.0",
+  "mypy>=1.10.0",
+  "types-pyyaml>=6.0.12.20250915",
+]
+
+[tool.uv]
+default-groups = ["dev"]
+
+[project.scripts]
+cybervisor = "cybervisor.cli:main"
+cybervisor-agent-hook = "cybervisor.agent_hook:main"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+cybervisor = ["assets/hooks/*.md"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+mypy_path = "src"
+packages = ["cybervisor"]

cybervisor-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cybervisor-0.1.0/src/cybervisor/__init__.py

@@ -0,0 +1,3 @@
+"""cybervisor package."""
+
+__version__ = "0.1.0"

cybervisor-0.1.0/src/cybervisor/__main__.py

@@ -0,0 +1,3 @@
+from cybervisor.cli import main
+
+raise SystemExit(main())

cybervisor-0.1.0/src/cybervisor/adapters/__init__.py

@@ -0,0 +1,3 @@
+from cybervisor.adapters.registry import get_adapter, supported_agent_names
+
+__all__ = ["get_adapter", "supported_agent_names"]