Merge branch 'main' of github.com:httpdss/struct

Author: httpdss

docs/cli-reference.md

@@ -117,7 +117,7 @@ Usage:
 struct completion install [bash|zsh|fish]
 ```
 
-- If no shell is provided, the command attempts to auto-detect your current shell and prints the exact commands to enable argcomplete-based completion for struct.
+- If no shell is provided, the command attempts to auto-detect your current shell and prints the exact commands to generate and install static completion files via shtab.
 - This does not modify your shell configuration; it only prints the commands you can copy-paste.
 
 ### `init`

docs/completion.md

@@ -1,13 +1,13 @@
 # Command-Line Auto-Completion
 
-STRUCT provides intelligent auto-completion for commands, options, and **structure names** using [argcomplete](https://kislyuk.github.io/argcomplete/). This makes discovering and using available structures much faster and more user-friendly.
+STRUCT provides intelligent auto-completion for commands, options, and structure names using static completion scripts generated by [shtab](https://github.com/Iterative/shtab). This approach is reliable across shells and doesn’t require runtime hooks or markers.
 
-!!! tip "New Feature: Structure Name Completion"
-    STRUCT now automatically completes structure names when using `struct generate`, showing all 47+ available structures from both built-in and custom paths!
+!!! tip "Structure Name Completion"
+    STRUCT completes structure names when using `struct generate`, showing available structures from both built-in and custom paths.
 
 ## Quick Setup
 
-The easiest way is to ask struct to print the exact commands for your shell:
+Ask struct to print the exact commands for your shell:
 
 ```sh
 # Auto-detect current shell and print install steps
@@ -19,77 +19,48 @@ struct completion install bash
 struct completion install fish
 ```
 
-You can still follow the manual steps below if you prefer.
+You can also generate completion files manually with shtab as shown below.
 
-For most users, this simple setup will enable full completion:
+## Manual Installation
 
-```sh
-# Install (if not already installed)
-pip install argcomplete
-
-# Enable completion for current session
-eval "$(register-python-argcomplete struct)"
-
-# Make permanent - add to your ~/.zshrc or ~/.bashrc
-echo 'eval "$(register-python-argcomplete struct)"' >> ~/.zshrc
-```
-
-## Detailed Installation
-
-### 1. Install argcomplete
+### 1) Install shtab
 
 ```sh
-pip install argcomplete
+pip install shtab
 ```
 
-### 2. Enable Global Completion (Optional)
+### 2) Generate and install completion for your shell
 
-This step is optional but can be done once per system:
+- Zsh
 
-```sh
-activate-global-python-argcomplete
-```
-
-This command sets up global completion for all Python scripts that use argcomplete.
+  ```sh
+  mkdir -p ~/.zfunc
+  struct --print-completion zsh > ~/.zfunc/_struct
+  # ensure in ~/.zshrc
+  fpath=(~/.zfunc $fpath)
+  autoload -U compinit && compinit
+  exec zsh
+  ```
 
-### 3. Register the Script
+- Bash
 
-Add the following line to your shell's configuration file:
+  ```sh
+  mkdir -p ~/.local/share/bash-completion/completions
+  struct --print-completion bash > ~/.local/share/bash-completion/completions/struct
+  source ~/.bashrc
+  ```
 
-**For Bash** (`.bashrc` or `.bash_profile`):
+- Fish
 
-```sh
-eval "$(register-python-argcomplete struct)"
-```
-
-**For Zsh** (`.zshrc`):
-
-```sh
-eval "$(register-python-argcomplete struct)"
-```
-
-**For Fish** (`.config/fish/config.fish`):
-
-```fish
-register-python-argcomplete --shell fish struct | source
-```
-
-### 4. Reload Your Shell
-
-```sh
-# For Bash
-source ~/.bashrc
-
-# For Zsh
-source ~/.zshrc
-
-# For Fish
-source ~/.config/fish/config.fish
-```
+  ```sh
+  mkdir -p ~/.config/fish/completions
+  struct --print-completion fish > ~/.config/fish/completions/struct.fish
+  fish -c 'source ~/.config/fish/completions/struct.fish'
+  ```
 
 ## Usage
 
-After completing the setup, you can use auto-completion by typing part of a command and pressing `Tab`:
+After installing the completion, use Tab to complete commands/options:
 
 ### Command Completion
 ```sh
@@ -132,12 +103,7 @@ struct generate --log <Tab>
 
 ### Per-Project Completion
 
-If you only want completion for specific projects, you can add completion to your project's virtual environment activation script:
-
-```sh
-# In your .venv/bin/activate file, add:
-eval "$(register-python-argcomplete struct)"
-```
+If you only want completion for a specific project/venv, generate the completion from the project’s venv and place it under your user completion directory (examples above). No runtime eval is needed.
 
 ### Custom Completion
 
