CLI: fix sh completion command flag

Author: xsedla1o

README.md

@@ -96,15 +96,12 @@ docker compose -f docker-compose.app.yml up -d --build
 
 Either way, to test that everything is running properly, you can run:
 ```shell
-curl -X 'GET' 'http://localhost:5000/' \
-     -H 'Accept: application/json' 
+dp3 sh health
 ```
 
 Which should return a JSON response with the following content:
 ```json
-{
-   "detail": "It works!"
-}
+{"detail": "It works!"}
 ```
 
 Final note, to simplify the experience of adjusting the app configuration, 
@@ -155,16 +152,14 @@ The `docker-compose.yml` configuration contains the configuration for the servic
 as well as a testing setup of the DP³ platform itself. 
 The full configuration is in `tests/test_config`.
 The setup includes one worker process and one API process to handle requests. 
-The API process is exposed on port 5000, so you can send requests to it using `curl` or from your browser:
+The API process is exposed on port 5000, so you can send requests to it using `curl`, from your browser, or using the `dp3 sh` CLI:
 
 ```shell
-curl -X 'GET' 'http://localhost:5000/' \
-     -H 'Accept: application/json' 
+dp3 sh health
 ```
 ```shell
-curl -X 'POST' 'http://localhost:5000/datapoints' \
-     -H 'Content-Type: application/json' \
-     --data '[{"type": "test_entity_type", "id": "abc", "attr": "test_attr_int", "v": 123, "t1": "2023-07-01T12:00:00", "t2": "2023-07-01T13:00:00"}]'
+echo '[{"type": "test_entity_type", "id": "abc", "attr": "test_attr_int", "v": 123, "t1": "2023-07-01T12:00:00", "t2": "2023-07-01T13:00:00"}]\n' \
+  | dp3 sh datapoints
 ```
 
 ### Testing

docs/howto/deploy-app.md

@@ -210,6 +210,9 @@ Generate the base supervisor configuration for the app:
 sudo $(which dp3) config supervisor --config <CONFIG_DIR> --app-name <APP_NAME>
 ```
 
+The generated supervisor configuration lives under `/etc/<APP_NAME>` and the process logs are written under `/var/log/<APP_NAME>`.
+For more on supervisor itself, see the [supervisorctl documentation](http://supervisord.org/running.html#running-supervisorctl).
+
 Enable and start the generated system service:
 
 ```shell
@@ -231,26 +234,66 @@ This creates two app-specific helpers:
 
 `<APPNAME>sh entities` returns the full entity-type configuration map exposed by the API. When you only need the configured entity type names, pipe it through `jq keys`.
 
-You can also enable shell completion for the wrapper or for `dp3 sh` itself:
+You can also enable shell completion for the wrapper or for `dp3` itself.
+The completion is registered for the executable name seen by the shell:
 
-```shell
-# Bash
-source <(<APPNAME>sh completion bash --command <APPNAME>sh)
-source <(dp3 sh completion bash --command dp3)
+- use `--command dp3` for the main `dp3` command tree
+- use `--command <APPNAME>sh` for the generated wrapper
 
-# Zsh
-source <(<APPNAME>sh completion zsh --command <APPNAME>sh)
-source <(dp3 sh completion zsh --command dp3)
+#### Session-local autocomplete 
 
-# Fish
-<APPNAME>sh completion fish --command <APPNAME>sh | source
-dp3 sh completion fish --command dp3 | source
-```
+Enable completion in the current shell session only:
 
-The generated completion is config-aware. It can suggest entity types and attribute names from the resolved DP3 configuration.
+=== "Bash"
 
