axor-cli 0.1.0__tar.gz

axor_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,107 @@
+name: CI/CD
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*.*.*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Checkout axor-core
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ github.repository_owner }}/axor-core
+          path: axor-core
+
+      - name: Checkout axor-claude
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ github.repository_owner }}/axor-claude
+          path: axor-claude
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          pip install -e axor-core/
+          pip install -e axor-claude/
+          pip install -e ".[dev]"
+
+      - name: Check entrypoint
+        run: |
+          python - << 'EOF'
+          import tomllib
+          with open("pyproject.toml", "rb") as f:
+              cfg = tomllib.load(f)
+          scripts = cfg["project"]["scripts"]
+          assert "axor" in scripts, "axor entrypoint missing"
+          assert scripts["axor"] == "axor_cli.main:main"
+          print("✓ axor entrypoint registered")
+          EOF
+
+      - name: Run unit tests
+        run: pytest tests/unit/ -v --tb=short
+
+  publish:
+    name: Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches package version
+        run: |
+          python - << 'EOF'
+          import pathlib
+          import re
+          import sys
+          import tomllib
+
+          ref = "${{ github.ref_name }}"
+          m = re.fullmatch(r"v(\d+\.\d+\.\d+)", ref)
+          if not m:
+              print(f"Tag {ref!r} must match vX.Y.Z")
+              sys.exit(1)
+
+          tag_version = m.group(1)
+          data = tomllib.loads(pathlib.Path("pyproject.toml").read_text(encoding="utf-8"))
+          pkg_version = data["project"]["version"]
+
+          if tag_version != pkg_version:
+              print(f"Version mismatch: tag={tag_version}, pyproject={pkg_version}")
+              sys.exit(1)
+
+          print(f"Version check passed: {pkg_version}")
+          EOF
+
+      - name: Build
+        run: |
+          pip install hatchling build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

axor_cli-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.pytest_cache/
+.coverage

axor_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0 — 2025-04-12
+
+Initial release.
+
+### Added
+- Core governance kernel (axor-core)
+- Claude Code adapter (axor-claude)  
+- CLI with interactive REPL (axor-cli)
+- Dynamic policy selection (7-policy matrix)
+- ContextManager with 11 waste categories
+- ToolResultBus for async tool loop
+- Federation via spawn_child with child_executor
+- CancelToken cooperative cancellation
+- BudgetPolicyEngine (60/80/90/95% thresholds)
+- TraceCollector with lineage (17 event kinds)

axor_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to axor-cli
+
+## Setup
+
+```bash
+git clone https://github.com/your-org/axor-cli
+cd axor-cli
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[claude,dev]"
+```
+
+## Running tests
+
+```bash
+pytest tests/unit/          # no API key needed
+```
+
+## Architecture
+
+axor-cli is a thin shell around axor-core + adapters:
+
+- `auth.py`     — key management only, no business logic
+- `adapters.py` — lazy imports, delegates to adapter's make_session()
+- `display.py`  — terminal output only, no execution logic
+- `streaming.py` — connects GovernedSession to terminal display
+- `main.py`     — REPL + argument parsing
+
+**No governance logic in CLI.** Policy, context, capabilities — all in axor-core.
+
+## Adding an adapter
+
+1. Add entry to `_REGISTRY` in `adapters.py`
+2. Add env var to `_ENV_VARS` in `auth.py`
+3. Adapter package must expose `make_session(**kwargs) -> GovernedSession`
+
+## Pull request checklist
+
+- [ ] `pytest tests/unit/` passes
+- [ ] No governance logic added to CLI
+- [ ] New adapter registered in both `adapters.py` and `auth.py`

axor_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Axor Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

