apcore-cli 0.10.4__tar.gz → 0.11.0__tar.gz

{apcore_cli-0.10.4 → apcore_cli-0.11.0}/CHANGELOG.md

@@ -5,6 +5,65 @@ All notable changes to apcore-cli (Python SDK) will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.11.0] - 2026-09-02
+
+Bumps the required `apcore` floor to `0.28.0` and `apcore-toolkit` to `0.10.2`, and fixes **three defects the 0.28.0 upgrade made reachable or visible**. Full suite: 815 passed, 5 xfailed (798 → 815; 17 new regression tests), verified in a throwaway venv built from the declared `dev` extra rather than the working interpreter. Each new test was confirmed to fail against the pre-fix behaviour rather than merely to pass against the new one.
+
+**Why a minor rather than a patch.** Every fix below restores behaviour that was already specified, but two of them change what a working consumer observes, and this ecosystem's rule — stated in apcore's own 0.28.0 release note — is that such a change "must ship as a **minor** (or major) version bump, never a patch". A script branching on exit code `1` from an `apcli` system command now sees `45`; a caller doing `handler.request_approval(...)["status"]` now gets a `TypeError`. Neither was correct behaviour, and both were reachable.
+
+### Fixed
+
+- **The `apcli health` summary line reported "no data" for a project whose modules it had just listed.** apcore classifies module health in **four** tiers — `healthy` / `degraded` / `error` / `unknown` — and the tally iterated only the first three. `unknown` means "no calls recorded yet", which is the state every module in a fresh project is in, so the common case rendered a populated table above a total that denied it:
+
+  ```
+    probe.echo                   unknown      0.0%         --
+  Summary: no data
+  ```
+
+  **Pre-existing, and not introduced by this upgrade** — all three SDKs have emitted `unknown` since the tier set existed. apcore 0.28.0 is what brought it into focus: `sys-health-summary.schema.json` had declared the enum as `["healthy", "degraded", "unhealthy"]`, a value **no SDK emits**, and the release corrects it to the four tiers actually produced, splitting the summary's `unhealthy` count field into `error` and `unknown`. With the canonical shape finally naming four tiers, rendering three is a plain omission. Fixed in all three SDKs together, with the tally now covering `unknown`; a genuinely empty tally still reads "no data".
+
+- **The approval gate crashed on every gate-routed approval — `CliApprovalHandler` returned a mapping where the protocol requires an `ApprovalResult`.** apcore's `BuiltinApprovalGate` reads the handler's answer by attribute (`result.status`, `result.approved_by` in `builtin_steps.py`), so the handler's `{"status": "approved", ...}` dict raised `AttributeError` *inside* the gate and reached the caller as `MODULE_EXECUTE_ERROR`. Every one of the eight return paths was affected, so a module annotated `requires_approval: true` could not execute through the wired handler at all — including the `--yes` and `APCORE_CLI_AUTO_APPROVE=1` bypasses, which return early and therefore failed the same way.
+
+  It survived because nothing exercised it: no test in this SDK called `request_approval`, and the class was only reachable through `executor.set_approval_handler` in `factory.py`. apcore-cli-rust converts through `cli_to_apcore_result` and apcore-cli-typescript's `ApprovalResult` is a structurally-typed interface, so neither had the defect — this was a Python-only divergence from a shape both other SDKs got right.
+
+  **Pre-existing, but apcore 0.28.0 widens the blast radius.** Before 0.28.0 the gate fired only for a module whose *annotation* said `requires_approval: true`. Since spec v1.28.0 §6.9 the gate fires on the union of three sources, so an ACL rule carrying `approval: required` (§6.1.6) now routes calls to modules annotated `requires_approval: false` through the same broken path — the exact shape argument-scoped approval was added for (`git push --force` needs a human, `git push` does not).
+
+  `_approval_result()` now constructs `apcore.approval.ApprovalResult`, falling back to the mapping shape when apcore is not importable so the handler stays usable in isolation.
+
+- **Every apcore error from an `apcli` system command exited 1 instead of its canonical code.** `exit_code_for_error` matched only on the CLI's own exception classes, none of which an apcore-raised `ModuleError` subclass is an instance of, so the wire code it carries was never read. `system_cmd._exit_on_system_error` documents the canonical taxonomy (44 module-not-found, 45 schema-validation, 46 approval-denied, 47 config-invalid, 77 ACL-denied) and delivered `1` for all of them. TS `exitCodeForError` falls through to a `codeMap` and Rust `map_module_error_to_exit_code` reads `err.code`; Python had the map — in `cli.py` — and never consulted it from this path.
+
+  **apcore 0.28.0 makes it newly reachable on a routine command.** `system.usage.summary` / `system.usage.module` now declare `"pattern": "^[1-9][0-9]*[hd]$"` on `period`, and 0.28.0 also stops `_DictSchemaAdapter.model_validate` being a pass-through, so dict-declared schemas are finally enforced. `apcore-cli apcli usage --period 0h` passes the flag through verbatim and now raises `SCHEMA_VALIDATION_ERROR` where it previously returned an empty window with exit 0 — and was reported as exit 1 rather than 45.
+
+  `APCORE_ERROR_CODE_MAP` moves to `exit_codes.py` as the single source of truth (`cli._ERROR_CODE_MAP` is now an alias, so the two copies cannot drift), gains the `DEPENDENCY_NOT_FOUND` / `DEPENDENCY_VERSION_MISMATCH` entries TS already had, and `exit_code_for_error` falls back to it.
+
+### Changed
+
+- **`apcore>=0.28.0`, `apcore-toolkit>=0.10.2`.** apcore-toolkit 0.10.2 is a dependency-tracking release with no source change; its stable surface consumed by the CLI (`format_*`, `DisplayResolver`, `BindingLoader`, `RegistryWriter`) is unchanged.
+
+- **Exit-code map parity pinned across the three SDKs.** A mechanical three-way diff of the maps found `DEPENDENCY_NOT_FOUND` and `DEPENDENCY_VERSION_MISMATCH` mapped to 44 here and in the other non-Rust SDK, but falling through to 1 in apcore-cli-rust (fixed in its 0.11.0). Both codes now carry an explicit assertion here too, so the three maps cannot drift again without a test going red.
+
+- **The new handler tests drive their coroutines with `asyncio.run` instead of `@pytest.mark.asyncio`.** This suite declares no async plugin — `pytest-asyncio` is absent from the `dev` extra and there is not one other async test in it — so a marker-based test is collected happily and then fails at run time with *"async def functions are not natively supported"* on any machine that does not happen to have the plugin installed for other reasons. Caught by CI, not locally, which is the point: the local interpreter had it and the declared dependency set does not.
+
+### Notes
+
+- **What the 0.27.0 → 0.28.0 delta does *not* touch.** The CLI never constructs or loads an `ACL`, never calls `check()` / `check_access()` (so §6.8.1's fail-closed legacy boolean does not reach it), never reads an `AuditEntry`, and never builds an `ACLRule` (so §6.1.5's `effect` value closure and the new `approval` field are inert here). `ExecutionPolicy.resolve()`'s new keyword-only call-site parameters are additive and the CLI configures no policy. `p99_latency_ms` changing value is display-only in `_format_usage_summary_tty`.
+- **`Executor.validate()` now reports the governance-effective requirement (§7.9.5), which is an improvement the CLI gets for free.** `apcli validate` and the `--dry-run` path forward `result.requires_approval` verbatim, so a call gated only by an ACL argument-scoped rule is now correctly reported as needing approval. Pinned by `test_preflight_reports_the_acl_sourced_requirement`.
+- **The CLI's own pre-execution `check_approval(module_def, ...)` still reads the static annotation**, which since spec v1.29.0 no longer means "no consent needed". That is correct here rather than a defect: the pre-check is an ergonomic early prompt, and a call it skips still meets the executor's gate, which now composes all three sources and routes to the same `CliApprovalHandler`. Verified end-to-end by `TestApprovalGateEndToEnd`.
+
+## [0.10.5] - 2026-08-17
+
+Patch release. Bumps the required `apcore` floor to `0.27.0` to track the aligned apcore 0.27.0 release (2026-08-14). **No source changes** — the full test suite passes unchanged (798 passed, 5 xfailed) against apcore 0.27.0.
+
+The apcore 0.26.0 → 0.27.0 delta is BREAKING at the spec level, but touches no surface the CLI consumes — verified against the release notes and the actual call sites:
+
+- **Middleware semantics** — `before_step` failure is now terminal/non-recoverable, `after_step` fires after a recovered step body, `state.outputs` excludes the current step in `after_step`. The CLI never constructs or configures middleware or pipelines; it only calls `executor.call` / `executor.validate` / `call_with_trace` with strategy names. No exposure.
+- **ACL-failed `validate()` introspection** — a failed `acl` check now withholds `module_preflight` / `module_preview` checks and `predicted_changes`. The CLI's `executor.validate()` calls (per-module `--dry-run`, `apcli validate`, and the `system.health.summary` probe) consume only `valid` / `checks` / `requires_approval`; the probe discards its result. Behavior stays correct (ACL-denied calls surface exit 77 as before).
+- **`Registry.register` metadata `dependencies` persistence** — the CLI never calls `register()` directly (module registration is via `discover()` / toolkit `RegistryWriter`); it only reads `len(descriptor.dependencies)` for the `--deps` column. No exposure.
+- **Schema conversion (A23)** — object detection, nullable `anyOf` wrapping, sorted `required` are SDK-conversion rules. The CLI runs its **own** schema→Click converter (`schema_parser.py`) on the descriptor's `input_schema`; it already strips `{"type": "null"}` branches from `anyOf` (v0.10.3) and treats `required` order-insensitively. No exposure.
+- **`pipeline.configure` 4-field set / `requires`/`provides` non-configurable** — the CLI never configures pipelines; a host config carrying other keys now fails at load (spec-mandated strictness, upstream concern).
+- **No type coercion at the module boundary** — CLI flag parsing (Click) produces typed values; only `--input -` JSON passthrough with string-typed numeric values now fails `SCHEMA_VALIDATION_ERROR` instead of being silently coerced (spec-mandated strictness).
+- **Removed/renamed API surface** — Python `apcore.middleware.namespace_keys` removed, `SchemaValidator` default flip, `TraceContext.inject()` raises `InvalidParentIdError` — none used by the CLI.
+
 ## [0.10.4] - 2026-07-14
 
 Patch release. Bumps the required `apcore` floor to `0.26.0` to align the ecosystem on the 0.26.0 governance layer (Execution Policy, governance events, no-handler fail-loud — additive, no breaking changes). No code or API changes; all 798 tests pass (5 xfailed) unmodified against apcore 0.26.0.

