agnara-cli 1.0.2__tar.gz → 1.0.4__tar.gz

{agnara_cli-1.0.2 → agnara_cli-1.0.4}/.gitignore

@@ -34,6 +34,13 @@ uv.lock.bak
 .dist-test/
 .release-validation/
 
+# Git worktrees for parallel agent work. MULTI_AGENT_PROTOCOL.md asks for a
+# sibling directory outside the checkout; `.worktrees/` is the only supported
+# location inside it. Untracked, a nested worktree makes `git status` dirty, so
+# the `repository-clean` release gate reports uncommitted changes for a tree
+# whose own content is untouched.
+/.worktrees/
+
 # Editors / OS
 .idea/
 .vscode/

{agnara_cli-1.0.2 → agnara_cli-1.0.4}/PKG-INFO

@@ -1,32 +1,40 @@
 Metadata-Version: 2.5
 Name: agnara-cli
-Version: 1.0.2
+Version: 1.0.4
 Summary: Project introspection and scaffolding CLI for Agnara.
 Project-URL: Homepage, https://github.com/Blandskron/agnara
 Project-URL: Repository, https://github.com/Blandskron/agnara
 Author-email: Agnara Maintainers <maintainers@agnara.dev>
 License: Apache-2.0
 License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Requires-Python: >=3.14
-Requires-Dist: agnara==1.0.2
+Requires-Dist: agnara==1.0.4
 Description-Content-Type: text/markdown
 
 # agnara-cli
 
 Project introspection and scaffolding CLI. Owns project/app generators, templates and diagnostics.
 
+```bash
+pip install "agnara-cli==1.0.3"
+agnara --help
+```
+
 This distribution is built and versioned with the synchronized workspace
 set. Which versions exist on an index is answered by its PyPI project page,
 not by this file: a README ships inside the artifact and cannot describe
 the state of a publication that happens after it is built.
 
 It installs the `agnara` console script.
+The governed Python exports are listed in
+[`docs/API_REFERENCE.md`](../../docs/API_REFERENCE.md); generated projects use
+the governed kernel imports. Importing a project target executes that module.
 
 - Import package: `agnara_cli`
 - Depends on: the exact synchronized `agnara` version
@@ -40,11 +48,41 @@ allowed dependency graph.
 `agnara project create`, `agnara app create` with its `app-api`, `app-mcp`,
 `app-agent` and `app-worker` profile shorthands, `agnara apps`,
 `agnara inspect`, `agnara graph`, `agnara schema openapi` and `agnara context`
-are implemented. `agnara doctor` remains ahead in the backlog.
+are implemented. The current checkout also implements the static `doctor`
+baseline described below; a development-server command remains unimplemented.
+The [maturity inventory](../../docs/MATURITY.md) records current boundaries;
+proposed commands in a specification do not make them available.
 
 `agnara --help` lists the commands the installed version actually has, which is
 the answer to trust over any list written down elsewhere.
 