@@ -158,60 +124,41 @@ complete -F _struct_structures struct-generate
 
 ### Completion Not Working
 
-1. **Check argcomplete installation**:
-
-   ```sh
-   python -c "import argcomplete; print('OK')"
-   ```
-
-2. **Verify global activation**:
+1. Verify shtab is installed in the environment you’re using:
 
    ```sh
-   activate-global-python-argcomplete --user
+   python -c "import shtab; print('OK')"
    ```
 
-3. **Check shell configuration**:
-   Make sure the eval statement is in the correct shell configuration file.
+2. Confirm the completion file exists in the expected location and is readable.
 
-4. **Restart your shell**:
-   Sometimes you need to completely restart your terminal.
+3. Ensure your shell is configured to load completions:
+   - zsh: fpath includes ~/.zfunc and compinit is run.
+   - bash: bash-completion is installed and sourced (on some distros).
+   - fish: the file is in ~/.config/fish/completions/.
 
-### Slow Completion
-
-If completion is slow, you can enable caching:
-
-```sh
-export ARGCOMPLETE_USE_TEMPFILES=1
-```
-
-Add this to your shell configuration file for persistent caching.
+4. Restart your shell (or run `exec zsh`/`source ~/.bashrc`).
 
 ### Debug Completion
 
-Enable debug mode to troubleshoot completion issues:
-
-```sh
-export _ARGCOMPLETE_DEBUG=1
-struct <Tab>
-```
+For shell-specific debugging, check that the generated file contains the struct completion function and is in the correct directory for your shell.
 
 ## Platform-Specific Notes
 
 ### macOS
 
-On macOS, you might need to install bash-completion first:
+On macOS, you may need to install bash-completion (for bash) or ensure zsh’s compinit is configured:
 
 ```sh
 # Using Homebrew
 brew install bash-completion
-
-# Then add to ~/.bash_profile:
+# bash profile
 [[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"
 ```
 
 ### Windows
 
-For Windows users using Git Bash or WSL, follow the same steps as Linux. For PowerShell, argcomplete support is limited.
+For Windows users using Git Bash or WSL, follow the same steps as Linux. PowerShell is not covered by shtab; use bash/zsh/fish.
 
 ### Docker
 

docs/installation.md

