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.
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/CHANGELOG.md +48 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/PKG-INFO +67 -4
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/README.md +64 -1
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/pyproject.toml +3 -3
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/__init__.py +14 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/acl_cmd.py +14 -14
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/acl_loader.py +2 -2
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/approval.py +10 -5
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/builtin_group.py +4 -2
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/cli.py +235 -148
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/discovery.py +62 -43
- apcore_cli-0.14.0/src/apcore_cli/exit.py +63 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/factory.py +65 -12
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/init_cmd.py +3 -2
- apcore_cli-0.14.0/src/apcore_cli/module_errors.py +149 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/openapi_cmd.py +8 -8
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/openapi_source.py +5 -4
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/schema_parser.py +5 -4
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/security/sandbox.py +3 -3
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/shell.py +3 -1
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/system_cmd.py +3 -2
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_approval.py +32 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_cli.py +95 -0
- apcore_cli-0.14.0/tests/test_host_hooks.py +249 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/.github/CODEOWNERS +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/.github/copilot-ignore +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/.github/workflows/ci.yml +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/.gitignore +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/.gitmessage +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/.pre-commit-config.yaml +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/CLAUDE.md +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/LICENSE +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/Makefile +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/README.md +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/extensions/math/add.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/extensions/math/multiply.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/extensions/sysutil/disk.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/extensions/sysutil/env.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/extensions/sysutil/info.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/extensions/text/reverse.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/extensions/text/upper.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/extensions/text/wordcount.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/examples/run_examples.sh +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/approval-gate.md +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/config-resolver.md +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/core-dispatcher.md +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/discovery.md +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/exposure-filtering.md +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/grouped-commands.md +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/output-formatter.md +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/overview.md +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/schema-parser.md +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/security-manager.md +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/shell-integration.md +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/planning/state.json +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/__main__.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/_sandbox_runner.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/config.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/display_helpers.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/exit_codes.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/exposure.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/output.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/ref_resolver.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/security/__init__.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/security/audit.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/security/auth.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/security/config_encryptor.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/strategy.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/system_usage.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/src/apcore_cli/validate.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/__init__.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/conformance/__init__.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/conformance/test_apcli_visibility.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/conformance/test_snake_case_kwargs.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/conftest.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/shell_test_utils.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_acl_cmd.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_acl_loader.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_apcli_integration.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_bugfixes.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_builtin_group.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_config.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_discovery.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_discovery_fe13.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_display_helpers.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_e2e.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_exit_codes.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_exposure.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_factory_fe13.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_init_cmd.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_integration.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_list_command_filters.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_openapi_cmd.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_openapi_source.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_output.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_output_format_exec.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_output_format_markdown_skill.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_public_api.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_ref_resolver.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_sandbox_runner.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_schema_parser.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_security/__init__.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_security/test_audit.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_security/test_auth.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_security/test_config_encryptor.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_security/test_sandbox.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_shell.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_strategy.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_system_cmd.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_system_usage.py +0 -0
- {apcore_cli-0.12.6 → apcore_cli-0.14.0}/tests/test_toolkit_integration.py +0 -0
- {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.
|
|
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.
|
|
25
|
-
Requires-Dist: apcore>=0.
|
|
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 [
|
|
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 [
|
|
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.
|
|
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.
|
|
30
|
-
"apcore-toolkit[http-proxy]>=0.14.
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
323
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
453
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 =
|
|
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
|
-
|
|
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
|
-
|
|
310
|
+
exit_with(_EXIT_INVALID_CLI_INPUT)
|
|
309
311
|
else:
|
|
310
312
|
mode = raw_mode # type: ignore[assignment]
|
|
311
313
|
|