+## `agnara doctor` (unreleased checkout)
+
+```bash
+agnara doctor --project path/to/project
+agnara doctor --project path/to/project --json
+```
+
+Read-only checks cover the executing Python >=3.14 baseline, strict project
+manifest, contained app directories and installed core/CLI/declared HTTP/MCP
+version metadata. A2A declarations fail with a message about missing diagnostic
+coverage, rather than claiming the provisional adapter has no runtime. Events
+declarations fail as a reserved namespace without an event runtime; Tasks
+declarations fail because no task runtime is implemented. These checks do not
+inspect those distributions' metadata and fail whether or not they are installed.
+No project or adapter code is imported, no files are written and no dependencies
+are installed.
+
+Reports always list unchecked runtime and architecture boundaries. The project's
+free-form Python constraint is not evaluated, and matching package metadata does
+not prove importability or transitive dependency compatibility. A passing
+report is not a runtime-readiness assertion. See the
+[doctor contract](../../docs/CLI_SPEC.md#agnara-doctor) and proposed ADR 0096.
+
+The versioned JSON or text report goes to stdout. Any failed check exits 1;
+all checks passing exits 0. Argument errors retain exit 2 on stderr. This
+command is unreleased checkout behavior, not a claim about the 1.0.3 wheel.
+
 ## `agnara inspect`
 
 ```bash

{agnara_cli-1.0.2 → agnara_cli-1.0.4}/README.md

@@ -2,12 +2,20 @@
 
 Project introspection and scaffolding CLI. Owns project/app generators, templates and diagnostics.
 
+```bash
+pip install "agnara-cli==1.0.3"
+agnara --help
+```
+
 This distribution is built and versioned with the synchronized workspace
 set. Which versions exist on an index is answered by its PyPI project page,
 not by this file: a README ships inside the artifact and cannot describe
 the state of a publication that happens after it is built.
 
 It installs the `agnara` console script.
+The governed Python exports are listed in
+[`docs/API_REFERENCE.md`](../../docs/API_REFERENCE.md); generated projects use
+the governed kernel imports. Importing a project target executes that module.
 
 - Import package: `agnara_cli`
 - Depends on: the exact synchronized `agnara` version
@@ -21,11 +29,41 @@ allowed dependency graph.
 `agnara project create`, `agnara app create` with its `app-api`, `app-mcp`,
 `app-agent` and `app-worker` profile shorthands, `agnara apps`,
 `agnara inspect`, `agnara graph`, `agnara schema openapi` and `agnara context`
-are implemented. `agnara doctor` remains ahead in the backlog.
+are implemented. The current checkout also implements the static `doctor`
+baseline described below; a development-server command remains unimplemented.
+The [maturity inventory](../../docs/MATURITY.md) records current boundaries;
+proposed commands in a specification do not make them available.
 
 `agnara --help` lists the commands the installed version actually has, which is
 the answer to trust over any list written down elsewhere.
 
+## `agnara doctor` (unreleased checkout)
+
+```bash
+agnara doctor --project path/to/project
+agnara doctor --project path/to/project --json
+```
+
+Read-only checks cover the executing Python >=3.14 baseline, strict project
+manifest, contained app directories and installed core/CLI/declared HTTP/MCP
+version metadata. A2A declarations fail with a message about missing diagnostic
+coverage, rather than claiming the provisional adapter has no runtime. Events
+declarations fail as a reserved namespace without an event runtime; Tasks
+declarations fail because no task runtime is implemented. These checks do not
+inspect those distributions' metadata and fail whether or not they are installed.
+No project or adapter code is imported, no files are written and no dependencies
+are installed.
+
+Reports always list unchecked runtime and architecture boundaries. The project's
+free-form Python constraint is not evaluated, and matching package metadata does
+not prove importability or transitive dependency compatibility. A passing
+report is not a runtime-readiness assertion. See the
+[doctor contract](../../docs/CLI_SPEC.md#agnara-doctor) and proposed ADR 0096.
+
+The versioned JSON or text report goes to stdout. Any failed check exits 1;
+all checks passing exits 0. Argument errors retain exit 2 on stderr. This
+command is unreleased checkout behavior, not a claim about the 1.0.3 wheel.
+
 ## `agnara inspect`
 
 ```bash

{agnara_cli-1.0.2 → agnara_cli-1.0.4}/pyproject.toml

@@ -1,20 +1,20 @@
 [project]
 name = "agnara-cli"
-version = "1.0.2"
+version = "1.0.4"
 description = "Project introspection and scaffolding CLI for Agnara."
 readme = "README.md"
 requires-python = ">=3.14"
 authors = [{name = "Agnara Maintainers", email = "maintainers@agnara.dev"}]
 license = {text = "Apache-2.0"}
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries :: Application Frameworks",
 ]
-dependencies = ["agnara==1.0.2"]
+dependencies = ["agnara==1.0.4"]
 
 [project.scripts]
 agnara = "agnara_cli._main:main"

{agnara_cli-1.0.2 → agnara_cli-1.0.4}/src/agnara_cli/__init__.py

@@ -1,8 +1,7 @@
 """Project introspection and scaffolding CLI for Agnara.
 
-Owns ``agnara project create``, ``agnara app create``, capability
-generation, introspection commands and diagnostics. Templates live here,
-never in ``agnara-core``.
+Owns project/app scaffolding and introspection commands. Templates live here,
+never in the ``agnara`` kernel.
 
 Currently implemented: ``agnara project create`` and ``agnara app create``,
 which generate a project and a bounded context from a reviewable plan,
@@ -12,11 +11,16 @@ application and presents its filtered protocol-neutral introspection
 snapshot as text or as deterministic JSON, ``agnara graph``, which draws the
 relationships in that same snapshot, ``agnara schema openapi``, which exports
 the OpenAPI document a composition already produced, and ``agnara context``,
-which writes the visible capabilities as Markdown for a model to read. Exposure
-selection and capability generation remain ahead in EPIC 0A.
+which writes the visible capabilities as Markdown for a model to read.
+App profiles and ``--with`` select generated adapter bindings. There is no
+standalone capability generator or development-server command.
 
-Depends on ``agnara-core``. Must not import a sibling adapter.
-See ``ARCHITECTURE.md`` section 15, ``docs/CLI_SPEC.md`` and EPIC 0A.
+The unreleased checkout's ``agnara doctor`` performs read-only static checks
+of the manifest, app paths and installed version metadata. Runtime registration,
+dependency cycles and architecture rules remain explicitly unchecked.
+
+Depends on ``agnara``. Must not import a sibling adapter.
+See ``ARCHITECTURE.md`` section 15, ``docs/CLI_SPEC.md`` and ``docs/MATURITY.md``.
 """
 
 #: The supported programmatic surface of this distribution.

agnara_cli-1.0.4/src/agnara_cli/_command.py

