cli-router 0.1.0__tar.gz

cli_router-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,68 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test package
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install test dependencies
+        run: python -m pip install --upgrade pip pytest
+      - name: Install package
+        run: python -m pip install -e .
+      - name: Run tests
+        run: python -m pytest tests -q
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build twine
+      - name: Build package
+        run: python -m build
+      - name: Check distributions
+        run: python -m twine check dist/*
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  pypi-publish:
+    name: Publish CLI-Router to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

cli_router-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,24 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install test dependencies
+        run: python -m pip install --upgrade pip pytest
+      - name: Install package
+        run: python -m pip install -e .
+      - name: Test
+        run: python -m pytest tests -q

cli_router-0.1.0/.gitignore

@@ -0,0 +1,224 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# CLI-Router local config and run artifacts
+/cli-router.yaml
+/.cli-router.yaml
+/PLAN.md
+/.cli-router/
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

cli_router-0.1.0/AGENTS.md

@@ -0,0 +1,204 @@
+# AGENTS.md
+
+Guidance for AI agents working in this repository.
+
+## Project Purpose
+
+CLI-Router is a Python command-line orchestrator for external AI coding CLIs. It is intentionally programmatic and non-intelligent:
+
+- It does not inspect repositories on its own unless a configured external tool does so.
+- It does not semantically choose models or providers.
+- It loads YAML config, renders prompt templates, runs configured commands, captures stdout/stderr, extracts configured output, writes artifacts, classifies failures, and applies configured fallback behavior.
+
+Keep that boundary intact. New behavior should make orchestration more reliable or configurable, not turn this package into an agent.
+
+## Source Layout
+
+- `cli_router/cli.py`: argparse CLI entry point and command dispatch.
+- `cli_router/config.py`: config discovery, merge, and validation.
+- `cli_router/runner.py`: subprocess execution, placeholder rendering, command timeout handling.
+- `cli_router/workflows.py`: `plan`, `implement`, and full `run` workflow execution.
+- `cli_router/extractors.py`: text and JSON output extraction.
+- `cli_router/failures.py`: external-tool failure classification and user-facing messages.
+- `cli_router/artifacts.py`: run directory and artifact persistence.
+- `cli_router/tools.py`: `tools list` and `tools test`.
+- `cli_router/presets/`: packaged YAML defaults/presets.
+- `examples/`: user-facing example configs.
+- `tests/`: pytest coverage using fake subprocess CLIs, not real Claude/Codex calls.
+
+## Development Commands
+
+Use these from the repository root:
+
+```bash
+python -m pytest tests -q
+python -m cli_router.cli --help
+python -m cli_router.cli check
+```
+
+Package verification:
+
+```bash
+python -m build
+python -m twine check dist/*
+```
+
+Editable install may fail on system Python environments protected by PEP 668. Use a virtual environment:
+
+```bash
+python -m venv /tmp/cli-router-venv
+/tmp/cli-router-venv/bin/python -m pip install -e .
+/tmp/cli-router-venv/bin/cli-router --help
+```
+
+`python -m build` and package install may need network access to fetch build dependencies.
+
+## Configuration Semantics
+
+Config lookup order is:
+
+1. `./cli-router.yaml`
+2. `./.cli-router.yaml`
+3. `~/.config/cli-router/config.yaml`
+4. Built-in defaults from `cli_router/presets/generic.yaml`
+
+Config version is currently `version: 1`.
+
+Supported placeholders are literal token replacements:
+
+- `{prompt}`
+- `{user_prompt}`
+- `{plan_path}`
+
+Do not switch to Python `str.format` semantics without a strong reason. Current literal replacement intentionally allows command snippets and prompts to contain unrelated braces.
+
+Workflow stages use:
+
+- `tool`: primary tool name.
+- `fallback_tools`: optional ordered list of tool names to try after failed attempts.
+- `input_template`: rendered prompt sent as `{prompt}` to the tool command.
+- `output_file`: planner output path, usually `PLAN.md`.
+
+Tool config supports:
+
+- `command`: list-form command preferred; string-form is parsed with `shlex.split`.
+- `output.format`: `text` or `json`.
+- `output.extract`: top-level or dotted JSON field path.
+- `timeout_seconds`: optional positive number; timeout returns exit code `124`.
+
+## Runtime Artifacts
+
+Runs write to `.cli-router/runs/<timestamp>/`.
+
+Primary stage attempt artifacts use the stage id:
+
+- `planner.stdout`
+- `planner.stderr`
+- `planner.extracted.md`
+
+Fallback attempts include the tool name:
+
+- `planner.codex-planner.stdout`
+- `planner.codex-planner.stderr`
+- `planner.codex-planner.extracted.md`
+
+Every run writes `run.yaml` containing stage summaries, commands, return codes, extracted output, and `failure_kind`.
+
+`.cli-router/runs/` is ignored by git. Do not commit generated run artifacts.
+
+## Failure Behavior
+
+Failure classification lives in `cli_router/failures.py`.
+
+Current `failure_kind` values include:
+
+- `usage_limit`
+- `unsupported_model`
+- `timeout`
+- `command_not_found`
+- `command_failed`
+- `extraction_failed`
+
+Known real-world messages are covered by tests, including:
+
+- Claude: `You've hit your session limit ...`
+- Claude/rate/quota variants containing usage limit, session limit, rate limit, quota, 429, or too many requests.
+- Codex/OpenAI unsupported model messages such as `model is not supported`.
+
+When adding a new failure classifier, add a focused test in `tests/test_failures.py` using the real observed stdout/stderr text when possible.
+
+## Testing Rules
+
+Prefer tests that use temporary configs and fake commands such as:
+
+```python
+[sys.executable, "-c", "import json; print(json.dumps({'result': 'plan'}))"]
+```
+
+Do not require real Claude, Codex, Hermes, OpenAI, network access, or credentials in the normal test suite.
+
+Use `tmp_path` and `monkeypatch.chdir(tmp_path)` for workflow tests that write `PLAN.md` or `.cli-router/runs/`.
+
+When changing workflow behavior, cover:
+
+- plan-only execution
+- full planner-to-coder execution
+- missing `PLAN.md` for `implement`
+- nonzero command failures
+- fallback ordering and artifact names
+- failure classification and exit codes
+
+When changing packaging, verify:
+
+```bash
+python -m pytest tests -q
+python -m build
+python -m twine check dist/*
+```
+
+## Real External CLI Trials
+
+Real Claude/Codex trials are useful but should be explicit and isolated.
+
+Use a temporary directory such as `/tmp/cli-router-real-test`; do not run real provider trials in the repo root unless the user explicitly wants repo files changed.
+
+Recommended safety controls:
+
+- Add `timeout_seconds` to every real tool.
+- For Codex trials, prefer `codex --ask-for-approval never exec --skip-git-repo-check --ephemeral --sandbox read-only ...`.
+- Use harmless prompts and include "Do not edit files" in `input_template`.
+- Expect provider/model availability to vary by account; classify and report unsupported model failures instead of treating them as code defects.
+
+Known observed Codex behavior in this environment:
+
+- Local Codex config default model was `gpt-5.5`.
+- `gpt-5` and `gpt-5-codex` returned unsupported-model errors for the ChatGPT-backed account.
+- `gpt-5.5` succeeded for both planner and coder in the real fallback trial.
+
+These observations are environment-specific. Do not hardcode them into package defaults without a product decision.
+
+## Design Constraints
+
+- Keep the CLI stable: `cli-router run`, `plan`, `implement`, `check`, `config show`, `tools list`, `tools test <name>`.
+- Keep dependencies minimal. Current runtime dependencies are `pyyaml` and `rich`; the CLI uses `argparse`.
+- Prefer list-form subprocess commands in examples and tests.
+- Preserve stdout/stderr exactly in artifacts. Do not redact or transform raw logs unless a user explicitly requests a privacy feature.
+- Avoid hidden behavior. If CLI-Router retries or falls back, make that visible through summaries and `run.yaml`.
+- Do not make built-in presets depend on provider credentials or paid services for basic `cli-router check`.
+- Do not mutate user configuration unless implementing an explicit config-editing command.
+
+## Git Hygiene
+
+The worktree may contain user or generated changes. Do not revert files you did not intentionally change.
+
+Generated files that should normally remain untracked:
+
+- `.cli-router/runs/`
+- `dist/`
+- `build/`
+- `*.egg-info/`
+- `__pycache__/`
+- `.pytest_cache/`
+
+Before finalizing substantive changes, run `git status --short` and report any verification commands run.
+

cli_router-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Initial PyPI-ready CLI-Router MVP.