feat: add DisplayResolver integration, grouped completion, path validation, and sync fixes for v0.3.0

- Integrate DisplayResolver from apcore-toolkit (optional) with --binding option
- Add "init" to BUILTIN_COMMANDS, add APCORE_AUTH_API_KEY to man page
- Add grouped shell completion with _APCORE_GRP support
- Add path traversal validation for --dir in init command
- Fix RegistryWriter API call (constructor takes no params)
- Bump apcore dependency to >=0.14.0

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tercel

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
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apcore-cli"
-version = "0.3.0"
+version = "0.3.1"
 description = "Terminal adapter for apcore — execute AI-Perceivable modules from the command line"
 readme = "README.md"
 license = "Apache-2.0"

src/apcore_cli/__main__.py

@@ -45,10 +45,16 @@ 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 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,6 +68,9 @@ 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"
@@ -138,8 +147,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,6 +200,12 @@ 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,
@@ -193,6 +217,7 @@ 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,
     ) -> None:
         if log_level is not None:
@@ -228,7 +253,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)
 
 

src/apcore_cli/cli.py

@@ -27,7 +27,7 @@
 
 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

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 init_module(module_id: str, style: str, output_dir: str | None, description:
 
         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:

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 = [
@@ -380,7 +386,7 @@ def man_cmd(ctx: click.Context, command: str) -> None:
         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)