fix: Resolve STDIN input issues, improve logging precedence, add Rich table output, and enhance completion/man page generation with robust program name handling.

Author: tercel

CHANGELOG.md

@@ -5,6 +5,42 @@ 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.2.0] - 2026-03-16
+
+### Added
+- `APCORE_CLI_LOGGING_LEVEL` env var — CLI-specific log level that takes priority over `APCORE_LOGGING_LEVEL`; 3-tier precedence: `--log-level` flag > `APCORE_CLI_LOGGING_LEVEL` > `APCORE_LOGGING_LEVEL` > `WARNING` (`__main__.py`)
+- `test_cli_logging_level_takes_priority_over_global` — verifies `APCORE_CLI_LOGGING_LEVEL=DEBUG` wins over `APCORE_LOGGING_LEVEL=ERROR`
+- `test_cli_logging_level_fallback_to_global` — verifies fallback when CLI-specific var is unset
+- `test_builtin_name_collision_exits_2` — schema property named `format` (or other reserved names) causes `build_module_command` to exit 2
+- `test_exec_result_table_format` — `--format table` renders Rich Key/Value table to stdout
+- `test_bash_completion_quotes_prog_name_in_directive` — verifies `shlex.quote()` applied to `complete -F` directive, not just embedded subshell
+- `test_zsh_completion_quotes_prog_name_in_directives` — verifies `compdef` line uses quoted prog_name
+- `test_fish_completion_quotes_prog_name_in_directives` — verifies `complete -c` lines use quoted prog_name
+- 17 new tests (244 → 261 total)
+
+### Changed
+- `--log-level` accepted choices: `WARN` → `WARNING` (`__main__.py`)
+- `schema_to_click_options`: schema-derived options now always have `required=False`; required fields marked `[required]` in help text instead of Click enforcement — allows `--input -` STDIN to supply required values without Click rejecting first (`schema_parser.py`)
+- `format_exec_result`: now routes through `resolve_format()` and renders Rich table when `--format table` is specified; previously ignored its `format` parameter (`output.py`)
+- `_generate_bash_completion`, `_generate_zsh_completion`, `_generate_fish_completion`: `shlex.quote()` applied to ALL prog_name positions in generated scripts (complete directives, compdef, complete -c), not only embedded subshell commands (`shell.py`)
+- `check_approval`: removed unused `ctx: click.Context` parameter (`approval.py`)
+- `set_audit_logger`: broadened type annotation from `AuditLogger` to `AuditLogger | None` (`cli.py`)
+- `collect_input`: simplified redundant condition `if not raw or raw_size == 0:` → `if not raw:` (`cli.py`)
+- Example `Input` models: all 7 modules updated with `Field(description=...)` on every field so CLI `--help` shows descriptive text for each flag
+
+### Fixed
+- **`--input -` STDIN blocked by Click required enforcement**: `schema_to_click_options` was generating `required=True` Click options; Click validated before the callback ran, rejecting STDIN-only invocations. Resolved by always using `required=False` and delegating required validation to `jsonschema.validate()` after input collection. Fixes all 6 `TestRealStdinPiping` failures.
+- **`--log-level` had no effect**: `logging.basicConfig()` is a no-op after the first call; subsequent `create_cli()` calls in tests retained the prior handler's level. Fixed by calling `logging.getLogger().setLevel()` explicitly after `basicConfig()`.
+- **`test_log_level_flag_takes_effect` false pass**: `--help` is an eager flag that exits before the group callback, so `--log-level DEBUG --help` never applied the log level. Test updated to use `completion bash` subcommand instead.
+- **Shell completion directives not shell-safe**: prog names with spaces or special characters were unquoted in `complete -F`, `compdef`, and `complete -c` lines. Fixed by assigning `quoted = shlex.quote(prog_name)` and using it in all directive positions.
+- **Audit `set_audit_logger(None)` type error**: type annotation rejected `None`; broadened to `AuditLogger | None`.
+- **Test logger level leakage**: tests modifying root logger level affected subsequent tests; fixed with `try/finally` that restores the original level.
+
+### Security
+- `AuditLogger._hash_input`: now uses `secrets.token_bytes(16)` per-invocation salt before hashing, preventing cross-invocation input correlation via SHA-256 rainbow tables
+- `build_module_command`: added reserved-name collision guard — exits 2 if a schema property (`input`, `yes`, `large_input`, `format`, `sandbox`) conflicts with a built-in CLI option name
+- `_prompt_with_timeout` (SIGALRM path): wrapped in `try/finally` to guarantee signal handler restoration regardless of exit path
+
 ## [0.1.0] - 2026-03-15
 
 ### Added

README.md

