transcrypto 1.6.0__py3-none-any.whl → 1.8.0__py3-none-any.whl

transcrypto/cli/bidsecret.py

@@ -0,0 +1,334 @@
+# SPDX-FileCopyrightText: Copyright 2026 Daniel Balparda <balparda@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""Balparda's TransCrypto CLI: Bid secret and SSS commands."""
+
+from __future__ import annotations
+
+import glob
+
+import typer
+
+from transcrypto import base, sss, transcrypto
+from transcrypto.cli import clibase
+
+# ================================== "BID" COMMAND =================================================
+
+
+bid_app = typer.Typer(
+  no_args_is_help=True,
+  help=(
+    'Bidding on a `secret` so that you can cryptographically convince a neutral '
+    'party that the `secret` that was committed to previously was not changed. '
+    'All methods require file key(s) as `-p`/`--key-path` (see provided examples). '
+    'All non-int inputs are raw, or you can use `--input-format <hex|b64|bin>`. '
+    'No measures are taken here to prevent timing attacks.'
+  ),
+)
+transcrypto.app.add_typer(bid_app, name='bid')
+
+
+@bid_app.command(
+  'new',
+  help=('Generate the bid files for `secret`.'),
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run transcrypto -i bin -p my-bid bid new "tomorrow it will rain"\n\n'
+    "Bid private/public commitments saved to 'my-bid.priv/.pub'"
+  ),
+)
+@clibase.CLIErrorGuard
+def BidNew(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: typer.Context,
+  secret: str = typer.Argument(..., help='Input data to bid to, the protected "secret"'),
+) -> None:
+  config: transcrypto.TransConfig = ctx.obj
+  base_path: str = transcrypto.RequireKeyPath(config, 'bid')
+  secret_bytes: bytes = transcrypto.BytesFromText(secret, config.input_format)
+  bid_priv: base.PrivateBid512 = base.PrivateBid512.New(secret_bytes)
+  bid_pub: base.PublicBid512 = base.PublicBid512.Copy(bid_priv)
+  transcrypto.SaveObj(bid_priv, base_path + '.priv', config.protect)
+  transcrypto.SaveObj(bid_pub, base_path + '.pub', config.protect)
+  config.console.print(f'Bid private/public commitments saved to {base_path + ".priv/.pub"!r}')
+
+
+@bid_app.command(
+  'verify',
+  help=('Verify the bid files for correctness and reveal the `secret`.'),
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run transcrypto -o bin -p my-bid bid verify\n\n'
+    'Bid commitment: OK\n\n'
+    'Bid secret:\n\n'
+    'tomorrow it will rain'
+  ),
+)
+@clibase.CLIErrorGuard
+def BidVerify(*, ctx: typer.Context) -> None:  # documentation is help/epilog/args # noqa: D103
+  config: transcrypto.TransConfig = ctx.obj
+  base_path: str = transcrypto.RequireKeyPath(config, 'bid')
+  bid_priv: base.PrivateBid512 = transcrypto.LoadObj(
+    base_path + '.priv', config.protect, base.PrivateBid512
+  )
+  bid_pub: base.PublicBid512 = transcrypto.LoadObj(
+    base_path + '.pub', config.protect, base.PublicBid512
+  )
+  bid_pub_expect: base.PublicBid512 = base.PublicBid512.Copy(bid_priv)
+  config.console.print(
+    'Bid commitment: '
+    + (
+      '[green]OK[/]'
+      if (
+        bid_pub.VerifyBid(bid_priv.private_key, bid_priv.secret_bid) and bid_pub == bid_pub_expect
+      )
+      else '[red]INVALID[/]'
+    )
+  )
+  config.console.print('Bid secret:')
+  config.console.print(transcrypto.BytesToText(bid_priv.secret_bid, config.output_format))
+
+
+# ================================== "SSS" COMMAND =================================================
+
+
+sss_app = typer.Typer(
+  no_args_is_help=True,
+  help=(
+    'SSS (Shamir Shared Secret) secret sharing crypto scheme. '
+    'All methods require file key(s) as `-p`/`--key-path` (see provided examples). '
+    'All non-int inputs are raw, or you can use `--input-format <hex|b64|bin>`. '
+    'No measures are taken here to prevent timing attacks.'
+  ),
+)
+transcrypto.app.add_typer(sss_app, name='sss')
+
+
+@sss_app.command(
+  'new',
+  help=(
+    'Generate the private keys with `bits` prime modulus size and so that at least a '
+    '`minimum` number of shares are needed to recover the secret. '
+    'This key will be used to generate the shares later (with the `shares` command).'
+  ),
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run transcrypto -p sss-key sss new 3 --bits 64  '
+    '# NEVER use such a small key: example only!\n\n'
+    "SSS private/public keys saved to 'sss-key.priv/.pub'"
+  ),
+)
+@clibase.CLIErrorGuard
+def SSSNew(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: typer.Context,
+  minimum: int = typer.Argument(
+    ..., min=2, help='Minimum number of shares required to recover secret, ≥ 2'
+  ),
+  bits: int = typer.Option(
+    1024,
+    '-b',
+    '--bits',
+    min=16,
+    help=(
+      'Prime modulus (`p`) size in bits, ≥16; the default (1024) is a safe size ***IFF*** you '
+      'are protecting symmetric keys; the number of bits should be comfortably larger '
+      'than the size of the secret you want to protect with this scheme'
+    ),
+  ),
+) -> None:
+  config: transcrypto.TransConfig = ctx.obj
+  base_path: str = transcrypto.RequireKeyPath(config, 'sss')
+  sss_priv: sss.ShamirSharedSecretPrivate = sss.ShamirSharedSecretPrivate.New(minimum, bits)
+  sss_pub: sss.ShamirSharedSecretPublic = sss.ShamirSharedSecretPublic.Copy(sss_priv)
+  transcrypto.SaveObj(sss_priv, base_path + '.priv', config.protect)
+  transcrypto.SaveObj(sss_pub, base_path + '.pub', config.protect)
+  config.console.print(f'SSS private/public keys saved to {base_path + ".priv/.pub"!r}')
+
+
+@sss_app.command(
+  'rawshares',
+  help=(
+    'Raw shares: Issue `count` private shares for an *integer* `secret` '
+    '(BEWARE: no modern message wrapping, padding or validation).'
+  ),
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run transcrypto -p sss-key sss rawshares 999 5\n\n'
+    "SSS 5 individual (private) shares saved to 'sss-key.share.1…5'\n\n"
+    '$ rm sss-key.share.2 sss-key.share.4  # this is to simulate only having shares 1,3,5'
+  ),
+)
+@clibase.CLIErrorGuard
+def SSSRawShares(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: typer.Context,
+  secret: str = typer.Argument(..., help='Integer secret to be protected, 1≤`secret`<*modulus*'),
+  count: int = typer.Argument(
+    ...,
+    min=1,
+    help=(
+      'How many shares to produce; must be ≥ `minimum` used in `new` command or else the '
+      '`secret` would become unrecoverable'
+    ),
+  ),
+) -> None:
+  config: transcrypto.TransConfig = ctx.obj
+  base_path: str = transcrypto.RequireKeyPath(config, 'sss')
+  sss_priv: sss.ShamirSharedSecretPrivate = transcrypto.LoadObj(
+    base_path + '.priv', config.protect, sss.ShamirSharedSecretPrivate
+  )
+  if count < sss_priv.minimum:
+    raise base.InputError(
+      f'count ({count}) must be >= minimum ({sss_priv.minimum}) to allow secret recovery'
+    )
+  secret_i: int = transcrypto.ParseInt(secret, min_value=1)
+  for i, share in enumerate(sss_priv.RawShares(secret_i, max_shares=count)):
+    transcrypto.SaveObj(share, f'{base_path}.share.{i + 1}', config.protect)
+  config.console.print(
+    f'SSS {count} individual (private) shares saved to {base_path + ".share.1…" + str(count)!r}'
+  )
+
+
+@sss_app.command(
+  'rawrecover',
+  help=(
+    'Raw recover *integer* secret from shares; will use any available shares '
+    'that were found (BEWARE: no modern message wrapping, padding or validation).'
+  ),
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run transcrypto -p sss-key sss rawrecover\n\n'
+    "Loaded SSS share: 'sss-key.share.3'\n\n"
+    "Loaded SSS share: 'sss-key.share.5'\n\n"
+    "Loaded SSS share: 'sss-key.share.1'  # using only 3 shares: number 2/4 are missing\n\n"
+    'Secret:\n\n'
+    '999'
+  ),
+)
+@clibase.CLIErrorGuard
+def SSSRawRecover(*, ctx: typer.Context) -> None:  # documentation is help/epilog/args # noqa: D103
+  config: transcrypto.TransConfig = ctx.obj
+  base_path: str = transcrypto.RequireKeyPath(config, 'sss')
+  sss_pub: sss.ShamirSharedSecretPublic = transcrypto.LoadObj(
+    base_path + '.pub', config.protect, sss.ShamirSharedSecretPublic
+  )
+  subset: list[sss.ShamirSharePrivate] = []
+  for fname in glob.glob(base_path + '.share.*'):  # noqa: PTH207
+    subset.append(transcrypto.LoadObj(fname, config.protect, sss.ShamirSharePrivate))
+    config.console.print(f'Loaded SSS share: {fname!r}')
+  config.console.print('Secret:')
+  config.console.print(sss_pub.RawRecoverSecret(subset))
+
+
+@sss_app.command(
+  'rawverify',
+  help=(
+    'Raw verify shares against a secret (private params; '
+    'BEWARE: no modern message wrapping, padding or validation).'
+  ),
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run transcrypto -p sss-key sss rawverify 999\n\n'
+    "SSS share 'sss-key.share.3' verification: OK\n\n"
+    "SSS share 'sss-key.share.5' verification: OK\n\n"
+    "SSS share 'sss-key.share.1' verification: OK\n\n"
+    '$ poetry run transcrypto -p sss-key sss rawverify 998\n\n'
+    "SSS share 'sss-key.share.3' verification: INVALID\n\n"
+    "SSS share 'sss-key.share.5' verification: INVALID\n\n"
+    "SSS share 'sss-key.share.1' verification: INVALID"
+  ),
+)
+@clibase.CLIErrorGuard
+def SSSRawVerify(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: typer.Context,
+  secret: str = typer.Argument(..., help='Integer secret used to generate the shares, ≥ 1'),
+) -> None:
+  config: transcrypto.TransConfig = ctx.obj
+  base_path: str = transcrypto.RequireKeyPath(config, 'sss')
+  sss_priv: sss.ShamirSharedSecretPrivate = transcrypto.LoadObj(
+    base_path + '.priv', config.protect, sss.ShamirSharedSecretPrivate
+  )
+  secret_i: int = transcrypto.ParseInt(secret, min_value=1)
+  for fname in glob.glob(base_path + '.share.*'):  # noqa: PTH207
+    share: sss.ShamirSharePrivate = transcrypto.LoadObj(
+      fname, config.protect, sss.ShamirSharePrivate
+    )
+    config.console.print(
+      f'SSS share {fname!r} verification: '
+      f'{"OK" if sss_priv.RawVerifyShare(secret_i, share) else "INVALID"}'
+    )
+
+
+@sss_app.command(
+  'shares',
+  help='Shares: Issue `count` private shares for a `secret`.',
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run transcrypto -i bin -p sss-key sss shares "abcde" 5\n\n'
+    "SSS 5 individual (private) shares saved to 'sss-key.share.1…5'\n\n"
+    '$ rm sss-key.share.2 sss-key.share.4  # this is to simulate only having shares 1,3,5'
+  ),
+)
+@clibase.CLIErrorGuard
+def SSSShares(  # documentation is help/epilog/args # noqa: D103
+  *,
+  ctx: typer.Context,
+  secret: str = typer.Argument(..., help='Secret to be protected'),
+  count: int = typer.Argument(
+    ...,
+    help=(
+      'How many shares to produce; must be ≥ `minimum` used in `new` command or else the '
+      '`secret` would become unrecoverable'
+    ),
+  ),
+) -> None:
+  config: transcrypto.TransConfig = ctx.obj
+  base_path: str = transcrypto.RequireKeyPath(config, 'sss')
+  sss_priv: sss.ShamirSharedSecretPrivate = transcrypto.LoadObj(
+    base_path + '.priv', config.protect, sss.ShamirSharedSecretPrivate
+  )
+  if count < sss_priv.minimum:
+    raise base.InputError(
+      f'count ({count}) must be >= minimum ({sss_priv.minimum}) to allow secret recovery'
+    )
+  pt: bytes = transcrypto.BytesFromText(secret, config.input_format)
+  for i, data_share in enumerate(sss_priv.MakeDataShares(pt, count)):
+    transcrypto.SaveObj(data_share, f'{base_path}.share.{i + 1}', config.protect)
+  config.console.print(
+    f'SSS {count} individual (private) shares saved to {base_path + ".share.1…" + str(count)!r}'
+  )
+
+
+@sss_app.command(
+  'recover',
+  help='Recover secret from shares; will use any available shares that were found.',
+  epilog=(
+    'Example:\n\n\n\n'
+    '$ poetry run transcrypto -o bin -p sss-key sss recover\n\n'
+    "Loaded SSS share: 'sss-key.share.3'\n\n"
+    "Loaded SSS share: 'sss-key.share.5'\n\n"
+    "Loaded SSS share: 'sss-key.share.1'  # using only 3 shares: number 2/4 are missing\n\n"
+    'Secret:\n\n'
+    'abcde'
+  ),
+)
+@clibase.CLIErrorGuard
+def SSSRecover(*, ctx: typer.Context) -> None:  # documentation is help/epilog/args # noqa: D103
+  config: transcrypto.TransConfig = ctx.obj
+  base_path: str = transcrypto.RequireKeyPath(config, 'sss')
+  subset: list[sss.ShamirSharePrivate] = []
+  data_share: sss.ShamirShareData | None = None
+  for fname in glob.glob(base_path + '.share.*'):  # noqa: PTH207
+    share: sss.ShamirSharePrivate = transcrypto.LoadObj(
+      fname, config.protect, sss.ShamirSharePrivate
+    )
+    subset.append(share)
+    if isinstance(share, sss.ShamirShareData):
+      data_share = share
+    config.console.print(f'Loaded SSS share: {fname!r}')
+  if data_share is None:
+    raise base.InputError('no data share found among the available shares')
+  pt: bytes = data_share.RecoverData(subset)
+  config.console.print('Secret:')
+  config.console.print(transcrypto.BytesToText(pt, config.output_format))