{apcore_cli-0.10.4 → apcore_cli-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: apcore-cli
-Version: 0.10.4
+Version: 0.11.0
 Summary: Terminal adapter for apcore — execute AI-Perceivable modules from the command line
 Project-URL: Homepage, https://aiperceivable.com
 Project-URL: Repository, https://github.com/aiperceivable/apcore-cli-python
@@ -21,8 +21,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
-Requires-Dist: apcore-toolkit>=0.10.0
-Requires-Dist: apcore>=0.26.0
+Requires-Dist: apcore-toolkit>=0.10.2
+Requires-Dist: apcore>=0.28.0
 Requires-Dist: click>=8.1
 Requires-Dist: cryptography>=41.0
 Requires-Dist: jsonschema>=4.20

{apcore_cli-0.10.4 → apcore_cli-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apcore-cli"
-version = "0.10.4"
+version = "0.11.0"
 description = "Terminal adapter for apcore — execute AI-Perceivable modules from the command line"
 readme = "README.md"
 license = "Apache-2.0"
@@ -26,8 +26,8 @@ classifiers = [
     "Environment :: Console",
 ]
 dependencies = [
-    "apcore>=0.26.0",
-    "apcore-toolkit>=0.10.0",
+    "apcore>=0.28.0",
+    "apcore-toolkit>=0.10.2",
     "click>=8.1",
     "jsonschema>=4.20",
     "rich>=13.0",

{apcore_cli-0.10.4 → apcore_cli-0.11.0}/src/apcore_cli/approval.py

@@ -71,6 +71,30 @@ def _read_timeout_from_env() -> int | None:
     return parsed
 
 
+def _approval_result(status: str, approved_by: str | None = None, reason: str | None = None) -> Any:
+    """Build the apcore-protocol ``ApprovalResult`` the executor's gate expects.
+
+    The approval gate reads the handler's return value by attribute
+    (``result.status`` in apcore ``builtin_steps``), so a plain mapping raises
+    ``AttributeError`` inside the gate and surfaces to the caller as
+    ``MODULE_EXECUTE_ERROR``. Mirrors the Rust adapter's ``cli_to_apcore_result``
+    and TypeScript's structurally-typed ``ApprovalResult`` object.
+
+    Falls back to the mapping shape when apcore is not importable so the handler
+    stays usable in isolation (unit tests that stub the runtime out).
+    """
+    payload: dict[str, Any] = {"status": status}
+    if approved_by is not None:
+        payload["approved_by"] = approved_by
+    if reason is not None:
+        payload["reason"] = reason
+    try:
+        from apcore.approval import ApprovalResult
+    except ImportError:
+        return payload
+    return ApprovalResult(**payload)
+
+
 # ---------------------------------------------------------------------------
 # CliApprovalHandler — implements apcore ApprovalHandler protocol (FE-11 §3.5)
 # ---------------------------------------------------------------------------
@@ -109,25 +133,25 @@ class CliApprovalHandler:
         # (`if !get_requires_approval(module_def) { return Approved::not_required }`).
         requires_attr = getattr(request, "requires_approval", None)
         if requires_attr is False:
-            return {"status": "approved", "approved_by": "not_required"}
+            return _approval_result("approved", approved_by="not_required")
         module_def = getattr(request, "module_def", None)
         if module_def is not None:
             annotations = getattr(module_def, "annotations", None)
             if annotations is not None:
                 requires = _get_annotation(annotations, "requires_approval", None)
                 if requires is False:
-                    return {"status": "approved", "approved_by": "not_required"}
+                    return _approval_result("approved", approved_by="not_required")
 
         # Bypass: auto_approve flag
         if self.auto_approve:
             logger.info("Approval bypassed via --yes flag for module '%s'.", module_id)
-            return {"status": "approved", "approved_by": "auto_approve"}
+            return _approval_result("approved", approved_by="auto_approve")
 
         # Bypass: APCORE_CLI_AUTO_APPROVE env var
         env_val = os.environ.get("APCORE_CLI_AUTO_APPROVE", "")
         if env_val == "1":
             logger.info("Approval bypassed via APCORE_CLI_AUTO_APPROVE for '%s'.", module_id)
-            return {"status": "approved", "approved_by": "env_auto_approve"}
+            return _approval_result("approved", approved_by="env_auto_approve")
         if env_val != "" and env_val != "1":
             # D10-009 cross-SDK parity: emit to stderr (matching TS) so log
             # capture / handler config does not mask the warning. Spec at
@@ -140,10 +164,7 @@ class CliApprovalHandler:
 
         # Non-TTY: reject
         if not sys.stdin.isatty():
-            return {
-                "status": "rejected",
-                "reason": "Non-interactive session without --yes",
-            }
+            return _approval_result("rejected", reason="Non-interactive session without --yes")
 
         # TTY prompt
         annotations = getattr(request, "annotations", None) or {}
@@ -154,21 +175,18 @@ class CliApprovalHandler:
         try:
             approved = _tty_prompt(module_id, self.timeout)
         except ApprovalTimeoutError:
-            return {"status": "timeout", "reason": f"Timed out after {self.timeout}s"}
+            return _approval_result("timeout", reason=f"Timed out after {self.timeout}s")
 
         if approved:
-            return {"status": "approved", "approved_by": "tty_user"}
-        return {"status": "rejected", "reason": "User rejected"}
+            return _approval_result("approved", approved_by="tty_user")
+        return _approval_result("rejected", reason="User rejected")
 
     async def check_approval(self, approval_id: str) -> Any:
         """Check status of a previously pending approval (Phase B).
 
         CLI does not support async approval polling; always returns rejected.
         """
-        return {
-            "status": "rejected",
-            "reason": "CLI does not support async approval polling",
-        }
+        return _approval_result("rejected", reason="CLI does not support async approval polling")
 
 
 # ---------------------------------------------------------------------------

{apcore_cli-0.10.4 → apcore_cli-0.11.0}/src/apcore_cli/cli.py

@@ -16,7 +16,11 @@ import jsonschema
 from apcore_cli.approval import check_approval
 from apcore_cli.builtin_group import RESERVED_GROUP_NAMES as RESERVED_GROUP_NAMES  # noqa: PLC0414
 from apcore_cli.display_helpers import get_display as _get_display
-from apcore_cli.exit_codes import EXIT_SCHEMA_CIRCULAR_REF, EXIT_SCHEMA_VALIDATION_ERROR
+from apcore_cli.exit_codes import (
+    APCORE_ERROR_CODE_MAP,
+    EXIT_SCHEMA_CIRCULAR_REF,
+    EXIT_SCHEMA_VALIDATION_ERROR,
+)
 from apcore_cli.output import format_exec_result
 from apcore_cli.ref_resolver import (
     CircularRefError,
@@ -428,30 +432,10 @@ class GroupedModuleGroup(LazyModuleGroup):
         )
 
 
-# Error code mapping from apcore error codes to CLI exit codes
-_ERROR_CODE_MAP = {
-    "MODULE_NOT_FOUND": 44,
-    "MODULE_LOAD_ERROR": 44,
-    "MODULE_DISABLED": 44,
-    "SCHEMA_VALIDATION_ERROR": 45,
-    "SCHEMA_CIRCULAR_REF": 48,
-    "APPROVAL_DENIED": 46,
-    "APPROVAL_TIMEOUT": 46,
-    "APPROVAL_PENDING": 46,
-    "CONFIG_NOT_FOUND": 47,
-    "CONFIG_INVALID": 47,
-    "MODULE_EXECUTE_ERROR": 1,
-    "MODULE_TIMEOUT": 1,
-    "ACL_DENIED": 77,
-    # Config Bus errors (apcore >= 0.15.0)
-    "CONFIG_NAMESPACE_RESERVED": 78,
-    "CONFIG_NAMESPACE_DUPLICATE": 78,
-    "CONFIG_ENV_PREFIX_CONFLICT": 78,
-    "CONFIG_ENV_MAP_CONFLICT": 78,
-    "CONFIG_MOUNT_ERROR": 66,
-    "CONFIG_BIND_ERROR": 65,
-    "ERROR_FORMATTER_DUPLICATE": 70,
-}
+# Error code mapping from apcore error codes to CLI exit codes. Single source
+# of truth lives in exit_codes so the dispatch paths that map by wire code and
+# exit_code_for_error cannot drift apart.
+_ERROR_CODE_MAP = APCORE_ERROR_CODE_MAP
 
 
 # D9-005: format_preflight_result and _first_failed_exit_code moved to

apcore_cli-0.11.0/src/apcore_cli/exit_codes.py

@@ -0,0 +1,121 @@
+"""Exit code constants and helper for mapping error classes to process exit codes.
+
+Mirrors apcore-cli-typescript ``src/errors.ts`` (``EXIT_CODES`` map and
+``exitCodeForError``) and apcore-cli-rust ``src/lib.rs`` (``EXIT_*`` consts).
+See ``apcore-cli/docs/features/core-dispatcher.md`` for the canonical exit-code
+table.
+"""
+
+from __future__ import annotations
+
+from apcore_cli.approval import ApprovalDeniedError, ApprovalTimeoutError
+from apcore_cli.security.auth import AuthenticationError
+from apcore_cli.security.config_encryptor import ConfigDecryptionError
+from apcore_cli.security.sandbox import (
+    ModuleExecutionError,
+    ModuleNotFoundError,
+    SchemaValidationError,
+)
+
+# ---------------------------------------------------------------------------
+# Exit code constants — match the EXIT_* names in apcore-cli-rust src/lib.rs
+# ---------------------------------------------------------------------------
+
+EXIT_SUCCESS = 0
+EXIT_MODULE_EXECUTE_ERROR = 1
+EXIT_MODULE_TIMEOUT = 1
+EXIT_INVALID_INPUT = 2
+EXIT_MODULE_NOT_FOUND = 44
+EXIT_MODULE_LOAD_ERROR = 44
+EXIT_MODULE_DISABLED = 44
+EXIT_DEPENDENCY_NOT_FOUND = 44
+EXIT_DEPENDENCY_VERSION_MISMATCH = 44
+EXIT_SCHEMA_VALIDATION_ERROR = 45
+EXIT_APPROVAL_DENIED = 46
+EXIT_APPROVAL_TIMEOUT = 46
+EXIT_CONFIG_NOT_FOUND = 47
+EXIT_CONFIG_INVALID = 47
+EXIT_SCHEMA_CIRCULAR_REF = 48
+EXIT_CONFIG_BIND_ERROR = 65
+EXIT_CONFIG_MOUNT_ERROR = 66
+EXIT_ERROR_FORMATTER_DUPLICATE = 70
+EXIT_ACL_DENIED = 77
+# Both namespace errors share exit code 78 per protocol spec.
+EXIT_CONFIG_NAMESPACE_RESERVED = 78
+EXIT_CONFIG_NAMESPACE_DUPLICATE = 78
+EXIT_SIGINT = 130
+
+# ---------------------------------------------------------------------------
+# Map: error class -> exit code (mirrors TS exitCodeForError instanceof chain)
+# ---------------------------------------------------------------------------
+
+EXIT_CODES: dict[type[BaseException], int] = {
+    ApprovalTimeoutError: EXIT_APPROVAL_TIMEOUT,
+    ApprovalDeniedError: EXIT_APPROVAL_DENIED,
+    AuthenticationError: EXIT_ACL_DENIED,
+    ConfigDecryptionError: EXIT_CONFIG_INVALID,
+    SchemaValidationError: EXIT_SCHEMA_VALIDATION_ERROR,
+    ModuleNotFoundError: EXIT_MODULE_NOT_FOUND,
+    ModuleExecutionError: EXIT_MODULE_EXECUTE_ERROR,
+    KeyboardInterrupt: EXIT_SIGINT,
+}
+
+
+# ---------------------------------------------------------------------------
+# Map: apcore wire error code -> exit code
+# ---------------------------------------------------------------------------
+# The CLI's own exception classes (above) never match an error raised by the
+# apcore runtime, which signals failure through ``ModuleError`` subclasses
+# carrying a ``code`` attribute. Matching on that code is what keeps the
+# canonical taxonomy (44 / 45 / 46 / 47 / 77) intact for every dispatch path —
+# ``apcli`` system commands included, which route apcore errors straight to
+# :func:`exit_code_for_error`. Mirrors the ``codeMap`` in TS ``exitCodeForError``
+# and Rust ``cli::map_apcore_error_to_exit_code``.
+APCORE_ERROR_CODE_MAP: dict[str, int] = {
+    "MODULE_NOT_FOUND": EXIT_MODULE_NOT_FOUND,
+    "MODULE_LOAD_ERROR": EXIT_MODULE_LOAD_ERROR,
+    "MODULE_DISABLED": EXIT_MODULE_DISABLED,
+    "DEPENDENCY_NOT_FOUND": EXIT_DEPENDENCY_NOT_FOUND,
+    "DEPENDENCY_VERSION_MISMATCH": EXIT_DEPENDENCY_VERSION_MISMATCH,
+    "SCHEMA_VALIDATION_ERROR": EXIT_SCHEMA_VALIDATION_ERROR,
+    "SCHEMA_CIRCULAR_REF": EXIT_SCHEMA_CIRCULAR_REF,
+    "APPROVAL_DENIED": EXIT_APPROVAL_DENIED,
+    "APPROVAL_TIMEOUT": EXIT_APPROVAL_TIMEOUT,
+    "APPROVAL_PENDING": EXIT_APPROVAL_DENIED,
+    "CONFIG_NOT_FOUND": EXIT_CONFIG_NOT_FOUND,
+    "CONFIG_INVALID": EXIT_CONFIG_INVALID,
+    "MODULE_EXECUTE_ERROR": EXIT_MODULE_EXECUTE_ERROR,
+    "MODULE_TIMEOUT": EXIT_MODULE_TIMEOUT,
+    "ACL_DENIED": EXIT_ACL_DENIED,
+    # Config Bus errors (apcore >= 0.15.0)
+    "CONFIG_NAMESPACE_RESERVED": EXIT_CONFIG_NAMESPACE_RESERVED,
+    "CONFIG_NAMESPACE_DUPLICATE": EXIT_CONFIG_NAMESPACE_DUPLICATE,
+    "CONFIG_ENV_PREFIX_CONFLICT": EXIT_CONFIG_NAMESPACE_DUPLICATE,
+    "CONFIG_ENV_MAP_CONFLICT": EXIT_CONFIG_NAMESPACE_DUPLICATE,
+    "CONFIG_MOUNT_ERROR": EXIT_CONFIG_MOUNT_ERROR,
+    "CONFIG_BIND_ERROR": EXIT_CONFIG_BIND_ERROR,
+    "ERROR_FORMATTER_DUPLICATE": EXIT_ERROR_FORMATTER_DUPLICATE,
+}
+
+
+def exit_code_for_error(err: BaseException) -> int:
+    """Return the configured exit code for an error instance.
+
+    Resolves in two steps, matching TS ``exitCodeForError`` and the Rust
+    ``ExitCode::from`` mapping: first the CLI's own exception classes
+    (:data:`EXIT_CODES`), then the apcore wire code the error carries
+    (:data:`APCORE_ERROR_CODE_MAP`). Falls back to ``1`` (generic execute
+    error) when neither matches.
+    """
+    for cls, code in EXIT_CODES.items():
+        if isinstance(err, cls):
+            return code
+
+    # Fall back to the apcore wire code. None of the classes above match an
+    # error raised by the apcore runtime, so without this every apcore failure
+    # would collapse to 1 — losing the taxonomy that scripted callers read.
+    wire_code = getattr(err, "code", None)
+    wire_code = getattr(wire_code, "value", wire_code)
+    if isinstance(wire_code, str) and wire_code in APCORE_ERROR_CODE_MAP:
+        return APCORE_ERROR_CODE_MAP[wire_code]
+    return 1

{apcore_cli-0.10.4 → apcore_cli-0.11.0}/src/apcore_cli/system_cmd.py

@@ -101,8 +101,15 @@ def _format_health_summary_tty(result: dict[str, Any]) -> None:
         rate = f"{m.get('error_rate', 0) * 100:.1f}%"
         click.echo(f"  {m['module_id']:<28} {m['status']:<12} {rate:<12} {top_str}")
 
+    # The health tiers are healthy / degraded / error / unknown — four, not
+    # three. `unknown` means "no calls recorded yet", which is the state every
+    # module in a fresh project is in, so omitting it made the summary line
+    # contradict the table right above it: the rows listed modules while the
+    # total read "no data". apcore >= 0.28.0 declares the four-tier set
+    # canonically in sys-health-summary.schema.json (§6.6); the SDKs have
+    # emitted `unknown` all along.
     parts = []
-    for key in ("healthy", "degraded", "error"):
+    for key in ("healthy", "degraded", "error", "unknown"):
         count = summary.get(key, 0)
         if count:
             parts.append(f"{count} {key}")

{apcore_cli-0.10.4 → apcore_cli-0.11.0}/tests/test_approval.py

@@ -1,5 +1,6 @@
 """Tests for Approval Gate (FE-03)."""
 
+import asyncio
 import logging
 from unittest.mock import MagicMock, patch
 
@@ -331,3 +332,190 @@ def test_validate_module_import_path():
     # Same callable behind both names.
     assert legacy_fp is new_fp
     assert legacy_efc is new_efc
+
+
+class TestApprovalHandlerProtocolResult:
+    """The gate reads the handler's return value by attribute, not by key.
+
+    apcore's ``BuiltinApprovalGate`` does ``result.status`` / ``result.approved_by``,
+    so a plain dict raised ``AttributeError`` inside the gate and reached the
+    caller as ``MODULE_EXECUTE_ERROR`` — every gate-routed approval failed.
+    Rust converts through ``cli_to_apcore_result`` and TypeScript's
+    ``ApprovalResult`` is structurally typed; Python needed the same shape.
+    """
+
+    # These drive the coroutine with `asyncio.run` rather than `async def` +
+    # `@pytest.mark.asyncio`: this suite declares no async plugin (there are no
+    # other async tests in it), so a marker-based test is silently collected and
+    # then fails at run time with "async def functions are not natively
+    # supported" wherever pytest-asyncio is not installed.
+
+    def test_request_approval_returns_attribute_addressable_result(self):
+        from apcore_cli.approval import CliApprovalHandler
+
+        handler = CliApprovalHandler(auto_approve=True)
+        result = asyncio.run(handler.request_approval(MagicMock(module_id="m.x", module_def=None)))
+
+        assert result.status == "approved"
+        assert result.approved_by == "auto_approve"
+
+    def test_check_approval_returns_attribute_addressable_result(self):
+        from apcore_cli.approval import CliApprovalHandler
+
+        result = asyncio.run(CliApprovalHandler().check_approval("approval-123"))
+
+        assert result.status == "rejected"
+        assert "async approval polling" in result.reason
+
+    def test_result_is_the_apcore_protocol_type(self):
+        """Not merely duck-typed: the gate's audit path constructs from it."""
+        from apcore.approval import ApprovalResult
+
+        from apcore_cli.approval import CliApprovalHandler
+
+        result = asyncio.run(
+            CliApprovalHandler(auto_approve=True).request_approval(MagicMock(module_id="m.x", module_def=None))
+        )
+        assert isinstance(result, ApprovalResult)
+
+
+class TestApprovalGateEndToEnd:
+    """The handler must survive a real trip through apcore's approval gate."""
+
+    def _app_with_handler(self, auto_approve=True):
+        """Build an app with the CLI handler wired to the executor.
+
+        ``auto_approve`` selects the handler's disposition: True answers
+        "approved", False falls through to the TTY prompt, which under pytest
+        has no terminal and therefore rejects. The rejecting variant is what
+        makes these tests discriminating — a call that merely succeeds proves
+        nothing, since a gate that never fired would also let it through.
+        """
+        from apcore import APCore
+
+        from apcore_cli.approval import CliApprovalHandler
+
+        app = APCore()
+
+        @app.module(id="danger.wipe", annotations={"requires_approval": True})
+        def wipe() -> dict:
+            return {"wiped": True}
+
+        @app.module(id="git.push", annotations={"requires_approval": False})
+        def git_push(remote: str = "origin", force: bool = False) -> dict:
+            return {"pushed": True, "force": force}
+
+        app.executor.set_approval_handler(CliApprovalHandler(auto_approve=auto_approve))
+        return app
+
+    def test_annotation_sourced_approval_executes(self):
+        app = self._app_with_handler()
+        assert app.executor.call("danger.wipe", {}) == {"wiped": True}
+
+    def test_acl_sourced_approval_executes(self):
+        """apcore >= 0.28.0 (spec v1.28.0 §6.1.6-§6.1.8): an ACL rule may require
+        a human for a call whose module annotation says ``requires_approval: false``.
+        The gate then fires on a module the CLI's own pre-check skips."""
+        from apcore.acl import ACL, ACLRule
+
+        app = self._app_with_handler()
+        app.executor.set_acl(
+            ACL(
+                rules=[
+                    ACLRule(
+                        callers=["*"],
+                        targets=["git.push"],
+                        effect="allow",
+                        approval="required",
+                        conditions={"arguments": {"has_key": ["force"]}},
+                    ),
+                    ACLRule(callers=["*"], targets=["*"], effect="allow"),
+                ],
+                default_effect="deny",
+            )
+        )
+
+        # Ungated call: the arguments condition is unsatisfied, no human needed.
+        assert app.executor.call("git.push", {"remote": "origin"}) == {
+            "pushed": True,
+            "force": False,
+        }
+        # Gated call: the ACL requires approval, the CLI handler answers it.
+        assert app.executor.call("git.push", {"remote": "origin", "force": True}) == {
+            "pushed": True,
+            "force": True,
+        }
+
+    def test_preflight_reports_the_acl_sourced_requirement(self):
+        """§7.9.5: ``validate()`` reports the governance-effective requirement,
+        which is what ``apcli validate`` forwards as ``requires_approval``."""
+        from apcore.acl import ACL, ACLRule
+
+        app = self._app_with_handler()
+        app.executor.set_acl(
+            ACL(
+                rules=[
+                    ACLRule(
+                        callers=["*"],
+                        targets=["git.push"],
+                        effect="allow",
+                        approval="required",
+                        conditions={"arguments": {"has_key": ["force"]}},
+                    ),
+                    ACLRule(callers=["*"], targets=["*"], effect="allow"),
+                ],
+                default_effect="deny",
+            )
+        )
+
+        assert app.executor.validate("git.push", {"remote": "origin"}).requires_approval is False
+        assert app.executor.validate("git.push", {"remote": "origin", "force": True}).requires_approval is True
+
+    def _acl_with_argument_scoped_rule(self):
+        from apcore.acl import ACL, ACLRule
+
+        return ACL(
+            rules=[
+                ACLRule(
+                    callers=["*"],
+                    targets=["git.push"],
+                    effect="allow",
+                    approval="required",
+                    conditions={"arguments": {"has_key": ["force"]}},
+                ),
+                ACLRule(callers=["*"], targets=["*"], effect="allow"),
+            ],
+            default_effect="deny",
+        )
+
+    def test_a_refusing_handler_blocks_only_the_acl_matched_call(self):
+        """The discriminating pair.
+
+        With auto-approve off and no TTY under pytest, ``CliApprovalHandler``
+        answers "rejected". If the gate did not fire — or fired but never
+        reached this handler — both calls would succeed and the assertion
+        below could not tell the difference.
+        """
+        from apcore.errors import ApprovalDeniedError
+
+        app = self._app_with_handler(auto_approve=False)
+        app.executor.set_acl(self._acl_with_argument_scoped_rule())
+
+        # No `force` key: the rule does not match, the handler is never asked.
+        assert app.executor.call("git.push", {"remote": "origin"}) == {
+            "pushed": True,
+            "force": False,
+        }
+
+        # `force` present: the ACL requires a human and the handler refused.
+        with pytest.raises(ApprovalDeniedError):
+            app.executor.call("git.push", {"remote": "origin", "force": True})
+
+    def test_a_refusing_handler_blocks_an_annotation_gated_module(self):
+        """Same discrimination for the pre-0.28.0 source of the requirement."""
+        from apcore.errors import ApprovalDeniedError
+
+        app = self._app_with_handler(auto_approve=False)
+
+        with pytest.raises(ApprovalDeniedError):
+            app.executor.call("danger.wipe", {})