@@ -0,0 +1,9 @@
+"""Private command output for diagnostics with an explicit exit status."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class CommandResult:
+    output: str
+    exit_code: int

agnara_cli-1.0.4/src/agnara_cli/_doctor.py

@@ -0,0 +1,222 @@
+"""Check project metadata and, on request, an explicit runtime composition."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from importlib.metadata import PackageNotFoundError, version
+
+from agnara_cli._apps import _manifest as load_project_manifest
+from agnara_cli._command import CommandResult
+from agnara_cli._manifest import ManifestError, ProjectManifest
+from agnara_cli._target import TargetError, resolve_target
+
+_ADAPTERS = {"http": "agnara-http", "mcp": "agnara-mcp"}
+_UNCHECKED_EXPOSURE_MESSAGES = {
+    "a2a": "adapter metadata checks are not implemented for this declared exposure",
+    "events": "reserved namespace; no implemented Agnara event runtime",
+    "tasks": "no implemented Agnara task runtime",
+}
+_UNCHECKED = (
+    "project_python_constraint",
+    "application_imports",
+    "runtime_registration",
+    "dependency_cycles",
+    "protocol_configuration",
+    "architecture_rules",
+    "transitive_dependencies",
+)
+
+
+def add_doctor_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "doctor",
+        help="check project metadata and optionally an explicit runtime composition",
+        description=(
+            "Static checks import no project code. An explicit --runtime target imports "
+            "trusted project code and checks compilation and declared app registration."
+        ),
+    )
+    parser.add_argument("--project", metavar="DIR", help="directory to search and its ancestors")
+    parser.add_argument(
+        "--runtime", metavar="MODULE:ATTRIBUTE", help="import and compile this target"
+    )
+    parser.add_argument(
+        "--path", action="append", default=[], metavar="DIR", help="runtime import path"
+    )
+    parser.add_argument("--dependencies", metavar="ATTRIBUTE", help="runtime target's DIRegistry")
+    parser.add_argument("--json", action="store_true", help="emit a versioned diagnostic report")
+
+    def handle(arguments: argparse.Namespace) -> CommandResult:
+        if arguments.runtime is None:
+            if arguments.path:
+                parser.error("--path requires --runtime")
+            if arguments.dependencies is not None:
+                parser.error("--dependencies requires --runtime")
+        return run_doctor(arguments)
+
+    parser.set_defaults(handler=handle)
+
+
+def _python_version() -> tuple[int, int, int]:
+    return sys.version_info[:3]
+
+
+def _distribution_check(
+    name: str,
+    checks: list[dict[str, str]],
+    *,
+    kernel: str | None = None,
+    compare: bool = False,
+) -> str | None:
+    try:
+        installed = version(name)
+    except PackageNotFoundError:
+        checks.append({"id": f"distribution:{name}", "status": "fail", "message": "not installed"})
+        return None
+    if not isinstance(installed, str) or not installed.strip():
+        checks.append(
+            {
+                "id": f"distribution:{name}",
+                "status": "fail",
+                "message": "installed metadata has no non-empty version",
+            }
+        )
+        return None
+    status = "pass"
+    message = f"installed {installed}"
+    if compare and kernel is None:
+        status, message = "fail", "cannot compare versions without installed agnara metadata"
+    elif compare and installed != kernel:
+        status, message = "fail", f"installed {installed}; expected kernel version {kernel}"
+    checks.append({"id": f"distribution:{name}", "status": status, "message": message})
+    return installed
+
+
+def _app_checks(manifest: ProjectManifest, checks: list[dict[str, str]]) -> None:
+    assert manifest.source is not None
+    root = manifest.source.parent.resolve()
+    for app in manifest.apps:
+        status = "pass"
+        message = f"directory exists: {app.path}"
+        try:
+            destination = (root / app.path).resolve()
+            if not destination.is_relative_to(root):
+                status, message = "fail", f"directory escapes project: {app.path}"
+            elif not destination.is_dir():
+                status, message = "fail", f"directory is missing or inaccessible: {app.path}"
+        except OSError, RuntimeError:
+            status, message = "fail", f"cannot resolve app directory: {app.path}"
+        checks.append({"id": f"app:{app.name}:path", "status": status, "message": message})
+
+
+def run_doctor(arguments: argparse.Namespace) -> CommandResult:
+    checks: list[dict[str, str]] = []
+    interpreter = _python_version()
+    checks.append(
+        {
+            "id": "python",
+            "status": "pass" if interpreter >= (3, 14) else "fail",
+            "message": f"executing Python {'.'.join(map(str, interpreter))}; requires >=3.14",
+        }
+    )
+    manifest = None
+    try:
+        manifest = load_project_manifest(arguments)
+        checks.append({"id": "manifest", "status": "pass", "message": "valid agnara.toml"})
+    except ManifestError as error:
+        checks.append({"id": "manifest", "status": "fail", "message": str(error)})
+
+    kernel = _distribution_check("agnara", checks)
+    _distribution_check("agnara-cli", checks, kernel=kernel, compare=True)
+    unchecked = list(_UNCHECKED)
+    project = None
+    if manifest is None:
+        unchecked.extend(("declared_app_paths", "declared_adapters"))
+    else:
+        project = {"name": manifest.name, "python": manifest.python}
+        _app_checks(manifest, checks)
+        exposures = dict.fromkeys(exposure for app in manifest.apps for exposure in app.exposures)
+        for exposure in exposures:
+            distribution = _ADAPTERS.get(exposure)
+            if distribution is None:
+                checks.append(
+                    {
+                        "id": f"exposure:{exposure}",
+                        "status": "fail",
+                        "message": _UNCHECKED_EXPOSURE_MESSAGES[exposure],
+                    }
+                )
+            else:
+                _distribution_check(distribution, checks, kernel=kernel, compare=True)
+
+        if arguments.runtime is not None:
+            _runtime_checks(arguments, manifest, checks, unchecked)
+
+    status = "fail" if any(check["status"] == "fail" for check in checks) else "pass"
+    report = {
+        "format": "agnara.doctor",
+        "format_version": 1,
+        "project": project,
+        "checks": checks,
+        "status": status,
+        "unchecked": unchecked,
+    }
+    if arguments.json:
+        output = json.dumps(report, indent=2, sort_keys=True)
+    else:
+        label = manifest.name if manifest is not None else "unknown project"
+        lines = [f"doctor {label}: {status}"]
+        lines.extend(f"[{check['status']}] {check['id']}: {check['message']}" for check in checks)
+        lines.append("Unchecked: " + ", ".join(unchecked))
+        output = "\n".join(lines)
+    return CommandResult(output, 1 if status == "fail" else 0)
+
+
+def _runtime_checks(
+    arguments: argparse.Namespace,
+    manifest: ProjectManifest,
+    checks: list[dict[str, str]],
+    unchecked: list[str],
+) -> None:
+    unchecked.remove("application_imports")
+    try:
+        target = resolve_target(
+            arguments.runtime,
+            dependencies=arguments.dependencies,
+        )
+    except TargetError as error:
+        checks.append({"id": "runtime:target", "status": "fail", "message": str(error)})
+        return
+
+    checks.append({"id": "runtime:target", "status": "pass", "message": "target compiled"})
+    unchecked.remove("runtime_registration")
+    for app in manifest.apps:
+        registered = target.app.apps.get(app.name)
+        checks.append(
+            {
+                "id": f"app:{app.name}:registration",
+                "status": "pass" if registered is not None else "fail",
+                "message": "registered"
+                if registered is not None
+                else "declared app is not registered",
+            }
+        )
+        module_check = f"app:{app.name}:module"
+        module = registered.descriptor.module if registered is not None else None
+        if module is None:
+            unchecked.append(module_check)
+            continue
+        matches = module == app.module
+        checks.append(
+            {
+                "id": module_check,
+                "status": "pass" if matches else "fail",
+                "message": (
+                    f"descriptor module matches {app.module}"
+                    if matches
+                    else f"descriptor module {module} differs from declared {app.module}"
+                ),
+            }
+        )

