usage: kanon search [-h] [--catalog-source <git-url>@<ref>]
                    [--catalog-default-branch <branch>]
                    [--format {names,json}] [--detail] [--tree]
                    [--max-depth N] [--no-filter-required] [-A] [--limit N]
                    [--no-limit] [--since-version <spec>] [--regex <pattern>]
                    [--match-fields <csv>]
                    [<substring>]

Print one catalog entry name per line to stdout, sorted
lexicographically and grouped under a per-source header on stderr.
Reads *-marketplace.xml files under repo-specs/ in the manifest repo
identified by the catalog source.

Requires a catalog source via --catalog-source or the
KANON_CATALOG_SOURCES environment variable (the single configured
entry is used). The CLI flag takes precedence when both are set.

Filter mode: supply an optional positional <substring> or --regex
<pattern> to narrow the catalog entries returned. The filter checks
the entry name, display-name, description, and keywords by default.
Use --match-fields <csv> to restrict to a subset of those fields.
  <substring> and --regex are mutually exclusive.
  --match-fields requires <substring> or --regex.
Zero matches: exits 0 with empty stdout and '0 entries match filter'
on stderr.

Format mode (--format): selects the output format. Choices:
  names (default) -- one entry name per line, pipeable into kanon add.
  json -- structured JSON array of entry objects. Default mode and
    --detail mode emit {name, display-name, type, description, version};
    -A/--all mode emits {name, version, ref, sha}.
The KANON_LIST_FORMAT environment variable sets the format when the
CLI flag is absent; the CLI flag takes precedence when both are set.
--format json is incompatible with --tree (hard error).

Tree mode (--tree): renders a three-layer ASCII dependency tree
per entry. Subject to a threshold guardrail: when the catalog has
more than KANON_TREE_NO_FILTER_THRESHOLD (default 20)
entries, a filter is required unless --no-filter-required is passed.
Resolution paths: positional <name> substring, --regex <pattern>,
--max-depth 0, or --no-filter-required.

All-versions mode (-A/--all): walks historical catalog versions
via git ls-remote --tags. Emits one <name>@<version> row per catalog
entry per version, newest version first (default: latest-only).
Default version cap: KANON_LIST_LIMIT (default 50, overridable via env var).
Use --limit N to cap at N versions, --no-limit to walk all versions.
Use --since-version <spec> to filter by a PEP 440 constraint
(e.g. '>=1.0,<2.0'). Mutually exclusive with --tree.

positional arguments:
  <substring>           Optional case-sensitive substring filter. When
                        supplied, only entries whose name, display-name,
                        description, or keywords contain the substring are
                        returned. Mutually exclusive with --regex. Use
                        --match-fields to restrict the fields checked.

