feat: implement man page rendering, add Config Bus namespace support, and enable backward-compatible configuration mapping

Author: tercel

pyproject.toml

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

src/apcore_cli/__init__.py

@@ -7,3 +7,21 @@
     __version__ = _get_version("apcore-cli")
 except PackageNotFoundError:
     __version__ = "unknown"
+
+# Config Bus namespace registration (apcore >= 0.15.0)
+try:
+    from apcore import Config
+
+    Config.register_namespace(
+        name="apcore-cli",
+        schema=None,
+        env_prefix="APCORE_CLI",
+        defaults={
+            "stdin_buffer_limit": 10_485_760,
+            "auto_approve": False,
+            "help_text_max_length": 1000,
+            "logging_level": "WARNING",
+        },
+    )
+except (ImportError, AttributeError):
+    pass  # apcore < 0.15.0 or not installed

src/apcore_cli/__main__.py

@@ -13,7 +13,7 @@
 from apcore_cli.config import ConfigResolver
 from apcore_cli.discovery import register_discovery_commands
 from apcore_cli.security.audit import AuditLogger
-from apcore_cli.shell import register_shell_commands
+from apcore_cli.shell import configure_man_help, register_shell_commands
 
 logger = logging.getLogger("apcore_cli")
 
@@ -256,6 +256,9 @@ def cli(
     # Register shell integration commands
     register_shell_commands(cli, prog_name=prog_name)
 
+    # Register --help --man support
+    configure_man_help(cli, prog_name, __version__)
+
     # Register init scaffolding command
     from apcore_cli.init_cmd import register_init_command
 

src/apcore_cli/cli.py

@@ -343,6 +343,13 @@ def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> Non
                 with formatter.section("Groups"):
                     formatter.write_dl(group_records)
 
+        # Footer hints for discoverability
+        formatter.write_paragraph()
+        formatter.write(
+            "Use --help --verbose to show all options (including built-in apcore options).\n"
+            "Use --help --man to display a formatted man page."
+        )
+
 
 # Error code mapping from apcore error codes to CLI exit codes
 _ERROR_CODE_MAP = {
@@ -359,6 +366,13 @@ def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> Non
     "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_MOUNT_ERROR": 66,
+    "CONFIG_BIND_ERROR": 65,
+    "ERROR_FORMATTER_DUPLICATE": 70,
 }
 
 

src/apcore_cli/config.py

@@ -16,13 +16,27 @@ class ConfigResolver:
     CLI flag > Environment variable > Config file > Default.
     """
 
+    # Namespace key -> legacy key mapping for backward compatibility
+    _NAMESPACE_TO_LEGACY: dict[str, str] = {
+        "apcore-cli.stdin_buffer_limit": "cli.stdin_buffer_limit",
+        "apcore-cli.auto_approve": "cli.auto_approve",
+        "apcore-cli.help_text_max_length": "cli.help_text_max_length",
+        "apcore-cli.logging_level": "logging.level",
+    }
+    _LEGACY_TO_NAMESPACE: dict[str, str] = {v: k for k, v in _NAMESPACE_TO_LEGACY.items()}
+
     DEFAULTS: dict[str, Any] = {
         "extensions.root": "./extensions",
         "logging.level": "WARNING",
         "sandbox.enabled": False,
         "cli.stdin_buffer_limit": 10_485_760,  # 10 MB
         "cli.auto_approve": False,
         "cli.help_text_max_length": 1000,
+        # Namespace-mode aliases (apcore >= 0.15.0 Config Bus)
+        "apcore-cli.stdin_buffer_limit": 10_485_760,
+        "apcore-cli.auto_approve": False,
+        "apcore-cli.help_text_max_length": 1000,
+        "apcore-cli.logging_level": "WARNING",
     }
 
     def __init__(
@@ -53,9 +67,13 @@ def resolve(
             if env_value is not None and env_value != "":
                 return env_value
 
-        # Tier 3: Config file
-        if self._config_file is not None and key in self._config_file:
-            return self._config_file[key]
+        # Tier 3: Config file (try both namespace and legacy keys)
+        if self._config_file is not None:
+            if key in self._config_file:
+                return self._config_file[key]
+            alt_key = self._NAMESPACE_TO_LEGACY.get(key) or self._LEGACY_TO_NAMESPACE.get(key)
+            if alt_key and alt_key in self._config_file:
+                return self._config_file[alt_key]
 
         # Tier 4: Default
         return self.DEFAULTS.get(key)

src/apcore_cli/shell.py

@@ -2,8 +2,10 @@
 
 from __future__ import annotations
 
+import os
 import re
 import shlex
+import subprocess
 import sys
 from datetime import date
 
@@ -480,6 +482,48 @@ def build_program_man_page(
     return "\n".join(s)
 
 
+def _render_man_page(roff: str) -> None:
+    """Render a roff man page to stdout.
+
+    When stdout is a TTY, attempts to render through mandoc or groff and
+    pipe through a pager for formatted display. When stdout is not a TTY
+    (piped or redirected), outputs raw roff for file redirection.
+    """
+    roff_bytes = roff.encode()
+    if not sys.stdout.isatty():
+        sys.stdout.write(roff)
+        return
+
+    # Try mandoc first (macOS/BSD), then groff
+    renderers = [
+        ["mandoc", "-a"],
+        ["groff", "-man", "-Tutf8"],
+    ]
+    for cmd in renderers:
+        try:
+            result = subprocess.run(
+                cmd,
+                input=roff_bytes,
+                capture_output=True,
+            )
+        except FileNotFoundError:
+            continue
+        if result.returncode == 0 and result.stdout:
+            pager = os.environ.get("PAGER", "less")
+            try:
+                subprocess.run(
+                    [pager, "-R"],
+                    input=result.stdout,
+                )
+                return
+            except FileNotFoundError:
+                # Pager not found — fall through to raw output
+                break
+
+    # Fallback: raw roff output
+    sys.stdout.write(roff)
+
+
 def configure_man_help(
     cli: click.Group,
     prog_name: str,
@@ -520,7 +564,7 @@ def configure_man_help(
     args = sys.argv[1:]
     if "--man" in args and ("--help" in args or "-h" in args):
         roff = build_program_man_page(cli, prog_name, version, description, docs_url)
-        click.echo(roff)
+        _render_man_page(roff)
         sys.exit(0)
 
 

tests/test_config.py

@@ -140,3 +140,47 @@ def test_flatten_dict_deeply_nested(self):
         resolver = ConfigResolver(config_path="/nonexistent/apcore.yaml")
         result = resolver._flatten_dict({"a": {"b": {"c": "deep_value"}}})
         assert result == {"a.b.c": "deep_value"}
+
+
+class TestNamespaceAwareConfigResolution:
+    """Config Bus namespace ↔ legacy key fallback (apcore >= 0.15.0)."""
+
+    def test_defaults_contain_namespace_keys(self):
+        resolver = ConfigResolver()
+        for key in [
+            "apcore-cli.stdin_buffer_limit",
+            "apcore-cli.auto_approve",
+            "apcore-cli.help_text_max_length",
+            "apcore-cli.logging_level",
+        ]:
+            assert key in resolver.DEFAULTS, f"Missing namespace default: {key}"
+
+    def test_resolve_namespace_key_from_legacy_config_file(self, tmp_path, clean_env):
+        """Querying 'apcore-cli.stdin_buffer_limit' finds 'cli.stdin_buffer_limit' in file."""
+        config_file = tmp_path / "apcore.yaml"
+        config_file.write_text("cli:\n  stdin_buffer_limit: 5242880\n")
+        resolver = ConfigResolver(config_path=str(config_file))
+        result = resolver.resolve("apcore-cli.stdin_buffer_limit")
+        assert result == 5242880
+
+    def test_resolve_legacy_key_from_namespace_config_file(self, tmp_path, clean_env):
+        """Querying 'cli.auto_approve' finds 'apcore-cli.auto_approve' in file."""
+        config_file = tmp_path / "apcore.yaml"
+        config_file.write_text("apcore-cli:\n  auto_approve: true\n")
+        resolver = ConfigResolver(config_path=str(config_file))
+        result = resolver.resolve("cli.auto_approve")
+        assert result is True
+
+    def test_direct_key_takes_precedence_over_alternate(self, tmp_path, clean_env):
+        """When both keys exist in file, the directly-queried key wins."""
+        config_file = tmp_path / "apcore.yaml"
+        config_file.write_text("cli:\n  help_text_max_length: 500\n" "apcore-cli:\n  help_text_max_length: 2000\n")
+        resolver = ConfigResolver(config_path=str(config_file))
+        assert resolver.resolve("cli.help_text_max_length") == 500
+        assert resolver.resolve("apcore-cli.help_text_max_length") == 2000
+
+    def test_namespace_mapping_is_bidirectional(self):
+        resolver = ConfigResolver()
+        assert len(resolver._NAMESPACE_TO_LEGACY) == len(resolver._LEGACY_TO_NAMESPACE)
+        for ns_key, legacy_key in resolver._NAMESPACE_TO_LEGACY.items():
+            assert resolver._LEGACY_TO_NAMESPACE[legacy_key] == ns_key