{agnara_cli-1.0.2 → agnara_cli-1.0.4}/src/agnara_cli/_generate.py

@@ -114,7 +114,7 @@ def build_plan(
             FileAction(
                 path=path,
                 contents=files[relative],
-                exists=target.exists(),
+                exists=target.is_symlink() or target.exists(),
                 intended_update=relative in intended,
             )
         )
@@ -152,13 +152,7 @@ def plan_json(plan: GenerationPlan) -> dict[str, object]:
 
 
 def apply_plan(plan: GenerationPlan, *, overwrite: bool = False) -> GenerationPlan:
-    """Write a plan, or refuse before writing anything.
-
-    Conflicts are checked against the whole plan first. A run that would
-    replace a file the operator did not authorize must leave the directory
-    exactly as it was, not half-written, so the refusal happens before the
-    first ``write_text``.
-    """
+    """Reject planned conflicts before writing and apply metadata updates last."""
     conflicts = plan.conflicts
     if conflicts and not overwrite:
         listed = ", ".join(str(action.path) for action in conflicts)
@@ -166,14 +160,22 @@ def apply_plan(plan: GenerationPlan, *, overwrite: bool = False) -> GenerationPl
             f"refusing to replace existing file(s) in {plan.root}: {listed}. "
             "Pass --overwrite to allow it."
         )
-    for action in plan.actions:
+    for action in sorted(plan.actions, key=lambda action: action.intended_update):
         target = plan.resolve(action)
+        mode = "w" if overwrite or action.intended_update else "x"
         try:
             target.parent.mkdir(parents=True, exist_ok=True)
             # newline="\n" so a generated file is byte-identical on every
             # platform; a project is shared, and its line endings are its own
             # decision rather than that of the machine that created it.
-            target.write_text(action.contents, encoding="utf-8", newline="\n")
+            with target.open(mode, encoding="utf-8", newline="\n") as stream:
+                stream.write(action.contents)
+        except FileExistsError as error:
+            if mode == "x" and error.filename == str(target):
+                raise GenerationError(
+                    f"refusing to replace existing file {target}. Pass --overwrite to allow it."
+                ) from error
+            raise GenerationError(f"cannot write {target}: {error}") from error
         except OSError as error:
             raise GenerationError(f"cannot write {target}: {error}") from error
     return plan

{agnara_cli-1.0.2 → agnara_cli-1.0.4}/src/agnara_cli/_main.py

@@ -10,7 +10,8 @@ Exit codes:
     visible" or nothing at all, as when a document was written to a file
 ``1``
     the operator's input or application could not be used, reported as a
-    diagnostic on stderr rather than a traceback
+    diagnostic on stderr rather than a traceback; doctor instead emits its
+    structured failed-check report on stdout
 ``2``
     argparse rejected the command line
 """
@@ -20,18 +21,21 @@ from __future__ import annotations
 import argparse
 import sys
 from collections.abc import Sequence
+from contextlib import redirect_stdout
 from importlib.metadata import PackageNotFoundError, version
 
 from agnara_cli._app import add_app_alias_parsers, add_app_parser
 from agnara_cli._apps import add_apps_parser
+from agnara_cli._command import CommandResult
 from agnara_cli._context import add_context_parser
+from agnara_cli._doctor import add_doctor_parser
 from agnara_cli._generate import GenerationError
 from agnara_cli._graph import add_graph_parser
 from agnara_cli._inspect import add_inspect_parser
 from agnara_cli._manifest import ManifestError
 from agnara_cli._project import add_project_parser
 from agnara_cli._schema import add_schema_parser
-from agnara_cli._target import TargetError
+from agnara_cli._target import TargetError, target_search_path
 
 __all__ = ["main"]
 
@@ -62,6 +66,7 @@ def _parser() -> argparse.ArgumentParser:
     add_project_parser(subparsers)
     add_schema_parser(subparsers)
     add_context_parser(subparsers)
+    add_doctor_parser(subparsers)
     return parser
 
 
@@ -77,10 +82,15 @@ def main(argv: Sequence[str] | None = None) -> int:
     """
     arguments = _parser().parse_args(argv)
     try:
-        output = arguments.handler(arguments)
+        # Handlers return their output. Imported targets can also print.
+        with target_search_path(getattr(arguments, "path", ())), redirect_stdout(sys.stderr):
+            output = arguments.handler(arguments)
     except (GenerationError, ManifestError, TargetError) as error:
         print(f"agnara: {error}", file=sys.stderr)
         return EXIT_FAILED
+    if isinstance(output, CommandResult):
+        _emit(output.output)
+        return output.exit_code
     _emit(output)
     return EXIT_OK
 

{agnara_cli-1.0.2 → agnara_cli-1.0.4}/src/agnara_cli/_schema.py

@@ -19,7 +19,7 @@ from __future__ import annotations
 import argparse
 import json
 from collections.abc import Callable, Mapping
-from typing import Any, cast
+from typing import Any, Never, cast
 
 from agnara_cli._target import TargetError, resolve_attribute
 from agnara_cli._write import write_document
@@ -91,6 +91,10 @@ def add_schema_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentPa
     openapi.set_defaults(handler=run_schema)
 
 
+def _reject_json_constant(token: str) -> Never:
+    raise ValueError(f"{token} is not a JSON number")
+
+
 def _document(value: object) -> tuple[dict[str, Any], bytes | None]:
     """Read a target into a document, keeping its exact bytes when it has them.
 
@@ -119,8 +123,10 @@ def _document(value: object) -> tuple[dict[str, Any], bytes | None]:
         except UnicodeDecodeError as error:
             raise TargetError("the OpenAPI document is not valid UTF-8") from error
         try:
-            parsed = json.loads(decoded)
-        except json.JSONDecodeError as error:
+            parsed = json.loads(decoded, parse_constant=_reject_json_constant)
+        except RecursionError as error:
+            raise TargetError("the OpenAPI document is nested too deeply to parse") from error
+        except ValueError as error:
             raise TargetError(f"the OpenAPI document is not valid JSON: {error}") from error
     elif isinstance(value, Mapping):
         parsed = dict(value)
@@ -144,27 +150,24 @@ def _document(value: object) -> tuple[dict[str, Any], bytes | None]:
 
 
 def _encode(document: Mapping[str, Any], served: bytes | None, *, pretty: bool) -> bytes:
-    if pretty:
-        return json.dumps(
-            document,
-            allow_nan=False,
-            ensure_ascii=False,
-            indent=2,
-            sort_keys=True,
-        ).encode("utf-8")
-    if served is not None:
+    if served is not None and not pretty:
         # Exactly what a server would send, including whatever the projection
         # chose. Re-serializing here would silently normalize it.
         return served
     try:
-        return json.dumps(document, **_JSON_ARGUMENTS).encode("utf-8")
-    except (TypeError, ValueError, UnicodeEncodeError) as error:
+        options = (
+            {**_JSON_ARGUMENTS, "separators": None, "indent": 2} if pretty else _JSON_ARGUMENTS
+        )
+        return json.dumps(document, **options).encode("utf-8")
+    except RecursionError as error:
+        raise TargetError("the OpenAPI document is nested too deeply to serialize") from error
+    except (TypeError, ValueError) as error:
         raise TargetError(f"the OpenAPI document cannot be serialized as JSON: {error}") from error
 
 
 def run_schema(arguments: argparse.Namespace) -> bytes | None:
     """Export the document, to stdout as exact bytes or to a file."""
-    value = resolve_attribute(arguments.target, search_path=arguments.path)
+    value = resolve_attribute(arguments.target)
     document, served = _document(value)
     body = _encode(document, served, pretty=arguments.pretty)
     if arguments.output is None:

{agnara_cli-1.0.2 → agnara_cli-1.0.4}/src/agnara_cli/_target.py

@@ -16,7 +16,8 @@ from __future__ import annotations
 import importlib
 import sys
 import traceback
-from collections.abc import Iterable, Sequence
+from collections.abc import Iterator, Sequence
+from contextlib import contextmanager
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -105,11 +106,19 @@ def _split(target: str) -> tuple[str, str]:
     return module_name, attribute
 
 
-def _import(module_name: str, search_path: Sequence[str]) -> object:
-    """Import the target module, with the requested paths ahead of the rest."""
+@contextmanager
+def target_search_path(search_path: Sequence[str]) -> Iterator[None]:
+    """Keep CLI search paths available while target code runs."""
     added = [str(Path(entry).resolve()) for entry in search_path]
     original = list(sys.path)
     sys.path[:0] = added
+    try:
+        yield
+    finally:
+        sys.path[:] = original
+
+
+def _import(module_name: str) -> object:
     try:
         return importlib.import_module(module_name)
     except ImportError as error:
@@ -124,11 +133,9 @@ def _import(module_name: str, search_path: Sequence[str]) -> object:
         # A module that raises while executing is the user's code failing, not
         # a CLI failure, and the operator needs the reason rather than a stack.
         raise TargetError(f"importing {module_name!r} failed: {_reason(error)}") from error
-    finally:
-        sys.path[:] = original
 
 
-def resolve_attribute(target: str, *, search_path: Iterable[str] = ()) -> object:
+def resolve_attribute(target: str) -> object:
     """Import ``module:attribute`` and return whatever it names.
 
     The generic half of target resolution. A command that needs an application
