Merge pull request #669 from algorandfoundation/chore/generate-args

chore: support passing client generator args to the language

Author: neilcampbell

docs/cli/index.md

@@ -70,6 +70,7 @@
     - [-v, --version ](#-v---version--1)
     - [Arguments](#arguments-7)
     - [APP_SPEC_PATH_OR_DIR](#app_spec_path_or_dir)
+    - [ARGS](#args)
   - [goal](#goal)
     - [Options](#options-11)
     - [--console](#--console)
@@ -588,7 +589,7 @@ Supply the path to an application specification file or a directory to recursive
 for "application.json" files
 
 ```shell
-algokit generate client [OPTIONS] APP_SPEC_PATH_OR_DIR
+algokit generate client [OPTIONS] [APP_SPEC_PATH_OR_DIR] [ARGS]...
 ```
 
 ### Options
@@ -615,7 +616,11 @@ The client generator version to pin to, for example, 1.0.0. If no version is spe
 
 
 ### APP_SPEC_PATH_OR_DIR
-Required argument
+Optional argument
+
+
+### ARGS
+Optional argument(s)
 
 ## goal
 

src/algokit/cli/generate.py

@@ -106,10 +106,17 @@ def generate_group() -> None:
     """Generate code for an Algorand project."""
 
 
-@generate_group.command("client")
+@generate_group.command(
+    "client",
+    context_settings={
+        "ignore_unknown_options": True,
+    },
+    add_help_option=False,
+)
 @click.argument(
     "app_spec_path_or_dir",
-    type=click.Path(exists=True, dir_okay=True, resolve_path=True, path_type=Path),
+    type=click.Path(dir_okay=True, resolve_path=True, path_type=Path),
+    required=False,
 )
 @click.option(
     "output_path_pattern",
@@ -138,13 +145,20 @@ def generate_group() -> None:
     "If a version is specified, AlgoKit checks if an installed version matches and runs the installed version. "
     "Otherwise, AlgoKit runs the specified version.",
 )
+@click.argument("args", nargs=-1, type=click.UNPROCESSED)
 def generate_client(
-    output_path_pattern: str | None, app_spec_path_or_dir: Path, language: str | None, version: str | None
+    app_spec_path_or_dir: Path | None,
+    output_path_pattern: str | None,
+    language: str | None,
+    version: str | None,
+    args: tuple[str, ...],
 ) -> None:
     """Create a typed ApplicationClient from an ARC-32/56 application.json
 
     Supply the path to an application specification file or a directory to recursively search
     for "application.json" files"""
+
+    generator = None
     if language is not None:
         generator = ClientGenerator.create_for_language(language, version)
     elif output_path_pattern is not None:
@@ -156,16 +170,41 @@ def generate_client(
                 "Could not determine language from file extension, Please use the --language option to specify a "
                 "target language"
             ) from ex
+
+    help_in_args = any(_is_help_flag(arg) for arg in args)
+    help_in_positional = app_spec_path_or_dir is not None and _is_help_flag(app_spec_path_or_dir)
+
+    if help_in_positional:
+        ctx = click.get_current_context()
+        click.echo(ctx.get_help())
+    elif generator:
+        if help_in_args:
+            generator.show_help()
+            return
+
+        if app_spec_path_or_dir is None:
+            raise click.ClickException("Missing argument 'APP_SPEC_PATH_OR_DIR'.")
+
+        try:
+            generator.generate_all(
+                app_spec_path_or_dir,
+                output_path_pattern,
+                list(args),
+                raise_on_path_resolution_failure=False,
+            )
+        except AppSpecsNotFoundError as ex:
+            raise click.ClickException("No app specs found") from ex
     else:
         raise click.ClickException(
             "One of --language or --output is required to determine the client language to generate"
         )
 
-    try:
-        generator.generate_all(
-            app_spec_path_or_dir,
-            output_path_pattern,
-            raise_on_path_resolution_failure=False,
-        )
-    except AppSpecsNotFoundError as ex:
-        raise click.ClickException("No app specs found") from ex
+
+HELP_FLAGS = ("--help", "-h")
+
+
+def _is_help_flag(value: str | Path) -> bool:
+    """Check if a value is a help flag (--help or -h)."""
+    if isinstance(value, Path):
+        return any(str(value).endswith(flag) for flag in HELP_FLAGS)
+    return value in HELP_FLAGS

src/algokit/cli/project/link.py

@@ -90,6 +90,7 @@ def _link_projects(
         generator.generate_all(
             contract_project_root,
             output_path_pattern,
+            None,  # no additional args for project link
             raise_on_path_resolution_failure=fail_fast,
         )
     except AppSpecsNotFoundError:

src/algokit/core/typed_client_generation.py

@@ -95,7 +95,10 @@ def resolve_output_path(self, app_spec: Path, output_path_pattern: str | None) -
         return (output_path, app_spec_type)
 
     @abc.abstractmethod
-    def generate(self, app_spec: Path, output: Path) -> None: ...
+    def generate(self, app_spec: Path, output: Path, args: list[str] | None = None) -> None: ...
+
+    @abc.abstractmethod
+    def show_help(self) -> None: ...
 
     @property
     @abc.abstractmethod
@@ -111,6 +114,7 @@ def generate_all(
         self,
         app_spec_path_or_dir: Path,
         output_path_pattern: str | None,
+        args: list[str] | None,
         *,
         raise_on_path_resolution_failure: bool,
     ) -> None:
@@ -142,11 +146,11 @@ def accumulate_items_to_generate(
 
         items_to_generate: dict[Path, tuple[Path, AppSpecType]] = reduce(accumulate_items_to_generate, app_specs, {})
         for output_path, (app_spec, _) in items_to_generate.items():
-            self.generate(app_spec, output_path)
+            self.generate(app_spec, output_path, args)
 
 
 class PythonClientGenerator(ClientGenerator, language="python", extension=".py"):
-    def generate(self, app_spec: Path, output: Path) -> None:
+    def generate(self, app_spec: Path, output: Path, args: list[str] | None = None) -> None:
         logger.info(f"Generating Python client code for application specified in {app_spec} and writing to {output}")
         cmd = [
             *self.command,
@@ -155,6 +159,9 @@ def generate(self, app_spec: Path, output: Path) -> None:
             "-o",
             str(output),
         ]
+        if args:
+            cmd.extend(args)
+
         run_result = proc.run(cmd)
         click.echo(run_result.output)
 
@@ -166,6 +173,39 @@ def generate(self, app_spec: Path, output: Path) -> None:
             )
             raise click.exceptions.Exit(run_result.exit_code)
 
+    def show_help(self) -> None:
+        """Show help for the Python client generator."""
+        cmd = [*self.command, "--help"]
+        run_result = proc.run(cmd)
+
+        # Filter out unwanted lines from the help output
+        filtered_lines = []
+        skip_next_lines = False
+
+        for line in run_result.output.splitlines():
+            # Skip usage line
+            if "usage: algokitgen-py" in line:
+                continue
+
+            # Start skipping when we encounter the -a option
+            if "-a APP_SPEC" in line:
+                skip_next_lines = True
+                continue
+
+            # If we're skipping and encounter a line that starts a new option (starts with a dash), stop skipping
+            if skip_next_lines:
+                is_new_option = line.lstrip().startswith("-")
+                if is_new_option:
+                    skip_next_lines = False
+                else:
+                    continue
+
+            filtered_lines.append(line)
+
+        click.echo("\n".join(filtered_lines))
+        if run_result.exit_code != 0:
+            raise click.exceptions.Exit(run_result.exit_code)
+
     @property
     def default_output_pattern(self) -> str:
         return f"{{contract_name}}_client{self.extension}"
@@ -257,8 +297,11 @@ def find_generate_command(self, version: str | None) -> list[str]:
 
 
 class TypeScriptClientGenerator(ClientGenerator, language="typescript", extension=".ts"):
-    def generate(self, app_spec: Path, output: Path) -> None:
+    def generate(self, app_spec: Path, output: Path, args: list[str] | None = None) -> None:
         cmd = [*self.command, "generate", "-a", str(app_spec), "-o", str(output)]
+        if args:
+            cmd.extend(args)
+
         logger.info(
             f"Generating TypeScript client code for application specified in {app_spec} and writing to {output}"
         )
@@ -273,6 +316,21 @@ def generate(self, app_spec: Path, output: Path) -> None:
             )
             raise click.exceptions.Exit(run_result.exit_code)
 
+    def show_help(self) -> None:
+        """Show help for the TypeScript client generator."""
+        cmd = [*self.command, "generate", "--help"]
+        run_result = proc.run(cmd)
+
+        # Filter out unwanted lines from the help output
+        filtered_lines = []
+        for line in run_result.output.splitlines():
+            if "-a" not in line and "Usage: algokitgen" not in line:
+                filtered_lines.append(line)
+
+        click.echo("\n".join(filtered_lines))
+        if run_result.exit_code != 0:
+            raise click.exceptions.Exit(run_result.exit_code)
+
     def find_project_generate_command(
         self, npm_command: list[str], npx_command: list[str], version: str | None
     ) -> list[str] | None:

tests/generate/test_generate_client.py

@@ -112,6 +112,7 @@ def test_generate_no_options(application_json: Path) -> None:
         ("-o client.ts --language python", "client.ts"),
         ("-o client.py --language python --version 1.1.2", "client.py"),
         ("-l python -v 1.1.0", "hello_world_app_client.py"),
+        ("-o client.py -p --mode minimal", "client.py"),
     ],
 )
 def test_generate_client_python(
@@ -124,7 +125,7 @@ def test_generate_client_python(
     proc_mock.should_bad_exit_on(["poetry", "show", PYTHON_PYPI_PACKAGE, "--tree"])
     proc_mock.should_bad_exit_on(["pipx", "list", "--short"])
 
-    result = invoke(f"generate client {options} {application_json.name}", cwd=application_json.parent)
+    result = invoke(f"generate client {application_json.name} {options}", cwd=application_json.parent)
     assert result.exit_code == 0
     verify(
         _normalize_output(result.output),
@@ -133,9 +134,8 @@ def test_generate_client_python(
     )
     version = options.split()[-1] if "--version" in options or "-v" in options else None
     assert len(proc_mock.called) == 4  # noqa: PLR2004
-    assert (
-        proc_mock.called[3].command
-        == _get_python_generate_command(version, application_json, expected_output_path).split()
+    assert " ".join(proc_mock.called[3].command).startswith(
+        _get_python_generate_command(version, application_json, expected_output_path)
     )
 
 
@@ -278,6 +278,7 @@ def test_generate_client_python_multiple_app_specs_in_directory(
         ("-o client.py --language typescript", "client.py"),
         ("-o client.ts --language typescript --version 3.0.0", "client.ts"),
         ("-l typescript -v 2.6.0", "HelloWorldAppClient.ts"),
+        ("-o client.ts -pn --mode minimal", "client.ts"),
     ],
 )
 def test_generate_client_typescript(
@@ -291,7 +292,7 @@ def test_generate_client_typescript(
     proc_mock.should_bad_exit_on([npm_command, "ls"])
     proc_mock.should_bad_exit_on([npm_command, "ls", "--global"])
 
-    result = invoke(f"generate client {options} {application_json.name}", cwd=application_json.parent)
+    result = invoke(f"generate client {application_json.name} {options}", cwd=application_json.parent)
 
     assert result.exit_code == 0
     verify(
@@ -301,9 +302,8 @@ def test_generate_client_typescript(
     )
     version = options.split()[-1] if "--version" in options or "-v" in options else "latest"
     assert len(proc_mock.called) == 3  # noqa: PLR2004
-    assert (
-        proc_mock.called[2].command
-        == _get_typescript_generate_command(version, application_json, expected_output_path).split()
+    assert " ".join(proc_mock.called[2].command).startswith(
+        _get_typescript_generate_command(version, application_json, expected_output_path)
     )
 
 

tests/generate/test_generate_client.test_generate_client_python[-o client.py -p --mode minimal-client.py].approved.txt

@@ -0,0 +1,18 @@
+DEBUG: Searching for project installed client generator
+DEBUG: Running 'poetry show algokit-client-generator --tree' in '{current_working_directory}'
+DEBUG: poetry: STDOUT
+DEBUG: poetry: STDERR
+DEBUG: Running 'pipx --version' in '{current_working_directory}'
+DEBUG: pipx: STDOUT
+DEBUG: pipx: STDERR
+DEBUG: Searching for globally installed client generator
+DEBUG: Running 'pipx list --short' in '{current_working_directory}'
+DEBUG: pipx: STDOUT
+DEBUG: pipx: STDERR
+DEBUG: No matching installed client generator found, run client generator via pipx
+Generating Python client code for application specified in {current_working_directory}/application.json and writing to client.py
+DEBUG: Running 'pipx run --spec=algokit-client-generator algokitgen-py -a {current_working_directory}/application.json -o client.py -p --mode minimal' in '{current_working_directory}'
+DEBUG: pipx: STDOUT
+DEBUG: pipx: STDERR
+STDOUT
+STDERR

tests/generate/test_generate_client.test_generate_client_typescript[linux--o client.ts -pn --mode minimal-client.ts].approved.txt

@@ -0,0 +1,15 @@
+DEBUG: Searching for project installed client generator
+DEBUG: Running 'npm ls --no-unicode' in '{current_working_directory}'
+DEBUG: npm: STDOUT
+DEBUG: npm: STDERR
+DEBUG: Searching for globally installed client generator
+DEBUG: Running 'npm --global ls --no-unicode' in '{current_working_directory}'
+DEBUG: npm: STDOUT
+DEBUG: npm: STDERR
+DEBUG: No matching installed client generator found, run client generator via npx
+Generating TypeScript client code for application specified in {current_working_directory}/application.json and writing to client.ts
+DEBUG: Running 'npx --yes @algorandfoundation/algokit-client-generator@latest generate -a {current_working_directory}/application.json -o client.ts -pn --mode minimal' in '{current_working_directory}'
+DEBUG: npx: STDOUT
+DEBUG: npx: STDERR
+STDOUT
+STDERR

tests/generate/test_generate_client.test_generate_client_typescript[macOS--o client.ts -pn --mode minimal-client.ts].approved.txt

@@ -0,0 +1,15 @@
+DEBUG: Searching for project installed client generator
+DEBUG: Running 'npm ls --no-unicode' in '{current_working_directory}'
+DEBUG: npm: STDOUT
+DEBUG: npm: STDERR
+DEBUG: Searching for globally installed client generator
+DEBUG: Running 'npm --global ls --no-unicode' in '{current_working_directory}'
+DEBUG: npm: STDOUT
+DEBUG: npm: STDERR
+DEBUG: No matching installed client generator found, run client generator via npx
+Generating TypeScript client code for application specified in {current_working_directory}/application.json and writing to client.ts
+DEBUG: Running 'npx --yes @algorandfoundation/algokit-client-generator@latest generate -a {current_working_directory}/application.json -o client.ts -pn --mode minimal' in '{current_working_directory}'
+DEBUG: npx: STDOUT
+DEBUG: npx: STDERR
+STDOUT
+STDERR

tests/generate/test_generate_client.test_generate_client_typescript[windows--o client.ts -pn --mode minimal-client.ts].approved.txt

@@ -0,0 +1,15 @@
+DEBUG: Searching for project installed client generator
+DEBUG: Running 'npm.cmd ls --no-unicode' in '{current_working_directory}'
+DEBUG: npm.cmd: STDOUT
+DEBUG: npm.cmd: STDERR
+DEBUG: Searching for globally installed client generator
+DEBUG: Running 'npm.cmd --global ls --no-unicode' in '{current_working_directory}'
+DEBUG: npm.cmd: STDOUT
+DEBUG: npm.cmd: STDERR
+DEBUG: No matching installed client generator found, run client generator via npx
+Generating TypeScript client code for application specified in {current_working_directory}/application.json and writing to client.ts
+DEBUG: Running 'npx.cmd --yes @algorandfoundation/algokit-client-generator@latest generate -a {current_working_directory}/application.json -o client.ts -pn --mode minimal' in '{current_working_directory}'
+DEBUG: npx.cmd: STDOUT
+DEBUG: npx.cmd: STDERR
+STDOUT
+STDERR