tan-cli 0.7.0__py3-none-any.whl

tan/commands/examples_cmd.py

@@ -0,0 +1,644 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`tan examples` -- the SDK's ready-made example projects, as a catalogue the
+New Project flow scaffolds from via `tan init --from-example <sourceDir>`.
+
+Mirrors `crates/tan-cli/src/commands/examples.rs` plus the two `tan-core`
+helpers it composes (`wizard/filesystem.rs::discover_examples`,
+`wizard/service/example_catalog.rs`). Kept in ONE module rather than split
+across a `tan.core` twin: the whole thing is a directory walk and two README
+scans, and a second file would only add an import.
+
+**Which rule decides where the catalogue comes from.** The example list is
+alp-sdk content, so the two candidate readings are "vendor a capture like
+`tan init` does" and "read the resolved checkout". This reads the checkout, on
+two invariants from
+`alp-sdk/docs/superpowers/specs/2026-07-29-tan-port-invariants.md`:
+
+* **I-32** bans *shelling* the SDK -- `tan init`/`tan scaffold` read a vendored
+  `--emit scaffold` tree "without ever shelling the SDK" because they must work
+  with NO checkout present at all. Nothing here spawns a subprocess; a
+  `read_dir` over `<sdk>/examples` is not a shell-out, so I-32 is untouched. Note
+  the anti-pattern it names (#22 in that doc) is *shelling* init instead of
+  reading the vendored tree -- not "reading a checkout".
+* **I-26** ("tan must never learn a hardware fact ... `metadata/**` stays in
+  alp-sdk") is what forbids the vendored alternative HERE. A baked example
+  catalogue is a copy of alp-sdk content that drifts from the customer's actual
+  checkout, and every `sourceDir` it hands back is a path
+  `tan init --from-example` then cannot find. `tan examples`' requirement is the
+  inverse of `tan init`'s: with no checkout resolvable the catalogue is
+  legitimately EMPTY (exit 0, `examples: []`), which is exactly what the Rust
+  oracle does -- so it has no reason to carry a capture.
+
+**One DELIBERATE divergence from the oracle** (tan-cli#400): an unresolvable
+checkout also emits an `examples.sdk-root-unresolved` warning, which
+`crates/tan-cli/src/commands/examples.rs` does not. That is a contract
+ADDITION, not a port regression -- the oracle's own renderer-only hint is the
+defect, and `crates/` ships to nobody (the release assets are PyInstaller
+freezes of `python/tan`). Do not "restore parity" by deleting it; nothing in
+`tests/parity/` pins this command's text or issues.
+
+**Every failure is an envelope, never a traceback.** Discovery swallows the IO
+errors the Rust swallows (an unreadable root or category is skipped, a README
+that will not read or is not UTF-8 is treated as absent -- `read_to_string().ok()`
+on the Rust side), and the catch-all in `examples` is the backstop for whatever
+nobody enumerated. There is no subprocess to time out: this command spawns
+nothing.
+
+No `--os`, no `--backend`, no SKU list, no hardware facts -- the catalogue is
+whatever directories carry a `board.yaml`, and nothing here reads one.
+
+**tan-cli#484** adds `category`/`som`/`board`/`cores`/`coreCount`/`osSet`/
+`declares` to each row, additively, when alp-sdk's generated
+`metadata/catalog.json` has an entry for that `sourceDir`
+(`tan.core.example_facets.load_example_facets`). That file is itself a
+pre-computed artefact of alp-sdk's topology resolver, so this still does not
+read a `board.yaml` or re-derive a hardware fact -- it reads one more
+generated JSON file, the same shape `tan.core.error_catalog` already reads
+`metadata/error-catalog.json` in.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+import typer
+
+from tan.core.example_facets import ExampleFacets, load_example_facets
+from tan.core.sdk_discovery import (
+    global_default_foreign_project_issue,
+    project_pin_issue,
+    resolve_sdk_root_wide,
+    sdk_ladder_divergence_issue,
+    with_sdk_search,
+)
+from tan.core.shapes import rejected_sdk_root_message
+from tan.core.global_flags import accept_global_flags
+from tan.envelope import Envelope, Issue, Project, SdkInfo, emit
+from tan.exit_codes import ExitCode
+from tan.output_format import FORMAT_HELP, OutputFormat
+
+#: `data.schemaVersion` for this command's payload.
+DATA_SCHEMA_VERSION = "1"
+
+#: First bytes that mark a README line as markdown STRUCTURE rather than prose.
+#: Verbatim from `is_readme_prose` (`wizard/service/example_catalog.rs`) --
+#: headings, blockquotes, HTML, links, badges, tables, list/rule markers, code.
+_NON_PROSE_PREFIXES = "#><[!|-*+=`"
+
+#: tan-cli#400: "no checkout resolved" is a DIAGNOSIS, not a shrug. Until this
+#: landed the condition existed only as a parenthetical question in the text
+#: renderer; the envelope carried `ok:true`, `examples: []`, `issues: []` --
+#: indistinguishable from a healthy SDK that genuinely ships no examples. The
+#: extension's picker therefore rendered an empty list with no error, no log
+#: line and no warning, and `tan init --from-example <sourceDir>` was
+#: unreachable with nothing pointing at the misconfigured root.
+#:
+#: Deliberately mirrors `presets_cmd.py`'s `SDK_UNRESOLVED_CODE` /
+#: `SDK_UNRESOLVED_MESSAGE` -- same `<command>.sdk-root-unresolved` spelling and
+#: same "condition, then what you got instead, then the remediation" shape that
+#: `presets`, `pinmux`, `build`, `generate`, `init`, `model` and `trace` all
+#: already use for this identical bad path. `reserved`, not `frozen`, in
+#: `contract/issue-codes.json`: no consumer matches it with `===` yet.
+SDK_UNRESOLVED_CODE = "examples.sdk-root-unresolved"
+SDK_UNRESOLVED_MESSAGE = (
+    "alp-sdk root is unresolved. Returning an empty example catalogue; "
+    "pass --sdk-root <path> to name the checkout."
+)
+
+#: What the reader GOT instead, for the `--sdk-root`-was-given-and-rejected
+#: branch (`tan.core.shapes.rejected_sdk_root_message`, tan-cli#497). The remediation
+#: clause above is dropped there: recommending the flag the caller just typed
+#: is what made the old message self-defeating.
+SDK_UNRESOLVED_CONSEQUENCE = "Returning an empty example catalogue."
+
+
+@dataclass(frozen=True)
+class Example:
+    """One catalogue entry. `id`/`sourceDir`/`title`/`description` are the
+    emitted JSON order the frozen oracle also uses, matching `ExampleEntry`'s
+    declaration order in `examples.rs`. `facets` (tan-cli#484) is an ADDITIVE
+    Python-only extension the oracle never carried -- when
+    `metadata/catalog.json` has an entry for this `sourceDir`, its fields are
+    appended after the original four, in the order alp-sdk's own issue
+    illustrated: `category`, `som`, `board`, `cores`, `coreCount`, `osSet`,
+    `declares`. `facets is None` (an older SDK, or an example the catalogue
+    does not know about yet) reproduces the pre-#484 four-key wire shape
+    exactly -- no existing reader breaks."""
+
+    id: str
+    source_dir: str
+    title: str
+    description: str
+    facets: ExampleFacets | None = None
+
+    def as_dict(self) -> dict[str, object]:
+        out: dict[str, object] = {
+            "id": self.id,
+            "sourceDir": self.source_dir,
+            "title": self.title,
+            "description": self.description,
+        }
+        facets = self.facets
+        if facets is not None:
+            out["category"] = facets.category
+            if facets.som is not None:
+                out["som"] = facets.som
+            if facets.board is not None:
+                out["board"] = facets.board
+            if facets.cores is not None:
+                out["cores"] = [dict(core) for core in facets.cores]
+            if facets.core_count is not None:
+                out["coreCount"] = facets.core_count
+            if facets.os_set is not None:
+                out["osSet"] = list(facets.os_set)
+            if facets.declares is not None:
+                out["declares"] = dict(facets.declares)
+        return out
+
+
+# ---------------------------------------------------------------------------
+# Discovery
+# ---------------------------------------------------------------------------
+
+
+def _read_readme(example_dir: Path) -> str | None:
+    """A `README.md`'s text, or `None` when there is not a usable one.
+
+    Missing, unreadable, and non-UTF-8 all collapse to `None`, matching Rust's
+    `std::fs::read_to_string(...).ok()`. `encoding="utf-8"` is explicit (I-27):
+    the default would decode with the host locale, so a README carrying a `⚠️`
+    -- alp-sdk already ships several -- raises `UnicodeDecodeError` on a cp1252
+    Windows host and passes on ubuntu CI.
+    """
+    try:
+        return (example_dir / "README.md").read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError, ValueError):
+        return None
+
+
+def _subdirectories(root: Path) -> list[Path]:
+    """`root`'s immediate subdirectories, or `[]` when it will not read.
+
+    `follow_symlinks=False` deliberately: Rust's `DirEntry::file_type()` does
+    not traverse a symlink, so a symlinked example directory is not a directory
+    to the oracle and is skipped. (The `board.yaml` probe below DOES follow, as
+    `Path::is_file()` does.) Order is not relied on -- results are sorted.
+    """
+    try:
+        with os.scandir(root) as entries:
+            return [
+                Path(entry.path)
+                for entry in entries
+                if _is_dir_no_follow(entry)
+            ]
+    except OSError:
+        return []
+
+
+def _is_dir_no_follow(entry: os.DirEntry) -> bool:
+    try:
+        return entry.is_dir(follow_symlinks=False)
+    except OSError:
+        return False
+
+
+def discover_examples(
+    examples_root: Path,
+    facets_by_source_dir: dict[str, ExampleFacets] | None = None,
+) -> list[Example]:
+    """Scan `<sdk>/examples` exactly two levels deep for `<category>/<name>`
+    directories carrying a `board.yaml`, sorted by source dir.
+
+    A missing or unreadable root is an EMPTY list, never an error: "no SDK" and
+    "no examples" are the same renderable answer, and `tan examples` returning
+    exit 0 with `examples: []` is what lets the New Project flow say "no
+    examples available" instead of showing a failure.
+
+    `facets_by_source_dir` (tan-cli#484, `tan.core.example_facets`) is looked
+    up by the SAME `source_dir` this function derives -- a directory this walk
+    finds but the catalogue does not know about (a newer example than the
+    checkout's committed `metadata/catalog.json`) simply gets no facets, same
+    as an omitted or unreadable catalogue; discovery is never gated on it.
+    """
+    facets_by_source_dir = facets_by_source_dir or {}
+    found: list[Example] = []
+    for category in _subdirectories(examples_root):
+        for project in _subdirectories(category):
+            try:
+                has_board = (project / "board.yaml").is_file()
+            except OSError:
+                has_board = False
+            if not has_board:
+                continue
+            # Always `/`-joined: `sourceDir` is handed straight back to
+            # `tan init --from-example`, and a Windows `\` there is not a path
+            # the SDK examples tree can be indexed by.
+            source_dir = f"{category.name}/{project.name}"
+            readme = _read_readme(project)
+            found.append(
+                Example(
+                    id=example_id_from_source_dir(source_dir),
+                    source_dir=source_dir,
+                    title=example_title_from_readme(readme, source_dir),
+                    description=example_description_from_readme(readme),
+                    facets=facets_by_source_dir.get(source_dir),
+                )
+            )
+    found.sort(key=lambda e: e.source_dir)
+    return found
+
+
+# ---------------------------------------------------------------------------
+# README-derived metadata (pure)
+# ---------------------------------------------------------------------------
+
+
+def example_id_from_source_dir(source_dir: str) -> str:
+    """The source dir is already unique across the catalogue, so it doubles as
+    the id. Kept as a named function because `id == sourceDir` is a contract the
+    extension may not assume forever, not an accident to inline away."""
+    return source_dir
+
+
+def example_title_from_readme(readme: str | None, source_dir: str) -> str:
+    """The README's first markdown heading, else a title-cased leaf name."""
+    for line in (readme or "").splitlines():
+        trimmed = line.strip()
+        if trimmed.startswith("#"):
+            title = trimmed.lstrip("#").strip()
+            if title:
+                return title
+    return _title_case_leaf(source_dir)
+
+
+def example_description_from_readme(readme: str | None) -> str:
+    """The README's first prose line -- skipping blanks, headings, blockquotes,
+    badges/links, HTML, tables, list markers and rules. `""` when there is
+    none."""
+    for line in (readme or "").splitlines():
+        trimmed = line.strip()
+        if trimmed and trimmed[0] not in _NON_PROSE_PREFIXES:
+            return trimmed
+    return ""
+
+
+def _title_case_leaf(source_dir: str) -> str:
+    """`audio/i2s-tone` -> `I2s Tone`: split the leaf on `-`/`_`, upper-case each
+    word's first character only, and leave the rest of the word as found (so it
+    really is `I2s`, not `I2S` -- the fallback is deliberately dumb, a README
+    heading is how an example spells its own name)."""
+    leaf = source_dir.rsplit("/", 1)[-1]
+    words = [w for w in leaf.replace("_", "-").split("-") if w]
+    return " ".join(w[:1].upper() + w[1:] for w in words)
+
+
+def strip_markdown_noise(text: str) -> str:
+    """Drop `![alt](url)` image/badge spans and `**` emphasis markers.
+
+    TEXT MODE ONLY -- `data.examples[]` keeps the raw README-derived value, so
+    the JSON a consumer parses is unaffected. A `![` with no closing `)` is not
+    markdown: keep it verbatim rather than eating the rest of the line.
+    """
+    out: list[str] = []
+    rest = text
+    while True:
+        start = rest.find("![")
+        if start == -1:
+            break
+        out.append(rest[:start])
+        end = rest.find(")", start)
+        if end == -1:
+            out.append(rest[start:])
+            rest = ""
+            break
+        rest = rest[end + 1 :]
+    out.append(rest)
+    return "".join(out).replace("**", "").strip()
+
+
+# ---------------------------------------------------------------------------
+# Filtering and text rendering
+# ---------------------------------------------------------------------------
+
+
+def example_matches_filter(entry: Example, needle: str) -> bool:
+    """Case-insensitive substring of `id` or `title`. Deliberately NOT
+    `sourceDir`/`description`: the former is the same string as `id`, the latter
+    is too free-form for a quick catalogue scan to key on."""
+    lowered = needle.lower()
+    return lowered in entry.id.lower() or lowered in entry.title.lower()
+
+
+def example_category(entry: Example) -> str:
+    """The example's top-level directory -- `ai` for `ai/cold-chain-monitor`.
+    Prefers the catalogue's `category` facet (tan-cli#484) when the bound
+    checkout's `metadata/catalog.json` carries one for this example -- the
+    same producer-wins fallback order `alp-sdk-vscode`'s own
+    `exampleCategory()` uses ("the day tan forwards a category that
+    disagrees with the directory, the producer is right") -- and falls back
+    to the id prefix only when no facet is present (an older SDK, or an
+    example the catalogue does not know about yet)."""
+    facets = entry.facets
+    if facets is not None:
+        return facets.category
+    return entry.id.split("/", 1)[0]
+
+
+def example_matches_category(entry: Example, category: str) -> bool:
+    return example_category(entry).lower() == category.lower()
+
+
+def render_examples_text(
+    examples: list[Example],
+    filter_: str | None,
+    category: str | None,
+    verbose: bool,
+    sdk_resolved: bool,
+) -> list[str]:
+    """One `id  title` line per example, `id` column aligned to the longest id in
+    THIS (possibly filtered) result set; `--verbose` appends the description.
+
+    Regression (tan-cli#164): this used to print only the count line, never the
+    entries `--from-example` needs a source dir from.
+
+    `sdk_resolved` splits the three ways an EMPTY result happens, which used to
+    collapse into one line that was wrong for two of them (tan-cli#400):
+
+    * **No checkout at all.** A headline only -- the diagnosis is the
+      `examples.sdk-root-unresolved` warning `examples()` prints straight after,
+      so the reason lives in exactly one place and reads the same in both output
+      modes. The filter branch is skipped HERE and not merely reordered: with no
+      catalogue to filter, `--filter blinky` used to answer `no example projects
+      match --filter "blinky".` and send the reader after a filter that had
+      nothing to do with it.
+    * **A checkout that ships no `examples/` tree.** Named as the checkout's own
+      answer. Byte-identical to the case above before this change, and the old
+      "is the alp-sdk checkout resolvable?" wording actively misdirected: it is,
+      and it has nothing.
+    * **A filter that matched nothing** -- unchanged, and now only reachable
+      when there really was a catalogue to filter.
+    """
+    if not examples:
+        if not sdk_resolved:
+            return ["examples: no example projects found."]
+        if filter_ is not None:
+            # `ensure_ascii=False` so a non-ASCII filter is echoed as typed,
+            # which is the closest one-liner to Rust's `{:?}` quoting.
+            return [
+                f"examples: no example projects match --filter "
+                f"{json.dumps(filter_, ensure_ascii=False)}."
+            ]
+        if category is not None:
+            return [
+                f"examples: no example projects in category "
+                f"{json.dumps(category, ensure_ascii=False)}."
+            ]
+        return ["examples: the resolved alp-sdk checkout ships no example projects."]
+    id_width = max(len(e.id) for e in examples)
+    lines = [f"examples: {len(examples)} example project(s) available"]
+    for e in examples:
+        line = f"  {strip_markdown_noise(e.id):<{id_width}}  {strip_markdown_noise(e.title)}"
+        if verbose:
+            description = strip_markdown_noise(e.description)
+            if description:
+                line += f"   -- {description}"
+        lines.append(line)
+    if filter_ is None and category is None:
+        categories = sorted({example_category(e) for e in examples})
+        lines.append("")
+        lines.append(f"categories: {' '.join(categories)}")
+        lines.append("narrow with --category <NAME>, or --filter <TEXT> to search.")
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class _ResolvedSdk:
+    """`_resolve_sdk`'s own return shape -- a named result, not a growing
+    tuple (the same reasoning `tan.core.sdk_discovery.SdkRootResolution` documents): a fact
+    one caller needs (`foreign_global_default_for`, tan-cli#464) must not
+    force every field before it to be re-counted by position.
+
+    `.path`/`.display` are `None` together, on the SAME two conditions
+    `SdkRootResolution.path` itself is `None` for: no `--sdk-root` and
+    nothing else resolved, or a rejected `--sdk-root` (tan-cli#900). Never a
+    bare `_resolve_sdk(...) is None` any more -- see that function's own
+    docstring for why."""
+
+    path: Path | None
+    display: str | None
+    tier: str
+    broken_project_pin: str | None = None
+    foreign_global_default_for: str | None = None
+
+
+def _resolve_sdk(sdk_root: str | None, workspace_root: Path) -> _ResolvedSdk:
+    """The resolved checkout as a [`_ResolvedSdk`] -- ALWAYS one, never a bare
+    `None` (tan-cli#900; the same fix tan-cli#468 made to
+    `presets_cmd.resolve_sdk`, applied here to this command's own WIDE ladder
+    instead of copying its narrow one). Collapsing to `None` the moment
+    nothing resolved is exactly what discarded `.broken_project_pin`/
+    `.foreign_global_default_for` on that path: a workspace whose
+    `.alp/sdk-path` names a checkout that no longer exists, with nothing else
+    resolvable, reported `examples.sdk-root-unresolved` alone -- the customer
+    was told the SDK could not be resolved but not that their own project pin
+    was the broken thing. Callers now check `.path is None`, the same
+    "unresolved" signal `SdkRootResolution.path` itself already carries.
+
+    `--sdk-root` is TERMINAL (I-31): a value that is not a real checkout
+    resolves to `.path is None` rather than falling through to discovery, so a
+    typo'd flag yields an empty catalogue instead of silently listing some
+    other checkout's examples.
+
+    `.display` is separate from `.path` because they are not interchangeable:
+    `Path("./sdk")` stringifies to `sdk`, dropping the `./` the caller typed,
+    while Rust records `--sdk-root` as-is -- and `sdk.root` is on the wire.
+
+    `.broken_project_pin` (tan-cli#263 review) is `None` on the `--sdk-root`
+    branch (nothing to fall through from), else whatever
+    `resolve_sdk_root_wide` carried through -- `examples()` turns it into the
+    shared `sdk.project-pin-unresolved` warning, unconditionally, whether or
+    not `.path` resolved. `.foreign_global_default_for` (tan-cli#464) is the
+    same carry-through for the `globalDefault` tier's own silence;
+    `examples()` turns it into `sdk.global-default-foreign-project`.
+    """
+    if sdk_root:
+        path = Path(sdk_root)
+        if (path / "scripts" / "alp_project.py").is_file():
+            return _ResolvedSdk(path, sdk_root, "sdkRootFlag")
+        return _ResolvedSdk(None, None, "sdkRootFlag")
+    # `.alp/sdk-path` project pin > the machine-global default
+    # (`~/.alp/sdk-default`) > the WIDE positional walk
+    # (`resolve_sdk_root_wide`) -- previously this went straight to the
+    # positional walk, silently ignoring `tan init`'s pin. Wide, not the narrow
+    # ladder thirteen other commands take: the oracle's `examples` lists the
+    # child `<ws>/alp-sdk`'s catalogue over a competing `../alp-sdk`'s
+    # (tan-cli#263). No `ALP_SDK_ROOT` tier (tried and reverted -- see
+    # `resolve_sdk_root_ladder`'s own docstring).
+    resolution = resolve_sdk_root_wide(None, workspace_root)
+    found = resolution.path
+    return _ResolvedSdk(
+        found,
+        str(found).replace("\\", "/") if found is not None else None,
+        resolution.tier,
+        resolution.broken_project_pin,
+        resolution.foreign_global_default_for,
+    )
+
+
+def examples(
+    filter_: str = typer.Option(
+        None, "--filter", metavar="TEXT", help="Only examples whose id or title contains TEXT."
+    ),
+    category: str = typer.Option(
+        None,
+        "--category",
+        metavar="NAME",
+        help="Only examples in this catalogue category (a bare `tan examples` "
+        "prints the list).",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", help="Append each example's description."),
+    project: str = typer.Option(
+        None, "--project", metavar="PATH", help="Project root (defaults to '.')."
+    ),
+    sdk_root: str = typer.Option(None, "--sdk-root", metavar="PATH", help="alp-sdk checkout root."),
+    output_format: OutputFormat = typer.Option(OutputFormat.TEXT, "--format", help=FORMAT_HELP),
+) -> None:
+    """List the SDK's ready-made example projects."""
+    json_mode = output_format == "json"
+
+    sdk: _ResolvedSdk | None = None
+    found: list[Example] = []
+    issues: list[Issue] = []
+    exit_code = ExitCode.SUCCESS
+    try:
+        # Unnormalised join, matching `cli_workspace_root` -- discovery probes
+        # this path's own parent, so collapsing a trailing `..` here would move
+        # which directory the sibling `alp-sdk` is looked for beside.
+        workspace_root = Path.cwd() / project if project else Path.cwd()
+        sdk = _resolve_sdk(sdk_root, workspace_root)
+        # tan-cli#900: computed unconditionally, BEFORE the `sdk.path is None`
+        # branch below -- `_resolve_sdk` always returns a `.broken_project_pin`/
+        # `.foreign_global_default_for` pair now, whether or not `.path`
+        # resolved, and a workspace pinned to a gone checkout with nothing
+        # else resolvable deserves the same disclosure a resolved run gets,
+        # not silence just because nothing happened to fall back to.
+        pin_issue = project_pin_issue(sdk.broken_project_pin, sdk.tier)
+        if pin_issue is not None:
+            issues.append(pin_issue)
+        # tan-cli#464: the catalogue this command just listed can come from
+        # a `globalDefault` pointer a DIFFERENT project's bootstrap
+        # relocation actually wrote -- the same silence `sdk.project-
+        # pin-unresolved` above closes one tier up.
+        foreign_issue = global_default_foreign_project_issue(sdk.foreign_global_default_for)
+        if foreign_issue is not None:
+            issues.append(foreign_issue)
+        if sdk.path is not None:
+            # tan-cli#484: an OPTIONAL enrichment pass, looked up by
+            # `sourceDir` -- `load_example_facets` never raises, so a
+            # checkout predating `metadata/catalog.json` (or one where it
+            # fails to parse) still lists every example exactly as before,
+            # just without the extra keys.
+            found = discover_examples(
+                sdk.path / "examples", load_example_facets(sdk.path)
+            )
+            # tan-cli#407: the catalogue this command just listed can come from
+            # a different checkout than `tan build` plans against, with both
+            # envelopes reporting `sourceTier: "discovery"`. `sdk_root` is the
+            # RAW flag, not `sdk.display`'s resolved text -- naming a root
+            # explicitly puts both ladders on the same terminal tier, and the
+            # helper returns `None` there rather than warning about a collision
+            # the user never reached.
+            divergence = sdk_ladder_divergence_issue(sdk_root, workspace_root, wide=True)
+            if divergence is not None:
+                issues.append(divergence)
+        else:
+            # tan-cli#400. NOT an error: `examples: []` from no checkout is a
+            # renderable answer the New Project flow is built on, so this stays
+            # `warning`/`ExitCode.SUCCESS` and the `examples-catalog` golden's
+            # `ok:true` at rc 0 is untouched. What changes is that the empty
+            # catalogue now carries a REASON. Its presence is also the JSON-side
+            # discriminator between the two empty answers -- a checkout that
+            # resolves and ships no `examples/` tree emits no issue at all,
+            # because that is not a misconfiguration to warn anybody about.
+            # tan-cli#497 defect 7: when `--sdk-root` WAS given and rejected,
+            # name the value. `SDK_UNRESOLVED_MESSAGE`'s remediation is "pass
+            # --sdk-root <path>" -- the flag they just passed -- and the failing
+            # path appeared nowhere in the envelope or the stderr text.
+            issues.append(
+                Issue(
+                    SDK_UNRESOLVED_CODE,
+                    "warning",
+                    rejected_sdk_root_message(sdk_root, SDK_UNRESOLVED_CONSEQUENCE)
+                    if sdk_root
+                    else with_sdk_search(SDK_UNRESOLVED_MESSAGE, workspace_root),
+                )
+            )
+        if filter_ is not None:
+            found = [e for e in found if example_matches_filter(e, filter_)]
+        if category is not None:
+            found = [e for e in found if example_matches_category(e, category)]
+    except Exception as err:  # noqa: BLE001 -- the backstop; see the module docstring
+        # No registry entry applies (`contract/issue-codes.json` covers
+        # `bootstrap.*`/`debug-config.*` only), so this follows the port's
+        # existing `<command>.internal-failure` spelling. Unreachable through
+        # any enumerated path -- every IO error above is already swallowed the
+        # way the oracle swallows it -- and here so that the one nobody thought
+        # of still arrives as an envelope instead of a traceback on stderr with
+        # an empty stdout the extension renders as nothing.
+        found = []
+        issues = [
+            Issue(
+                "examples.internal-failure",
+                "error",
+                f"examples failed unexpectedly: {err.__class__.__name__}: {err}",
+            )
+        ]
+        exit_code = ExitCode.INTERNAL_FAILURE
+
+    if json_mode:
+        emit(
+            Envelope(
+                "examples",
+                # Both null, always: the catalogue is an SDK-wide fact, so there
+                # is no project this answer belongs to. Pinned by
+                # `contract/envelopes/examples-catalog`.
+                Project(root=None, board_yaml=None),
+                {
+                    "schemaVersion": DATA_SCHEMA_VERSION,
+                    "examples": [e.as_dict() for e in found],
+                },
+                issues,
+                exit_code,
+                sdk=(
+                    SdkInfo.from_resolution(sdk.display, sdk)
+                    if sdk is not None and sdk.path is not None
+                    else None
+                ),
+            )
+        )
+    else:
+        resolved = sdk is not None and sdk.path is not None
+        for line in render_examples_text(found, filter_, category, verbose, resolved):
+            print(line, file=sys.stderr)
+        for issue in issues:
+            print(f"examples: {issue.message}", file=sys.stderr)
+    raise typer.Exit(int(exit_code))
+
+
+# tan-cli#261: adds the seven oracle `GlobalArgs` flags this command was
+# still missing (`--all`/`--board-yaml`/`--ci`/`--no-color`/
+# `--non-interactive`/`--quiet`/`--target`) on top of `--verbose`, already
+# declared and read above; see `tan.core.global_flags`. Every one of them is
+# genuinely inert for `examples` -- its envelope's `project` is always
+# `Project(root=None, board_yaml=None)`, an SDK-wide catalogue with no
+# project of its own to anchor a `--board-yaml`/`--target` on.
+examples = accept_global_flags(examples)