axor_cli-0.1.0/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: axor-cli
+Version: 0.1.0
+Summary: CLI for axor-core governance kernel — governed agent sessions in your terminal
+Project-URL: Bug Tracker, https://github.com/Bucha11/axor-cli/issues
+Project-URL: Changelog, https://github.com/Bucha11/axor-cli/releases
+Project-URL: Repository, https://github.com/Bucha11/axor-cli
+License: MIT
+License-File: LICENSE
+Keywords: agents,axor,claude,cli,governance,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Terminals
+Requires-Python: >=3.11
+Requires-Dist: axor-core>=0.1.0
+Provides-Extra: all
+Requires-Dist: axor-claude>=0.1.0; extra == 'all'
+Requires-Dist: axor-openai>=0.1.0; extra == 'all'
+Provides-Extra: claude
+Requires-Dist: axor-claude>=0.1.0; extra == 'claude'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: axor-openai>=0.1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# axor-cli
+
+[![CI](https://github.com/Bucha11/axor-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Bucha11/axor-cli/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/axor-cli)](https://pypi.org/project/axor-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/axor-cli)](https://pypi.org/project/axor-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+
+**Governed agent sessions in your terminal.**
+
+Run Claude (or other LLMs) under axor-core governance — controlled context, explicit tool permissions, token optimization, and full audit trail.
+
+---
+
+## Installation
+
+```bash
+# CLI + Claude adapter
+pip install axor-cli[claude]
+
+# or step by step
+pip install axor-cli
+pip install axor-claude
+```
+
+---
+
+## Quick Start
+
+```bash
+# Interactive REPL
+axor claude
+
+# Single task and exit
+axor claude "refactor the auth module"
+
+# With options
+axor claude --policy readonly "review this PR for security issues"
+axor claude --limit 100000 "migrate the entire codebase to Go"
+axor claude --model claude-opus-4-5 "design the new architecture"
+```
+
+---
+
+## Authentication
+
+On first run, axor asks for your API key and saves it to `~/.axor/config.toml` (permissions: 600):
+
+```
+$ axor claude
+
+  No API key found for 'claude'.
+  (checked: --api-key flag, ANTHROPIC_API_KEY env var, ~/.axor/config.toml)
+
+  Anthropic API key (hidden): ****
+  Save to ~/.axor/config.toml for future sessions? [Y/n]: y
+  ✓ Key saved to ~/.axor/config.toml (permissions: 600)
+```
+
+Key priority (highest to lowest):
+
+| Source | When used |
+|--------|-----------|
+| `--api-key` flag | One-off override, never saved |
+| `ANTHROPIC_API_KEY` env var | CI/CD, containers |
+| `~/.axor/config.toml` | Persistent, set via `/auth` |
+
+Manage saved keys with `/auth` in the REPL:
+
+```
+> /auth              # set or update key (prompts, then saves)
+> /auth --show       # show where key is loaded from (never shows the key)
+> /auth --clear      # remove saved key
+```
+
+---
+
+## Interactive REPL
+
+```
+$ axor claude
+axor v0.1.0 │ adapter: claude │ model: claude-sonnet-4-5
+Type a task, a /command, or 'exit' to quit.
+
+> refactor the auth module to add rate limiting
+  ↳ read(path='auth.py') → def authenticate(token):…
+  ↳ write(path='auth.py') → …
+✓ done │ policy: moderate_mutative │ tokens: 1,247 (in: 800 out: 447)
+
+> /cost
+  → Tokens spent this session: 1,247
+
+> /compact
+  → Context compaction requested — will apply on next execution.
+
+> exit
+  → Bye.
+```
+
+### REPL commands
+
+| Command | Class | Description |
+|---------|-------|-------------|
+| `/auth` | built-in | Set or update API key |
+| `/auth --clear` | built-in | Remove saved key |
+| `/auth --show` | built-in | Show key source (never the key itself) |
+| `/model` | built-in | List available models |
+| `/help` | built-in | All commands |
+| `/cost` | governed | Token usage for this session |
+| `/policy` | governed | Last execution policy |
+| `/compact` | governed | Compress context |
+| `/status` | governed | Session overview |
+| `/tools` | governed | Tools available to current policy |
+| `exit` / `quit` / `^D` | — | Exit |
+
+Governed commands (`/cost`, `/policy`, etc.) are handled by axor-core — they never reach the executor.
+
+---
+
+## CLI options
+
+```
+axor <adapter> [task] [options]
+
+Arguments:
+  adapter           Adapter: claude, openai
+  task              Single task — runs and exits (skips REPL)
+
+Options:
+  -p, --policy      Preset: readonly, sandboxed, standard, federated
+  -l, --limit       Soft token limit (budget optimization signals)
+  -m, --model       Model override (e.g. claude-opus-4-5)
+  --api-key         API key for this session (never saved)
+  --tools           Tools to enable (default: read write bash search glob)
+  --no-skills       Skip CLAUDE.md and .claude/skills/
+  --no-plugins      Skip .claude/plugins/
+  --list-adapters   Show installed adapters and exit
+  --version         Show version
+```
+
+---
+
+## Examples
+
+```bash
+# Analysis only — no writes, no bash
+axor claude --policy readonly "find all security issues in auth.py"
+
+# Specific tools only
+axor claude --tools read search "find all TODO comments"
+
+# Large migration with budget
+axor claude --limit 200000 "rewrite the API layer to use async/await"
+
+# Specific model
+axor claude --model claude-opus-4-5 "design the new microservices architecture"
+
+# No extension loading (faster startup)
+axor claude --no-skills --no-plugins "quick question"
+
+# CI — reads key from env, single task, exits
+ANTHROPIC_API_KEY=sk-ant-... axor claude "run code review"
+```
+
+---
+
+## Adapters
+
+```bash
+axor --list-adapters
+
+Available adapters:
+  claude       installed
+  openai       not installed  →  pip install axor-openai
+```
+
+Each adapter package must expose `make_session(**kwargs) -> GovernedSession`.
+
+---
+
+## Streaming output
+
+When an adapter supports streaming (e.g. `axor-claude`), text is printed to the terminal as it arrives — no waiting for the full response. A spinner shows while Claude is thinking.
+
+Non-streaming adapters print the full output when execution completes.
+
+---
+
+## Config file
+
+`~/.axor/config.toml` — auto-created with `chmod 600`:
+
+```toml
+[claude]
+api_key = "sk-ant-..."
+
+[openai]
+api_key = "sk-..."
+```
+
+---
+
+## Repository structure
+
+```
+axor-cli/
+├── axor_cli/
+│   ├── main.py        CLI entrypoint, REPL loop, argument parsing
+│   ├── auth.py        Key management — ~/.axor/config.toml, priority chain
+│   ├── adapters.py    Adapter registry, lazy imports, build_session()
+│   ├── display.py     Terminal formatting — color, spinner, streaming output
+│   ├── streaming.py   Connects GovernedSession to terminal display
+│   └── _version.py
+└── tests/
+    ├── conftest.py         tmp_home fixture, anthropic mock
+    └── unit/
+        ├── test_auth.py        11 tests — config file, permissions, priority
+        ├── test_adapters.py     8 tests — registry, availability, session build
+        ├── test_display.py      display formatting
+        └── test_streaming.py   11 tests — output, callback, error, policy override
+```
+
+---
+
+## Running tests
+
+```bash
+pytest tests/unit/   # no API key needed, anthropic SDK mocked
+```
+
+---
+
+## Requirements
+
+- Python 3.11+
+- `axor-core >= 0.1.0`
+- At least one adapter: `axor-claude` or `axor-openai`
+
+---
+
+## License
+
+MIT