tan-cli 0.7.0__py3-none-any.whl

tan/core/image_bundle.py

@@ -0,0 +1,247 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Pure model + string builders for `tan image` -- port of
+`crates/tan-core/src/image_bundle.rs` plus the `path_guard::is_plain_relative`
+seam it depends on.
+
+The IO (tar/gzip/sha256/copy/mkdir) lives in `tan.commands.image_cmd`; every
+*decision* that does not touch the filesystem is here so it stays unit-testable:
+the bundle-manifest shape + key order, the OS-independent forward-slash artefact
+paths, and the ok-slice gate.
+
+Two deliberate contract fixes carried over from the Rust:
+  - the helper entry carries `chip` (the real schema field) instead of the
+    perpetually-`null` `role` the retired Python emitted;
+  - artefact paths are built as forward-slash STRINGS, never from a `Path`, so
+    the machine contract never leaks a Windows `\\` separator.
+"""
+
+from __future__ import annotations
+
+import ntpath
+import os
+import re
+from typing import Any
+
+#: Bundle-manifest `schema_version` (matches the system-manifest v1 line).
+BUNDLE_SCHEMA_VERSION = 1
+#: `generated_by` value -- tan-branded (the retired Python emitted `west alp-image`).
+GENERATED_BY = "tan image"
+#: Bundle root directory name, under the build root.
+BUNDLE_DIR = "image-bundle"
+#: Per-slice archive subdirectory name.
+SLICES_DIR = "slices"
+#: Helper-MCU firmware subdirectory name.
+HELPERS_DIR = "helper-mcus"
+#: Output bundle-manifest filename.
+BUNDLE_MANIFEST = "bundle-manifest.json"
+
+#: The not-yet-built sentinel a SoM preset uses for a helper firmware that has no
+#: release yet. A legitimate state, so it is a warning, never a failure.
+PENDING_SENTINEL = "TBD"
+
+_SEPARATORS = re.compile(r"[/\\]")
+
+
+def is_plain_relative(path: str) -> bool:
+    """True when `path` is safe to join onto a trusted base: relative, and built
+    only from ordinary names. Port of `tan_core::path_guard::is_plain_relative`.
+
+    `os.path.isabs()` is NOT this check, for the same reason `Path::is_absolute()`
+    is not: on Windows it is false for `/x`, `\\x` and `C:x`, none of which
+    contains a `..` either, yet every one of them makes `base / p` discard part
+    or all of `base`. An empty path and a bare `.` are rejected too: both make
+    `base / p` resolve to `base` itself, so a caller meaning "a file under base"
+    would act on base.
+
+    Platform-dependent exactly as `Path::components()` is: `C:foo` is a drive
+    prefix on Windows and an ordinary filename on POSIX.
+    """
+    if os.name == "nt":
+        drive, rest = os.path.splitdrive(path)
+        if drive:
+            return False  # Component::Prefix -- `C:`, `C:/`, `\\\\server\\share`
+        if rest[:1] in ("/", "\\"):
+            return False  # Component::RootDir -- `\\x` and `/x` both
+        parts = _SEPARATORS.split(rest)
+    else:
+        if path.startswith("/"):
+            return False  # Component::RootDir
+        parts = path.split("/")
+    parts = [p for p in parts if p != ""]  # repeated separators collapse
+    if not parts:
+        return False  # "" and "." and "/" all yield nothing usable
+    # `.` is normalized away EXCEPT at the start of the path, where it is a real
+    # `Component::CurDir` -- so `a/./b` passes and `./a` does not.
+    for index, part in enumerate(parts):
+        if part == "." and index > 0:
+            continue
+        if part in (".", ".."):
+            return False
+    return True
+
+
+def is_plain_filename(name: str) -> bool:
+    """True when `name` is safe to use as ONE filename component -- the check
+    [`slice_archive_name`] needs, which is strictly narrower than
+    [`is_plain_relative`].
+
+    `is_plain_relative` answers "is this a safe RELATIVE PATH", so it correctly
+    accepts nested shapes: `a/b` and `a/./b` are both plain relative paths. A
+    value that gets interpolated into a single filename may not contain a
+    separator at all -- `a/b` there means a `slices/a/` subdirectory that was
+    never created, not a filename.
+
+    Both separators AND a Windows drive prefix are rejected on BOTH platforms,
+    unlike `is_plain_relative`'s deliberately platform-dependent component scan.
+    The resulting string is not only a local filename: [`slice_artefact_rel`]
+    folds it into the machine contract in `bundle-manifest.json`, which is read
+    on whatever OS consumes the bundle, and a `\\` a Linux `tan image` treated
+    as an ordinary character is a separator to the Windows consumer that reads
+    it back.
+
+    The drive check is `ntpath.splitdrive`, run unconditionally, NOT
+    `os.path.splitdrive` behind an `os.name == "nt"` guard (tan-cli#499 defect 9
+    REVIEW). The guarded version applied the cross-OS rule above to the
+    separators and then abandoned it one line later: on POSIX,
+    `os.path.splitdrive` is `posixpath`'s, which never finds a drive, so a
+    `core_id` of `C:foo` was accepted and written to `bundle-manifest.json` as
+    `C:foo-zephyr.tar.gz` -- a drive-RELATIVE path to the Windows consumer that
+    reads the bundle back, which is precisely the hazard the separator rule is
+    stated to prevent. One rule, applied to every component of it.
+    """
+    if not name or name in (".", ".."):
+        return False
+    if _SEPARATORS.search(name):
+        return False
+    if ntpath.splitdrive(name)[0]:
+        return False  # `C:` / `C:foo` -- a drive prefix, not a name
+    return True
+
+
+def slice_archive_name(core_id: str, os_name: str) -> str | None:
+    """Archive filename for a slice: `<core_id>-<os>.tar.gz`.
+
+    `None` when `core_id`/`os` are not safe to fold into a filename that will be
+    joined onto the bundle's `slices/` dir. Both come straight off
+    system-manifest.yaml -- a deliberately tolerant reader, not a validator --
+    and this used to interpolate them unchecked: a `core_id` of
+    `../../../../home/u/x` or (Windows) `C:/x` escaped `image-bundle/slices/`
+    entirely, so the caller's unlink + create could clobber an arbitrary
+    `*.tar.gz` outside the build tree. The guard lives HERE, not at the call
+    site, because [`slice_artefact_rel`] needs the identical check for the
+    manifest's `artefact` string -- a per-call-site guard is how this class of
+    bug keeps recurring.
+
+    The check is [`is_plain_filename`], NOT `is_plain_relative` (tan-cli#499
+    defect 9): the path guard accepts a nested `a/b`, which produced
+    `slices/a/b-zephyr.tar.gz` in a directory nothing had created, so
+    `image_cmd._tar_gzip_dir` raised and the WHOLE `tan image` run aborted at
+    exit 3 with no `bundle-manifest.json` and already-tarred slices orphaned --
+    where the equally-invalid `../x` took the intended `image.slice-unsafe-name`
+    warning-skip and still produced a bundle. This is a deliberate divergence
+    from the frozen oracle, which shares the defect; `is_plain_relative` itself
+    is unchanged, so its own nested-path contract (`a/./b` is plain) still holds.
+    """
+    if not is_plain_filename(core_id) or not is_plain_filename(os_name):
+        return None
+    return f"{core_id}-{os_name}.tar.gz"
+
+
+def slice_artefact_rel(core_id: str, os_name: str) -> str | None:
+    """Forward-slash relative artefact path: `slices/<core_id>-<os>.tar.gz`.
+    `None` for the same unsafe shapes [`slice_archive_name`] rejects."""
+    name = slice_archive_name(core_id, os_name)
+    return None if name is None else f"{SLICES_DIR}/{name}"
+
+
+def helper_artefact_rel(basename: str) -> str:
+    """Forward-slash relative artefact path: `helper-mcus/<basename>`."""
+    return f"{HELPERS_DIR}/{basename}"
+
+
+def helper_firmware_candidates(
+    raw: str, build_root: str, sdk_root: str | None
+) -> list[tuple[str, str]]:
+    """Labeled `(root, absolute_candidate)` pairs for a helper's declared
+    `firmware_path`, in resolution order (alp-sdk#330).
+
+    alp-sdk's `som-preset-v2.schema.json` defines a relative `firmware_path` as
+    repository-relative -- relative to the SDK checkout, not to this project's
+    build tree. `build_root` is still tried FIRST, ahead of `sdk_root`,
+    mirroring the precedence `flash_plan.resolve_artefact_path` already
+    established for the identical two-roots ambiguity (tan-cli#301, #322): a
+    helper artefact the CURRENT build actually produced under `build/` is the
+    one this run just made, and must win over a same-named file the SDK
+    happens to ship. `sdk_root` is the fallback that lets a genuinely
+    SDK-shipped firmware (the common case) resolve at all -- build-root-only
+    resolution never could, which is the whole bug.
+
+    An absolute `raw` yields itself alone, unchanged: `sdk_root` never applies
+    to it (matches `system_manifest.anchor_under`'s own absolute passthrough).
+
+    Returned in full even when nothing resolves, so the caller can name every
+    root it tried and the absolute path each one produced (issue #330: the old
+    message named only the raw relative string, so the reporter had to go find
+    the file by hand to prove it existed).
+    """
+    if os.path.isabs(raw):
+        return [("absolute path", raw)]
+    candidates = [("build root", os.path.join(build_root, raw))]
+    if sdk_root is not None:
+        candidates.append(("sdk root", os.path.join(sdk_root, raw)))
+    return candidates
+
+
+def slice_should_bundle(status: Any) -> bool:
+    """A slice is bundled iff it built successfully (`status == "ok"`)."""
+    return status == "ok"
+
+
+def slice_entry(
+    core_id: str, os_name: str, artefact: str, sha256: str, size: int
+) -> dict[str, Any]:
+    """One bundled slice's manifest entry; key order IS the on-disk order."""
+    return {
+        "core_id": core_id,
+        "os": os_name,
+        "artefact": artefact,
+        "sha256": sha256,
+        "size": size,
+    }
+
+
+def helper_entry(
+    name: str | None, chip: str | None, artefact: str, sha256: str, size: int
+) -> dict[str, Any]:
+    """One bundled helper firmware's manifest entry. `name`/`chip` are `null`
+    only if the manifest omitted them -- and `chip`, not the retired Python's
+    always-`null` `role`, is the field."""
+    return {
+        "name": name,
+        "chip": chip,
+        "artefact": artefact,
+        "sha256": sha256,
+        "size": size,
+    }
+
+
+def assemble_bundle_manifest(
+    hw_info: dict,
+    boot_order: list,
+    slices: list[dict[str, Any]],
+    helper_mcus: list[dict[str, Any]],
+) -> dict[str, Any]:
+    """The written `bundle-manifest.json`, and the envelope's `data`. Insertion
+    order IS the key order: schema_version, generated_by, hw_info, slices,
+    helper_mcus, boot_order. Pure: no IO."""
+    return {
+        "schema_version": BUNDLE_SCHEMA_VERSION,
+        "generated_by": GENERATED_BY,
+        # Carried verbatim off the YAML so additive keys (`eeprom`, anything a
+        # newer SDK adds) survive into the bundle -- see
+        # `system_manifest.raw_passthrough`.
+        "hw_info": hw_info,
+        "slices": slices,
+        "helper_mcus": helper_mcus,
+        "boot_order": boot_order,
+    }

tan/core/inert.py

@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The one spelling of "tan accepts this option and does nothing with it"
+(tan-cli#886).
+
+`--help` marks an option inert in four structurally different situations, and
+until this module existed the difference lived only in free prose that varied
+per site: "Accepted by other commands; not implemented for `build` yet
+(tan-cli#427)", "Accepted for compatibility (tan-cli#290)", "(unused:
+faultdecode is HW-free)", "(unused; see below)". Four meanings, six spellings,
+two of which said nothing at all once the option was read out of its
+surrounding help block.
+
+**Why that is a defect and not a style nit.** `alp-sdk-vscode` records tan's
+whole option surface into a golden (`test/golden/tan-surface/surface.json`)
+and renders the inert ones for the customer. Only ONE of the four kinds will
+ever start acting; the other three are permanent by design. Telling someone
+"not implemented yet, see tan-cli#427" about `doctor --build` invites them to
+wait for a flag that is never going to act. With nothing structured to read,
+the consumer's only options were to pattern-match tan's prose -- fragile, and
+a condition pinned to one spelling is blind to the other five -- or to
+hand-maintain its own copy of a table tan already knows
+(alp-sdk-vscode#577 did the latter).
+
+**The marker.** Every inert option's help ends with a single whitespace-free
+token, `(inert:KIND)` or `(inert:KIND:REF)`:
+
+    --build       Accepted for compatibility: ... (inert:compatibility:tan-cli#290)
+    --project     Project root. Not read: ... (inert:not-applicable)
+
+`deferred` has no live instance to show, so this block cannot illustrate it.
+`--plan` filled the slot until tan-cli#427 RETIRED that flag, and
+`--no-auto-bootstrap` took it over until the same issue retired that one too.
+Measured on this tree with the census gate's own walk: 458 options, 120 marked
+-- parity 117, compatibility 1, not-applicable 2, deferred 0. (A hand-rolled
+walk reports 2: typer vendors click, so `isinstance(cmd, click.Group)` is
+False and the recursion never starts. Use `hasattr(cmd, "list_commands")`.)
+
+The kind stays in the closed vocabulary because it is the right marker the
+next time tan declares a flag it has not built yet. A RETIRED flag is NOT it
+and carries no marker at all: its value selects a real, distinct refusal
+rather than being accepted and dropped.
+
+Three properties of that shape are deliberate, and each rules out a rendering
+defect measured on the real `--help`:
+
+1. **Parentheses, not square brackets.** Typer runs this app with
+   `rich_markup_mode="rich"`, so help text is rich MARKUP: a `[inert:deferred]`
+   marker parses as a style tag and renders as *nothing at all* -- measured, the
+   whole token vanishes from `tan build --help`. `\\[` escapes it, but only
+   while the markup mode stays `rich`, so the escape is a second thing to keep
+   true. Parentheses need neither.
+2. **No whitespace inside the token.** Rich wraps help text at spaces. A
+   `(inert: deferred, ref: tan-cli#427)` marker splits across two lines in a
+   narrow terminal and a consumer's regex has to re-join them first; this one
+   cannot split.
+3. **The ref lives in the marker, not a second time in the prose.** The prose
+   the twelve `build` flags shared already ended `(tan-cli#427).`; keeping both
+   would be two places to keep true for one fact.
+
+**`deferred` is the only kind that requires a ref**, and `inert_help` refuses
+to render one without it. That requirement is the whole point of publishing
+the kind: `deferred` means "an upstream issue tracks its arrival", so a
+`deferred` marker naming no issue is a promise with nothing behind it. The
+permanent kinds MAY carry a ref (`compatibility` and `parity` both name the
+issue that explains the history) and a consumer must not read the presence of
+a ref as "this will arrive" -- the KIND is what says that, never the ref.
+"""
+from __future__ import annotations
+
+import re
+
+#: An upstream issue tracks this option's arrival: it is accepted now, it does
+#: nothing now, and it is expected to start acting. The ONLY kind that is not
+#: permanent, and the only one that requires a ref.
+DEFERRED = "deferred"
+
+#: Kept so an existing caller's command line keeps parsing, after the
+#: behaviour it used to select stopped being conditional. Permanent.
+COMPATIBILITY = "compatibility"
+
+#: Accepted only because a sibling surface accepts it -- the v0.4.1 oracle's
+#: clap `GlobalArgs` are `global = true`, so every verb parses all ten
+#: (tan-cli#261). Permanent; see `tan.core.global_flags`.
+PARITY = "parity"
+
+#: Structurally meaningless for THIS command -- there is no behaviour for it
+#: to select, no matter what tan implements later. Permanent.
+NOT_APPLICABLE = "not-applicable"
+
+#: The closed vocabulary. A consumer switches on exactly these; anything else
+#: is a tan bug, not a value to fall back on.
+INERT_KINDS: tuple[str, ...] = (DEFERRED, COMPATIBILITY, PARITY, NOT_APPLICABLE)
+
+#: The kinds that will never start acting. Stated as its own tuple rather than
+#: as "everything except DEFERRED" so adding a fifth kind forces a decision
+#: about which side it lands on instead of inheriting one.
+PERMANENT_KINDS: tuple[str, ...] = (COMPATIBILITY, PARITY, NOT_APPLICABLE)
+
+#: How the marker is read back OUT of rendered `--help` text -- published in
+#: `contract/README.md` for the extension, and used by this repo's own gate
+#: (`tests/gates/test_inert_option_markers.py`) so both sides read one regex.
+MARKER_RE = re.compile(r"\(inert:(?P<kind>[a-z-]+)(?::(?P<ref>[^)\s]+))?\)")
+
+#: The only ref spelling tan emits. `tan-cli#N` rather than a full URL: it is
+#: what every other cross-reference in this CLI's prose already uses, and it
+#: survives the line-wrapping rule above (a URL would not be shorter).
+REF_RE = re.compile(r"^tan-cli#[1-9][0-9]*$")
+
+
+def inert_help(prose: str, kind: str, ref: str | None = None) -> str:
+    """Render `prose` with the inert marker appended.
+
+    Raises `ValueError` -- at IMPORT time, since every call site is a
+    `typer.Option(...)` default evaluated when its module loads -- rather than
+    emitting a marker a consumer cannot switch on. A malformed marker that
+    only fails a test run would still have shipped in someone's branch;
+    failing the import fails the CLI itself.
+    """
+    if kind not in INERT_KINDS:
+        raise ValueError(
+            f"unknown inert kind {kind!r}; expected one of {', '.join(INERT_KINDS)}. "
+            "The vocabulary is closed on purpose -- a consumer switches on it "
+            "(tan-cli#886). Adding a kind means adding it to INERT_KINDS, to "
+            "PERMANENT_KINDS or not, and to contract/README.md."
+        )
+    if kind == DEFERRED and ref is None:
+        raise ValueError(
+            "a deferred option must name the issue tracking its arrival: "
+            "`deferred` is the one kind that promises the flag will start "
+            "acting, and a promise with no issue behind it is exactly what "
+            "tan-cli#886 asked to make impossible. Use a permanent kind "
+            f"({', '.join(PERMANENT_KINDS)}) if nothing tracks it."
+        )
+    if ref is not None and not REF_RE.match(ref):
+        raise ValueError(
+            f"inert ref {ref!r} is not of the form 'tan-cli#123'. One spelling "
+            "keeps the consumer's extraction regex (MARKER_RE) exact."
+        )
+    stripped = prose.strip()
+    if not stripped:
+        raise ValueError(
+            "inert help needs prose of its own: the marker says WHICH KIND of "
+            "inert, never what the option would have meant. An option whose "
+            "help is only a marker reads as nameless in `--help`."
+        )
+    marker = f"(inert:{kind})" if ref is None else f"(inert:{kind}:{ref})"
+    return f"{stripped} {marker}"

tan/core/jlink_binary.py

@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Where tan may take the J-Link Commander binary from (tan-cli#1336).
+
+Flow D spawns the J-Link tool with the user's privileges while a probe is
+attached, for the probe listing, the DPIDR preflight, the write and the
+read-back. The workspace `.venv` is part of the PROJECT -- a checkout can ship
+its own `.venv/bin/JLinkExe` -- so tan's "a west-capable venv is trusted"
+rule (right for `west`) must not reach this program. It is resolved ONLY from:
+
+1. an explicit `--jlink <path>` (a CLI input);
+2. the `TAN_JLINK` environment variable (an environment input);
+3. `PATH` as the user's own environment has it -- never with the project venv
+   prepended, and skipping any PATH entry that is a virtualenv bin directory inside the project
+   directory (an activated project `.venv/bin` is still the project's);
+4. a known SEGGER install root: `/opt/SEGGER/*`, `/Applications/SEGGER/*`,
+   `%ProgramFiles%` / `%ProgramFiles(x86)%` `\\SEGGER\\*`.
+
+Never a manifest field: `build/system-manifest.yaml` is regenerated from the
+checkout and is exactly the surface a hostile project controls.
+
+The ONE resolution is used by every J-Link spawn in a run, so the listing that
+verifies the probe, the preflight that verifies the board, the write and the
+read-back all execute the same binary, and the envelope reports it as
+`jlink.binary`.
+"""
+from __future__ import annotations
+
+import glob
+import os
+import sys
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from tan.core.tool_lookup import resolve_tool
+
+#: The binary identities, in preference order (same as `flash_plan._JLINK_BINARIES`).
+JLINK_NAMES = ("JLinkExe", "JLink")
+
+#: The environment override.
+ENV_OVERRIDE = "TAN_JLINK"
+
+
+@dataclass(frozen=True)
+class JlinkBinary:
+    """A resolved J-Link binary: absolute `path` and where it came from."""
+
+    path: str
+    source: str
+
+
+def _install_roots(env: Mapping[str, str], platform: str) -> list[str]:
+    roots: list[str] = []
+    if platform.startswith("win"):
+        for var in ("ProgramFiles", "ProgramFiles(x86)"):
+            base = env.get(var)
+            if base:
+                roots += sorted(glob.glob(os.path.join(base, "SEGGER", "JLink*")), reverse=True)
+    elif platform == "darwin":
+        roots += sorted(glob.glob("/Applications/SEGGER/JLink*"), reverse=True)
+    else:
+        roots += sorted(glob.glob("/opt/SEGGER/JLink*"), reverse=True)
+    return roots
+
+
+def _in_dir(directory: str, platform: str) -> str | None:
+    suffixes = ("", ".exe") if platform.startswith("win") else ("",)
+    for name in JLINK_NAMES:
+        for suffix in suffixes:
+            candidate = os.path.join(directory, name + suffix)
+            if os.path.isfile(candidate):
+                return candidate
+    return None
+
+
+def _inside(path: str, root: str) -> bool:
+    try:
+        real_path, real_root = os.path.realpath(path), os.path.realpath(root)
+        return os.path.commonpath([real_path, real_root]) == real_root
+    except (ValueError, OSError):
+        return False
+
+
+def _is_project_venv_bin(entry: str, project_dir: str) -> bool:
+    """A PATH entry that is a virtualenv `bin`/`Scripts` directory (its parent holds
+    `pyvenv.cfg`) living INSIDE the project directory."""
+    return _inside(entry, project_dir) and os.path.isfile(
+        os.path.join(os.path.dirname(os.path.realpath(entry)), "pyvenv.cfg")
+    )
+
+
+def _path_without_project(env: Mapping[str, str], project_dir: str | None) -> dict[str, str]:
+    """`env` with every PATH entry that is a project virtualenv's bin directory removed
+    -- an ACTIVATED project `.venv` on the user's PATH is still the project's, and the
+    whole point of tan-cli#1336 is that the project's venv never supplies this binary."""
+    path = env.get("PATH")
+    if not project_dir or not path:
+        return dict(env)
+    kept = [d for d in path.split(os.pathsep) if d and not _is_project_venv_bin(d, project_dir)]
+    return {**env, "PATH": os.pathsep.join(kept)}
+
+
+def resolve_jlink(
+    cli_path: str | None,
+    env: Mapping[str, str] | None = None,
+    *,
+    platform: str | None = None,
+    project_dir: str | None = None,
+) -> JlinkBinary | None:
+    """The J-Link binary tan may spawn, or `None` when none is found. An
+    explicit `cli_path` / `TAN_JLINK` that does not name an existing file
+    resolves to `None` rather than falling through: the operator named a
+    binary, and quietly using a different one is the thing this refuses."""
+    env = os.environ if env is None else env
+    platform = sys.platform if platform is None else platform
+    for value, source in ((cli_path, "the --jlink flag"), (env.get(ENV_OVERRIDE), f"{ENV_OVERRIDE}")):
+        if value:
+            path = os.path.abspath(value)
+            return JlinkBinary(path, source) if os.path.isfile(path) else None
+    path_env = _path_without_project(env, project_dir)
+    for name in JLINK_NAMES:
+        found = resolve_tool(name, path_env).resolved
+        if found:
+            return JlinkBinary(os.path.abspath(found), "PATH")
+    for root in _install_roots(env, platform):
+        found = _in_dir(root, platform)
+        if found:
+            return JlinkBinary(found, f"SEGGER install {root}")
+    return None