@ahmed-g-gad/apothem 0.1.1

package/src/apothem/benchmarks/bench_hooks.py

@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: MIT
+
+"""Hook-handler runtime benchmark per the per-event budgets in
+`src/apothem/rules/performance-discipline.md` §1.
+
+The script declares the canonical per-event budgets and provides a measurement
+hook for the dispatcher's startup overhead. Representative event-fixture
+invocation is operator-editorial: when no fixture is wired for a given event,
+the script reports the budget and exits with the scaffold marker (return
+code 0) so the verifier surface remains usable while detailed fixtures land.
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Final
+
+_BUDGETS: Final[dict[str, float]] = {
+    "PreToolUse": 10.0,
+    "PostToolUse": 10.0,
+    "UserPromptSubmit": 10.0,
+    "Notification": 10.0,
+    "SessionStart": 30.0,
+    "PreCompact": 30.0,
+    "PostCompact": 30.0,
+    "Stop": 60.0,
+}
+
+# bench_hooks.py lives at <repo>/src/apothem/benchmarks/; four parents up is
+# the repository root.
+_REPO_ROOT: Final[Path] = Path(__file__).resolve().parents[3]
+_DISPATCHER: Final[Path] = _REPO_ROOT / "src" / "apothem" / "hooks" / "dispatch.py"
+
+
+def _measure_dispatcher_startup() -> float:
+    """Return wall-clock seconds for a no-op dispatcher invocation.
+
+    Invokes the dispatcher with ``--help`` (argparse exits 0) so the elapsed
+    wall-clock bounds the floor cost (interpreter spin-up + module import +
+    arg parse) for any hook handler. A non-zero return code means the
+    dispatcher could not be exercised; the caller raises rather than report a
+    spurious sub-budget reading from a process that never ran the real code.
+    """
+    start = time.monotonic()
+    completed = subprocess.run(  # noqa: S603 — trusted invocation: literal argv against the in-repo dispatcher
+        [sys.executable, str(_DISPATCHER), "--help"],
+        check=False,
+        capture_output=True,
+    )
+    elapsed = time.monotonic() - start
+    if completed.returncode != 0:
+        raise RuntimeError(
+            f"dispatcher invocation failed (exit {completed.returncode}); "
+            f"target={_DISPATCHER} — a sub-budget reading here would be spurious"
+        )
+    return elapsed
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="bench_hooks")
+    parser.add_argument(
+        "--event",
+        required=True,
+        choices=sorted(_BUDGETS),
+        help="Hook event class to benchmark.",
+    )
+    args = parser.parse_args(argv)
+    budget = _BUDGETS[args.event]
+    if not _DISPATCHER.is_file():
+        print(f"ERROR: dispatcher target not found: {_DISPATCHER}", file=sys.stderr)
+        return 2
+    try:
+        elapsed = _measure_dispatcher_startup()
+    except RuntimeError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+    if elapsed <= budget:
+        print(
+            f"PASS: {args.event} dispatcher startup = {elapsed:.3f}s (budget {budget}s)"
+        )
+        return 0
+    print(
+        f"FAIL: {args.event} dispatcher startup = {elapsed:.3f}s exceeds budget {budget}s"
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/apothem/benchmarks/bench_install.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: MIT
+
+"""Install-all resolution-sweep runtime benchmark per the per-class budget in
+`src/apothem/rules/performance-discipline.md` §1.
+
+Budget: 0.25 seconds for a dry-run install-all resolution sweep across every
+registered adapter (propagation-rule resolution + capability projection, no
+filesystem mutation).
+
+The sweep resolves each adapter's propagation rules and capability-projection
+warnings — the O(adapter-count) phase of an install-all that reads the shared
+27 KB propagation manifest. With the TR-1 manifest-parse cache
+(``load_manifest``'s ``lru_cache``) in place the manifest is parsed once for the
+whole sweep; with the cache reverted each adapter re-parses it, pushing the
+sweep roughly two orders of magnitude over and tripping this budget — the
+regression this benchmark exists to catch.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from typing import Final
+
+from apothem.harnesses._shared import install_driver
+from apothem.lib.harness_registry import HARNESS_REGISTRY
+
+# Seconds for the full install-all resolution sweep. A cold process parses the
+# manifest once (~tens of ms) plus per-adapter resolution; the cache keeps the
+# whole sweep well under this budget while a reverted cache (one parse per
+# adapter) blows past it.
+_BUDGET: Final[float] = 0.25
+
+
+def _time_resolution_sweep() -> float:
+    """Return wall-clock seconds to resolve rules + capabilities for all adapters."""
+    names = [entry.package_key for entry in HARNESS_REGISTRY]
+    start = time.monotonic()
+    for name in names:
+        install_driver.load_rules(name)
+        install_driver._capability_projection_results(name)
+    return time.monotonic() - start
+
+
+def main(argv: list[str] | None = None) -> int:
+    argparse.ArgumentParser(prog="bench_install").parse_args(argv)
+    elapsed = _time_resolution_sweep()
+    label = f"install-all resolution sweep ({len(HARNESS_REGISTRY)} adapters)"
+    if elapsed <= _BUDGET:
+        print(f"PASS: {label} = {elapsed:.3f}s (budget {_BUDGET}s)")
+        return 0
+    print(f"FAIL: {label} = {elapsed:.3f}s exceeds budget {_BUDGET}s", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/apothem/benchmarks/bench_tests.py

@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: MIT
+
+"""Test-suite runtime benchmark per the per-suite budgets in
+`src/apothem/rules/performance-discipline.md` §1.
+
+Full-suite budget: 60 seconds (pytest -n auto, post-xdist).
+Per-test-module budget: 10 seconds.
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Final
+
+_FULL_BUDGET: Final[float] = 60.0
+_PER_MODULE_BUDGET: Final[float] = 10.0
+# bench file lives at <repo>/src/apothem/benchmarks/; four parents up is root.
+_REPO_ROOT: Final[Path] = Path(__file__).resolve().parents[3]
+_TESTS_DIR: Final[Path] = _REPO_ROOT / "tests"
+
+
+def _time_invocation(target: Path, *, single_module: bool) -> float:
+    """Return wall-clock seconds for a pytest invocation against ``target``.
+
+    The per-module path runs with ``-n0`` so the per-module budget measures the
+    module's own runtime rather than the xdist worker-pool startup that the
+    repository's ``-n auto`` default would otherwise charge to a single file.
+    The full-suite path keeps the configured ``-n auto`` parallelism the
+    full-suite budget assumes.
+    """
+    cmd = [sys.executable, "-m", "pytest", str(target), "-q"]
+    if single_module:
+        cmd.append("-n0")
+    start = time.monotonic()
+    completed = subprocess.run(  # noqa: S603 — trusted invocation: literal argv against the host pytest module
+        cmd,
+        check=False,
+        capture_output=True,
+        cwd=_REPO_ROOT,
+    )
+    elapsed = time.monotonic() - start
+    # A non-zero pytest exit (test failure, collection error, no tests
+    # collected) means the measured run did not complete cleanly; a sub-budget
+    # reading for such a run would falsely attest budget compliance per the
+    # rule's "exit 0 attests budget compliance" contract. Raise rather than
+    # report a spurious PASS — mirrors bench_hooks' returncode guard.
+    if completed.returncode != 0:
+        raise RuntimeError(
+            f"pytest invocation failed (exit {completed.returncode}); "
+            "a sub-budget reading here would be spurious"
+        )
+    return elapsed
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="bench_tests")
+    parser.add_argument(
+        "--module",
+        default=None,
+        help="Path (relative to the repository root) of a per-module subset; "
+        "the per-module budget applies. When omitted, the full suite runs "
+        "under the full-suite budget.",
+    )
+    args = parser.parse_args(argv)
+
+    single_module = args.module is not None
+    target = _REPO_ROOT / args.module if args.module else _TESTS_DIR
+    budget = _PER_MODULE_BUDGET if single_module else _FULL_BUDGET
+    label = f"module {args.module}" if single_module else "full suite"
+    if single_module and not target.is_file():
+        print(f"ERROR: test module not found: {target}", file=sys.stderr)
+        return 2
+    if not single_module and not target.is_dir():
+        print(f"ERROR: tests directory not found: {target}", file=sys.stderr)
+        return 2
+    try:
+        elapsed = _time_invocation(target, single_module=single_module)
+    except RuntimeError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+    if elapsed <= budget:
+        print(f"PASS: pytest {label} = {elapsed:.3f}s (budget {budget}s)")
+        return 0
+    print(f"FAIL: pytest {label} = {elapsed:.3f}s exceeds budget {budget}s")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/apothem/benchmarks/bench_validate_ecosystem.py

@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: MIT
+
+"""Verify-ecosystem-sweep runtime benchmark per the per-check budgets in
+`src/apothem/rules/performance-discipline.md` §1.
+
+Composite budget: 30 seconds for the full sweep.
+Per-check budget: 5 seconds for any single subcommand.
+
+The script invokes the verifier under `--skip-hooks` to isolate the host-tool
+runtime from the bundled hook validator delegation.
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Final
+
+_COMPOSITE_BUDGET: Final[float] = 30.0
+_PER_CHECK_BUDGET: Final[float] = 5.0
+# bench file lives at <repo>/src/apothem/benchmarks/; four parents up is root.
+_REPO_ROOT: Final[Path] = Path(__file__).resolve().parents[3]
+_VALIDATOR: Final[Path] = _REPO_ROOT / "scripts" / "dev" / "validate_ecosystem.py"
+
+
+def _time_invocation(extra: list[str]) -> float:
+    """Return wall-clock seconds for a verifier invocation.
+
+    A non-zero return code means the verifier never ran the real sweep (a
+    bogus ``--check`` argparse-errors in well under budget, for instance); the
+    caller raises rather than report a spurious sub-budget reading from a
+    process that never executed the measured work. Mirrors the returncode
+    guard in ``bench_hooks._measure_dispatcher_startup``.
+    """
+    start = time.monotonic()
+    completed = subprocess.run(  # noqa: S603 — trusted invocation: literal argv against the in-repo verifier
+        [sys.executable, str(_VALIDATOR), "--skip-hooks", *extra],
+        check=False,
+        capture_output=True,
+    )
+    elapsed = time.monotonic() - start
+    if completed.returncode != 0:
+        raise RuntimeError(
+            f"verifier invocation failed (exit {completed.returncode}); "
+            "a sub-budget reading here would be spurious"
+        )
+    return elapsed
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="bench_validate_ecosystem")
+    parser.add_argument(
+        "--check",
+        default=None,
+        help="Restrict the benchmark to a single subcommand (per-check budget applies).",
+    )
+    args = parser.parse_args(argv)
+
+    if not _VALIDATOR.is_file():
+        print(f"ERROR: validator target not found: {_VALIDATOR}", file=sys.stderr)
+        return 2
+    extra = ["--check", args.check] if args.check else []
+    try:
+        elapsed = _time_invocation(extra)
+    except RuntimeError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+    # `--check all` is a full composite run, so it earns the composite budget,
+    # not the per-check budget — keying on the value, not merely arg presence.
+    per_check = args.check is not None and args.check != "all"
+    budget = _PER_CHECK_BUDGET if per_check else _COMPOSITE_BUDGET
+    label = f"--check {args.check}" if args.check else "composite sweep"
+    if elapsed <= budget:
+        print(f"PASS: validate_ecosystem {label} = {elapsed:.3f}s (budget {budget}s)")
+        return 0
+    print(f"FAIL: validate_ecosystem {label} = {elapsed:.3f}s exceeds budget {budget}s")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/apothem/cli/README.md

@@ -0,0 +1,33 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# cli
+
+> **Role.** The `apothem` command-line surface — the host-agnostic AI harness configuration manager. Reached via `python -m apothem` or the `apothem` console script declared in `pyproject.toml`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `__init__.py` | The CLI command surface — defines the `apothem` command tree. |
+| `_common_flags.py` | Shared Click options plus the console factory used across CLI commands. |
+| `_json_formatter.py` | JSON-output helper for the CLI (machine-readable command output). |
+| `reference_export.py` | Deterministic JSON exporter for source-generated documentation reference — introspects the CLI command tree and harness registry. Runnable via `python -m apothem.cli.reference_export <kind>`; spawned by `site/scripts/update-reference-inventory.mjs` and the docs-drift CI gate. |
+| `completions/` | Shell completion scripts: `apothem.bash`, `apothem.zsh`, `apothem.fish`, `apothem.ps1`. |
+
+## Conventions
+
+- The propagation domain model (`propagation.py` loader + `propagation-manifest.yaml` contract) lives in the shared [`lib/`](../lib/) package, not here — harness adapters consume it without importing the presentation-layer cli package.
+
+## Operating in this folder
+
+- **Layer boundary.** The CLI consumes the propagation domain and the harness registry; it does not host them. New presentation-only helpers belong here; new domain logic belongs in the shared [`lib/`](../lib/) or per-harness packages.
+- **Strict-typed surface.** This package sits inside the `mypy --strict` scope (`src/apothem/cli/`). Keep modern typing — `list[T]` / `dict[K, V]` / `X | None`, `typing.Protocol` for structural typing, `typing.cast()` to narrow `Any`.
+- Snake_case modules; private/shared helpers use a leading underscore (the `_common_flags`, `_json_formatter` pattern). Ambiguity is surfaced through structured inquiry or a `TODO(clarify)` marker — never invented.
+- **Adding a command/helper:** author it as a `.py` module under this package, wiring it into the command tree rather than as a free-standing script. Preserve the JSON-output path for any machine-readable command.
+- **A documented public CLI surface change** (a command, a flag, an environment variable) updates its `site/content/docs/` page in the same change-set.
+- Validate with `python -m ruff check` and `python -m ruff format`, `python -m mypy src/apothem/cli/`, then `python -m pytest`, then `python -m apothem.conformity.gate --all .`.
+
+## Related
+
+- [`lib/`](../lib/) — the shared package hosting the propagation domain model + manifest.
+- [`harnesses/`](../harnesses/) — the per-harness adapters that consume the propagation manifest via the shared install driver.

package/src/apothem/cli/__init__.py

@@ -0,0 +1,229 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem CLI — host-agnostic AI harness configuration manager.
+
+Entry point: the Click group ``apothem.cli:main``. There is no
+``[project.scripts]`` console-script shim; the engine is invoked through
+the module surface (``python -m apothem``) — the same surface the npm
+shim (``npx @ahmed-g-gad/apothem``), the Claude Code plugin, and the
+one-shot installers run. Uses Click for argument parsing and Rich for
+terminal output.
+
+The CLI surface provides continuous-form command aliases
+(``Installing``/``Updating``/``Uninstalling`` plus lowercase
+variants, hidden from ``--help`` but still resolvable), per-subcommand
+epilog blocks, a standard cross-subcommand flag set, shell-completion
+script emission (``apothem completion <shell>``), and a JSON output mode.
+
+This module is the thin assembly layer: it defines the ``main`` group and
+wires every command onto it by importing the per-command modules. The
+helpers, epilogs, and command bodies live in sibling modules:
+
+- ``_helpers`` — shared constants, the structured CLI-error type, the adapter
+  protocol + load helpers, profile read/write, lifecycle-envelope builders,
+  harness selection, project-root resolution, ``AliasedGroup``, and the
+  drift/plan helpers.
+- ``_epilogs`` — the per-subcommand ``--help`` epilog strings.
+- ``_materialize`` — the shared install/update materialization orchestrators.
+- ``_cmd_*`` — one module per command / command-group.
+
+The shared helpers are re-exported on this package namespace so that the
+existing test seams (``patch("apothem.cli.NAME")`` /
+``monkeypatch.setattr(cli, "NAME", ...)``) keep landing: the command bodies
+and orchestrators resolve those helpers through ``apothem.cli`` at call time.
+"""
+
+from __future__ import annotations
+
+import click
+
+import apothem
+
+# Re-export the shared helper surface on the package namespace. The command
+# modules and orchestrators resolve the patchable helpers through this package
+# (``apothem.cli.NAME``) at call time, so every name the test-suite patches or
+# imports from ``apothem.cli`` must be bound here.
+from apothem.cli._helpers import (
+    _ADAPTER_LOAD_ERRORS as _ADAPTER_LOAD_ERRORS,
+)
+from apothem.cli._helpers import (
+    _CONTEXT as _CONTEXT,
+)
+from apothem.cli._helpers import (
+    _EXIT_EXPECTED as _EXIT_EXPECTED,
+)
+from apothem.cli._helpers import (
+    _EXIT_PARTIAL as _EXIT_PARTIAL,
+)
+from apothem.cli._helpers import (
+    _PLACEHOLDER_IDENTITY as _PLACEHOLDER_IDENTITY,
+)
+from apothem.cli._helpers import (
+    AliasedGroup as AliasedGroup,
+)
+from apothem.cli._helpers import (
+    _Adapter as _Adapter,
+)
+from apothem.cli._helpers import (
+    _adapter_failure_result as _adapter_failure_result,
+)
+from apothem.cli._helpers import (
+    _adapter_requires_project as _adapter_requires_project,
+)
+from apothem.cli._helpers import (
+    _adapter_resolve_output_path as _adapter_resolve_output_path,
+)
+from apothem.cli._helpers import (
+    _all_adapters as _all_adapters,
+)
+from apothem.cli._helpers import (
+    _CliUserError as _CliUserError,
+)
+from apothem.cli._helpers import (
+    _complete_harness as _complete_harness,
+)
+from apothem.cli._helpers import (
+    _configure_stdio as _configure_stdio,
+)
+from apothem.cli._helpers import (
+    _drift_state as _drift_state,
+)
+from apothem.cli._helpers import (
+    _dry_run_plan as _dry_run_plan,
+)
+from apothem.cli._helpers import (
+    _emit_expected_error as _emit_expected_error,
+)
+from apothem.cli._helpers import (
+    _error_envelope as _error_envelope,
+)
+from apothem.cli._helpers import (
+    _format_error_plain as _format_error_plain,
+)
+from apothem.cli._helpers import (
+    _harness_roots as _harness_roots,
+)
+from apothem.cli._helpers import (
+    _invoke_with_project as _invoke_with_project,
+)
+from apothem.cli._helpers import (
+    _lifecycle_envelope as _lifecycle_envelope,
+)
+from apothem.cli._helpers import (
+    _load_adapter as _load_adapter,
+)
+from apothem.cli._helpers import (
+    _load_adapter_for_entry as _load_adapter_for_entry,
+)
+from apothem.cli._helpers import (
+    _load_profile as _load_profile,
+)
+from apothem.cli._helpers import (
+    _materialization_error as _materialization_error,
+)
+from apothem.cli._helpers import (
+    _parse_set_value as _parse_set_value,
+)
+from apothem.cli._helpers import (
+    _partition_blast_radius as _partition_blast_radius,
+)
+from apothem.cli._helpers import (
+    _path_is_within as _path_is_within,
+)
+from apothem.cli._helpers import (
+    _placeholder_advisory_entry as _placeholder_advisory_entry,
+)
+from apothem.cli._helpers import (
+    _placeholder_identity_fields as _placeholder_identity_fields,
+)
+from apothem.cli._helpers import (
+    _profile_error as _profile_error,
+)
+from apothem.cli._helpers import (
+    _profile_scaffold_text as _profile_scaffold_text,
+)
+from apothem.cli._helpers import (
+    _project_option as _project_option,
+)
+from apothem.cli._helpers import (
+    _render_blast_radius as _render_blast_radius,
+)
+from apothem.cli._helpers import (
+    _require_project_for_selection as _require_project_for_selection,
+)
+from apothem.cli._helpers import (
+    _require_project_if_needed as _require_project_if_needed,
+)
+from apothem.cli._helpers import (
+    _resolve_profile_path as _resolve_profile_path,
+)
+from apothem.cli._helpers import (
+    _resolve_project_root as _resolve_project_root,
+)
+from apothem.cli._helpers import (
+    _result_dicts as _result_dicts,
+)
+from apothem.cli._helpers import (
+    _selected_harness_ids as _selected_harness_ids,
+)
+from apothem.cli._helpers import (
+    _set_nested as _set_nested,
+)
+from apothem.cli._helpers import (
+    _stdin_is_interactive as _stdin_is_interactive,
+)
+from apothem.cli._helpers import (
+    _unknown_harness_error as _unknown_harness_error,
+)
+from apothem.cli._helpers import (
+    _warning_dicts as _warning_dicts,
+)
+from apothem.cli._helpers import (
+    _write_profile_text_safely as _write_profile_text_safely,
+)
+from apothem.cli._helpers import (
+    console as console,
+)
+from apothem.cli._materialize import (
+    _dry_run_materialization as _dry_run_materialization,
+)
+from apothem.cli._materialize import (
+    _materialize as _materialize,
+)
+
+# Harness-registry helpers used at call time through the package namespace.
+from apothem.lib.harness_registry import get_harness_entry as get_harness_entry
+from apothem.lib.harness_registry import iter_harness_entries as iter_harness_entries
+
+# Single version source: the package root resolves the version tree-first
+# (the co-located pyproject.toml), then installed metadata, then the
+# explicit unknown sentinel.
+_VERSION = apothem.__version__
+
+
+# -----------------------------------------------------------------------
+# Top-level group.
+# -----------------------------------------------------------------------
+
+
+@click.group(cls=AliasedGroup, context_settings=_CONTEXT)
+@click.version_option(version=_VERSION, prog_name="Apothem")
+def main() -> None:
+    """Apothem — host-agnostic AI harness configuration manager."""
+    _configure_stdio()
+
+
+# Import every command module after ``main`` exists; each registers its
+# command(s) / group(s) onto ``main`` via ``@main.command`` / ``@main.group``
+# at import time. Imported for their registration side effects.
+from apothem.cli import _cmd_completion as _cmd_completion  # noqa: E402
+from apothem.cli import _cmd_diff as _cmd_diff  # noqa: E402
+from apothem.cli import _cmd_doctor as _cmd_doctor  # noqa: E402
+from apothem.cli import _cmd_harnesses as _cmd_harnesses  # noqa: E402
+from apothem.cli import _cmd_install as _cmd_install  # noqa: E402
+from apothem.cli import _cmd_migrate_workspace as _cmd_migrate_workspace  # noqa: E402
+from apothem.cli import _cmd_profile as _cmd_profile  # noqa: E402
+from apothem.cli import _cmd_status as _cmd_status  # noqa: E402
+from apothem.cli import _cmd_uninstall as _cmd_uninstall  # noqa: E402
+from apothem.cli import _cmd_update as _cmd_update  # noqa: E402
+from apothem.cli import _cmd_verify as _cmd_verify  # noqa: E402

package/src/apothem/cli/_cmd_completion.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: MIT
+
+"""``apothem completion`` — emit a sourceable shell-completion script."""
+
+from __future__ import annotations
+
+import click
+from click.shell_completion import get_completion_class
+
+from apothem.cli import main
+from apothem.cli._epilogs import _EP_COMPLETION
+
+_NATIVE_COMPLETION_SHELLS: tuple[str, ...] = ("bash", "zsh", "fish")
+
+
+_COMPLETION_SHELLS: tuple[str, ...] = (*_NATIVE_COMPLETION_SHELLS, "powershell")
+
+
+_COMPLETION_PROG_NAME = "apothem"
+
+
+_COMPLETION_COMPLETE_VAR = "_APOTHEM_COMPLETE"
+
+
+def _powershell_completion_snippet() -> str:
+    """Return a PowerShell ``Register-ArgumentCompleter`` snippet for apothem.
+
+    Click 8.x ships no PowerShell completion class, so this snippet bridges the
+    gap: it registers a native argument completer that shells out to Click's
+    env-var completion protocol (``_APOTHEM_COMPLETE=powershell_complete``),
+    parses the ``type,value`` lines Click emits, and surfaces them as
+    PowerShell ``CompletionResult`` objects. It is opt-in like the native
+    scripts — append it to ``$PROFILE`` to enable.
+    """
+    return f"""\
+# Apothem shell completion for PowerShell.
+# Append to your PowerShell profile ($PROFILE) to enable, then restart the shell:
+#   apothem completion powershell >> $PROFILE
+Register-ArgumentCompleter -Native -CommandName {_COMPLETION_PROG_NAME} -ScriptBlock {{
+    param($wordToComplete, $commandAst, $cursorPosition)
+    $env:{_COMPLETION_COMPLETE_VAR} = "powershell_complete"
+    $env:COMP_WORDS = $commandAst.ToString()
+    $env:COMP_CWORD = $cursorPosition
+    try {{
+        {_COMPLETION_PROG_NAME} | ForEach-Object {{
+            $type, $value, $help = $_ -split ",", 3
+            if ($value) {{
+                [System.Management.Automation.CompletionResult]::new(
+                    $value, $value, 'ParameterValue', ($help, $value -ne $null)[0]
+                )
+            }}
+        }}
+    }} finally {{
+        Remove-Item Env:{_COMPLETION_COMPLETE_VAR}
+        Remove-Item Env:COMP_WORDS
+        Remove-Item Env:COMP_CWORD
+    }}
+}}
+"""
+
+
+@main.command(epilog=_EP_COMPLETION)
+@click.argument(
+    "shell",
+    type=click.Choice(_COMPLETION_SHELLS, case_sensitive=False),
+)
+def completion(shell: str) -> None:
+    """Print a shell-completion script for SHELL to stdout.
+
+    Supported shells: bash, zsh, fish, powershell. The emitted script is the one
+    Click's env-var completion protocol generates for the native shells; for
+    PowerShell (which Click does not generate natively) it is a documented
+    ``Register-ArgumentCompleter`` snippet that bridges to the same protocol.
+    Enabling completion is opt-in: this command only prints the script — pipe or
+    append it to the shell's completion file yourself (see ``--help``).
+    """
+    target = shell.lower()
+    if target == "powershell":
+        click.echo(_powershell_completion_snippet(), nl=False)
+        return
+    completion_cls = get_completion_class(target)
+    if completion_cls is None:  # pragma: no cover - guarded by click.Choice
+        raise click.ClickException(
+            f"Completion is not supported for {shell!r}. "
+            f"Supported shells: {', '.join(_COMPLETION_SHELLS)}."
+        )
+    comp = completion_cls(main, {}, _COMPLETION_PROG_NAME, _COMPLETION_COMPLETE_VAR)
+    click.echo(comp.source())