apcore-cli 0.12.6__tar.gz → 0.14.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/CHANGELOG.md +48 -0
  2. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/PKG-INFO +67 -4
  3. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/README.md +64 -1
  4. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/pyproject.toml +3 -3
  5. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/__init__.py +14 -0
  6. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/acl_cmd.py +14 -14
  7. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/acl_loader.py +2 -2
  8. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/approval.py +10 -5
  9. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/builtin_group.py +4 -2
  10. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/cli.py +235 -148
  11. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/discovery.py +62 -43
  12. apcore_cli-0.14.0/src/apcore_cli/exit.py +63 -0
  13. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/factory.py +65 -12
  14. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/init_cmd.py +3 -2
  15. apcore_cli-0.14.0/src/apcore_cli/module_errors.py +149 -0
  16. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/openapi_cmd.py +8 -8
  17. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/openapi_source.py +5 -4
  18. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/schema_parser.py +5 -4
  19. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/security/sandbox.py +3 -3
  20. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/shell.py +3 -1
  21. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/system_cmd.py +3 -2
  22. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_approval.py +32 -0
  23. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_cli.py +95 -0
  24. apcore_cli-0.14.0/tests/test_host_hooks.py +249 -0
  25. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/.github/CODEOWNERS +0 -0
  26. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/.github/copilot-ignore +0 -0
  27. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/.github/workflows/ci.yml +0 -0
  28. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/.gitignore +0 -0
  29. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/.gitmessage +0 -0
  30. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/.pre-commit-config.yaml +0 -0
  31. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/CLAUDE.md +0 -0
  32. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/LICENSE +0 -0
  33. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/Makefile +0 -0
  34. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/README.md +0 -0
  35. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/extensions/math/add.py +0 -0
  36. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/extensions/math/multiply.py +0 -0
  37. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/extensions/sysutil/disk.py +0 -0
  38. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/extensions/sysutil/env.py +0 -0
  39. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/extensions/sysutil/info.py +0 -0
  40. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/extensions/text/reverse.py +0 -0
  41. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/extensions/text/upper.py +0 -0
  42. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/extensions/text/wordcount.py +0 -0
  43. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/run_examples.sh +0 -0
  44. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/approval-gate.md +0 -0
  45. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/config-resolver.md +0 -0
  46. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/core-dispatcher.md +0 -0
  47. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/discovery.md +0 -0
  48. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/exposure-filtering.md +0 -0
  49. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/grouped-commands.md +0 -0
  50. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/output-formatter.md +0 -0
  51. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/overview.md +0 -0
  52. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/schema-parser.md +0 -0
  53. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/security-manager.md +0 -0
  54. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/shell-integration.md +0 -0
  55. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/state.json +0 -0
  56. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/__main__.py +0 -0
  57. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/_sandbox_runner.py +0 -0
  58. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/config.py +0 -0
  59. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/display_helpers.py +0 -0
  60. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/exit_codes.py +0 -0
  61. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/exposure.py +0 -0
  62. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/output.py +0 -0
  63. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/ref_resolver.py +0 -0
  64. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/security/__init__.py +0 -0
  65. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/security/audit.py +0 -0
  66. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/security/auth.py +0 -0
  67. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/security/config_encryptor.py +0 -0
  68. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/strategy.py +0 -0
  69. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/system_usage.py +0 -0
  70. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/validate.py +0 -0
  71. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/__init__.py +0 -0
  72. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/conformance/__init__.py +0 -0
  73. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/conformance/test_apcli_visibility.py +0 -0
  74. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/conformance/test_snake_case_kwargs.py +0 -0
  75. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/conftest.py +0 -0
  76. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/shell_test_utils.py +0 -0
  77. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_acl_cmd.py +0 -0
  78. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_acl_loader.py +0 -0
  79. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_apcli_integration.py +0 -0
  80. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_bugfixes.py +0 -0
  81. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_builtin_group.py +0 -0
  82. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_config.py +0 -0
  83. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_discovery.py +0 -0
  84. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_discovery_fe13.py +0 -0
  85. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_display_helpers.py +0 -0
  86. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_e2e.py +0 -0
  87. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_exit_codes.py +0 -0
  88. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_exposure.py +0 -0
  89. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_factory_fe13.py +0 -0
  90. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_init_cmd.py +0 -0
  91. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_integration.py +0 -0
  92. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_list_command_filters.py +0 -0
  93. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_openapi_cmd.py +0 -0
  94. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_openapi_source.py +0 -0
  95. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_output.py +0 -0
  96. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_output_format_exec.py +0 -0
  97. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_output_format_markdown_skill.py +0 -0
  98. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_public_api.py +0 -0
  99. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_ref_resolver.py +0 -0
  100. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_sandbox_runner.py +0 -0
  101. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_schema_parser.py +0 -0
  102. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_security/__init__.py +0 -0
  103. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_security/test_audit.py +0 -0
  104. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_security/test_auth.py +0 -0
  105. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_security/test_config_encryptor.py +0 -0
  106. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_security/test_sandbox.py +0 -0
  107. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_shell.py +0 -0
  108. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_strategy.py +0 -0
  109. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_system_cmd.py +0 -0
  110. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_system_usage.py +0 -0
  111. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_toolkit_integration.py +0 -0
  112. {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_validate.py +0 -0
@@ -5,6 +5,54 @@ All notable changes to apcore-cli (Python SDK) will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [0.14.0] - 2026-11-19
9
+
10
+ ### Added
11
+
12
+ - Embedded hosts can observe and translate failures: `build_module_command()`,
13
+ `create_cli()` and `register_exec_command()` accept
14
+ `on_error(ModuleErrorContext)`, `exit_codes` (apcore code -> host code),
15
+ `exit` (replace the exit action), and `error_stream` (`"stdout"` for agent
16
+ contracts that require the failure document on stdout; defaults to stderr).
17
+ - `extra_input` merges host-injected values (for example a program-level
18
+ `--json` flag) into module input before validation, instead of forcing hosts
19
+ to wrap `execute` and merge afterwards.
20
+ - `set_exit_handler()` / `exit_with()` make every library-side exit go through
21
+ one handler. The default raises `SystemExit`. An embedded host can install
22
+ a handler that raises its own error or maps the code.
23
+
24
+ ### Fixed
25
+
26
+ - Invalid module IDs, missing modules, invalid input (including files and
27
+ stdin), and incompatible dispatch flags use the same error callback, output
28
+ destination, and exit mapping as execution failures. A custom exit exception
29
+ unwinds after a single callback and error envelope.
30
+ - `set_docs_url()` strips trailing slashes, so help output no longer emits
31
+ `//commands/...`. The link is built from the canonical module path rather
32
+ than the leaf command name, so a module nested under a group
33
+ (`series.asset.add` -> `add`) keeps its full path.
34
+
35
+ ### Changed
36
+
37
+ - Library code no longer calls `sys.exit()` directly; `collect_input()`,
38
+ `create_cli()`, the module commands, the built-in commands and the ACL loader
39
+ route through `exit_with()`.
40
+
41
+ ## [0.13.0] - 2026-11-10
42
+
43
+ ### Added
44
+
45
+ - Embedded hosts can use `print_result=False` and `on_result(result, module_id)` on `create_cli()`, `build_module_command()`, and `register_exec_command()` to render raw non-streaming results themselves.
46
+
47
+ ### Changed
48
+
49
+ - Module execution rejects `--sandbox` combined with `--trace`, `--strategy`, or `--stream` with exit code 2. Omit those options for sandboxed execution.
50
+
51
+ ### Fixed
52
+
53
+ - Terminal trace diagnostics remain on stderr when result printing is disabled.
54
+ - The CLI and executor approval handler read custom prompts from `annotations.extra["approval_message"]` when the direct annotation is absent.
55
+
8
56
  ## [0.12.3] - 2026-10-10
9
57
 
10
58
  ### Changed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: apcore-cli
3
- Version: 0.12.6
3
+ Version: 0.14.0
4
4
  Summary: Terminal adapter for apcore — execute AI-Perceivable modules from the command line
5
5
  Project-URL: Homepage, https://aiperceivable.com
6
6
  Project-URL: Repository, https://github.com/aiperceivable/apcore-cli-python
@@ -21,8 +21,8 @@ Classifier: Programming Language :: Python :: 3.13
21
21
  Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
22
22
  Classifier: Topic :: Software Development :: Libraries :: Python Modules
23
23
  Requires-Python: >=3.11
24
- Requires-Dist: apcore-toolkit[http-proxy]>=0.14.1
25
- Requires-Dist: apcore>=0.32.2
24
+ Requires-Dist: apcore-toolkit[http-proxy]>=0.14.2
25
+ Requires-Dist: apcore>=0.33.0
26
26
  Requires-Dist: click>=8.1
27
27
  Requires-Dist: cryptography>=41.0
28
28
  Requires-Dist: jsonschema>=4.20
@@ -160,6 +160,69 @@ cli(standalone_mode=True)
160
160
  cli = create_cli(registry=registry, executor=executor, prog_name="myapp")
161
161
  ```
162
162
 
163
+ #### Render a module result in the host
164
+
165
+ ```python
166
+ import json
167
+
168
+ import click
169
+ from apcore_cli import build_module_command
170
+
171
+
172
+ def render_result(result, module_id):
173
+ click.echo(json.dumps({"module_id": module_id, "result": result}, default=str))
174
+
175
+
176
+ status = build_module_command(
177
+ descriptor,
178
+ executor,
179
+ cmd_name="status",
180
+ print_result=False,
181
+ on_result=render_result,
182
+ )
183
+ status()
184
+ ```
185
+
186
+ The callback receives the raw result and canonical module ID after a successful
187
+ non-streaming call. Pass the same keyword options to `create_cli()` for
188
+ generated module commands and `apcli exec`. Result printing defaults to
189
+ enabled. The print setting leaves preflight reports, streaming output, errors,
190
+ and terminal traces on their own output paths.
191
+
192
+ #### Own the failure path
193
+
194
+ Validation still runs before `execute`, but the resulting failure no longer
195
+ terminates the host behind its back:
196
+
197
+ ```python
198
+ from apcore_cli import ModuleErrorContext
199
+
200
+ def _exit(code: int) -> None:
201
+ raise HostCliExit(code)
202
+
203
+ status = build_module_command(
204
+ descriptor,
205
+ executor,
206
+ cmd_name="status",
207
+ exit_codes={"SCHEMA_VALIDATION_ERROR": 2},
208
+ on_error=lambda ctx: log.warning("%s failed with %s", ctx.module_id, ctx.code),
209
+ exit=_exit,
210
+ error_stream="stdout", # agent contract: one document on stdout
211
+ extra_input=lambda: {"json": True}, # program-level flags merged pre-validation
212
+ )
213
+ ```
214
+
215
+ `on_error` receives a `ModuleErrorContext(error, exit_code, code, module_id)`.
216
+ `exit` defaults to the process-wide `set_exit_handler()` handler, which by
217
+ default raises `SystemExit`; install one handler for the whole library:
218
+
219
+ ```python
220
+ from apcore_cli import set_exit_handler
221
+
222
+ set_exit_handler(lambda code: (_ for _ in ()).throw(HostCliExit(code)))
223
+ ```
224
+
225
+
163
226
  #### Python API
164
227
 
165
228
  The `apcore_cli` package re-exports the following public surface (see [`src/apcore_cli/__init__.py`](src/apcore_cli/__init__.py) for the canonical `__all__`):
@@ -167,7 +230,7 @@ The `apcore_cli` package re-exports the following public surface (see [`src/apco
167
230
  | Export | Description |
168
231
  |--------|-------------|
169
232
  | `__version__` | Package version string |
170
- | `create_cli(...)` | Factory that builds a ready-to-invoke `click.Group`. See the [`create_cli` reference](https://github.com/aiperceivable/apcore-cli) in the docs site for the full 14-parameter signature: `extensions_dir`, `prog_name`, `commands_dir`, `binding_path`, `registry`, `executor`, `extra_commands`, `app`, `expose`, **`apcli`** (FE-13 P0 break), `allowed_prefixes`, `version`, `description`, **`builtin_group_name`** (default `"apcli"`, v0.8.0+). |
233
+ | `create_cli(...)` | Factory that builds a ready-to-invoke `click.Group`. Accepts `print_result` and `on_result` for embedded result handling. See the [shared dispatcher spec](https://github.com/aiperceivable/apcore-cli/blob/main/docs/features/core-dispatcher.md) for the embedding contract. |
171
234
  | `ApcliGroup`, `ApcliMode`, `RESERVED_GROUP_NAMES` | FE-13 built-in `apcli` group surface (P0 break in v0.8.0). |
172
235
  | `ExposureFilter` | Declarative filter controlling which modules are exposed by the CLI (FE-12). |
173
236
  | `CliApprovalHandler`, `check_approval` | TTY-aware HITL approval handler / helper (FE-11). |
@@ -119,6 +119,69 @@ cli(standalone_mode=True)
119
119
  cli = create_cli(registry=registry, executor=executor, prog_name="myapp")
120
120
  ```
121
121
 
122
+ #### Render a module result in the host
123
+
124
+ ```python
125
+ import json
126
+
127
+ import click
128
+ from apcore_cli import build_module_command
129
+
130
+
131
+ def render_result(result, module_id):
132
+ click.echo(json.dumps({"module_id": module_id, "result": result}, default=str))
133
+
134
+
135
+ status = build_module_command(
136
+ descriptor,
137
+ executor,
138
+ cmd_name="status",
139
+ print_result=False,
140
+ on_result=render_result,
141
+ )
142
+ status()
143
+ ```
144
+
145
+ The callback receives the raw result and canonical module ID after a successful
146
+ non-streaming call. Pass the same keyword options to `create_cli()` for
147
+ generated module commands and `apcli exec`. Result printing defaults to
148
+ enabled. The print setting leaves preflight reports, streaming output, errors,
149
+ and terminal traces on their own output paths.
150
+
151
+ #### Own the failure path
152
+
153
+ Validation still runs before `execute`, but the resulting failure no longer
154
+ terminates the host behind its back:
155
+
156
+ ```python
157
+ from apcore_cli import ModuleErrorContext
158
+
159
+ def _exit(code: int) -> None:
160
+ raise HostCliExit(code)
161
+
162
+ status = build_module_command(
163
+ descriptor,
164
+ executor,
165
+ cmd_name="status",
166
+ exit_codes={"SCHEMA_VALIDATION_ERROR": 2},
167
+ on_error=lambda ctx: log.warning("%s failed with %s", ctx.module_id, ctx.code),
168
+ exit=_exit,
169
+ error_stream="stdout", # agent contract: one document on stdout
170
+ extra_input=lambda: {"json": True}, # program-level flags merged pre-validation
171
+ )
172
+ ```
173
+
174
+ `on_error` receives a `ModuleErrorContext(error, exit_code, code, module_id)`.
175
+ `exit` defaults to the process-wide `set_exit_handler()` handler, which by
176
+ default raises `SystemExit`; install one handler for the whole library:
177
+
178
+ ```python
179
+ from apcore_cli import set_exit_handler
180
+
181
+ set_exit_handler(lambda code: (_ for _ in ()).throw(HostCliExit(code)))
182
+ ```
183
+
184
+
122
185
  #### Python API
123
186
 
124
187
  The `apcore_cli` package re-exports the following public surface (see [`src/apcore_cli/__init__.py`](src/apcore_cli/__init__.py) for the canonical `__all__`):
@@ -126,7 +189,7 @@ The `apcore_cli` package re-exports the following public surface (see [`src/apco
126
189
  | Export | Description |
127
190
  |--------|-------------|
128
191
  | `__version__` | Package version string |
129
- | `create_cli(...)` | Factory that builds a ready-to-invoke `click.Group`. See the [`create_cli` reference](https://github.com/aiperceivable/apcore-cli) in the docs site for the full 14-parameter signature: `extensions_dir`, `prog_name`, `commands_dir`, `binding_path`, `registry`, `executor`, `extra_commands`, `app`, `expose`, **`apcli`** (FE-13 P0 break), `allowed_prefixes`, `version`, `description`, **`builtin_group_name`** (default `"apcli"`, v0.8.0+). |
192
+ | `create_cli(...)` | Factory that builds a ready-to-invoke `click.Group`. Accepts `print_result` and `on_result` for embedded result handling. See the [shared dispatcher spec](https://github.com/aiperceivable/apcore-cli/blob/main/docs/features/core-dispatcher.md) for the embedding contract. |
130
193
  | `ApcliGroup`, `ApcliMode`, `RESERVED_GROUP_NAMES` | FE-13 built-in `apcli` group surface (P0 break in v0.8.0). |
131
194
  | `ExposureFilter` | Declarative filter controlling which modules are exposed by the CLI (FE-12). |
132
195
  | `CliApprovalHandler`, `check_approval` | TTY-aware HITL approval handler / helper (FE-11). |
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "apcore-cli"
7
- version = "0.12.6"
7
+ version = "0.14.0"
8
8
  description = "Terminal adapter for apcore — execute AI-Perceivable modules from the command line"
9
9
  readme = "README.md"
10
10
  license = "Apache-2.0"
@@ -26,8 +26,8 @@ classifiers = [
26
26
  "Environment :: Console",
27
27
  ]
28
28
  dependencies = [
29
- "apcore>=0.32.2",
30
- "apcore-toolkit[http-proxy]>=0.14.1",
29
+ "apcore>=0.33.0",
30
+ "apcore-toolkit[http-proxy]>=0.14.2",
31
31
  "click>=8.1",
32
32
  "jsonschema>=4.20",
33
33
  "rich>=13.0",
@@ -44,6 +44,13 @@ from apcore_cli.discovery import (
44
44
  register_list_command,
45
45
  register_validate_command,
46
46
  )
47
+ from apcore_cli.exit import (
48
+ ExitHandler,
49
+ exit_with,
50
+ get_exit_handler,
51
+ reset_exit_handler,
52
+ set_exit_handler,
53
+ )
47
54
  from apcore_cli.exit_codes import (
48
55
  EXIT_ACL_DENIED,
49
56
  EXIT_APPROVAL_DENIED,
@@ -73,6 +80,7 @@ from apcore_cli.exit_codes import (
73
80
  from apcore_cli.exposure import ExposureFilter
74
81
  from apcore_cli.factory import create_cli
75
82
  from apcore_cli.init_cmd import register_init_command
83
+ from apcore_cli.module_errors import ModuleErrorContext
76
84
  from apcore_cli.output import (
77
85
  format_exec_result,
78
86
  format_module_detail,
@@ -147,6 +155,12 @@ __all__ = [
147
155
  "Sandbox",
148
156
  # Core dispatcher (parity with TS/Rust embedder API).
149
157
  "build_module_command",
158
+ "set_exit_handler",
159
+ "get_exit_handler",
160
+ "reset_exit_handler",
161
+ "exit_with",
162
+ "ExitHandler",
163
+ "ModuleErrorContext",
150
164
  "collect_input",
151
165
  "validate_module_id",
152
166
  "set_all_options_help",
@@ -14,7 +14,6 @@ Mirrors ``src/acl-cmd.ts`` (TypeScript) and ``src/acl_cmd.rs`` (Rust).
14
14
  from __future__ import annotations
15
15
 
16
16
  import json
17
- import sys
18
17
  from typing import Any
19
18
 
20
19
  import click
@@ -23,6 +22,7 @@ from rich.console import Console
23
22
  from rich.table import Table
24
23
 
25
24
  from apcore_cli.acl_loader import build_context, get_cli_identity, merge_identity
25
+ from apcore_cli.exit import exit_with
26
26
 
27
27
  # Exit codes (FE-14 §6). 47 is a *configuration* fault; 77 is an actual
28
28
  # access decision. Conflating them would make a broken ACL file read as a
@@ -135,7 +135,7 @@ def register_acl_command(
135
135
  allow_unicode=True,
136
136
  ).rstrip()
137
137
  )
138
- sys.exit(EXIT_OK)
138
+ exit_with(EXIT_OK)
139
139
 
140
140
  rows = _rule_rows(acl)
141
141
  payload = {
@@ -180,7 +180,7 @@ def register_acl_command(
180
180
  _truncate(str(row["description"])),
181
181
  )
182
182
  Console().print(table)
183
- sys.exit(EXIT_OK)
183
+ exit_with(EXIT_OK)
184
184
 
185
185
  # -- check --------------------------------------------------------------
186
186
 
@@ -258,7 +258,7 @@ def register_acl_command(
258
258
  """
259
259
  if acl is None:
260
260
  click.echo(f"Error: {_NO_ACL_MESSAGE}", err=True)
261
- sys.exit(EXIT_ACL_CONFIG)
261
+ exit_with(EXIT_ACL_CONFIG)
262
262
 
263
263
  arguments: dict[str, Any] | None = None
264
264
  if input_json is not None:
@@ -266,10 +266,10 @@ def register_acl_command(
266
266
  parsed = json.loads(input_json)
267
267
  except json.JSONDecodeError as exc:
268
268
  click.echo(f"Error: --input is not valid JSON: {exc}", err=True)
269
- sys.exit(EXIT_INVALID_INPUT)
269
+ exit_with(EXIT_INVALID_INPUT)
270
270
  if not isinstance(parsed, dict):
271
271
  click.echo("Error: --input JSON must be an object.", err=True)
272
- sys.exit(EXIT_INVALID_INPUT)
272
+ exit_with(EXIT_INVALID_INPUT)
273
273
  arguments = parsed
274
274
 
275
275
  # §4.5 precedence: a restated flag overrides its root counterpart for
@@ -319,8 +319,8 @@ def register_acl_command(
319
319
 
320
320
  if decision.access == "deny":
321
321
  click.echo(f"Access denied: {caller} -> {target}", err=True)
322
- sys.exit(EXIT_ACL_DENIED)
323
- sys.exit(EXIT_OK)
322
+ exit_with(EXIT_ACL_DENIED)
323
+ exit_with(EXIT_OK)
324
324
 
325
325
  # -- validate -----------------------------------------------------------
326
326
 
@@ -342,7 +342,7 @@ def register_acl_command(
342
342
  """
343
343
  if acl is None:
344
344
  click.echo(f"Error: {_NO_ACL_MESSAGE}", err=True)
345
- sys.exit(EXIT_ACL_CONFIG)
345
+ exit_with(EXIT_ACL_CONFIG)
346
346
 
347
347
  findings = acl.validate_rules()
348
348
  rows = [
@@ -390,7 +390,7 @@ def register_acl_command(
390
390
  "every call it matches."
391
391
  )
392
392
 
393
- sys.exit(EXIT_ACL_CONFIG if rows else EXIT_OK)
393
+ exit_with(EXIT_ACL_CONFIG if rows else EXIT_OK)
394
394
 
395
395
  # -- status -------------------------------------------------------------
396
396
 
@@ -421,13 +421,13 @@ def register_acl_command(
421
421
  "Error: Executor does not expose governance_state(); cannot report ACL status.",
422
422
  err=True,
423
423
  )
424
- sys.exit(EXIT_ACL_CONFIG)
424
+ exit_with(EXIT_ACL_CONFIG)
425
425
 
426
426
  try:
427
427
  state = executor.governance_state()
428
428
  except Exception as exc: # pragma: no cover - defensive
429
429
  click.echo(f"Error: Failed to read governance state: {exc}", err=True)
430
- sys.exit(EXIT_ACL_CONFIG)
430
+ exit_with(EXIT_ACL_CONFIG)
431
431
 
432
432
  values = {field: bool(getattr(state, field, False)) for field, _ in _GOVERNANCE_ROWS}
433
433
  unprotected = bool(getattr(state, "unprotected_control_surface", False))
@@ -449,8 +449,8 @@ def register_acl_command(
449
449
 
450
450
  if strict and unprotected:
451
451
  click.echo("Unprotected control surface.", err=True)
452
- sys.exit(EXIT_ACL_CONFIG)
453
- sys.exit(EXIT_OK)
452
+ exit_with(EXIT_ACL_CONFIG)
453
+ exit_with(EXIT_OK)
454
454
 
455
455
  _ = (acl_list, acl_check, acl_validate, acl_status)
456
456
 
@@ -17,11 +17,11 @@ from __future__ import annotations
17
17
 
18
18
  import logging
19
19
  import os
20
- import sys
21
20
  from collections.abc import Callable
22
21
  from pathlib import Path
23
22
  from typing import TYPE_CHECKING, Any
24
23
 
24
+ from apcore_cli.exit import exit_with
25
25
  from apcore_cli.security.audit import get_audit_logger
26
26
 
27
27
  if TYPE_CHECKING: # pragma: no cover - typing only
@@ -489,7 +489,7 @@ def enforce_acl_for_unguarded_path(
489
489
  import click
490
490
 
491
491
  click.echo(f"Error: Permission denied for module '{module_id}'.", err=True)
492
- sys.exit(EXIT_ACL_DENIED)
492
+ exit_with(EXIT_ACL_DENIED)
493
493
  return bool(decision.approval_required)
494
494
 
495
495
 
@@ -44,6 +44,14 @@ def _get_annotation(annotations: Any, key: str, default: Any = None) -> Any:
44
44
  return getattr(annotations, key, default)
45
45
 
46
46
 
47
+ def _get_approval_message(annotations: Any, module_id: str) -> str:
48
+ extra = _get_annotation(annotations, "extra")
49
+ message = _get_annotation(annotations, "approval_message", _get_annotation(extra, "approval_message"))
50
+ if isinstance(message, str) and message:
51
+ return message
52
+ return f"Module '{module_id}' requires approval to execute."
53
+
54
+
47
55
  def _read_timeout_from_env() -> int | None:
48
56
  """Parse APCORE_CLI_APPROVAL_TIMEOUT, warn on malformed, return None on absent/invalid.
49
57
 
@@ -168,8 +176,7 @@ class CliApprovalHandler:
168
176
 
169
177
  # TTY prompt
170
178
  annotations = getattr(request, "annotations", None) or {}
171
- extra = getattr(annotations, "extra", {}) if not isinstance(annotations, dict) else annotations
172
- message = extra.get("approval_message") or f"Module '{module_id}' requires approval to execute."
179
+ message = _get_approval_message(annotations, module_id)
173
180
 
174
181
  click.echo(message, err=True)
175
182
  try:
@@ -281,9 +288,7 @@ def _prompt_with_timeout(module_def: Any, timeout: int = 60) -> None:
281
288
 
282
289
  module_id = getattr(module_def, "module_id", getattr(module_def, "canonical_id", "unknown"))
283
290
  annotations = getattr(module_def, "annotations", None) or {}
284
- message = _get_annotation(annotations, "approval_message", None)
285
- if message is None:
286
- message = f"Module '{module_id}' requires approval to execute."
291
+ message = _get_approval_message(annotations, module_id)
287
292
 
288
293
  click.echo(message, err=True)
289
294
 
@@ -21,6 +21,8 @@ import re
21
21
  import sys
22
22
  from typing import Any, Literal, TypedDict
23
23
 
24
+ from apcore_cli.exit import exit_with
25
+
24
26
  logger = logging.getLogger("apcore_cli.builtin_group")
25
27
 
26
28
  # ---------------------------------------------------------------------------
@@ -302,10 +304,10 @@ class ApcliGroup:
302
304
  f"Error: apcli.mode must be a string; got {type(raw_mode).__name__}. "
303
305
  "Expected one of all|none|include|exclude.\n"
304
306
  )
305
- sys.exit(_EXIT_INVALID_CLI_INPUT)
307
+ exit_with(_EXIT_INVALID_CLI_INPUT)
306
308
  elif raw_mode not in _VALID_USER_MODES:
307
309
  sys.stderr.write(f"Error: Invalid apcli mode: '{raw_mode}'. Must be one of: all, none, include, exclude.\n")
308
- sys.exit(_EXIT_INVALID_CLI_INPUT)
310
+ exit_with(_EXIT_INVALID_CLI_INPUT)
309
311
  else:
310
312
  mode = raw_mode # type: ignore[assignment]
311
313