options:
  -h, --help            show this help message and exit
  --catalog-source <git-url>@<ref>
                        Remote catalog source as '<git_url>@<ref>' where ref
                        is a branch, tag, or 'latest'. Overrides the
                        KANON_CATALOG_SOURCES env var. Required when
                        KANON_CATALOG_SOURCES configures no single source. May
                        be repeated to search several sources; the supplied
                        flags fully replace KANON_CATALOG_SOURCES for this
                        invocation.
  --catalog-default-branch <branch>
                        Branch to use for a catalog source supplied without an
                        '@ref'. Precedence: an inline '@ref' on the source >
                        this flag > the KANON_CATALOG_DEFAULT_BRANCH env var
                        (default 'main') > the literal 'auto', which resolves
                        the remote HEAD symref via 'git ls-remote --symref'. A
                        defaulted branch is verified to exist on the remote
                        (fail fast) and a single WARNING naming it is written
                        to stderr.
  --format {names,json}
                        Output format. 'names' (default): one entry name per
                        line, pipeable into kanon add. 'json': structured JSON
                        array. Default mode and --detail mode emit {name,
                        display-name, type, description, version} objects;
                        -A/--all mode emits {name, version, ref, sha} objects.
                        The KANON_LIST_FORMAT environment variable sets the
                        format when this flag is absent; the CLI flag takes
                        precedence when both are set. --format json is
                        incompatible with --tree (hard error at validation
                        time).
  --detail              Print a human-readable multi-line record per entry
                        (display-name, description, version, type). Human-
                        readable only -- not pipeable into kanon add. For
                        machine consumers, combine with --format json.
  --tree                Render a three-layer ASCII dependency tree per entry:
                        the catalog entry (root), the XML manifests reachable
                        via transitive <include> directives, and the <project>
                        repos referenced by those manifests. Each node shows
                        the version resolved at command-execution time.
                        Mutually exclusive with -A/--all. Subject to the
                        threshold guardrail (KANON_TREE_NO_FILTER_THRESHOLD,
                        default 20): when the catalog exceeds the threshold,
                        supply a filter -- positional substring, --regex,
                        --max-depth 0 -- or pass --no-filter-required.
  --max-depth N         Cap the tree depth rendered by --tree. 0 = root entry
                        node only (no XML or project layers). 1 = root + XML
                        layer only. Default: unlimited. --max-depth 0 also
                        satisfies the threshold guardrail as a valid filter.
  --no-filter-required  Bypass the threshold guardrail for --tree. Normally,
                        catalogs with more than KANON_TREE_NO_FILTER_THRESHOLD
                        (default 20) entries require a filter (positional
                        substring, --regex, or --max-depth 0) to avoid
                        accidental full-catalog tree renders. Pass this flag
                        to bypass the check.
  -A, --all             Show all tagged versions of each matching manifest
                        instead of the latest-only default. Walks all
                        historical tagged versions of the manifest repo and
                        emits one <name>@<version> row per catalog entry per
                        version. Versions are ordered newest-first by PEP 440
                        natural sort; entries within each version are sorted
                        lexicographically. Mutually exclusive with --tree.
                        Default cap: KANON_LIST_LIMIT (default 50, overridable
                        via env var). Use --limit N or --no-limit to control
                        the number of versions walked.
  --limit N             Cap the number of versions walked by -A/--all.
                        Default: KANON_LIST_LIMIT (default 50, overridable via
                        the KANON_LIST_LIMIT environment variable). Mutually
                        exclusive with --no-limit.
  --no-limit            Walk all PEP 440-valid tags when using -A/--all, with
                        no cap. Equivalent to --limit <very-large-number>.
                        Mutually exclusive with --limit.
  --since-version <spec>
                        Filter the versions walked by -A/--all to those
                        matching a PEP 440 specifier constraint (e.g.
                        '>=1.0,<2.0'). The constraint is evaluated against the
                        PEP 440 version parsed from each tag name. Tags that
                        do not parse as PEP 440 are skipped. Example: --since-
                        version '>=1.0,<2.0'
  --regex <pattern>     Regular-expression filter (Python re.search). When
                        supplied, only entries whose name, display-name,
                        description, or keywords match the pattern are
                        returned. The keywords field matches when any element
                        satisfies re.search. Mutually exclusive with the
                        positional <substring>. Use --match-fields to restrict
                        the fields checked. Example: --regex '^foo'
  --match-fields <csv>  Comma-separated list of fields to check when
                        filtering. Legal values: name, display-name,
                        description, keywords. Default (when --match-fields is
                        not supplied): all four fields. Requires the
                        positional <substring> or --regex to be present;
                        supplying --match-fields without a filter is a hard
                        error. Example: --match-fields keywords

Examples:
  kanon search --catalog-source https://example.com/org/repo.git@main
  kanon search foo --catalog-source https://example.com/org/repo.git@main
  kanon search --regex '^foo' --catalog-source ...
  kanon search foo --match-fields keywords --catalog-source ...
  kanon search --format json --catalog-source https://example.com/org/repo.git@main
  kanon search --format json -A --catalog-source ...
  kanon search --detail --catalog-source https://example.com/org/repo.git@main
  kanon search --tree --catalog-source https://example.com/org/repo.git@main
  kanon search --tree --max-depth 0 --catalog-source ...
  kanon search --tree --no-filter-required --catalog-source ...
  kanon search -A --catalog-source https://example.com/org/repo.git@main
  kanon search -A --limit 3 --catalog-source ...
  kanon search -A --no-limit --catalog-source ...
  kanon search -A --since-version '>=1.0,<2.0' --catalog-source ...
  KANON_CATALOG_SOURCES=https://example.com/org/repo.git@v1.0.0 kanon search
  KANON_LIST_FORMAT=json kanon search --catalog-source ...