@@ -9,11 +9,7 @@ pip install git+https://github.com/httpdss/struct.git
 ```
 
 !!! tip "Enable Auto-Completion"
-    After installation, enable command-line auto-completion for better productivity:
-    ```sh
-    eval "$(register-python-argcomplete struct)"
-    ```
-    For permanent setup, see the [Command-Line Completion](completion.md) guide.
+    After installation, enable command-line auto-completion using static scripts generated by shtab. See the [Command-Line Completion](completion.md) guide for per-shell instructions.
 
 ## From Source
 

requirements.txt

@@ -4,7 +4,7 @@ openai
 python-dotenv
 jinja2
 PyGithub
-argcomplete
+shtab
 colorlog
 boto3
 google-cloud

struct_module/commands/completion.py

@@ -6,7 +6,7 @@
 class CompletionCommand(Command):
   def __init__(self, parser):
     super().__init__(parser)
-    parser.description = "Manage CLI shell completions for struct (argcomplete)"
+    parser.description = "Manage CLI shell completions for struct (shtab-generated)"
     sub = parser.add_subparsers(dest="action")
 
     install = sub.add_parser("install", help="Print the commands to enable completion for your shell")
@@ -29,32 +29,37 @@ def _install(self, args):
     print(f"Detected shell: {shell}")
 
     if shell == "bash":
-      print("\n# One-time dependency (if not installed):")
-      print("python -m pip install argcomplete")
-      print("\n# Enable completion for 'struct' in bash (append to ~/.bashrc):")
-      print('echo "eval \"$(register-python-argcomplete struct)\"" >> ~/.bashrc')
-      print("\n# Apply now:")
+      print("\n# Install shtab (once, in your environment):")
+      print("python -m pip install shtab")
+      print("\n# Generate static bash completion for 'struct':")
+      print("mkdir -p ~/.local/share/bash-completion/completions")
+      print("struct --print-completion bash > ~/.local/share/bash-completion/completions/struct")
+      print("\n# Apply now (or open a new shell):")
       print("source ~/.bashrc")
 
     elif shell == "zsh":
-      print("\n# One-time dependency (if not installed):")
-      print("python -m pip install argcomplete")
-      print("\n# Enable completion for 'struct' in zsh (append to ~/.zshrc):")
-      print('echo "eval \"$(register-python-argcomplete --shell zsh struct)\"" >> ~/.zshrc')
-      print("\n# Apply now:")
-      print("source ~/.zshrc")
+      print("\n# Install shtab (once, in your environment):")
+      print("python -m pip install shtab")
+      print("\n# Generate static zsh completion for 'struct':")
+      print("mkdir -p ~/.zfunc")
+      print("struct --print-completion zsh > ~/.zfunc/_struct")
+      print("\n# Ensure zsh loads user functions/completions (append to ~/.zshrc if needed):")
+      print('echo "fpath=(~/.zfunc $fpath)" >> ~/.zshrc')
+      print('echo "autoload -U compinit && compinit" >> ~/.zshrc')
+      print("\n# Apply now (or open a new shell):")
+      print("exec zsh")
 
     elif shell == "fish":
-      print("\n# One-time dependency (if not installed):")
-      print("python -m pip install argcomplete")
-      print("\n# Install fish completion file for 'struct':")
+      print("\n# Install shtab (once, in your environment):")
+      print("python -m pip install shtab")
+      print("\n# Generate static fish completion for 'struct':")
       print('mkdir -p ~/.config/fish/completions')
-      print('register-python-argcomplete --shell fish struct > ~/.config/fish/completions/struct.fish')
+      print('struct --print-completion fish > ~/.config/fish/completions/struct.fish')
       print("\n# Apply now:")
       print("fish -c 'source ~/.config/fish/completions/struct.fish'")
 
     else:
       self.logger.error(f"Unsupported shell: {shell}. Supported: {', '.join(SUPPORTED_SHELLS)}")
       return
 
-    print("\nTip: If 'register-python-argcomplete' is not found, try:\n  python -m argcomplete.shellintegration <shell>")
+    print("\nTip: You can also print completion directly via: struct --print-completion <shell>")

struct_module/commands/generate.py

@@ -12,6 +12,7 @@
 class GenerateCommand(Command):
   def __init__(self, parser):
     super().__init__(parser)
+    parser.description = "Generate the project structure from a YAML configuration file"
     structure_arg = parser.add_argument('structure_definition', type=str, help='Path to the YAML configuration file')
     structure_arg.completer = structures_completer
     parser.add_argument('base_path', type=str, help='Base path where the structure will be created')

struct_module/commands/generate_schema.py

@@ -6,6 +6,7 @@
 class GenerateSchemaCommand(Command):
     def __init__(self, parser):
         super().__init__(parser)
+        parser.description = "Generate JSON schema for available structures"
         parser.add_argument('-s', '--structures-path', type=str, help='Path to structure definitions')
         parser.add_argument('-o', '--output', type=str, help='Output file path for the schema (default: stdout)')
         parser.set_defaults(func=self.execute)

struct_module/commands/info.py

@@ -8,6 +8,7 @@
 class InfoCommand(Command):
     def __init__(self, parser):
       super().__init__(parser)
+      parser.description = "Show information about the package or structure definition"
       parser.add_argument('structure_definition', type=str, help='Name of the structure definition')
       parser.add_argument('-s', '--structures-path', type=str, help='Path to structure definitions')
       parser.add_argument('--mcp', action='store_true', help='Enable MCP (Model Context Protocol) integration')

struct_module/commands/list.py

@@ -9,7 +9,9 @@
 class ListCommand(Command):
   def __init__(self, parser):
     super().__init__(parser)
+    parser.description = "List available structures"
     parser.add_argument('-s', '--structures-path', type=str, help='Path to structure definitions')
+    parser.add_argument('--names-only', action='store_true', help='Print only structure names, one per line (for shell completion)')
     parser.add_argument('--mcp', action='store_true', help='Enable MCP (Model Context Protocol) integration')
     parser.set_defaults(func=self.execute)
 
@@ -30,7 +32,6 @@ def _list_structures(self, args):
     else:
       paths_to_list = [contribs_path]
 
-    print("📃 Listing available structures\n")
     all_structures = set()
     for path in paths_to_list:
       for root, _, files in os.walk(path):
@@ -39,11 +40,23 @@ def _list_structures(self, args):
             rel_path = os.path.relpath(file_path, path)
             if file.endswith(".yaml"):
               rel_path = rel_path[:-5]
-              if path != contribs_path:
+              # Mark custom path entries with '+ ' unless names-only requested
+              if not args.names_only and path != contribs_path:
                 rel_path = f"+ {rel_path}"
               all_structures.add(rel_path)
 
     sorted_list = sorted(all_structures)
+
+    if args.names_only:
+      # Print plain names without bullets or headers, remove '+ ' marker
+      for structure in sorted_list:
+        if structure.startswith('+ '):
+          print(structure[2:])
+        else:
+          print(structure)
+      return
+
+    print("📃 Listing available structures\n")
     for structure in sorted_list:
       print(f" - {structure}")
 

struct_module/commands/mcp.py

@@ -8,6 +8,7 @@
 class MCPCommand(Command):
     def __init__(self, parser):
         super().__init__(parser)
+        parser.description = "MCP (Model Context Protocol) support for struct tool"
         parser.add_argument('--server', action='store_true',
                           help='Start the MCP server for stdio communication')
         parser.set_defaults(func=self.execute)