@@ -8,7 +8,7 @@ Terminal adapter for apcore. Execute AI-Perceivable modules from the command lin
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://python.org)
-[![Tests](https://img.shields.io/badge/tests-244%20passed-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-261%20passed-brightgreen.svg)]()
 
 | | |
 |---|---|
@@ -170,7 +170,7 @@ apcore-cli [OPTIONS] COMMAND [ARGS]
 | Option | Default | Description |
 |--------|---------|-------------|
 | `--extensions-dir` | `./extensions` | Path to apcore extensions directory |
-| `--log-level` | `INFO` | Logging: `DEBUG`, `INFO`, `WARN`, `ERROR` |
+| `--log-level` | `WARNING` | Logging: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
 | `--version` | | Show version and exit |
 | `--help` | | Show help and exit |
 
@@ -227,7 +227,8 @@ apcore-cli uses a 4-tier configuration precedence:
 |----------|-------------|---------|
 | `APCORE_EXTENSIONS_ROOT` | Path to extensions directory | `./extensions` |
 | `APCORE_CLI_AUTO_APPROVE` | Set to `1` to bypass all approval prompts | *(unset)* |
-| `APCORE_LOGGING_LEVEL` | Log level | `INFO` |
+| `APCORE_CLI_LOGGING_LEVEL` | CLI-specific log level (takes priority over `APCORE_LOGGING_LEVEL`) | `WARNING` |
+| `APCORE_LOGGING_LEVEL` | Global apcore log level (fallback when `APCORE_CLI_LOGGING_LEVEL` is unset) | `WARNING` |
 | `APCORE_AUTH_API_KEY` | API key for remote registry authentication | *(unset)* |
 | `APCORE_CLI_SANDBOX` | Set to `1` to enable subprocess sandboxing | *(unset)* |
 
@@ -266,7 +267,7 @@ sandbox:
 | `module_id` (`math.add`) | Command name (`apcore-cli math.add`) |
 | `description` | `--help` text |
 | `input_schema.properties` | CLI flags (`--a`, `--b`) |
-| `input_schema.required` | Required flag enforcement |
+| `input_schema.required` | Validated post-collection via `jsonschema.validate()` (required fields shown as `[required]` in `--help`) |
 | `annotations.requires_approval` | HITL approval prompt |
 
 ### Architecture
@@ -377,7 +378,7 @@ apcore-cli --extensions-dir ./extensions greet.hello --name Alice --greeting Hi
 git clone https://github.com/aipartnerup/apcore-cli-python.git
 cd apcore-cli-python
 pip install -e ".[dev]"
-pytest                           # 244 tests
+pytest                           # 261 tests
 pytest --cov                     # with coverage report
 bash examples/run_examples.sh   # run all examples
 ```

examples/extensions/math/add.py

@@ -1,11 +1,11 @@
 """math.add — Add two numbers."""
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class Input(BaseModel):
-    a: int
-    b: int
+    a: int = Field(..., description="First operand")
+    b: int = Field(..., description="Second operand")
 
 
 class Output(BaseModel):

examples/extensions/math/multiply.py

@@ -1,11 +1,11 @@
 """math.multiply — Multiply two numbers."""
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class Input(BaseModel):
-    a: int
-    b: int
+    a: int = Field(..., description="First operand")
+    b: int = Field(..., description="Second operand")
 
 
 class Output(BaseModel):

examples/extensions/sysutil/disk.py

@@ -2,11 +2,11 @@
 
 import os
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class Input(BaseModel):
-    path: str = "/"
+    path: str = Field("/", description="Filesystem path to check (default: /)")
 
 
 class Output(BaseModel):

examples/extensions/sysutil/env.py

@@ -2,12 +2,12 @@
 
 import os
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class Input(BaseModel):
-    name: str
-    default: str = ""
+    name: str = Field(..., description="Environment variable name to read")
+    default: str = Field("", description="Value to return if the variable is not set")
 
 
 class Output(BaseModel):

examples/extensions/text/reverse.py

@@ -1,10 +1,10 @@
 """text.reverse — Reverse a string."""
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class Input(BaseModel):
-    text: str
+    text: str = Field(..., description="Input string to reverse")
 
 
 class Output(BaseModel):

examples/extensions/text/upper.py

@@ -1,10 +1,10 @@
 """text.upper — Convert text to uppercase."""
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class Input(BaseModel):
-    text: str
+    text: str = Field(..., description="Input string to convert")
 
 
 class Output(BaseModel):

examples/extensions/text/wordcount.py

@@ -1,10 +1,10 @@
 """text.wordcount — Count words, characters, and lines."""
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class Input(BaseModel):
-    text: str
+    text: str = Field(..., description="Input text to analyse")
 
 
 class Output(BaseModel):

src/apcore_cli/__main__.py

@@ -36,13 +36,35 @@ def _extract_extensions_dir(argv: list[str] | None = None) -> str | None:
     return None
 
 
-def create_cli(extensions_dir: str | None = None) -> click.Group:
+def create_cli(extensions_dir: str | None = None, prog_name: str | None = None) -> click.Group:
     """Create the CLI application.
 
     Args:
         extensions_dir: Override for extensions directory.
                         When None, resolves via ConfigResolver (env/file/default).
+        prog_name: Name shown in help text and version output.
+                   Defaults to the basename of sys.argv[0], so downstream projects
+                   that install their own entry-point script get the correct name
+                   automatically (e.g. ``mycli`` instead of ``apcore-cli``).
     """
+    if prog_name is None:
+        prog_name = os.path.basename(sys.argv[0]) or "apcore-cli"
+
+    # Resolve CLI log level (3-tier precedence, evaluated before Click runs):
+    #   APCORE_CLI_LOGGING_LEVEL (CLI-specific) > APCORE_LOGGING_LEVEL (global) > WARNING
+    # The --log-level flag (parsed later) can further override at runtime.
+    _cli_level_str = os.environ.get("APCORE_CLI_LOGGING_LEVEL", "").upper()
+    _global_level_str = os.environ.get("APCORE_LOGGING_LEVEL", "").upper()
+    _active_level_str = _cli_level_str or _global_level_str
+    _default_level = getattr(logging, _active_level_str, logging.WARNING) if _active_level_str else logging.WARNING
+    logging.basicConfig(level=_default_level, format="%(levelname)s: %(message)s")
+    # basicConfig is a no-op if handlers already exist; always set the root level explicitly.
+    logging.getLogger().setLevel(_default_level)
+    # Silence noisy upstream apcore loggers unless the user requests verbose output.
+    # Always set explicitly so the level is deterministic regardless of prior state.
+    apcore_level = _default_level if _default_level <= logging.INFO else logging.ERROR
+    logging.getLogger("apcore").setLevel(apcore_level)
+
     if extensions_dir is not None:
         ext_dir = extensions_dir
     else:
@@ -97,12 +119,12 @@ def create_cli(extensions_dir: str | None = None) -> click.Group:
         cls=LazyModuleGroup,
         registry=registry,
         executor=executor,
-        name="apcore-cli",
+        name=prog_name,
         help="CLI adapter for the apcore module ecosystem.",
     )
     @click.version_option(
         version=__version__,
-        prog_name="apcore-cli",
+        prog_name=prog_name,
     )
     @click.option(
         "--extensions-dir",
@@ -113,28 +135,39 @@ def create_cli(extensions_dir: str | None = None) -> click.Group:
     @click.option(
         "--log-level",
         default=None,
-        type=click.Choice(["DEBUG", "INFO", "WARN", "ERROR"], case_sensitive=False),
-        help="Log level.",
+        type=click.Choice(["DEBUG", "INFO", "WARNING", "ERROR"], case_sensitive=False),
+        help="Log verbosity. Overrides APCORE_CLI_LOGGING_LEVEL and APCORE_LOGGING_LEVEL env vars.",
     )
     @click.pass_context
     def cli(ctx: click.Context, extensions_dir_opt: str | None = None, log_level: str | None = None) -> None:
+        if log_level is not None:
+            # basicConfig() is a no-op once handlers exist; set level on the root logger directly.
+            level = getattr(logging, log_level.upper(), logging.WARNING)
+            logging.getLogger().setLevel(level)
+            # Keep apcore logger in sync: verbose when user asks for it, quiet otherwise.
+            apcore_level = level if level <= logging.INFO else logging.ERROR
+            logging.getLogger("apcore").setLevel(apcore_level)
         ctx.ensure_object(dict)
         ctx.obj["extensions_dir"] = ext_dir
 
     # Register discovery commands
     register_discovery_commands(cli, registry)
 
     # Register shell integration commands
-    register_shell_commands(cli)
+    register_shell_commands(cli, prog_name=prog_name)
 
     return cli
 
 
-def main() -> None:
-    """Main entry point for apcore-cli."""
-    # Extract --extensions-dir from argv before Click parses
+def main(prog_name: str | None = None) -> None:
+    """Main entry point for apcore-cli.
+
+    Args:
+        prog_name: Override the program name shown in help/version output.
+                   When None, inferred from sys.argv[0] automatically.
+    """
     ext_dir = _extract_extensions_dir()
-    cli = create_cli(extensions_dir=ext_dir)
+    cli = create_cli(extensions_dir=ext_dir, prog_name=prog_name)
     cli(standalone_mode=True)