gd-tools-cli 0.8.0__tar.gz → 0.10.0__tar.gz

{gd_tools_cli-0.8.0 → gd_tools_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gd-tools-cli
-Version: 0.8.0
+Version: 0.10.0
 Summary: A modern development workflow CLI for GDScript projects in Godot 4.5+
 Author-email: mansyar <m.ansyarafi@gmail.com>
 License: MIT
@@ -142,7 +142,7 @@ func test_health_starts_at_full() -> void:
 |---------|-------------|
 | `gd-tools init` | Bootstrap a Godot project -- deploy the native test and coverage addons, generate configs. |
 | `gd-tools doctor` | Diagnose the development environment -- Godot, native test addon, coverage addon, tooling; reports legacy GUT artifacts as migration advice. |
-| `gd-tools test` | Run tests with optional coverage, thresholds, and JUnit XML output. Suites must extend `GdToolsTest`; `GutTest` suites are rejected with exit 2 and migration guidance. Accepts optional path arguments to override configured test directories. `--parallel N` runs suites through a bounded worker pool. `--changed` runs only the suites mapped from git-changed files. `--watch` re-runs affected suites on `.gd` file changes. `--durations N` reports the N slowest tests after the run. `--exitfirst` (`-x`) stops dispatching new suites after the first failing suite; `--shard K/N` runs one round-robin shard for CI matrix splitting. Every run publishes a machine-readable artifact index under `.gd-tools/artifacts/<run_id>/`. |
+| `gd-tools test` | Run tests with optional coverage, thresholds, and JUnit XML output. Suites must extend `GdToolsTest`; `GutTest` suites are rejected with exit 2 and migration guidance. Accepts optional path arguments to override configured test directories. `--parallel N` runs suites through a bounded worker pool. `--changed` runs only the suites mapped from git-changed files. `--watch` re-runs affected suites on `.gd` file changes. `--durations N` reports the N slowest tests after the run. `--exitfirst` (`-x`) stops dispatching new suites after the first failing suite; `--shard K/N` runs one round-robin shard for CI matrix splitting; `--random-order` (with `--no-random-order` to turn a configured shuffle off) shuffles suite and test-method execution order, and `--seed N` pins the shuffle so a run can be replayed. Every run publishes a machine-readable artifact index under `.gd-tools/artifacts/<run_id>/`. |
 | `gd-tools migrate` | Guided GUT-to-native migration. Default: read-only report with unsupported-construct inventory and proposed base-class rewrites. `--apply` renames clean suites to `GdToolsTest` and translates `.gutconfig.json` into `gd-tools.toml` (merge, never clobber). `--config-only` translates config only. |
 | `gd-tools lint` | Lint GDScript files using gdlint with text, JSON, or GitHub Actions annotation output. Accepts one or more file or directory paths. |
 | `gd-tools format` | Format GDScript files using gdformat with check and diff modes. Accepts one or more file or directory paths. |
@@ -165,6 +165,9 @@ gd-tools test --changed                    # only suites mapped from git-changed
 gd-tools test --changed --base main        # PR/CI mode: diff from merge-base with main
 gd-tools test --exitfirst                  # stop dispatching after the first failing suite
 gd-tools test --shard 2/4                  # CI sharding: run suite shard 2 of 4
+gd-tools test --random-order               # shuffle suite and test method order
+gd-tools test --seed 42                    # --seed implies --random-order; replayable
+gd-tools test --no-random-order            # discovery order for one run, config regardless
 ```
 
 `--tag` is repeatable, and `--test-timeout` (per test) is separate from
@@ -216,6 +219,25 @@ own coverage report; merge the shards with `gd-tools coverage merge`.
 [sharding recipe](./docs/USER_GUIDE.md#sharding-a-test-run-across-ci-jobs)
 for a GitHub Actions matrix example.
 
+`--random-order` shuffles the execution order of the selected suites, and of
+the test methods within each suite, to surface tests that depend on a
+neighbour's side effects. The order is a pure function of the seed and the
+selected suite/test set: the run summary reports
+`Random order: seed <N> (replay with --seed <N>)` — exempt from `--quiet`,
+since a shuffled failure cannot be reproduced without its seed — and
+re-running with that
+seed reproduces the order exactly. `--seed N` pins the shuffle and implies
+`--random-order`; without it a fresh 31-bit seed is generated per run. Persist
+the choice with `random_order = true` and `seed = 42` under `[test]`, and undo
+it for one run with the paired `--no-random-order`. Shuffling
+never changes shard membership — `--shard` assigns suites from the
+deterministic plan order, so CI matrix jobs still cover every suite exactly
+once — and `--watch` resolves one seed for the whole session so successive
+re-runs stay comparable. `--verbose` lists the resolved order suite-by-suite,
+and the seed is recorded in `artifacts.json`. A seed reproduces an order for
+the same Python version, not across versions: `random.Random` is what draws
+the order and CPython may change its shuffle algorithm between releases.
+
 Repeat runs are faster: the `godot --headless --import` step is cached under
 `.gd-tools/native/import-cache/` and skipped when `project.godot`, any
 project source/resource file (scripts, scenes, import sidecars, addons), or
@@ -406,6 +428,8 @@ runtime = "native"        # native (default); "gut" is no longer a runnable runt
 timeout_seconds = 5.0     # default per-test timeout for async native tests
 retries = 0               # opt-in retries per native test; retried passes are flagged as flaky
 # parallel = 4            # opt-in parallel suite execution (1-32; unset runs sequentially)
+# random_order = true     # opt-in shuffled suite and test-method order
+# seed = 42               # pin the shuffle seed so a shuffled run is replayable
 tags = []                 # native suite tag filters
 
 [lint]

{gd_tools_cli-0.8.0 → gd_tools_cli-0.10.0}/README.md

@@ -100,7 +100,7 @@ func test_health_starts_at_full() -> void:
 |---------|-------------|
 | `gd-tools init` | Bootstrap a Godot project -- deploy the native test and coverage addons, generate configs. |
 | `gd-tools doctor` | Diagnose the development environment -- Godot, native test addon, coverage addon, tooling; reports legacy GUT artifacts as migration advice. |
-| `gd-tools test` | Run tests with optional coverage, thresholds, and JUnit XML output. Suites must extend `GdToolsTest`; `GutTest` suites are rejected with exit 2 and migration guidance. Accepts optional path arguments to override configured test directories. `--parallel N` runs suites through a bounded worker pool. `--changed` runs only the suites mapped from git-changed files. `--watch` re-runs affected suites on `.gd` file changes. `--durations N` reports the N slowest tests after the run. `--exitfirst` (`-x`) stops dispatching new suites after the first failing suite; `--shard K/N` runs one round-robin shard for CI matrix splitting. Every run publishes a machine-readable artifact index under `.gd-tools/artifacts/<run_id>/`. |
+| `gd-tools test` | Run tests with optional coverage, thresholds, and JUnit XML output. Suites must extend `GdToolsTest`; `GutTest` suites are rejected with exit 2 and migration guidance. Accepts optional path arguments to override configured test directories. `--parallel N` runs suites through a bounded worker pool. `--changed` runs only the suites mapped from git-changed files. `--watch` re-runs affected suites on `.gd` file changes. `--durations N` reports the N slowest tests after the run. `--exitfirst` (`-x`) stops dispatching new suites after the first failing suite; `--shard K/N` runs one round-robin shard for CI matrix splitting; `--random-order` (with `--no-random-order` to turn a configured shuffle off) shuffles suite and test-method execution order, and `--seed N` pins the shuffle so a run can be replayed. Every run publishes a machine-readable artifact index under `.gd-tools/artifacts/<run_id>/`. |
 | `gd-tools migrate` | Guided GUT-to-native migration. Default: read-only report with unsupported-construct inventory and proposed base-class rewrites. `--apply` renames clean suites to `GdToolsTest` and translates `.gutconfig.json` into `gd-tools.toml` (merge, never clobber). `--config-only` translates config only. |
 | `gd-tools lint` | Lint GDScript files using gdlint with text, JSON, or GitHub Actions annotation output. Accepts one or more file or directory paths. |
 | `gd-tools format` | Format GDScript files using gdformat with check and diff modes. Accepts one or more file or directory paths. |
@@ -123,6 +123,9 @@ gd-tools test --changed                    # only suites mapped from git-changed
 gd-tools test --changed --base main        # PR/CI mode: diff from merge-base with main
 gd-tools test --exitfirst                  # stop dispatching after the first failing suite
 gd-tools test --shard 2/4                  # CI sharding: run suite shard 2 of 4
+gd-tools test --random-order               # shuffle suite and test method order
+gd-tools test --seed 42                    # --seed implies --random-order; replayable
+gd-tools test --no-random-order            # discovery order for one run, config regardless
 ```
 
 `--tag` is repeatable, and `--test-timeout` (per test) is separate from
@@ -174,6 +177,25 @@ own coverage report; merge the shards with `gd-tools coverage merge`.
 [sharding recipe](./docs/USER_GUIDE.md#sharding-a-test-run-across-ci-jobs)
 for a GitHub Actions matrix example.
 
+`--random-order` shuffles the execution order of the selected suites, and of
+the test methods within each suite, to surface tests that depend on a
+neighbour's side effects. The order is a pure function of the seed and the
+selected suite/test set: the run summary reports
+`Random order: seed <N> (replay with --seed <N>)` — exempt from `--quiet`,
+since a shuffled failure cannot be reproduced without its seed — and
+re-running with that
+seed reproduces the order exactly. `--seed N` pins the shuffle and implies
+`--random-order`; without it a fresh 31-bit seed is generated per run. Persist
+the choice with `random_order = true` and `seed = 42` under `[test]`, and undo
+it for one run with the paired `--no-random-order`. Shuffling
+never changes shard membership — `--shard` assigns suites from the
+deterministic plan order, so CI matrix jobs still cover every suite exactly
+once — and `--watch` resolves one seed for the whole session so successive
+re-runs stay comparable. `--verbose` lists the resolved order suite-by-suite,
+and the seed is recorded in `artifacts.json`. A seed reproduces an order for
+the same Python version, not across versions: `random.Random` is what draws
+the order and CPython may change its shuffle algorithm between releases.
+
 Repeat runs are faster: the `godot --headless --import` step is cached under
 `.gd-tools/native/import-cache/` and skipped when `project.godot`, any
 project source/resource file (scripts, scenes, import sidecars, addons), or
@@ -364,6 +386,8 @@ runtime = "native"        # native (default); "gut" is no longer a runnable runt
 timeout_seconds = 5.0     # default per-test timeout for async native tests
 retries = 0               # opt-in retries per native test; retried passes are flagged as flaky
 # parallel = 4            # opt-in parallel suite execution (1-32; unset runs sequentially)
+# random_order = true     # opt-in shuffled suite and test-method order
+# seed = 42               # pin the shuffle seed so a shuffled run is replayable
 tags = []                 # native suite tag filters
 
 [lint]

{gd_tools_cli-0.8.0 → gd_tools_cli-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gd-tools-cli"
-version = "0.8.0"
+version = "0.10.0"
 description = "A modern development workflow CLI for GDScript projects in Godot 4.5+"
 readme = "README.md"
 license = {text = "MIT"}
@@ -110,7 +110,7 @@ target-version = ["py310"]
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.8.0"
+version = "0.10.0"
 version_files = ["pyproject.toml:version"]
 changelog_file = "CHANGELOG.md"
 tag_format = "v$version"

gd_tools_cli-0.10.0/src/gd_tools/addon_check.py

@@ -0,0 +1,157 @@
+"""Stale addon detection module.
+
+Checks whether the deployed coverage addon version matches the installed
+gd-tools-cli package version. Prints warnings to stderr when the addon
+is missing or stale. Fails silently on any error and can be disabled via
+the GD_TOOLS_NO_UPDATE_CHECK environment variable.
+"""
+
+import os
+
+import click
+from packaging.version import parse as parse_version
+
+from gd_tools import __version__
+from gd_tools.config import find_project_root
+
+ADDON_VERSION_FILENAME = "_version.txt"
+COVERAGE_ADDON_DIR = "gd-tools-coverage"
+NATIVE_ADDON_DIR = "gd-tools-test"
+
+
+def _stale_refusal(label: str, deployed: str) -> str:
+    """Build the refusal message for a stale/unparseable addon.
+
+    Args:
+        label: Human-readable addon label ("Coverage"/"Native test").
+        deployed: Deployed version string (raw, may be unparseable).
+
+    Returns:
+        Refusal message naming both versions, the fix, and the abort.
+    """
+    return (
+        f"Error: {label} addon is outdated (v{deployed} deployed, "
+        f"v{__version__} installed). Run `gd-tools init` to "
+        "update. Aborted before running tests."
+    )
+
+
+def _missing_refusal(label: str) -> str:
+    """Build the refusal message for a missing version file.
+
+    Args:
+        label: Human-readable addon label ("Coverage"/"Native test").
+
+    Returns:
+        Refusal message naming the CLI version, the fix, and abort.
+    """
+    return (
+        f"Error: {label} addon version file not found "
+        f"(deployed version unknown, v{__version__} installed). "
+        "Run `gd-tools init` to deploy the addon. "
+        "Aborted before running tests."
+    )
+
+
+def check_coverage_addon_gate() -> str | None:
+    """Check the coverage-run addon gate before suite dispatch.
+
+    Compares the deployed coverage and native test addon versions
+    against the CLI version. A missing, unparseable, or older
+    deployed version refuses the run. Newer deployed addons and
+    matching versions pass. Suppressed by
+    ``GD_TOOLS_NO_UPDATE_CHECK=1``. Never raises; unexpected
+    errors defer to the caller's existing behavior.
+
+    Returns:
+        Refusal message when the run must abort, else None.
+    """
+    if os.environ.get("GD_TOOLS_NO_UPDATE_CHECK") == "1":
+        return None
+    try:
+        project_root = find_project_root()
+    except Exception:
+        return None
+    for addon_dir, label in (
+        (COVERAGE_ADDON_DIR, "Coverage"),
+        (NATIVE_ADDON_DIR, "Native test"),
+    ):
+        version_file = (
+            project_root / "addons" / addon_dir / ADDON_VERSION_FILENAME
+        )
+        try:
+            exists = version_file.exists()
+        except Exception:
+            return None
+        if not exists:
+            return _missing_refusal(label)
+        try:
+            addon_version = version_file.read_text(encoding="utf-8").strip()
+        except Exception:
+            return None
+        try:
+            addon_parsed = parse_version(addon_version)
+            package_parsed = parse_version(__version__)
+        except (TypeError, ValueError):
+            return _stale_refusal(label, addon_version)
+        if addon_parsed < package_parsed:
+            return _stale_refusal(label, addon_version)
+    return None
+
+
+def check_addon_version() -> None:
+    """Check if the deployed coverage addon version is stale.
+
+    Compares the version in _version.txt against the installed package
+    version. Prints a warning to stderr if the addon is missing or stale.
+    Fails silently on any unexpected error.
+
+    FR2: Stale Addon Check on CLI Invocation.
+    FR3: Suppressed by GD_TOOLS_NO_UPDATE_CHECK=1.
+    FR4: Uses packaging.version.parse() for comparison.
+    """
+    # FR3.1: Environment variable disables check entirely.
+    if os.environ.get("GD_TOOLS_NO_UPDATE_CHECK") == "1":
+        return
+
+    try:
+        project_root = find_project_root()
+        version_file = (
+            project_root
+            / "addons"
+            / "gd-tools-coverage"
+            / ADDON_VERSION_FILENAME
+        )
+
+        if not version_file.exists():
+            click.echo(
+                "WARNING: Coverage addon version file not found. "
+                "Run `gd-tools init` to deploy the addon.",
+                err=True,
+            )
+            return
+
+        addon_version = version_file.read_text(encoding="utf-8").strip()
+        stale_msg = (
+            f"WARNING: Coverage addon is outdated (v{addon_version} "
+            f"deployed, v{__version__} available). "
+            f"Run `gd-tools init` to update."
+        )
+
+        # FR4.1: Compare versions using packaging.version.parse().
+        try:
+            addon_parsed = parse_version(addon_version)
+            package_parsed = parse_version(__version__)
+        except (TypeError, ValueError):
+            # FR4.2: Unparseable version = treated as stale.
+            click.echo(stale_msg, err=True)
+            return
+
+        # FR2.4: Stale (addon < package)
+        if addon_parsed < package_parsed:
+            click.echo(stale_msg, err=True)
+        # FR2.5: Match = no warning
+        # FR2.6: Newer addon (downgrade) = no warning
+    except Exception:
+        # FR2.8: Fail silently on any unexpected error.
+        pass

{gd_tools_cli-0.8.0 → gd_tools_cli-0.10.0}/src/gd_tools/addons/gd-tools-test/gd_tools_native_coverage.gd

@@ -358,8 +358,14 @@ static func _inject_trackers(
 		var branch_type = str(entry.get("branch_type", ""))
 		var insert_index := target_index
 		if branch_type in ["match_case", "if_false", "elif_true"]:
-			insert_index = target_index + 1
-		var indent := _extract_indent(source_lines[insert_index])
+			var header_end := _find_header_end(source_lines, target_index)
+			if header_end >= 0:
+				insert_index = header_end + 1
+			else:
+				insert_index = target_index + 1
+		var indent := ""
+		if insert_index >= 0 and insert_index < source_lines.size():
+			indent = _extract_indent(source_lines[insert_index])
 		if indent.is_empty():
 			indent = _extract_indent(source_lines[target_index])
 		var tracker := "%sGdToolsNativeCoverage.hit(%d, %d)" % [
@@ -512,3 +518,105 @@ static func _extract_indent(line: String) -> String:
 		else:
 			break
 	return indent
+
+
+static func _find_header_end(source_lines: PackedStringArray, start_index: int) -> int:
+	## Scan forward from a branch header start line to its terminating colon.
+	##
+	## Returns the 0-based line index holding the first `:` at bracket-depth 0
+	## outside strings and comments, or -1 when it cannot be resolved. The
+	## caller fails open on -1 by keeping the historical insertion position
+	## rather than corrupting the source.
+	var size := source_lines.size()
+	if start_index < 0 or start_index >= size:
+		return -1
+	var depth := 0
+	var in_single := ""
+	var in_triple := ""
+	var escaped := false
+	var i := start_index
+	while i < size:
+		var line := source_lines[i]
+		var last_code := ""
+		var j := 0
+		var length := line.length()
+		while j < length:
+			if not in_triple.is_empty():
+				if escaped:
+					escaped = false
+					j += 1
+					continue
+				if line.substr(j, 1) == "\\":
+					escaped = true
+					j += 1
+					continue
+				if line.substr(j, 3) == in_triple:
+					in_triple = ""
+					j += 3
+					continue
+				j += 1
+				continue
+			if not in_single.is_empty():
+				if escaped:
+					escaped = false
+					j += 1
+					continue
+				if line.substr(j, 1) == "\\":
+					escaped = true
+					j += 1
+					continue
+				if line.substr(j, 1) == in_single:
+					in_single = ""
+					j += 1
+					continue
+				j += 1
+				continue
+			var ch := line.substr(j, 1)
+			if ch == "#":
+				break
+			if ch == "\"" or ch == "'":
+				var triple := ch + ch + ch
+				if line.substr(j, 3) == triple:
+					in_triple = triple
+					escaped = false
+					j += 3
+					continue
+				in_single = ch
+				escaped = false
+				j += 1
+				continue
+			if ch == "(" or ch == "[" or ch == "{":
+				depth += 1
+				last_code = ch
+				j += 1
+				continue
+			if ch == ")" or ch == "]" or ch == "}":
+				depth = maxi(0, depth - 1)
+				last_code = ch
+				j += 1
+				continue
+			if ch == ":":
+				if depth == 0:
+					return i
+				last_code = ch
+				j += 1
+				continue
+			if ch == " " or ch == "\t" or ch == "\r":
+				j += 1
+				continue
+			if ch == "\\":
+				last_code = ch
+				j += 1
+				continue
+			last_code = ch
+			j += 1
+		if not in_single.is_empty():
+			in_single = ""
+			escaped = false
+		else:
+			escaped = false
+		if depth > 0 or last_code == "\\":
+			i += 1
+			continue
+		return -1
+	return -1

{gd_tools_cli-0.8.0 → gd_tools_cli-0.10.0}/src/gd_tools/atomic_io.py

@@ -8,9 +8,11 @@ this module: the content is staged in a temporary file beside the destination, f
 and fsynced, and moved into place with a single ``os.replace``.
 """
 
+import json
 import os
 import tempfile
 from pathlib import Path
+from typing import Any
 
 
 def atomic_write_bytes(path: Path | str, payload: bytes) -> Path:
@@ -76,3 +78,36 @@ def atomic_write_text(path: Path | str, text: str) -> Path:
             written.
     """
     return atomic_write_bytes(path, text.encode("utf-8"))
+
+
+def atomic_write_json(
+    path: Path | str,
+    payload: Any,
+    *,
+    sort_keys: bool = True,
+    indent: int | None = 2,
+) -> Path:
+    """Serialize ``payload`` as JSON and write it atomically as UTF-8.
+
+    Convenience wrapper around :func:`atomic_write_text` for JSON
+    documents. A trailing newline is appended so the file ends cleanly
+    for diffing and line-oriented tooling.
+
+    Args:
+        path: Destination file path (a :class:`~pathlib.Path` or a
+            string).
+        payload: JSON-serializable value (dicts, lists, scalars).
+        sort_keys: Sort dictionary keys; ``True`` matches the writers
+            this helper consolidates.
+        indent: JSON indentation depth, or ``None`` for compact output.
+
+    Returns:
+        The destination path.
+
+    Raises:
+        TypeError, ValueError: If ``payload`` is not JSON-serializable.
+        OSError: If the temporary file or final replacement cannot be
+            written.
+    """
+    text = json.dumps(payload, indent=indent, sort_keys=sort_keys) + "\n"
+    return atomic_write_text(path, text)

gd_tools_cli-0.10.0/src/gd_tools/cli.py

@@ -0,0 +1,219 @@
+"""CLI entry point for gd-tools."""
+
+import sys
+from pathlib import Path
+from typing import Any
+
+import click
+from click.shell_completion import (
+    BashComplete,
+    add_completion_class,
+)
+
+from . import __version__
+from .addon_check import check_addon_version
+from .commands.clean import clean
+from .commands.completion import create_completion_command
+from .commands.config import config
+from .commands.coverage import coverage
+from .commands.doctor import doctor
+from .commands.format import format
+from .commands.init import init
+from .commands.install_hooks import install_hooks
+from .commands.lint import lint
+from .commands.migrate import migrate
+from .commands.test import test
+from .commands.version import version
+from .config import set_explicit_project_root
+from .update_check import check_for_update
+from .verbosity import Verbosity, set_verbosity
+
+
+def _configure_windows_utf8() -> None:
+    """Reconfigure stdout/stderr to UTF-8 on Windows.
+
+    Windows defaults to the system codepage (e.g. cp1252) for console
+    output, which cannot encode Unicode characters used by Rich (✓, ✗,
+    ⚠). This reconfigures the standard streams to UTF-8, matching the
+    effect of setting PYTHONUTF8=1.
+    """
+    if sys.platform != "win32":
+        return
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(encoding="utf-8")
+            except (ValueError, OSError):
+                pass
+
+
+_configure_windows_utf8()
+
+
+_SOURCE_POWERSHELL = """Register-ArgumentCompleter -Native -CommandName %(prog_name)s -ScriptBlock {
+    param($wordToComplete, $commandAst, $cursorPosition)
+
+    $words = $commandAst.CommandElements | ForEach-Object { $_.ToString() }
+    $env:COMP_WORDS = $words -join ' '
+    $commandElements = $commandAst.CommandElements
+    $env:COMP_CWORD = $commandElements.Count
+    for ($i = 0; $i -lt $commandElements.Count; $i++) {
+        if ($cursorPosition -le $commandElements[$i].Extent.StartOffset) {
+            $env:COMP_CWORD = $i
+            break
+        }
+    }
+
+    $env:%(complete_var)s = "powershell_complete"
+    %(prog_name)s | ForEach-Object {
+        $values = $_.Split(",")
+        if ($values[0] -eq "dir") {
+            [System.Management.Automation.CompletionResult]::new($values[1], $values[1], "ParameterValue", $values[1])
+        } elseif ($values[0] -eq "file") {
+            [System.Management.Automation.CompletionResult]::new($values[1], $values[1], "ParameterValue", $values[1])
+        } else {
+            $help = if ($values[2] -eq "_") { "" } else { $values[2] }
+            [System.Management.Automation.CompletionResult]::new($values[1], $values[1], "ParameterValue", $help)
+        }
+    }
+
+    $env:COMP_WORDS = $null
+    $env:COMP_CWORD = 0
+    $env:%(complete_var)s = $null
+}
+"""
+
+
+class PowerShellComplete(BashComplete):
+    """Shell completion for PowerShell.
+
+    Click 8.2.x does not include a PowerShell completion class.
+    This subclass reuses BashComplete's completion args and
+    format_completion, providing a PowerShell-compatible source
+    template using Register-ArgumentCompleter.
+    """
+
+    name = "powershell"
+    source_template = _SOURCE_POWERSHELL
+
+
+add_completion_class(PowerShellComplete)
+
+
+class GdToolsGroup(click.Group):
+    """Custom Click group that converts NotImplementedError to exit code 2.
+
+    Stub commands raise ``NotImplementedError`` to indicate they are not
+    yet implemented. This class catches that exception and exits with
+    code 2 (configuration/usage error), consistent with the gd-tools
+    error convention.
+    """
+
+    def invoke(self, ctx) -> Any:
+        """Invoke the group, catching NotImplementedError as exit code 2.
+
+        Performs an update check before dispatching to the subcommand.
+        If a newer version is available, a notification is printed to
+        stderr. The check fails silently and never blocks execution.
+
+        In quiet mode (``--quiet``/``-q``), both the update check and
+        the addon version check are skipped entirely.
+
+        Args:
+            ctx: The Click context for this invocation.
+
+        Returns:
+            The result of the underlying command invocation.
+
+        Raises:
+            SystemExit: With code 2 if a command raises
+                NotImplementedError.
+        """
+        # Use raw ctx.params here — set_verbosity() runs inside the group
+        # callback (invoked by super().invoke below), so get_verbosity()
+        # is not yet set at this point.
+        quiet = ctx.params.get("quiet", False)
+        if not quiet:
+            latest = check_for_update()
+            if latest is not None:
+                click.echo(
+                    f"A new version of gd-tools is available: {latest} "
+                    f"(you have {__version__}).\n"
+                    f"Run `pip install --upgrade gd-tools-cli` to update.",
+                    err=True,
+                )
+            check_addon_version()
+        try:
+            return super().invoke(ctx)
+        except NotImplementedError:
+            click.echo(
+                "Error: This command is not yet implemented.",
+                err=True,
+            )
+            ctx.exit(2)
+
+
+@click.group(cls=GdToolsGroup)
+@click.version_option(
+    version=__version__,
+    prog_name="gd-tools",
+    message="%(prog)s %(version)s",
+)
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    default=False,
+    help="Show verbose output including underlying commands and timing.",
+)
+@click.option(
+    "--quiet",
+    "-q",
+    is_flag=True,
+    default=False,
+    help="Suppress non-essential output (update checks, progress info).",
+)
+@click.option(
+    "--project",
+    "-p",
+    "project_path",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=None,
+    help="Path to the Godot project root. Defaults to discovery from "
+    "the current working directory.",
+)
+def cli(verbose: bool, quiet: bool, project_path: Path | None):
+    """gd-tools: A modern development workflow CLI for GDScript."""
+    set_explicit_project_root(project_path)
+    if verbose and quiet:
+        click.echo(
+            "Error: --verbose and --quiet are mutually exclusive.", err=True
+        )
+        ctx = click.get_current_context()
+        ctx.exit(2)
+    if verbose:
+        set_verbosity(Verbosity.VERBOSE)
+    elif quiet:
+        set_verbosity(Verbosity.QUIET)
+    else:
+        set_verbosity(Verbosity.DEFAULT)
+
+
+# Register the extracted commands, preserving the original help order:
+# init, doctor, version, clean, install-hooks, test, migrate, lint,
+# format, coverage, config, completion.
+cli.add_command(init)
+cli.add_command(doctor)
+cli.add_command(version)
+cli.add_command(clean)
+cli.add_command(install_hooks)
+
+
+cli.add_command(test)
+cli.add_command(migrate)
+cli.add_command(lint)
+cli.add_command(format)
+cli.add_command(coverage)
+cli.add_command(config)
+cli.add_command(create_completion_command(cli))