harnessweaver-cli 0.7.1__tar.gz → 0.7.2__tar.gz

{harnessweaver_cli-0.7.1 → harnessweaver_cli-0.7.2}/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to the `harnessweaver` command and its project templates. Th
 
 ## [Unreleased]
 
+## 0.7.2 - 2026-11-08
+
+### Changed
+
+- `harnessweaver init` ends with next steps that work right after `uvx --from harnessweaver-cli harnessweaver init`, with nothing installed yet: `uv sync`, then `uv run harnessweaver spec validate --env offline` and `uv run harnessweaver test`. The templates' READMEs run their commands the same way, and the package's README uses absolute links, which work on PyPI.
+
+### Fixed
+
+- A template's `app/main.py` now prints why a run didn't complete, as `error: <code>: <message>` (for example `error: provider_error: openai.chat needs $LITELLM_API_KEY`), and the `chat` template's terminal app shows the reason next to the status. A first run against a real model with no key or no gateway printed only `status: failed` and `output: None`.
+
 ## 0.7.1 - 2026-11-01
 
 The first version published to PyPI.

{harnessweaver_cli-0.7.1 → harnessweaver_cli-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: harnessweaver-cli
-Version: 0.7.1
+Version: 0.7.2
 Summary: Developer tooling for HarnessWeaver: the harnessweaver command.
 Author-email: Muthu Kumaran R <rsmk7new@gmail.com>
 License-Expression: Apache-2.0
@@ -23,22 +23,25 @@ Description-Content-Type: text/markdown
 
 # harnessweaver-cli
 
-Developer tooling for [HarnessWeaver](../../README.md). Installs the `harnessweaver` command. The full reference, with every option and exit code, is [docs/cli.md](../../docs/cli.md).
+Developer tooling for [HarnessWeaver](https://github.com/Wise-DreamerZ/HarnessWeaver). Installs the `harnessweaver` command. The full reference, with every option and exit code, is [the CLI page](https://harnessweaver.wisedreamerz.com/docs/cli/) of the docs.
 
 ```bash
 uv add --dev harnessweaver-cli
-harnessweaver --help
+uv run harnessweaver --help
 ```
 
 ## Start a project
 
 ```bash
-harnessweaver init invoice-bot              # the extraction template; -t picks another
+uvx --from harnessweaver-cli harnessweaver init invoice-bot   # the extraction template; -t picks another
 cd invoice-bot
-harnessweaver spec validate --env offline   # load it the way the app will
-harnessweaver test                          # its tests, offline
+uv sync                                                        # the project's own dependencies, the CLI among them
+uv run harnessweaver spec validate --env offline               # load it the way the app will
+uv run harnessweaver test                                      # its tests, offline
 ```
 
+`uvx` runs the command once without installing it. A new project lists `harnessweaver-cli` among its development dependencies, so from then on `uv run harnessweaver` is the project's own copy.
+
 `init` copies a template and puts the project name in it; there is no template
 language. A plugin's templates are named `<namespace>.<template>`
 (`harnessweaver init -t acme.rag`). Every template's output passes its own tests

{harnessweaver_cli-0.7.1 → harnessweaver_cli-0.7.2}/README.md

@@ -1,21 +1,24 @@
 # harnessweaver-cli
 
-Developer tooling for [HarnessWeaver](../../README.md). Installs the `harnessweaver` command. The full reference, with every option and exit code, is [docs/cli.md](../../docs/cli.md).
+Developer tooling for [HarnessWeaver](https://github.com/Wise-DreamerZ/HarnessWeaver). Installs the `harnessweaver` command. The full reference, with every option and exit code, is [the CLI page](https://harnessweaver.wisedreamerz.com/docs/cli/) of the docs.
 
 ```bash
 uv add --dev harnessweaver-cli
-harnessweaver --help
+uv run harnessweaver --help
 ```
 
 ## Start a project
 
 ```bash
-harnessweaver init invoice-bot              # the extraction template; -t picks another
+uvx --from harnessweaver-cli harnessweaver init invoice-bot   # the extraction template; -t picks another
 cd invoice-bot
-harnessweaver spec validate --env offline   # load it the way the app will
-harnessweaver test                          # its tests, offline
+uv sync                                                        # the project's own dependencies, the CLI among them
+uv run harnessweaver spec validate --env offline               # load it the way the app will
+uv run harnessweaver test                                      # its tests, offline
 ```
 
+`uvx` runs the command once without installing it. A new project lists `harnessweaver-cli` among its development dependencies, so from then on `uv run harnessweaver` is the project's own copy.
+
 `init` copies a template and puts the project name in it; there is no template
 language. A plugin's templates are named `<namespace>.<template>`
 (`harnessweaver init -t acme.rag`). Every template's output passes its own tests

{harnessweaver_cli-0.7.1 → harnessweaver_cli-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "harnessweaver-cli"
-version = "0.7.1"
+version = "0.7.2"
 description = "Developer tooling for HarnessWeaver: the harnessweaver command."
 readme = "README.md"
 license = "Apache-2.0"

{harnessweaver_cli-0.7.1 → harnessweaver_cli-0.7.2}/src/harnessweaver_cli/scaffold.py

@@ -137,10 +137,13 @@ def init(
         raise fail(f"invalid project name {app_name!r}: use lowercase letters, digits and dashes")
     written = render_template(template, directory, app_name, force=force)
     typer.echo(f"created {len(written)} files in {directory} from the {template} template")
+    # The project installs its own CLI, so these steps work right after
+    # `uvx --from harnessweaver-cli harnessweaver init`, with nothing on PATH yet.
     typer.echo("next:")
     typer.echo(f"  cd {directory}")
-    typer.echo("  harnessweaver spec validate --env offline")
-    typer.echo("  harnessweaver test")
+    typer.echo("  uv sync")
+    typer.echo("  uv run harnessweaver spec validate --env offline")
+    typer.echo("  uv run harnessweaver test")
 
 
 def run_tests(

{harnessweaver_cli-0.7.1 → harnessweaver_cli-0.7.2}/src/harnessweaver_cli/templates/agent/README.md

@@ -8,11 +8,12 @@ A support agent that looks up orders and issues refunds. A Pydantic AI agent run
 - `evals/redteam.yaml` is the red-team set: injected instructions and over-the-limit refunds are blocked, and a large refund waits for a person.
 
 ```bash
-harnessweaver spec validate --env offline     # check the spec
-harnessweaver test                            # run the tests offline
-harnessweaver eval run --env offline          # grade the red-team set
-harnessweaver policy test                     # once you write policy_tests.yaml
-HARNESSWEAVER_ENV=offline python -m app.main  # ask the agent once
+uv sync                                              # install the project and its tools
+uv run harnessweaver spec validate --env offline     # check the spec
+uv run harnessweaver test                            # run the tests offline
+uv run harnessweaver eval run --env offline          # grade the red-team set
+uv run harnessweaver policy test                     # once you write policy_tests.yaml
+HARNESSWEAVER_ENV=offline uv run python -m app.main  # ask the agent once
 ```
 
 Approve a waiting refund with `harness.approve(run_id, approval_id, approver=...)`; the agent continues from where it stopped, and only the approved call runs. After changing a tool's description or schema, review it and run `harnessweaver tools pin`.

{harnessweaver_cli-0.7.1 → harnessweaver_cli-0.7.2}/src/harnessweaver_cli/templates/agent/app/main.py

@@ -13,6 +13,8 @@ async def main() -> None:
     result = await harness.run("support", "Where is my order A-1001?", principal="demo")
     print(f"status: {result.status.value}")
     print(f"output: {result.output}")
+    if result.error is not None:  # why the run didn't complete
+        print(f"error: {result.error.code.value}: {result.error.message}")
 
 
 if __name__ == "__main__":

{harnessweaver_cli-0.7.1 → harnessweaver_cli-0.7.2}/src/harnessweaver_cli/templates/chat/README.md

@@ -8,8 +8,9 @@ A chat assistant whose answers stream to the user, governed by HarnessWeaver.
 - `harness.offline.yaml` swaps the model for a scripted one that streams, so everything runs with no network.
 
 ```bash
-harnessweaver spec validate --env offline     # check the spec
-harnessweaver test                            # run the tests offline
-harnessweaver eval run --env offline          # grade evals/golden.yaml
-HARNESSWEAVER_ENV=offline python -m app.main  # chat in the terminal
+uv sync                                              # install the project and its tools
+uv run harnessweaver spec validate --env offline     # check the spec
+uv run harnessweaver test                            # run the tests offline
+uv run harnessweaver eval run --env offline          # grade evals/golden.yaml
+HARNESSWEAVER_ENV=offline uv run python -m app.main  # chat in the terminal
 ```

{harnessweaver_cli-0.7.1 → harnessweaver_cli-0.7.2}/src/harnessweaver_cli/templates/chat/app/main.py

@@ -26,7 +26,8 @@ async def main() -> None:
                 if event.type == "chunk" and event.chunk is not None:
                     print(event.chunk.delta, end="", flush=True)
             result = await harness.result(run_id)
-            print("" if result.ok else f"[{result.status.value}]")
+            why = f": {result.error.message}" if result.error is not None else ""
+            print("" if result.ok else f"[{result.status.value}{why}]")
 
 
 if __name__ == "__main__":

{harnessweaver_cli-0.7.1 → harnessweaver_cli-0.7.2}/src/harnessweaver_cli/templates/extraction/README.md

@@ -6,11 +6,12 @@ Typed extraction from customer support messages, governed by HarnessWeaver.
 - `harness.offline.yaml` swaps the model for a scripted one, so everything runs with no network.
 
 ```bash
-harnessweaver spec validate --env offline     # check the spec
-harnessweaver doctor --env offline            # adoption level and what to do next
-harnessweaver test                            # run the tests offline
-harnessweaver eval run --env offline          # grade evals/golden.yaml; exits 1 on a regression
-HARNESSWEAVER_ENV=offline python -m app.main  # run the task once
+uv sync                                              # install the project and its tools
+uv run harnessweaver spec validate --env offline     # check the spec
+uv run harnessweaver doctor --env offline            # adoption level and what to do next
+uv run harnessweaver test                            # run the tests offline
+uv run harnessweaver eval run --env offline          # grade evals/golden.yaml; exits 1 on a regression
+HARNESSWEAVER_ENV=offline uv run python -m app.main  # run the task once
 ```
 
 To call a real model, run LiteLLM Proxy at `base_url`, set `LITELLM_API_KEY`, and map the `fast` alias to a model in `harness.yaml`.

{harnessweaver_cli-0.7.1 → harnessweaver_cli-0.7.2}/src/harnessweaver_cli/templates/extraction/app/main.py

@@ -15,6 +15,8 @@ async def main() -> None:
     result = await harness.run("extract", Message(text=SAMPLE), principal="demo")
     print(f"status: {result.status.value}")
     print(f"output: {result.output}")
+    if result.error is not None:  # why the run didn't complete
+        print(f"error: {result.error.code.value}: {result.error.message}")
 
 
 if __name__ == "__main__":

{harnessweaver_cli-0.7.1 → harnessweaver_cli-0.7.2}/src/harnessweaver_cli/templates/rag/README.md

@@ -8,10 +8,11 @@ Answers from a knowledge base, with sources, governed by HarnessWeaver.
 - `harness.offline.yaml` swaps the model for a scripted one, so everything runs with no network.
 
 ```bash
-harnessweaver spec validate --env offline     # check the spec
-harnessweaver test                            # run the tests offline
-harnessweaver eval run --env offline          # grade evals/golden.yaml
-HARNESSWEAVER_ENV=offline python -m app.main  # answer one question
+uv sync                                              # install the project and its tools
+uv run harnessweaver spec validate --env offline     # check the spec
+uv run harnessweaver test                            # run the tests offline
+uv run harnessweaver eval run --env offline          # grade evals/golden.yaml
+HARNESSWEAVER_ENV=offline uv run python -m app.main  # answer one question
 ```
 
 Add passages to `data/kb.yaml`, or replace the `memory` provider with a vector store plugin; the ACL re-check and the citation guard stay the same.

{harnessweaver_cli-0.7.1 → harnessweaver_cli-0.7.2}/src/harnessweaver_cli/templates/rag/app/main.py

@@ -13,6 +13,8 @@ async def main() -> None:
     result = await harness.run("answer", "How long does a refund take?", principal="demo")
     print(f"status: {result.status.value}")
     print(f"output: {result.output}")
+    if result.error is not None:  # why the run didn't complete
+        print(f"error: {result.error.code.value}: {result.error.message}")
 
 
 if __name__ == "__main__":

{harnessweaver_cli-0.7.1 → harnessweaver_cli-0.7.2}/src/harnessweaver_cli/templates/workflow/README.md

@@ -7,10 +7,11 @@ A support-ticket pipeline: clean the ticket, then classify and summarize it in p
 - `harness.offline.yaml` swaps the model for a scripted one whose first draft misses the category, so the review loop shows offline.
 
 ```bash
-harnessweaver spec validate --env offline     # check the spec
-harnessweaver test                            # run the tests offline
-harnessweaver eval run --env offline          # grade evals/golden.yaml
-HARNESSWEAVER_ENV=offline python -m app.main  # triage one ticket
+uv sync                                              # install the project and its tools
+uv run harnessweaver spec validate --env offline     # check the spec
+uv run harnessweaver test                            # run the tests offline
+uv run harnessweaver eval run --env offline          # grade evals/golden.yaml
+HARNESSWEAVER_ENV=offline uv run python -m app.main  # triage one ticket
 ```
 
 Finished steps are checkpointed: after an approval, only the interrupted step runs again.

{harnessweaver_cli-0.7.1 → harnessweaver_cli-0.7.2}/src/harnessweaver_cli/templates/workflow/app/main.py

@@ -14,6 +14,8 @@ async def main() -> None:
     result = await harness.run("triage", ticket, principal="demo")
     print(f"status: {result.status.value}")
     print(f"output: {result.output}")
+    if result.error is not None:  # why the run didn't complete
+        print(f"error: {result.error.code.value}: {result.error.message}")
 
 
 if __name__ == "__main__":

{harnessweaver_cli-0.7.1 → harnessweaver_cli-0.7.2}/tests/test_init.py

@@ -1,7 +1,9 @@
 """``harnessweaver init`` and ``harnessweaver test``, including T6: a template's own tests pass."""
 
+import importlib
 import sys
 from pathlib import Path
+from types import ModuleType
 
 import pytest
 from typer.testing import CliRunner
@@ -9,7 +11,7 @@ from typer.testing import CliRunner
 import harnessweaver as hw
 from harnessweaver.core.registry import PluginCatalog, PluginSource
 from harnessweaver_cli.main import app
-from harnessweaver_cli.scaffold import BUILTIN_TEMPLATES
+from harnessweaver_cli.scaffold import BUILTIN_TEMPLATES, render_template
 
 runner = CliRunner()
 
@@ -40,7 +42,62 @@ def test_init_renders_the_extraction_template(tmp_path: Path) -> None:
     assert "__app_name__" not in "".join(
         (target / f).read_text(encoding="utf-8") for f in files(target)
     )
-    assert "harnessweaver spec validate --env offline" in result.output
+    # The next steps work right after `uvx ... init`, with nothing installed yet.
+    assert "  uv sync\n" in result.output
+    assert "  uv run harnessweaver spec validate --env offline\n" in result.output
+    assert "  uv run harnessweaver test\n" in result.output
+
+
+BROKEN = "models:\n  provider: scripted\n  replies: [{ fail: true }]\n"
+"""An overlay whose model fails every call, the way a missing key or gateway does."""
+
+
+def forget_app() -> None:
+    """Drop the ``app`` modules, so the next import reads the current template's code."""
+    for name in [m for m in sys.modules if m == "app" or m.startswith("app.")]:
+        del sys.modules[name]
+
+
+def broken_app(template: str, root: Path, monkeypatch: pytest.MonkeyPatch) -> ModuleType:
+    """Render ``template`` into ``root`` with a failing model, and import its ``app.main``."""
+    render_template(template, root, "demo")
+    (root / "harness.broken.yaml").write_text(BROKEN, encoding="utf-8")
+    monkeypatch.setenv("HARNESSWEAVER_ENV", "broken")
+    monkeypatch.syspath_prepend(str(root))
+    forget_app()
+    return importlib.import_module("app.main")
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize("template", ["extraction", "rag", "agent", "workflow"])
+async def test_a_template_app_says_why_its_run_failed(
+    template: str,
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """A first run against a real model often fails (no key, no gateway): say why."""
+    try:
+        await broken_app(template, tmp_path / "demo", monkeypatch).main()
+    finally:
+        forget_app()
+    out = capsys.readouterr().out
+    assert "status: failed\n" in out
+    assert "error: provider_error: the script says this call fails\n" in out
+
+
+@pytest.mark.anyio
+async def test_the_chat_template_says_why_a_turn_failed(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    try:
+        main = broken_app("chat", tmp_path / "demo", monkeypatch)
+        messages = iter(["hello", ""])
+        monkeypatch.setattr(main, "ask", lambda: next(messages))
+        await main.main()
+    finally:
+        forget_app()
+    assert "[failed: the script says this call fails]" in capsys.readouterr().out
 
 
 def test_init_never_overwrites_without_force(tmp_path: Path) -> None: