apcore-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{apcore_cli-0.3.0 → apcore_cli-0.4.0}/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.4.0] - 2026-03-29
+
+### Added
+- **Verbose help mode** — Built-in apcore options (`--input`, `--yes`, `--large-input`, `--format`, `--sandbox`) are now hidden from `--help` output by default. Pass `--help --verbose` to display the full option list including built-in options.
+- **Universal man page generation** — `build_program_man_page()` generates a complete roff man page covering all registered commands. `configure_man_help()` adds `--help --man` support to any Click CLI, enabling downstream projects to get man pages for free.
+- **Documentation URL support** — `set_docs_url()` sets a base URL for online docs. Per-command help shows `Docs: {url}/commands/{name}`, man page SEE ALSO includes `Full documentation at {url}`. No default — disabled when not set.
+
+### Changed
+- `build_module_command()` respects the global verbose help flag to control built-in option visibility.
+- `--sandbox` is now always hidden from help (not yet implemented). Only four built-in options (`--input`, `--yes`, `--large-input`, `--format`) toggle with `--verbose`.
+- Improved built-in option descriptions for clarity.
+
+---
+
+## [0.3.1] - 2026-03-27
+
+### Added
+
+- **DisplayResolver integration** — `__main__.py` integrates `DisplayResolver` from `apcore-toolkit` (optional) when `--binding` option is provided; gracefully skipped when not installed.
+- **`init` to `BUILTIN_COMMANDS`** — `init` subcommand is now registered in the builtin commands set.
+- **`APCORE_AUTH_API_KEY` to man page** — environment variable documented in generated roff man page.
+- **Grouped shell completion with `_APCORE_GRP`** — bash/zsh/fish completion scripts now support two-level group/command completion via the `_APCORE_GRP` environment variable (`shell.py`).
+- **Path traversal validation for `--dir` in `init` command** — rejects paths containing `..` segments to prevent directory escape (`init_cmd.py`).
+
+### Fixed
+
+- **`RegistryWriter` API call** — constructor now called without parameters; fixes `TypeError` introduced by upstream API change.
+
+### Changed
+
+- `apcore` dependency bumped to `>=0.14.0`.
+
+---
+
 ## [0.3.0] - 2026-03-23
 
 ### Added

{apcore_cli-0.3.0 → apcore_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apcore-cli
-Version: 0.3.0
+Version: 0.4.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
@@ -20,7 +20,7 @@ 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>=0.13.1
+Requires-Dist: apcore>=0.14.0
 Requires-Dist: click>=8.1
 Requires-Dist: cryptography>=41.0
 Requires-Dist: jsonschema>=4.20
@@ -85,7 +85,7 @@ Terminal adapter for apcore. Execute AI-Perceivable modules from the command lin
 pip install apcore-cli
 ```
 
-Requires Python 3.11+ and `apcore >= 0.13.0`.
+Requires Python 3.11+ and `apcore >= 0.14.0`.
 
 ## Quick Start
 
@@ -241,6 +241,8 @@ apcore-cli [OPTIONS] COMMAND [ARGS]
 | `--log-level` | `WARNING` | Logging: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
 | `--version` | | Show version and exit |
 | `--help` | | Show help and exit |
+| `--verbose` | | Show hidden built-in options in `--help` output |
+| `--man` | | Print man page to stdout (use with `--help`) |
 
 ### Built-in Commands
 
@@ -253,7 +255,7 @@ apcore-cli [OPTIONS] COMMAND [ARGS]
 
 ### Module Execution Options
 
-When executing a module (e.g. `apcore-cli math.add`), these built-in options are always available:
+When executing a module (e.g. `apcore-cli math.add`), these built-in options are available (hidden by default; pass `--help --verbose` to display them):
 
 | Option | Description |
 |--------|-------------|
@@ -261,7 +263,7 @@ When executing a module (e.g. `apcore-cli math.add`), these built-in options are
 | `--yes` / `-y` | Bypass approval prompts |
 | `--large-input` | Allow STDIN input larger than 10MB |
 | `--format` | Output format: `json` or `table` |
-| `--sandbox` | Run module in subprocess sandbox |
+| `--sandbox` | Run module in subprocess sandbox *(not yet implemented)* |
 
 Schema-generated flags (e.g. `--a`, `--b`) are added automatically from the module's `input_schema`.
 
@@ -328,7 +330,8 @@ cli:
 - **Schema validation** -- inputs validated against JSON Schema before execution, with `$ref`/`allOf`/`anyOf`/`oneOf` resolution
 - **Security** -- API key auth (keyring + AES-256-GCM), append-only audit logging, subprocess sandboxing
 - **Shell completions** -- `apcore-cli completion bash|zsh|fish` generates completion scripts with dynamic module ID completion
-- **Man pages** -- `apcore-cli man <command>` generates roff-formatted man pages
+- **Man pages** -- `apcore-cli man <command>` generates per-command man pages; `--help --man` prints a full-program man page via `configure_man_help()`
+- **Documentation URL** -- `set_docs_url()` sets a base URL; per-command help shows `Docs: {url}/commands/{name}`, man page SEE ALSO links to the full docs site
 - **Audit logging** -- all executions logged to `~/.apcore-cli/audit.jsonl` with SHA-256 input hashing
 
 ## How It Works
@@ -353,6 +356,10 @@ apcore-cli (the adapter)
     |
     +-- ConfigResolver       4-tier config precedence
     +-- LazyModuleGroup      Dynamic Click command generation
+    +-- set_verbose_help     Toggle built-in option visibility
+    +-- set_docs_url         Set base URL for online docs
+    +-- build_program_man_page  Full-program roff man page
+    +-- configure_man_help   Add --help --man support to any CLI
     +-- schema_parser        JSON Schema -> Click options
     +-- ref_resolver         $ref / allOf / anyOf / oneOf
     +-- approval             TTY-aware HITL approval

{apcore_cli-0.3.0 → apcore_cli-0.4.0}/README.md

@@ -48,7 +48,7 @@ Terminal adapter for apcore. Execute AI-Perceivable modules from the command lin
 pip install apcore-cli
 ```
 
-Requires Python 3.11+ and `apcore >= 0.13.0`.
+Requires Python 3.11+ and `apcore >= 0.14.0`.
 
 ## Quick Start
 
@@ -204,6 +204,8 @@ apcore-cli [OPTIONS] COMMAND [ARGS]
 | `--log-level` | `WARNING` | Logging: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
 | `--version` | | Show version and exit |
 | `--help` | | Show help and exit |
+| `--verbose` | | Show hidden built-in options in `--help` output |
+| `--man` | | Print man page to stdout (use with `--help`) |
 
 ### Built-in Commands
 
@@ -216,7 +218,7 @@ apcore-cli [OPTIONS] COMMAND [ARGS]
 
 ### Module Execution Options
 
-When executing a module (e.g. `apcore-cli math.add`), these built-in options are always available:
+When executing a module (e.g. `apcore-cli math.add`), these built-in options are available (hidden by default; pass `--help --verbose` to display them):
 
 | Option | Description |
 |--------|-------------|
@@ -224,7 +226,7 @@ When executing a module (e.g. `apcore-cli math.add`), these built-in options are
 | `--yes` / `-y` | Bypass approval prompts |
 | `--large-input` | Allow STDIN input larger than 10MB |
 | `--format` | Output format: `json` or `table` |
-| `--sandbox` | Run module in subprocess sandbox |
+| `--sandbox` | Run module in subprocess sandbox *(not yet implemented)* |
 
 Schema-generated flags (e.g. `--a`, `--b`) are added automatically from the module's `input_schema`.
 
@@ -291,7 +293,8 @@ cli:
 - **Schema validation** -- inputs validated against JSON Schema before execution, with `$ref`/`allOf`/`anyOf`/`oneOf` resolution
 - **Security** -- API key auth (keyring + AES-256-GCM), append-only audit logging, subprocess sandboxing
 - **Shell completions** -- `apcore-cli completion bash|zsh|fish` generates completion scripts with dynamic module ID completion
-- **Man pages** -- `apcore-cli man <command>` generates roff-formatted man pages
+- **Man pages** -- `apcore-cli man <command>` generates per-command man pages; `--help --man` prints a full-program man page via `configure_man_help()`
+- **Documentation URL** -- `set_docs_url()` sets a base URL; per-command help shows `Docs: {url}/commands/{name}`, man page SEE ALSO links to the full docs site
 - **Audit logging** -- all executions logged to `~/.apcore-cli/audit.jsonl` with SHA-256 input hashing
 
 ## How It Works
@@ -316,6 +319,10 @@ apcore-cli (the adapter)
     |
     +-- ConfigResolver       4-tier config precedence
     +-- LazyModuleGroup      Dynamic Click command generation
+    +-- set_verbose_help     Toggle built-in option visibility
+    +-- set_docs_url         Set base URL for online docs
+    +-- build_program_man_page  Full-program roff man page
+    +-- configure_man_help   Add --help --man support to any CLI
     +-- schema_parser        JSON Schema -> Click options
     +-- ref_resolver         $ref / allOf / anyOf / oneOf
     +-- approval             TTY-aware HITL approval

{apcore_cli-0.3.0 → apcore_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apcore-cli"
-version = "0.3.0"
+version = "0.4.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.13.1",
+    "apcore>=0.14.0",
     "click>=8.1",
     "jsonschema>=4.20",
     "rich>=13.0",

{apcore_cli-0.3.0 → apcore_cli-0.4.0}/src/apcore_cli/__main__.py

@@ -9,7 +9,7 @@ import sys
 import click
 
 from apcore_cli import __version__
-from apcore_cli.cli import GroupedModuleGroup, set_audit_logger
+from apcore_cli.cli import GroupedModuleGroup, set_audit_logger, set_verbose_help
 from apcore_cli.config import ConfigResolver
 from apcore_cli.discovery import register_discovery_commands
 from apcore_cli.security.audit import AuditLogger
@@ -45,10 +45,22 @@ def _extract_commands_dir(argv: list[str] | None = None) -> str | None:
     return _extract_argv_option(argv, "--commands-dir")
 
 
+def _extract_binding_path(argv: list[str] | None = None) -> str | None:
+    """Extract --binding value from argv before Click parses it."""
+    return _extract_argv_option(argv, "--binding")
+
+
+def _has_verbose_flag(argv: list[str] | None = None) -> bool:
+    """Check if --verbose is present in argv (pre-parse, before Click)."""
+    args = argv if argv is not None else sys.argv[1:]
+    return "--verbose" in args
+
+
 def create_cli(
     extensions_dir: str | None = None,
     prog_name: str | None = None,
     commands_dir: str | None = None,
+    binding_path: str | None = None,
 ) -> click.Group:
     """Create the CLI application.
 
@@ -62,10 +74,18 @@ def create_cli(
         commands_dir: Directory containing convention-based modules.
                       When set, scans for plain-function modules and registers
                       them via ConventionScanner (requires apcore-toolkit).
+        binding_path: Path to binding.yaml file or directory for display resolution.
+                      When set, applies DisplayResolver to convention-scanned modules
+                      (requires apcore-toolkit).
     """
     if prog_name is None:
         prog_name = os.path.basename(sys.argv[0]) or "apcore-cli"
 
+    # Pre-parse --verbose before Click runs so build_module_command knows
+    # whether to hide built-in options.
+    verbose = _has_verbose_flag()
+    set_verbose_help(verbose)
+
     # 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.
@@ -106,7 +126,7 @@ def create_cli(
 
     if ext_dir_missing:
         click.echo(
-            f"Error: Extensions directory not found: '{ext_dir}'. " "Set APCORE_EXTENSIONS_ROOT or verify the path.",
+            f"Error: Extensions directory not found: '{ext_dir}'. Set APCORE_EXTENSIONS_ROOT or verify the path.",
             err=True,
         )
         sys.exit(EXIT_CONFIG_NOT_FOUND)
@@ -138,8 +158,17 @@ def create_cli(
                 conv_scanner = ConventionScanner()
                 conv_modules = conv_scanner.scan(commands_dir)
                 if conv_modules:
-                    writer = RegistryWriter(registry=registry)
-                    writer.write(conv_modules)
+                    if binding_path is not None:
+                        try:
+                            from apcore_toolkit import DisplayResolver
+
+                            display_resolver = DisplayResolver()
+                            conv_modules = display_resolver.resolve(conv_modules, binding_path=binding_path)
+                            logger.info("DisplayResolver: applied binding from %s", binding_path)
+                        except ImportError:
+                            logger.warning("DisplayResolver not available in apcore-toolkit")
+                    writer = RegistryWriter()
+                    writer.write(conv_modules, registry)
                     logger.info("Convention scanner: registered %d modules from %s", len(conv_modules), commands_dir)
             except ImportError:
                 logger.warning("apcore-toolkit not installed — convention module scanning unavailable")
@@ -182,18 +211,33 @@ def create_cli(
         default=None,
         help="Path to convention-based commands directory.",
     )
+    @click.option(
+        "--binding",
+        "binding_opt",
+        default=None,
+        help="Path to binding.yaml file or directory for display resolution.",
+    )
     @click.option(
         "--log-level",
         default=None,
         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.option(
+        "--verbose",
+        "verbose_help",
+        is_flag=True,
+        default=False,
+        help="Show all options in help output (including built-in apcore options).",
+    )
     @click.pass_context
     def cli(
         ctx: click.Context,
         extensions_dir_opt: str | None = None,
         commands_dir_opt: str | None = None,
+        binding_opt: str | None = None,
         log_level: str | None = None,
+        verbose_help: bool = False,
     ) -> None:
         if log_level is not None:
             # basicConfig() is a no-op once handlers exist; set level on the root logger directly.
@@ -204,6 +248,7 @@ def create_cli(
             logging.getLogger("apcore").setLevel(apcore_level)
         ctx.ensure_object(dict)
         ctx.obj["extensions_dir"] = ext_dir
+        ctx.obj["verbose_help"] = verbose_help
 
     # Register discovery commands
     register_discovery_commands(cli, registry)
@@ -228,7 +273,8 @@ def main(prog_name: str | None = None) -> None:
     """
     ext_dir = _extract_extensions_dir()
     cmd_dir = _extract_commands_dir()
-    cli = create_cli(extensions_dir=ext_dir, prog_name=prog_name, commands_dir=cmd_dir)
+    bind_path = _extract_binding_path()
+    cli = create_cli(extensions_dir=ext_dir, prog_name=prog_name, commands_dir=cmd_dir, binding_path=bind_path)
     cli(standalone_mode=True)
 
 

{apcore_cli-0.3.0 → apcore_cli-0.4.0}/src/apcore_cli/cli.py

@@ -27,11 +27,38 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger("apcore_cli.cli")
 
-BUILTIN_COMMANDS = ["exec", "list", "describe", "completion", "man"]
+BUILTIN_COMMANDS = ["completion", "describe", "exec", "init", "list", "man"]
 
 # Module-level audit logger, set during CLI init
 _audit_logger: AuditLogger | None = None
 
+# Module-level verbose help flag, set during CLI init
+_verbose_help: bool = False
+
+
+def set_verbose_help(verbose: bool) -> None:
+    """Set the verbose help flag. When False, built-in options are hidden."""
+    global _verbose_help
+    _verbose_help = verbose
+
+
+# Module-level docs URL, set by downstream projects
+_docs_url: str | None = None
+
+
+def set_docs_url(url: str | None) -> None:
+    """Set the base URL for online documentation links in help and man pages.
+
+    Pass None to disable. Command-level help appends ``/commands/{name}``
+    automatically.
+
+    Example::
+
+        set_docs_url("https://docs.apcore.dev/cli")
+    """
+    global _docs_url
+    _docs_url = url
+
 
 def set_audit_logger(audit_logger: AuditLogger | None) -> None:
     """Set the global audit logger instance. Pass None to clear."""
@@ -452,18 +479,27 @@ def build_module_command(
             sys.exit(exit_code)
 
     # Build the command with schema-generated options + built-in options
+    _epilog_parts: list[str] = []
+    if not _verbose_help:
+        _epilog_parts.append("Use --verbose to show all options (including built-in apcore options).")
+    if _docs_url:
+        _epilog_parts.append(f"Docs: {_docs_url}/commands/{effective_cmd_name}")
+    _epilog = "\n".join(_epilog_parts) if _epilog_parts else None
     cmd = click.Command(
         name=effective_cmd_name,
         help=cmd_help,
         callback=callback,
+        epilog=_epilog,
     )
 
-    # Add built-in options
+    # Add built-in options (hidden unless --verbose is passed with --help)
+    _hide = not _verbose_help
     cmd.params.append(
         click.Option(
             ["--input"],
             default=None,
-            help="Read input from file or STDIN ('-').",
+            help="Read JSON input from a file path, or use '-' to read from stdin pipe.",
+            hidden=_hide,
         )
     )
     cmd.params.append(
@@ -471,7 +507,8 @@ def build_module_command(
             ["--yes", "-y"],
             is_flag=True,
             default=False,
-            help="Bypass approval prompts.",
+            help="Skip interactive approval prompts (for scripts and CI).",
+            hidden=_hide,
         )
     )
     cmd.params.append(
@@ -479,7 +516,8 @@ def build_module_command(
             ["--large-input"],
             is_flag=True,
             default=False,
-            help="Allow STDIN input larger than 10MB.",
+            help="Allow stdin input larger than 10MB (default limit protects against accidental pipes).",
+            hidden=_hide,
         )
     )
     cmd.params.append(
@@ -487,20 +525,23 @@ def build_module_command(
             ["--format"],
             type=click.Choice(["json", "table"]),
             default=None,
-            help="Output format.",
+            help="Set output format: 'json' for machine-readable, 'table' for human-readable.",
+            hidden=_hide,
         )
     )
+    # --sandbox is always hidden (not yet implemented)
     cmd.params.append(
         click.Option(
             ["--sandbox"],
             is_flag=True,
             default=False,
-            help="Run module in subprocess sandbox.",
+            help="Run module in an isolated subprocess with restricted filesystem and env access.",
+            hidden=True,
         )
     )
 
     # Guard: schema property names must not collide with built-in option names.
-    _reserved = {"input", "yes", "large_input", "format", "sandbox"}
+    _reserved = {"input", "yes", "large_input", "format", "sandbox", "verbose"}
     for opt in schema_options:
         if opt.name in _reserved:
             click.echo(

{apcore_cli-0.3.0 → apcore_cli-0.4.0}/src/apcore_cli/init_cmd.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import sys
 from pathlib import Path
 
 import click
@@ -59,6 +60,10 @@ def register_init_command(cli: click.Group) -> None:
 
         MODULE_ID is the module identifier (e.g., ops.deploy, user.create).
         """
+        if output_dir is not None and ".." in Path(output_dir).parts:
+            click.echo("Error: Output directory must not contain '..' path components.", err=True)
+            sys.exit(2)
+
         # Parse module_id into parts
         parts = module_id.rsplit(".", 1)
         if len(parts) == 2:

{apcore_cli-0.3.0 → apcore_cli-0.4.0}/src/apcore_cli/shell.py

@@ -59,7 +59,7 @@ def _generate_bash_completion(prog_name: str) -> str:
         "\n"
         "    if [[ ${COMP_CWORD} -eq 1 ]]; then\n"
         f"        local all_ids=$({groups_and_top_cmd})\n"
-        '        local builtins="exec list describe completion man"\n'
+        '        local builtins="completion describe exec init list man"\n'
         '        COMPREPLY=( $(compgen -W "${builtins} ${all_ids}" -- ${cur}) )\n'
         "        return 0\n"
         "    fi\n"
@@ -124,6 +124,7 @@ def _generate_zsh_completion(prog_name: str) -> str:
         "        'list:List available modules'\n"
         "        'describe:Show module metadata and schema'\n"
         "        'completion:Generate shell completion script'\n"
+        "        'init:Scaffolding commands'\n"
         "        'man:Generate man page'\n"
         "    )\n"
         "\n"
@@ -208,6 +209,8 @@ def _generate_fish_completion(prog_name: str) -> str:
         f'complete -c {quoted} -n "__fish_use_subcommand"'
         ' -a completion -d "Generate shell completion script"\n'
         f'complete -c {quoted} -n "__fish_use_subcommand"'
+        ' -a init -d "Scaffolding commands"\n'
+        f'complete -c {quoted} -n "__fish_use_subcommand"'
         ' -a man -d "Generate man page"\n'
         f'complete -c {quoted} -n "__fish_use_subcommand"'
         f' -a "({groups_and_top_cmd})" -d "Module group or command"\n'
@@ -304,6 +307,9 @@ def _generate_man_page(command_name: str, command: click.Command | None, prog_na
         "Global apcore logging verbosity. One of: DEBUG, INFO, WARNING, ERROR. "
         "Used as fallback when \\fBAPCORE_CLI_LOGGING_LEVEL\\fR is not set. Default: WARNING."
     )
+    sections.append(".TP")
+    sections.append("\\fBAPCORE_AUTH_API_KEY\\fR")
+    sections.append("API key for authenticating with the apcore registry.")
 
     sections.append(".SH EXIT CODES")
     exit_codes = [
@@ -333,6 +339,187 @@ def _generate_man_page(command_name: str, command: click.Command | None, prog_na
     return "\n".join(sections)
 
 
+def _roff_escape(s: str) -> str:
+    """Escape a string for roff output."""
+    return s.replace("\\", "\\\\").replace("-", "\\-").replace("'", "\\(aq")
+
+
+def build_program_man_page(
+    cli: click.Group,
+    prog_name: str,
+    version: str,
+    description: str | None = None,
+    docs_url: str | None = None,
+) -> str:
+    """Build a complete roff man page for the entire CLI program.
+
+    Covers all registered commands including downstream business commands
+    injected via GroupedModuleGroup.
+    """
+    today = date.today().isoformat()
+    desc = description or cli.help or f"{prog_name} CLI"
+    s: list[str] = []
+
+    s.append(f'.TH "{prog_name.upper()}" "1" "{today}" "{prog_name} {version}" "{prog_name} Manual"')
+
+    s.append(".SH NAME")
+    s.append(f"{prog_name} \\- {_roff_escape(desc)}")
+
+    s.append(".SH SYNOPSIS")
+    s.append(f"\\fB{prog_name}\\fR [\\fIglobal\\-options\\fR] \\fIcommand\\fR [\\fIcommand\\-options\\fR]")
+
+    s.append(".SH DESCRIPTION")
+    s.append(_roff_escape(desc))
+
+    # Global options
+    ctx = click.Context(cli, info_name=prog_name)
+    params = cli.get_params(ctx)
+    visible_params = [p for p in params if not getattr(p, "hidden", False) and p.name not in ("help", "version", "man")]
+    if visible_params:
+        s.append(".SH GLOBAL OPTIONS")
+        for p in visible_params:
+            record = p.get_help_record(ctx)
+            if record:
+                s.append(".TP")
+                s.append(f"\\fB{_roff_escape(record[0])}\\fR")
+                s.append(_roff_escape(record[1]))
+
+    # Commands
+    cmd_names = cli.list_commands(ctx)
+    if cmd_names:
+        s.append(".SH COMMANDS")
+        for name in sorted(cmd_names):
+            if name == "help":
+                continue
+            cmd = cli.get_command(ctx, name)
+            if cmd is None:
+                continue
+
+            cmd_desc = cmd.get_short_help_str() if cmd else ""
+            s.append(".TP")
+            s.append(f"\\fB{prog_name} {_roff_escape(name)}\\fR")
+            if cmd_desc:
+                s.append(_roff_escape(cmd_desc))
+
+            # Command options
+            sub_ctx = click.Context(cmd, info_name=name, parent=ctx)
+            sub_params = [
+                p for p in cmd.get_params(sub_ctx) if not getattr(p, "hidden", False) and p.name not in ("help",)
+            ]
+            for p in sub_params:
+                record = p.get_help_record(sub_ctx)
+                if record:
+                    s.append(".RS")
+                    s.append(".TP")
+                    s.append(f"\\fB{_roff_escape(record[0])}\\fR")
+                    s.append(_roff_escape(record[1]))
+                    s.append(".RE")
+
+            # Nested subcommands (groups)
+            if isinstance(cmd, click.Group):
+                sub_names = cmd.list_commands(sub_ctx)
+                for sub_name in sorted(sub_names):
+                    if sub_name == "help":
+                        continue
+                    sub_cmd = cmd.get_command(sub_ctx, sub_name)
+                    if sub_cmd is None:
+                        continue
+                    sub_desc = sub_cmd.get_short_help_str() if sub_cmd else ""
+                    s.append(".TP")
+                    s.append(f"\\fB{prog_name} {_roff_escape(name)} {_roff_escape(sub_name)}\\fR")
+                    if sub_desc:
+                        s.append(_roff_escape(sub_desc))
+                    nested_ctx = click.Context(sub_cmd, info_name=sub_name, parent=sub_ctx)
+                    nested_params = [
+                        p
+                        for p in sub_cmd.get_params(nested_ctx)
+                        if not getattr(p, "hidden", False) and p.name not in ("help",)
+                    ]
+                    for p in nested_params:
+                        record = p.get_help_record(nested_ctx)
+                        if record:
+                            s.append(".RS")
+                            s.append(".TP")
+                            s.append(f"\\fB{_roff_escape(record[0])}\\fR")
+                            s.append(_roff_escape(record[1]))
+                            s.append(".RE")
+
+    # Environment
+    s.append(".SH ENVIRONMENT")
+    s.append(".TP")
+    s.append("\\fBAPCORE_EXTENSIONS_ROOT\\fR")
+    s.append("Path to the apcore extensions directory.")
+    s.append(".TP")
+    s.append("\\fBAPCORE_CLI_AUTO_APPROVE\\fR")
+    s.append("Set to \\fB1\\fR to bypass approval prompts.")
+    s.append(".TP")
+    s.append("\\fBAPCORE_CLI_LOGGING_LEVEL\\fR")
+    s.append("CLI\\-specific logging verbosity (DEBUG|INFO|WARNING|ERROR).")
+
+    # Exit codes
+    s.append(".SH EXIT CODES")
+    codes = [
+        ("0", "Success."),
+        ("1", "Module execution error."),
+        ("2", "Invalid input."),
+        ("44", "Module not found."),
+        ("45", "Schema validation error."),
+        ("46", "Approval denied or timed out."),
+        ("47", "Configuration error."),
+        ("77", "ACL denied."),
+        ("130", "Cancelled by user (SIGINT)."),
+    ]
+    for code, meaning in codes:
+        s.append(f".TP\n\\fB{code}\\fR\n{meaning}")
+
+    s.append(".SH SEE ALSO")
+    s.append(f"\\fB{prog_name} \\-\\-help \\-\\-verbose\\fR for full option list.")
+    if docs_url:
+        s.append(f".PP\nFull documentation at \\fI{_roff_escape(docs_url)}\\fR")
+
+    return "\n".join(s)
+
+
+def configure_man_help(
+    cli: click.Group,
+    prog_name: str,
+    version: str,
+    description: str | None = None,
+    docs_url: str | None = None,
+) -> None:
+    """Configure --help --man support on a Click CLI group.
+
+    When --man is passed with --help, outputs a complete roff man page
+    covering all registered commands. Downstream projects call this once
+    to get man page generation for free.
+
+    .. note::
+        Call this **after** all commands are registered on ``cli``.
+        The argv pre-parse triggers immediate man page generation, so
+        commands added later will not appear in the output.
+
+    Usage:
+        configure_man_help(cli, "reach", "0.2.0", "ReachForge", "https://reachforge.dev/docs")
+    """
+    # Add --man as a hidden Click option
+    cli.params.append(
+        click.Option(
+            ["--man"],
+            is_flag=True,
+            default=False,
+            hidden=True,
+            help="Output man page in roff format (use with --help).",
+        )
+    )
+
+    # Pre-parse: if both --help and --man in argv, generate man page and exit
+    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)
+        sys.exit(0)
+
+
 def register_shell_commands(cli: click.Group, prog_name: str = "apcore-cli") -> None:
     """Register completion and man commands."""
 
@@ -380,7 +567,7 @@ def register_shell_commands(cli: click.Group, prog_name: str = "apcore-cli") ->
         parent_group = parent.command
         cmd = parent_group.commands.get(command) if isinstance(parent_group, click.Group) else None
 
-        known_builtins = {"list", "describe", "completion", "man"}
+        known_builtins = {"completion", "describe", "exec", "init", "list", "man"}
         if cmd is None and command not in known_builtins:
             click.echo(f"Error: Unknown command '{command}'.", err=True)
             sys.exit(2)

{apcore_cli-0.3.0 → apcore_cli-0.4.0}/tests/test_cli.py

@@ -880,3 +880,56 @@ class TestGroupedE2E:
         group = self._make_e2e_group()
         result = CliRunner().invoke(group, ["product", "nonexistent"])
         assert result.exit_code == 2
+
+
+class TestVerboseHelp:
+    """Tests for --verbose help flag controlling built-in option visibility."""
+
+    def test_builtin_options_hidden_by_default(self):
+        """Built-in options are hidden from help by default."""
+        from apcore_cli import cli as cli_mod
+
+        cli_mod._verbose_help = False
+        try:
+            module_def = _make_mock_module_def()
+            cmd = build_module_command(module_def, _make_mock_executor())
+            hidden_names = [p.name for p in cmd.params if getattr(p, "hidden", False)]
+            assert "input" in hidden_names
+            assert "yes" in hidden_names
+            assert "large_input" in hidden_names
+            assert "format" in hidden_names
+            assert "sandbox" in hidden_names
+        finally:
+            cli_mod._verbose_help = False
+
+    def test_builtin_options_shown_when_verbose(self):
+        """Built-in options are visible when verbose help is enabled."""
+        from apcore_cli import cli as cli_mod
+
+        cli_mod._verbose_help = True
+        try:
+            module_def = _make_mock_module_def()
+            cmd = build_module_command(module_def, _make_mock_executor())
+            hidden_names = [p.name for p in cmd.params if getattr(p, "hidden", False)]
+            assert "input" not in hidden_names
+            assert "yes" not in hidden_names
+            assert "large_input" not in hidden_names
+            assert "format" not in hidden_names
+            # sandbox is always hidden (not yet implemented)
+            assert "sandbox" in hidden_names
+        finally:
+            cli_mod._verbose_help = False
+
+    def test_set_verbose_help_function(self):
+        """set_verbose_help correctly sets the module-level flag."""
+        from apcore_cli import cli as cli_mod
+        from apcore_cli.cli import set_verbose_help
+
+        original = cli_mod._verbose_help
+        try:
+            set_verbose_help(True)
+            assert cli_mod._verbose_help is True
+            set_verbose_help(False)
+            assert cli_mod._verbose_help is False
+        finally:
+            cli_mod._verbose_help = original

{apcore_cli-0.3.0 → apcore_cli-0.4.0}/tests/test_shell.py

@@ -7,6 +7,8 @@ from apcore_cli.shell import (
     _generate_bash_completion,
     _generate_fish_completion,
     _generate_zsh_completion,
+    build_program_man_page,
+    configure_man_help,
     register_shell_commands,
 )
 
@@ -231,3 +233,105 @@ class TestManCommand:
         assert "SYNOPSIS" in result.output
         # Should reflect the actual --tag option, not generic [ARGUMENTS]
         assert "--tag" in result.output
+
+
+class TestBuildProgramManPage:
+    def test_generates_roff_with_th_header(self):
+        @click.group()
+        def cli():
+            pass
+
+        @cli.command()
+        @click.option("--name", help="Your name")
+        def hello(name):
+            pass
+
+        roff = build_program_man_page(cli, "test-cli", "1.0.0")
+        assert '.TH "TEST-CLI"' in roff
+        assert ".SH COMMANDS" in roff
+        assert "hello" in roff
+
+    def test_includes_nested_subcommands(self):
+        @click.group()
+        def cli():
+            pass
+
+        @cli.group()
+        def grp():
+            pass
+
+        @grp.command()
+        @click.option("--flag", is_flag=True, help="A flag")
+        def sub(flag):
+            pass
+
+        roff = build_program_man_page(cli, "mycli", "1.0.0")
+        assert "mycli grp sub" in roff
+
+    def test_includes_standard_sections(self):
+        @click.group()
+        def cli():
+            """My test CLI."""
+
+        roff = build_program_man_page(cli, "test-cli", "1.0.0")
+        assert ".SH NAME" in roff
+        assert ".SH SYNOPSIS" in roff
+        assert ".SH DESCRIPTION" in roff
+        assert ".SH ENVIRONMENT" in roff
+        assert ".SH EXIT CODES" in roff
+        assert ".SH SEE ALSO" in roff
+
+    def test_uses_custom_description(self):
+        @click.group()
+        def cli():
+            pass
+
+        roff = build_program_man_page(cli, "test-cli", "1.0.0", description="Custom desc")
+        assert "Custom desc" in roff
+
+    def test_includes_command_options(self):
+        @click.group()
+        def cli():
+            pass
+
+        @cli.command()
+        @click.option("--output", "-o", help="Output file")
+        def build(output):
+            pass
+
+        roff = build_program_man_page(cli, "test-cli", "1.0.0")
+        assert "Output file" in roff
+
+    def test_skips_help_command(self):
+        @click.group()
+        def cli():
+            pass
+
+        @cli.command()
+        def help():
+            pass
+
+        roff = build_program_man_page(cli, "test-cli", "1.0.0")
+        # "help" should not appear in the COMMANDS section as a listed command
+        assert "test\\-cli help" not in roff
+
+
+class TestConfigureManHelp:
+    def test_adds_hidden_man_option(self):
+        @click.group()
+        def cli():
+            pass
+
+        configure_man_help(cli, "test-cli", "1.0.0")
+        man_params = [p for p in cli.params if p.name == "man"]
+        assert len(man_params) == 1
+        assert man_params[0].hidden is True
+
+    def test_man_option_is_flag(self):
+        @click.group()
+        def cli():
+            pass
+
+        configure_man_help(cli, "test-cli", "1.0.0")
+        man_params = [p for p in cli.params if p.name == "man"]
+        assert man_params[0].is_flag is True