-The generated supervisor configuration lives under `/etc/<APP_NAME>` and the process logs are written under `/var/log/<APP_NAME>`.
-For more on supervisor itself, see the [supervisorctl documentation](http://supervisord.org/running.html#running-supervisorctl).
+    ```shell
+    source <(dp3 sh completion bash --command dp3 --command <APPNAME>sh)
+    ```
+
+=== "Zsh"
+
+    ```shell
+    source <(dp3 sh completion zsh --command dp3 --command <APPNAME>sh)
+    ```
+
+=== "Fish"
+
+    ```shell
+    dp3 sh completion fish --command dp3 --command <APPNAME>sh | source
+    ```
+
+#### Persistent activation
+
+To keep completion enabled across shell sessions, add the appropriate command to your shell startup file.
+
+=== "Bash"
+
+    Add one of these to `~/.bashrc`:
+
+    ```shell
+    source <(<APPNAME>sh completion bash --command <APPNAME>sh)
+    source <(dp3 sh completion bash --command dp3)
+    ```
+
+=== "Zsh"
+
+    Add one of these to `~/.zshrc`:
+
+    ```shell
+    source <(<APPNAME>sh completion zsh --command <APPNAME>sh)
+    source <(dp3 sh completion zsh --command dp3)
+    ```
+
+=== "Fish"
+
+    Write the generated completion to a Fish completion file:
+
+    ```shell
+    <APPNAME>sh completion fish --command <APPNAME>sh > ~/.config/fish/completions/<APPNAME>sh.fish
+    dp3 sh completion fish --command dp3 > ~/.config/fish/completions/dp3.fish
+    ```
+
+The generated completion is config-aware. It can suggest entity types and attribute names from the resolved DP3 configuration.
 
 ### 6. Check that the deployment is healthy
 

docs/howto/get-started.md

@@ -246,6 +246,62 @@ A healthy API responds with:
 
 At this point, you have a local DP³ environment ready for trying configuration changes and testing new code.
 
+### Optional: enable shell completion for `dp3`
+
+By default, the following will generate completion for the `dp3` executable.
+
+#### Session-local activation
+
+Enable completion in the current shell session only:
+
+=== "Bash"
+
+    ```shell
+    source <(dp3 sh completion bash)
+    ```
+
+=== "Zsh"
+
+    ```shell
+    source <(dp3 sh completion zsh)
+    ```
+
+=== "Fish"
+
+    ```shell
+    dp3 sh completion fish | source
+    ```
+
+#### Persistent activation
+
+To keep completion enabled across shell sessions, add the appropriate command to your shell startup file.
+
+=== "Bash"
+
+    Add this to `~/.bashrc`:
+
+    ```shell
+    source <(dp3 sh completion bash)
+    ```
+
+=== "Zsh"
+
+    Add this to `~/.zshrc`:
+
+    ```shell
+    source <(dp3 sh completion zsh)
+    ```
+
+=== "Fish"
+
+    Write the generated completion to a Fish completion file:
+
+    ```shell
+    dp3 sh completion fish > ~/.config/fish/completions/dp3.fish
+    ```
+
+The generated completion is config-aware. It can suggest entity types and attribute names from the resolved DP3 configuration.
+
 ## 7. Sanity-check configuration changes as you iterate
 
 When you change configuration, especially `config/db_entities`, validate it before restarting services:

dp3/bin/sh.py

@@ -21,7 +21,7 @@ def render_completion_shellcode(shell_name: str, command_names: list[str]) -> st
 
 def handle_completion(_client, args) -> int:
     """Print shell completion registration code."""
-    sys.stdout.write(render_completion_shellcode(args.shell_name, args.command))
+    sys.stdout.write(render_completion_shellcode(args.shell_name, args.completion_commands))
     if not sys.stdout.isatty():
         sys.stdout.write("\n")
     return 0
@@ -37,24 +37,25 @@ def register_completion_parser(commands) -> None:
             "output in your shell or source it from your shell startup file."
         ),
     )
-    completion_commands = completion_parser.add_subparsers(dest="shell_name", required=True)
-    for shell_name in ["bash", "zsh", "fish"]:
-        shell_parser = completion_commands.add_parser(
-            shell_name, help=f"Print a {shell_name.capitalize()} completion script."
-        )
-        shell_parser.add_argument(
-            "-c",
-            "--command",
-            action="append",
-            default=[],
-            help=(
-                "Command name to register completion for. Repeat to register multiple "
-                "commands. Use 'dp3' for 'dp3 sh' and '<APPNAME>sh' for wrapper commands."
-            ),
-        )
-        shell_parser.set_defaults(
-            handler=handle_completion, requires_api=False, load_model_spec=False
-        )
+    completion_parser.add_argument(
+        "shell_name",
+        help="Shell name.",
+        choices=["bash", "zsh", "fish", "tcsh", "powershell"],
+    )
+    completion_parser.add_argument(
+        "-c",
+        "--command",
+        dest="completion_commands",
+        action="append",
+        default=None,
+        help=(
+            "Command name to register completion for. Repeat to register multiple "
+            "commands. Use 'dp3' for 'dp3 sh' and '<APPNAME>sh' for wrapper commands."
+        ),
+    )
+    completion_parser.set_defaults(
+        handler=handle_completion, requires_api=False, load_model_spec=False
+    )
 
 
 def init_parser(parser: argparse.ArgumentParser) -> None:

dp3/template/appsh

@@ -1,2 +1,12 @@
 #!/bin/sh
+
+if [ -n "${_ARGCOMPLETE:-}" ] && [ -n "${COMP_LINE:-}" ] && [ -n "${COMP_POINT:-}" ]; then
+    wrapper_name="${0##*/}"
+    completion_prefix="{{DP3_EXE}} sh"
+    completion_suffix="${COMP_LINE#"$wrapper_name"}"
+    COMP_LINE="$completion_prefix$completion_suffix"
+    COMP_POINT=$((COMP_POINT + ${#completion_prefix} - ${#wrapper_name}))
+    export COMP_LINE COMP_POINT
+fi
+
 DP3_CONFIG_DIR="{{CONFIG_DIR}}" exec {{DP3_EXE}} sh "$@"

tests/test_common/test_sh_completion.py

@@ -5,6 +5,7 @@
 
 from argcomplete.finders import CompletionFinder
 
+from dp3.bin.cli import init_parser as init_root_parser
 from dp3.bin.sh import init_parser, render_completion_shellcode
 from dp3.bin.shcmd.common import complete_entity_type_names
 
@@ -230,3 +231,9 @@ def test_fish_completion_script_registers_commands(self):
         script = render_completion_shellcode("fish", ["dp3", "appsh"])
         self.assertIn("complete --command dp3", script)
         self.assertIn("complete --command appsh", script)
+
+    def test_completion_command_flag_does_not_override_root_command(self):
+        parser = init_root_parser()
+        args = parser.parse_args(["sh", "completion", "zsh", "-c", "dp3"])
+        self.assertEqual("sh", args.command)
+        self.assertEqual(["dp3"], args.completion_commands)