@@ -137,7 +144,7 @@ def resolve_attribute(target: str, *, search_path: Iterable[str] = ()) -> object
     and reads it structurally instead.
     """
     module_name, attribute = _split(target)
-    module = _import(module_name, tuple(search_path))
+    module = _import(module_name)
     return _attribute(module, attribute)
 
 
@@ -153,7 +160,6 @@ def _registry(module: object, name: str | None) -> DIRegistry | None:
 def resolve_target(
     target: str,
     *,
-    search_path: Iterable[str] = (),
     dependencies: str | None = None,
 ) -> ResolvedTarget:
     """Import ``module:attribute`` and compile every declared capability.
@@ -164,7 +170,7 @@ def resolve_target(
     fails with the reason rather than being described as if it had none.
     """
     module_name, attribute = _split(target)
-    module = _import(module_name, tuple(search_path))
+    module = _import(module_name)
     app = _attribute(module, attribute)
     if not isinstance(app, Agnara):
         raise TargetError(
@@ -173,9 +179,10 @@ def resolve_target(
     registry = _registry(module, dependencies)
     compile_against = DIRegistry() if registry is None else registry
     try:
+        capabilities = app.compile()
         plans = tuple(
-            ExecutionPlan.compile(app.capabilities[capability_id], compile_against)
-            for capability_id in app.capabilities
+            ExecutionPlan.compile(capabilities[capability_id], compile_against)
+            for capability_id in capabilities
         )
     except Exception as error:
         # A schema error with no registry named is nearly always a dependency

{agnara_cli-1.0.2 → agnara_cli-1.0.4}/src/agnara_cli/_view.py

@@ -130,7 +130,6 @@ def resolve_view(arguments: argparse.Namespace) -> View:
     """
     resolved = resolve_target(
         arguments.target,
-        search_path=arguments.path,
         dependencies=arguments.dependencies,
     )
     visibility = POSTURES[arguments.visibility](_rule(arguments.as_scope, arguments.hide))

{agnara_cli-1.0.2 → agnara_cli-1.0.4}/src/agnara_cli/_write.py

@@ -17,9 +17,12 @@ __all__ = ["write_document"]
 def write_document(destination: str, body: bytes, *, overwrite: bool) -> None:
     """Write ``body`` to ``destination``, refusing an unauthorized replacement."""
     path = Path(destination)
-    if path.exists() and not overwrite:
-        raise TargetError(f"{destination!r} already exists; pass --overwrite to replace it")
     try:
-        path.write_bytes(body)
+        with path.open("wb" if overwrite else "xb") as stream:
+            stream.write(body)
+    except FileExistsError as error:
+        raise TargetError(
+            f"{destination!r} already exists; pass --overwrite to replace it"
+        ) from error
     except OSError as error:
         raise TargetError(f"cannot write {destination!r}: {error}") from error