find - chirp-ui

Fuzzy component discovery over the shipped manifest —python -m chirp_ui find.

Sprint 6 of the agent-grounding-depth epic. The manifest is the registry projection; this module turns it into a one-liner for humans and agents who know what they want but not the exact BEM block name.

Search model

A component matches a query when the query is a case-insensitive substring of any of:

name — the manifest key, e.g. metric-card
block — the BEM block, e.g. metric-card(usually same as name)
category — e.g. data-display, feedback
description — the {#- chirp-ui: ... -#}doc-block text

Query filters (--categoryetc.) are applied AFTER substring match, so find --category=feedbacklists every component in that category even when no term is given.

Use--authoring=preferredto list the registry-blessed primitives agents should reach for first, or--authoring=compatibilityto audit legacy helpers retained for existing templates. Use--maturity=experimentalto inspect public surfaces still going through pre-1.0 stabilization, or--maturity=stableto list normal public vocabulary. Use--role=patternto inspect recipe-first or pattern-like surfaces without mixing them into primitive/component searches.

Output

Default output is one line per hit, stable/sorted::

{name:<30} {category:<16} {first-line-of-description}

Use--detailsto include the registry metadata agents need when choosing a surface: role, maturity, authoring, macro, template, runtime requirements, and slots.

Exit code0always (including zero hits) — this is discovery, not validation.

Seedocs/plans/PLAN-agent-grounding-depth.md § Sprint 6.

find

Name	Type	Default	Description
`type`		—
`qualified_name`		—
`element_type`		—
`description`		—
`source_file`		—
`line_number`		—
`is_autodoc`		—
`autodoc_element`		—
`_autodoc_template`		—
`_autodoc_url_path`		—
`_autodoc_page_type`		—
`title`		—
`doc_content_hash`		—

Symbols on this page

function components_by_authoring

Return manifest component entries with the given authoring hint.

This is the Python API twin ofpython -m chirp_ui find --authoring=.... It returns…

function preferred_components

Return components marked as preferred authoring vocabulary.

function compatibility_components

Return compatibility components retained for existing or narrow uses.

function components_by_maturity

Return manifest component entries with the given maturity label.

function components_by_role

Return manifest component entries with the given role label.

function search

Return(name, category, summary)rows sorted by name.

function detailed_search

Return detailed registry rows sorted by name.

function format_rows

Format rows as an aligned three-column table (no header).

function format_detailed_rows

Format detailed rows as an aligned table with a header.

function main

components_by_authoring

function

def components_by_authoring(authoring: str, *, manifest: Manifest | None = None, category: str | None = None) -> dict[str, ComponentEntry]

Return manifest component entries with the given authoring hint.

This is the Python API twin ofpython -m chirp_ui find --authoring=.... It returns a name-keyed dict in sorted order so downstream agents/tools can inspect full manifest entries without hand-filtering JSON.

Parameters

Name	Type	Default
`authoring`	`str`	—
`manifest`	`Manifest \| None`	`None`
`category`	`str \| None`	`None`

preferred_components

function

def preferred_components(*, manifest: Manifest | None = None, category: str | None = None) -> dict[str, ComponentEntry]

Return components marked as preferred authoring vocabulary.

Parameters

Name	Type	Default	Description
`manifest`	`Manifest \| None`	`None`
`category`	`str \| None`	`None`

compatibility_components

function

def compatibility_components(*, manifest: Manifest | None = None, category: str | None = None) -> dict[str, ComponentEntry]

Return compatibility components retained for existing or narrow uses.

Parameters

Name	Type	Default	Description
`manifest`	`Manifest \| None`	`None`
`category`	`str \| None`	`None`

components_by_maturity

function

def components_by_maturity(maturity: str, *, manifest: Manifest | None = None, category: str | None = None, authoring: str | None = None) -> dict[str, ComponentEntry]

Return manifest component entries with the given maturity label.

Parameters

Name	Type	Default
`maturity`	`str`	—
`manifest`	`Manifest \| None`	`None`
`category`	`str \| None`	`None`
`authoring`	`str \| None`	`None`

components_by_role

function

def components_by_role(role: str, *, manifest: Manifest | None = None, category: str | None = None, maturity: str | None = None, authoring: str | None = None) -> dict[str, ComponentEntry]

Return manifest component entries with the given role label.

Parameters

Name	Type	Default
`role`	`str`	—
`manifest`	`Manifest \| None`	`None`
`category`	`str \| None`	`None`
`maturity`	`str \| None`	`None`
`authoring`	`str \| None`	`None`

function

def search(manifest: Manifest, query: str = '', *, category: str | None = None, authoring: str | None = None, maturity: str | None = None, role: str | None = None) -> list[SearchRow]

Return(name, category, summary)rows sorted by name.

Parameters

Name	Type	Default
`manifest`	`Manifest`	—
`query`	`str`	`''`
`category`	`str \| None`	`None`
`authoring`	`str \| None`	`None`
`maturity`	`str \| None`	`None`
`role`	`str \| None`	`None`

detailed_search

function

def detailed_search(manifest: Manifest, query: str = '', *, category: str | None = None, authoring: str | None = None, maturity: str | None = None, role: str | None = None) -> list[DetailedSearchRow]

Return detailed registry rows sorted by name.

Parameters

Name	Type	Default
`manifest`	`Manifest`	—
`query`	`str`	`''`
`category`	`str \| None`	`None`
`authoring`	`str \| None`	`None`
`maturity`	`str \| None`	`None`
`role`	`str \| None`	`None`

format_rows

function

def format_rows(rows: Iterable[SearchRow]) -> str

Format rows as an aligned three-column table (no header).

Parameters

Name	Type	Default	Description
`rows`	`Iterable[SearchRow]`	—

format_detailed_rows

function

def format_detailed_rows(rows: Iterable[DetailedSearchRow]) -> str

Format detailed rows as an aligned table with a header.

Parameters

Name	Type	Default	Description
`rows`	`Iterable[DetailedSearchRow]`	—

main

function

def main(argv: list[str] | None = None) -> int

Parameters

Name	Type	Default	Description
`argv`	`list[str] \| None`	`None`

View source · /home/runner/work/chirp-ui/chirp-ui/site/../src/chirp_ui/find.py:1