feat: Add max_content_width to create_cli() for improved help formatting and optimize simplify_ids prefix generation for shorter module IDs.

Author: tercel

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.1] - 2026-03-20
+
+### Added
+- **`max_content_width` parameter on `create_cli()`** -- overrides Click's default terminal-width-based help formatting. When the terminal is narrow, Click calculates description column width from the longest command name, often leaving zero space for descriptions (shown as `...`). This parameter forces a wider layout so descriptions are always visible.
+
+### Improved
+- **`simplify_ids` prefix optimization** -- when `simplify_ids=True`, module ID prefix now uses only the first path segment instead of all segments. This produces shorter, cleaner command names while maintaining uniqueness via function name differentiation and `deduplicate_ids()` safety net.
+  - Before: `credit_purchase.purchase.status.get_purchase_status_by_payment_intent.get` (73 chars)
+  - After: `credit_purchase.get_purchase_status_by_payment_intent.get` (57 chars)
+- Default (`simplify_ids=False`) behavior unchanged -- all path segments preserved for backward compatibility.
+
 ## [0.3.0] - 2026-03-20
 
 ### Added

README.md

@@ -285,7 +285,7 @@ cli = apcore.create_cli(
     prog_name="myapp-cli",
     base_url="http://localhost:8000",
     simplify_ids=True,
-    help_text_max_length=500,
+    max_content_width=160,       # wider help output for long command names
 )
 
 if __name__ == "__main__":
@@ -451,7 +451,14 @@ scanner = get_scanner("native")
 modules = scanner.scan(app, include=r"users\.", exclude=r"\.delete$")
 ```
 
-The `simplify_ids` option extracts the original Python function name from FastAPI's auto-generated operationId, producing much shorter and more readable module IDs. It defaults to `False` for backward compatibility.
+The `simplify_ids` option extracts the original Python function name from FastAPI's auto-generated operationId and uses only the first path segment as prefix, producing much shorter and more readable module IDs:
+
+```
+Default:       credit_purchase.purchase.status.get_purchase_status_by_payment_intent.get  (73 chars)
+simplify_ids:  credit_purchase.get_purchase_status_by_payment_intent.get                  (57 chars)
+```
+
+It defaults to `False` for backward compatibility.
 
 Users only need to interact with two things:
 - **`FastAPIApcore`** -- the unified entry point (import from `fastapi_apcore`)

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-apcore"
-version = "0.3.0"
+version = "0.3.1"
 description = "FastAPI integration for apcore AI-Perceivable Core — exposes FastAPI routes as apcore modules with auto-discovery, schema extraction from Pydantic models, and OpenAPI-based scanning."
 requires-python = ">=3.11"
 readme = "README.md"

src/fastapi_apcore/client.py

@@ -533,6 +533,7 @@ def create_cli(
         include: str | None = None,
         exclude: str | None = None,
         help_text_max_length: int = 1000,
+        max_content_width: int | None = None,
     ) -> Any:
         """Create an apcore-cli Click group with all API routes as commands.
 
@@ -553,6 +554,9 @@ def create_cli(
             exclude: Regex pattern — skip matching module IDs.
             help_text_max_length: Max characters for CLI help text per
                 command. Defaults to 1000.
+            max_content_width: Maximum width for CLI help output. When set,
+                overrides Click's default (terminal width, max 80). Useful
+                when command names are long and truncate descriptions.
 
         Returns:
             A Click Group that can be invoked with ``cli(standalone_mode=True)``.
@@ -609,13 +613,25 @@ def create_cli(
         executor = Executor(registry)
 
         # 3. Build Click group
+        ctx_settings: dict[str, Any] = {}
+        if max_content_width is not None:
+            ctx_settings["max_content_width"] = max_content_width
+
+        # Compute the effective help width for the command list.
+        # Click uses min(terminal_width, max_content_width), so when the
+        # terminal is narrow, long command names push the description column
+        # to zero and everything shows "...".  We override format_commands
+        # to use the configured max_content_width directly.
+        effective_width = max_content_width
+
         @click.group(
             cls=LazyModuleGroup,
             registry=registry,
             executor=executor,
             help_text_max_length=help_text_max_length,
             name=prog_name,
             help=f"{prog_name} — CLI for {app.title or 'FastAPI'} API.",
+            context_settings=ctx_settings,
         )
         @click.version_option(
             version=app.version or "0.0.0",
@@ -638,6 +654,19 @@ def cli(log_level: str | None = None) -> None:
         register_discovery_commands(cli, registry)
         register_shell_commands(cli, prog_name=prog_name)
 
+        # Override format_commands to use effective_width so descriptions
+        # are not truncated when the terminal is narrower than the content.
+        if effective_width is not None:
+            _original_format_commands = cli.format_commands
+
+            def _wide_format_commands(ctx: Any, formatter: Any) -> None:
+                original_width = formatter.width
+                formatter.width = max(formatter.width, effective_width)
+                _original_format_commands(ctx, formatter)
+                formatter.width = original_width
+
+            cli.format_commands = _wide_format_commands  # type: ignore[method-assign]
+
         return cli
 
     def to_openai_tools(

src/fastapi_apcore/scanners/openapi.py

@@ -121,16 +121,17 @@ def get_source_name(self) -> str:
         return "openapi-fastapi"
 
     def _generate_module_id(self, operation: dict[str, Any], path: str, method: str) -> str:
-        """Generate module_id from tags + function_name + method.
+        """Generate module_id from prefix + function_name + method.
 
         When ``simplify_ids=True`` (set in constructor), extracts the clean
-        function name from FastAPI's operationId::
+        function name and uses only the first path segment as prefix::
 
-            GET /product/{product_id}  → product.get_product.get
-            POST /task/create          → task.create_task.post
+            GET  /product/{product_id}                      → product.get_product.get
+            POST /task/create                               → task.create_task.post
+            GET  /virtual-purchase/purchase/status/{id}     → virtual_purchase.get_purchase_status_by_payment_intent.get
 
         When ``simplify_ids=False`` (default), uses the raw operationId
-        with only the trailing method stripped::
+        with only the trailing method stripped, and all path segments as prefix::
 
             GET /product/{product_id}  → product.get_product_product__product_id_.get
         """
@@ -144,7 +145,12 @@ def _generate_module_id(self, operation: dict[str, Any], path: str, method: str)
 
         if tags:
             prefix = str(tags[0]).lower().replace(" ", "_")
+        elif self._simplify_ids:
+            # Only first path segment as prefix — shorter, still unique
+            path_parts = [p for p in path.strip("/").split("/") if not p.startswith("{")]
+            prefix = path_parts[0] if path_parts else "root"
         else:
+            # All path segments as prefix (default, backward compatible)
             path_parts = [p for p in path.strip("/").split("/") if not p.startswith("{")]
             prefix = ".".join(path_parts) if path_parts else "root"