transcrypto/cli/clibase.py

@@ -0,0 +1,303 @@
+# SPDX-FileCopyrightText: Copyright 2026 Daniel Balparda <balparda@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""Balparda's CLI base library."""
+
+from __future__ import annotations
+
+import dataclasses
+import functools
+import logging
+import os
+import threading
+from collections import abc
+from typing import cast
+
+import click
+import typer
+from click import testing as click_testing
+from rich import console as rich_console
+from rich import logging as rich_logging
+
+from transcrypto import base
+
+# Logging
+_LOG_FORMAT_NO_PROCESS: str = '%(funcName)s: %(message)s'
+_LOG_FORMAT_WITH_PROCESS: str = '%(processName)s/' + _LOG_FORMAT_NO_PROCESS
+_LOG_FORMAT_DATETIME: str = '[%Y%m%d-%H:%M:%S]'  # e.g., [20240131-13:45:30]
+_LOG_LEVELS: dict[int, int] = {
+  0: logging.ERROR,
+  1: logging.WARNING,
+  2: logging.INFO,
+  3: logging.DEBUG,
+}
+_LOG_COMMON_PROVIDERS: set[str] = {
+  'werkzeug',
+  'gunicorn.error',
+  'gunicorn.access',
+  'uvicorn',
+  'uvicorn.error',
+  'uvicorn.access',
+  'django.server',
+}
+
+__console_lock: threading.RLock = threading.RLock()
+__console_singleton: rich_console.Console | None = None
+
+
+def Console() -> rich_console.Console:
+  """Get the global console instance.
+
+  Returns:
+    rich.console.Console: The global console instance.
+
+  """
+  with __console_lock:
+    if __console_singleton is None:
+      return rich_console.Console()  # fallback console if InitLogging hasn't been called yet
+    return __console_singleton
+
+
+def ResetConsole() -> None:
+  """Reset the global console instance."""
+  global __console_singleton  # noqa: PLW0603
+  with __console_lock:
+    __console_singleton = None
+
+
+def InitLogging(
+  verbosity: int,
+  /,
+  *,
+  include_process: bool = False,
+  soft_wrap: bool = False,
+  color: bool | None = False,
+) -> tuple[rich_console.Console, int, bool]:
+  """Initialize logger (with RichHandler) and get a rich.console.Console singleton.
+
+  This method will also return the actual decided values for verbosity and color use.
+  If you have a CLI app that uses this, its pytests should call `ResetConsole()` in a fixture, like:
+
+      from transcrypto import logging
+      @pytest.fixture(autouse=True)
+      def _reset_base_logging() -> Generator[None, None, None]:  # type: ignore
+        logging.ResetConsole()
+        yield  # stop
+
+  Args:
+    verbosity (int): Logging verbosity level: 0==ERROR, 1==WARNING, 2==INFO, 3==DEBUG
+    include_process (bool, optional): Whether to include process name in log output.
+    soft_wrap (bool, optional): Whether to enable soft wrapping in the console.
+        Default is False, and it means rich will hard-wrap long lines (by adding line breaks).
+    color (bool | None, optional): Whether to enable/disable color output in the console.
+        If None, respects NO_COLOR env var.
+
+  Returns:
+    tuple[rich_console.Console, int, bool]:
+        (The initialized console instance, actual log level, actual color use)
+
+  Raises:
+    RuntimeError: if you call this more than once
+
+  """
+  global __console_singleton  # noqa: PLW0603
+  with __console_lock:
+    if __console_singleton is not None:
+      raise RuntimeError(
+        'calling InitLogging() more than once is forbidden; '
+        'use Console() to get a console after first creation'
+      )
+    # set level
+    logging_level: int = _LOG_LEVELS.get(min(verbosity, 3), logging.ERROR)
+    # respect NO_COLOR unless the caller has already decided (treat env presence as "disable color")
+    no_color: bool = (
+      False
+      if (os.getenv('NO_COLOR') is None and color is None)
+      else ((os.getenv('NO_COLOR') is not None) if color is None else (not color))
+    )
+    # create console and configure logging
+    console = rich_console.Console(soft_wrap=soft_wrap, no_color=no_color)
+    logging.basicConfig(
+      level=logging_level,
+      format=_LOG_FORMAT_WITH_PROCESS if include_process else _LOG_FORMAT_NO_PROCESS,
+      datefmt=_LOG_FORMAT_DATETIME,
+      handlers=[
+        rich_logging.RichHandler(  # we show name/line, but want time & level
+          console=console,
+          rich_tracebacks=True,
+          show_time=True,
+          show_level=True,
+          show_path=True,
+        ),
+      ],
+      force=True,  # force=True to override any previous logging config
+    )
+    # configure common loggers
+    logging.captureWarnings(True)
+    for name in _LOG_COMMON_PROVIDERS:
+      log: logging.Logger = logging.getLogger(name)
+      log.handlers.clear()
+      log.propagate = True
+      log.setLevel(logging_level)
+    __console_singleton = console  # need a global statement to re-bind this one
+    logging.info(
+      f'Logging initialized at level {logging.getLevelName(logging_level)} / '
+      f'{"NO " if no_color else ""}COLOR'
+    )
+    return (console, logging_level, not no_color)
+
+
+@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
+class CLIConfig:
+  """CLI global context, storing the configuration."""
+
+  console: rich_console.Console
+  verbose: int
+  color: bool | None
+
+
+def CLIErrorGuard[**P](fn: abc.Callable[P, None], /) -> abc.Callable[P, None]:
+  """Guard CLI command functions.
+
+  Returns:
+    A wrapped function that catches expected user-facing errors and prints them consistently.
+
+  """
+
+  @functools.wraps(fn)
+  def _Wrapper(*args: P.args, **kwargs: P.kwargs) -> None:
+    try:
+      # call the actual function
+      fn(*args, **kwargs)
+    except (base.Error, ValueError) as err:
+      # get context
+      ctx: object | None = dict(kwargs).get('ctx')
+      if not isinstance(ctx, typer.Context):
+        ctx = next((a for a in args if isinstance(a, typer.Context)), None)
+      # print error nicely
+      if isinstance(ctx, typer.Context):
+        # we have context
+        obj: CLIConfig = cast('CLIConfig', ctx.obj)
+        if obj.verbose >= 2:  # verbose >= 2 means INFO level or more verbose  # noqa: PLR2004
+          obj.console.print_exception()  # print full traceback
+        else:
+          obj.console.print(str(err))  # print only error message
+      # no context
+      elif logging.getLogger().getEffectiveLevel() < logging.INFO:
+        Console().print(str(err))  # print only error message (DEBUG level is verbose already)
+      else:
+        Console().print_exception()  # print full traceback (less verbose mode needs it)
+
+  return _Wrapper
+
+
+def _ClickWalk(
+  command: click.Command,
+  ctx: typer.Context,
+  path: list[str],
+  /,
+) -> abc.Iterator[tuple[list[str], click.Command, typer.Context]]:
+  """Recursively walk Click commands/groups.
+
+  Yields:
+    tuple[list[str], click.Command, typer.Context]: path, command, ctx
+
+  """
+  yield (path, command, ctx)  # yield self
+  # now walk subcommands, if any
+  sub_cmd: click.Command | None
+  sub_ctx: typer.Context
+  # prefer the explicit `.commands` mapping when present; otherwise fall back to
+  # click's `list_commands()`/`get_command()` for dynamic groups
+  if not isinstance(command, click.Group):
+    return
+  # explicit commands mapping
+  if command.commands:
+    for name, sub_cmd in sorted(command.commands.items()):
+      sub_ctx = typer.Context(sub_cmd, info_name=name, parent=ctx)
+      yield from _ClickWalk(sub_cmd, sub_ctx, [*path, name])
+    return
+  # dynamic commands
+  for name in sorted(command.list_commands(ctx)):
+    sub_cmd = command.get_command(ctx, name)
+    if sub_cmd is None:
+      continue  # skip invalid subcommands
+    sub_ctx = typer.Context(sub_cmd, info_name=name, parent=ctx)
+    yield from _ClickWalk(sub_cmd, sub_ctx, [*path, name])
+
+
+def GenerateTyperHelpMarkdown(
+  typer_app: typer.Typer,
+  /,
+  *,
+  prog_name: str,
+  heading_level: int = 1,
+  code_fence_language: str = 'text',
+) -> str:
+  """Capture `--help` for a Typer CLI and all subcommands as Markdown.
+
+  This function converts a Typer app to its underlying Click command tree and then:
+  - invokes `--help` for the root ("Main") command
+  - walks commands/subcommands recursively
+  - invokes `--help` for each command path
+
+  It emits a Markdown document with a heading per command and a fenced block
+  containing the exact `--help` output.
+
+  Notes:
+    - This uses Click's `CliRunner().invoke(...)` for faithful output.
+    - The walk is generic over Click `MultiCommand`/`Group` structures.
+    - If a command cannot be loaded, it is skipped.
+
+  Args:
+    typer_app: The Typer app (e.g. `app`).
+    prog_name: Program name used in usage strings (e.g. "profiler").
+    heading_level: Markdown heading level for each command section.
+    code_fence_language: Language tag for fenced blocks (default: "text").
+
+  Returns:
+    Markdown string.
+
+  """
+  # prepare Click root command and context
+  click_root: click.Command = typer.main.get_command(typer_app)
+  root_ctx: typer.Context = typer.Context(click_root, info_name=prog_name)
+  runner = click_testing.CliRunner()
+  parts: list[str] = []
+  for path, _, _ in _ClickWalk(click_root, root_ctx, []):
+    # build command path
+    command_path: str = ' '.join([prog_name, *path]).strip()
+    heading_prefix: str = '#' * max(1, heading_level + len(path))
+    ResetConsole()  # ensure clean state for each command (also it raises on duplicate loggers)
+    # invoke --help for this command path
+    result: click_testing.Result = runner.invoke(
+      click_root,
+      [*path, '--help'],
+      prog_name=prog_name,
+      color=False,
+    )
+    if result.exit_code != 0 and not result.output:
+      continue  # skip invalid commands
+    # build markdown section
+    global_prefix: str = (  # only for the top-level command
+      (
+        '<!-- cspell:disable -->\n'
+        '<!-- auto-generated; DO NOT EDIT! see base.GenerateTyperHelpMarkdown() -->\n\n'
+      )
+      if not path
+      else ''
+    )
+    extras: str = (  # type of command, by level
+      ('Command-Line Interface' if not path else 'Command') if len(path) <= 1 else 'Sub-Command'
+    )
+    parts.extend(
+      (
+        f'{global_prefix}{heading_prefix} `{command_path}` {extras}',
+        '',
+        f'```{code_fence_language}',
+        result.output.strip(),
+        '```',
+        '',
+      )
+    )
+  # join all parts and return
+  return '\n'.join(parts).rstrip()