tan-cli 0.7.0__py3-none-any.whl

tan/core/setools_scratch.py

@@ -0,0 +1,243 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Per-run scratch overlay of an Alif SETOOLS install, the DEVICE-entry source
+and the ATOC report parser -- the side-effect-free half of the Flow D sign step
+(tan-cli#1325, tan-cli#1322, tan-cli#1318).
+
+**Why a scratch tree (tan-cli#1325).** `app-gen-toc` writes its inputs and
+outputs into the install it runs from: `build/images/`, `build/config/`,
+`build/AppTocPackage.bin`, an APPEND-mode `build/app-package-map.txt` and
+`build/logs/SBContent.log`. Running it inside the customer's shared install
+overwrote a package another user of that install (a raw bench recipe, another
+tan run, another slice) had left there. So every sign now runs in a private
+overlay and the shared install is only ever READ.
+
+**What the overlay is, measured against SETOOLS SE_FW_1.110.00.** The tool
+`chdir`s into one of its own subdirectories and then addresses the output tree
+as `../build/...` (its log line reads `Logging to ../build/logs/SBContent.log`),
+so a symlinked SUBDIRECTORY would resolve `..` back into the shared install and
+write there. Therefore:
+
+* every top-level FILE (the `app-gen-*`/`app-write-mram` executables,
+  `version.txt`, ...) is symlinked -- read-only and cwd-independent;
+* every top-level DIRECTORY is COPIED (`bin/`, `cert/`, `utils/`: ~2.5 MiB
+  measured -- the tool writes there, e.g. its logs), so its `..` is the scratch
+  root. The ONLY exceptions are an explicit read-only allowlist,
+  [`_LINK_DIRS`] (`alif/`: ~74 MiB of System Package images the signing step
+  does not read, so copying it per run would cost more than it isolates), and
+  `utils/key`, the signing keys, which are symlinked INTO the copied `utils/`
+  rather than duplicated into the temp directory (measured: `app-gen-toc` signs
+  correctly through the link and the shared install stays byte-identical);
+* `build/` is a FRESH real directory holding only what this one sign needs
+  (`config/`, `images/`, `logs/`), so `app-package-map.txt` is never shared
+  history and the post-sign report belongs to exactly this run.
+
+Where a symlink cannot be created (Windows without the privilege) the file is
+copied instead.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import tempfile
+from dataclasses import dataclass
+
+from tan.core.flash_plan import FlashPlanError
+
+#: Top-level directories that are symlinked, not copied: read-only to the sign
+#: step (see the module docstring). Everything else is copied.
+_LINK_DIRS = frozenset({"alif"})
+
+#: Directory, relative to the install root, whose contents are key material:
+#: linked into the copy instead of duplicated.
+_KEY_DIR = os.path.join("utils", "key")
+
+#: The stock device configuration SETOOLS ships, relative to the install root.
+STOCK_DEVICE_CONFIG_REL = os.path.join("build", "config", "app-device-config.json")
+
+#: The DEVICE entry's `version` in the bench recipe
+#: (alp-sdk `scripts/bench/aen/flash-run.sh`).
+DEVICE_ENTRY_VERSION = "0.5.00"
+
+#: Registered issue code (`contract/issue-codes.json`) for the refusal below.
+DEVICE_CONFIG_MISSING_CODE = "flash.device-config-missing"
+
+_DEVICE_BASENAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+class DeviceConfigMissingError(FlashPlanError):
+    """No device configuration could be found for the DEVICE ATOC entry.
+    `code` is the registered issue code `tan flash` reports for it."""
+
+    code = DEVICE_CONFIG_MISSING_CODE
+
+
+@dataclass(frozen=True)
+class DeviceConfig:
+    """The resolved DEVICE-entry source: an absolute `path` (read-only), a human
+    `source` naming where it came from, and the `metadata.device` the file itself
+    declares (`None` when it does not parse)."""
+
+    path: str
+    source: str
+    metadata_device: str | None = None
+
+    @property
+    def name(self) -> str:
+        return os.path.basename(self.path)
+
+
+def read_metadata_device(path: str) -> str | None:
+    """`metadata.device` out of a device-config JSON, or `None`."""
+    try:
+        with open(path, encoding="utf-8") as fh:
+            doc = json.load(fh)
+        device = doc["metadata"]["device"]
+    except (OSError, ValueError, KeyError, TypeError):
+        return None
+    return device if isinstance(device, str) else None
+
+
+def family_mismatch(metadata_device: str | None, flash_device: str | None) -> str | None:
+    """A warning when the device configuration was written for a different Alif
+    family than `flash_device` (the J-Link part profile): the part numbers share
+    their first three characters within a family (`AE8...` Ensemble E8). `None`
+    when they agree or either is unknown."""
+    if not metadata_device or not flash_device:
+        return None
+    if metadata_device[:3].upper() == flash_device[:3].upper():
+        return None
+    return (
+        f"the device configuration declares device '{metadata_device}' but this slice's J-Link "
+        f"part profile is '{flash_device}' -- a different Alif family. The DEVICE entry carries "
+        "firewall, clock and boot settings. This is a warning, not a refusal: the metadata may be "
+        "stale (the stock SETOOLS file declares an E7 part, yet its compiled blob is byte-identical "
+        "to the E8 board's original DEVICE entry). Confirm it is the right file (it is the stock "
+        "SETOOLS config unless flash_args.setools_device_config names another)."
+    )
+
+
+def resolve_device_config(
+    explicit: str | None, setools_dir: str, *, entry_id: str
+) -> DeviceConfig:
+    """`flash_args.setools_device_config` (already resolved to an absolute path
+    by the caller) when set -- refusing, never falling through to the stock
+    file, if it does not exist -- else SETOOLS' own stock
+    `build/config/app-device-config.json`. Refuses with
+    [`DeviceConfigMissingError`] when neither exists: the DEVICE entry carries the
+    firewall/clock/boot configuration a table-replacing ATOC write would
+    otherwise delete (tan-cli#1322), so dropping it silently is not an option.
+    `--no-device-config` never reaches here."""
+    if explicit:
+        if not os.path.isfile(explicit):
+            raise DeviceConfigMissingError(
+                f"alif_mram_jlink[{entry_id}]: flash_args.setools_device_config is "
+                f"'{explicit}' but no such file exists -- the DEVICE entry's source "
+                "is never silently swapped for the stock config. Fix the path, or "
+                "pass --no-device-config to sign an app-only ATOC (a table-replacing "
+                "write then deletes the resident DEVICE entry)."
+            )
+        config = DeviceConfig(explicit, "flash_args.setools_device_config")
+    else:
+        stock = os.path.join(setools_dir, STOCK_DEVICE_CONFIG_REL)
+        if not os.path.isfile(stock):
+            raise DeviceConfigMissingError(
+                f"alif_mram_jlink[{entry_id}]: no device configuration for the DEVICE "
+                f"ATOC entry -- flash_args.setools_device_config is unset and SETOOLS "
+                f"ships no '{stock}'. The ATOC write REPLACES the whole table, so a "
+                "missing DEVICE entry deletes the resident one (firewall regions, HFXO "
+                "trims, SE_BOOT_INFO). Point flash_args.setools_device_config at an "
+                "Alif device-config JSON, or pass --no-device-config to knowingly sign "
+                "an app-only ATOC."
+            )
+        config = DeviceConfig(stock, "the stock SETOOLS build/config/app-device-config.json")
+    config = DeviceConfig(config.path, config.source, read_metadata_device(config.path))
+    if _DEVICE_BASENAME_RE.match(config.name) is None:
+        raise DeviceConfigMissingError(
+            f"alif_mram_jlink[{entry_id}]: the device configuration file name "
+            f"'{config.name}' is not a plain file name (letters, digits, '.', '_', '-')"
+        )
+    return config
+
+
+def _link_or_copy(src: str, dst: str) -> None:
+    try:
+        os.symlink(src, dst, target_is_directory=os.path.isdir(src))
+    except (OSError, NotImplementedError):
+        if os.path.isdir(src):
+            shutil.copytree(src, dst, symlinks=True)
+        else:
+            shutil.copy2(src, dst)
+
+
+def make_scratch(setools_dir: str, parent: str | None = None) -> str:
+    """Create a private overlay of `setools_dir` (see the module docstring) and
+    return its root. The shared install is only read. Raises `OSError` on a
+    filesystem failure; the half-built directory is removed first."""
+    root = tempfile.mkdtemp(prefix="tan-setools-", dir=parent)
+    try:
+        shared_key = os.path.join(setools_dir, _KEY_DIR)
+        key_abs = os.path.abspath(shared_key)
+
+        def _skip_keys(directory: str, names: list[str]) -> list[str]:
+            # The signing keys are never copied: a kill between a copy and its removal would
+            # leave them in the temp directory (tan-cli#1485). They are linked in below.
+            return [n for n in names if os.path.abspath(os.path.join(directory, n)) == key_abs]
+
+        for entry in os.scandir(setools_dir):
+            if entry.name == "build":
+                continue
+            dst = os.path.join(root, entry.name)
+            if entry.is_dir(follow_symlinks=False) and entry.name not in _LINK_DIRS:
+                shutil.copytree(entry.path, dst, symlinks=True, ignore=_skip_keys)
+            else:
+                _link_or_copy(entry.path, dst)
+        scratch_utils = os.path.dirname(os.path.join(root, _KEY_DIR))
+        if os.path.isdir(shared_key) and os.path.isdir(scratch_utils):
+            _link_or_copy(shared_key, os.path.join(root, _KEY_DIR))
+        for sub in ("config", "images", "logs"):
+            os.makedirs(os.path.join(root, "build", sub))
+    except BaseException:
+        shutil.rmtree(root, ignore_errors=True)
+        raise
+    return root
+
+
+def cleanup_scratch(path: str | None) -> bool:
+    """Remove a scratch overlay made by [`make_scratch`] -- ONLY the overlay:
+    symlinks are unlinked, never followed. `True` when nothing is left."""
+    if not path:
+        return True
+    shutil.rmtree(path, ignore_errors=True)
+    return not os.path.exists(path)
+
+
+# ── the ATOC report ─────────────────────────────────────────────────────────
+
+_TOC_ENTRY_RE = re.compile(
+    r"APP TOC entry for\s+(\S+)\s+obj_address\s+(0x[0-9A-Fa-f]+)"
+)
+_PACKAGE_SIZE_RE = re.compile(r"APP Package total size:\s*(\d+)\s*bytes")
+
+
+@dataclass(frozen=True)
+class AtocReport:
+    """What `app-package-map.txt` says about the package this run built:
+    `entries` are `(name, obj_address)` per `APP TOC entry for` line (empty for
+    a report that carries none), `package_size` the reported total in bytes."""
+
+    entries: tuple[tuple[str, str], ...] = ()
+    package_size: int | None = None
+
+
+def parse_atoc_report(text: str) -> AtocReport:
+    """Parse the entry list and total size out of an `app-package-map.txt`. The
+    scratch report is fresh (one block), so every match belongs to this run."""
+    # `app-gen-toc` pads the name field with NULs ("DEVICE\x00\x00"); they are not
+    # part of the name (bench round 6).
+    entries = tuple(
+        (m.group(1).replace("\x00", ""), m.group(2)) for m in _TOC_ENTRY_RE.finditer(text)
+    )
+    sizes = _PACKAGE_SIZE_RE.findall(text)
+    return AtocReport(entries=entries, package_size=int(sizes[-1]) if sizes else None)

tan/core/shapes.py

@@ -0,0 +1,194 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Two questions four command modules each answered with their own private
+copy: "is this directory an alp-sdk checkout?" and "what shape is this YAML
+value?" (tan-cli#408).
+
+Neither is domain logic worth four implementations. `_is_sdk_root` had two
+(`build_cmd.py`, `flash_cmd.py`) and `_yaml_kind` two
+(`diff_cmd.py`, `pinmux_cmd.py`), and the copies had already drifted in TYPE
+-- one took `str`, one took `Path` -- which is exactly how a "same" helper
+stops being the same one.
+
+Lives under `tan.core` rather than beside any one caller because
+`tan/commands/*` import each other freely and `build_cmd` already imports
+`sdk_cmd` at module level; a shared helper hosted in either would be a new
+edge in that graph. `tan.core` imports no command module, so this direction
+cannot cycle.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+#: THE marker for an alp-sdk checkout (I-31), as path segments so callers can
+#: join it either way. THE single spelling: `build_cmd` and, since
+#: tan-cli#815, `sdk_cmd` both re-export this one rather than holding a
+#: literal of their own. Relocating `scripts/alp_project.py` is a one-line
+#: change here, which is the whole point -- a second literal meant missing it
+#: silently broke SDK resolution in five commands.
+SDK_MARKER = ("scripts", "alp_project.py")
+
+
+def is_sdk_root(path: Path | str) -> bool:
+    """Whether `path` is an alp-sdk checkout -- port of `util.rs::
+    has_loader_script`, and INCAPABLE OF RAISING.
+
+    Accepts `Path` or `str` because the copies this replaces disagreed:
+    `build_cmd`'s took a `Path`, `flash_cmd`'s took a `str`. Callers keep
+    whichever they already hold rather than converting at
+    every site.
+
+    tan-cli#408 asks for a deliberate decision on the `except (OSError,
+    ValueError)` guard the string-based copy carried, so: **it stays**,
+    and the reason is that this is a PRE-FLIGHT guard. Every caller is asking
+    "may I use this?" in a command whose whole job is to answer with an
+    envelope; a path with an embedded NUL or an unreadable parent must read
+    as "not an SDK root", never as a traceback where a refusal belongs.
+
+    Measured on this tree's interpreter (CPython 3.14.6), both
+    `Path.is_file()` and `os.path.isfile()` already return `False` rather
+    than raising on an embedded NUL, so the guard catches nothing there
+    today. It is kept anyway: `requires-python = ">=3.12"`, the floor was not
+    measured here, and a guard that costs one `try` is not worth trading for
+    an assumption about an interpreter nobody ran.
+    """
+    try:
+        return os.path.isfile(os.path.join(str(path), *SDK_MARKER))
+    except (OSError, ValueError):
+        return False
+
+
+def is_file(path: Path | str) -> bool:
+    """`os.path.isfile`, INCAPABLE OF RAISING -- the same pre-flight contract
+    `is_sdk_root` above documents at length.
+
+    Four private copies preceded this one (tan-cli#815): `size_cmd`,
+    `image_cmd` and `flash_cmd` each held a byte-identical `str` version, and
+    `bootstrap_cmd`'s took a `Path` -- the TYPE drift this module's docstring
+    was written about, so the signature is `Path | str` for the same reason
+    `is_sdk_root`'s is: callers keep whichever they already hold.
+
+    Its narrower `except OSError` (the others caught `(OSError, ValueError)`)
+    was INERT: `pathlib` catches `ValueError` inside `Path.is_file()`, so
+    there was nothing to miss. Measured, not assumed -- an earlier draft of
+    tan-cli#815 called that half a behaviour change and it was not. The type
+    change does move one input: `Path('')` normalises to `Path('.')`, so the
+    old `_is_dir("")` answered `True` where this answers `False`. Unreachable
+    from its call sites, every one of which passes a join.
+
+    All three `str` callers read `build/system-manifest.yaml`, whose values
+    are manifest-supplied strings that may carry an embedded NUL or an
+    overlong component. Such a path is "not a file", never an exception
+    escaping the envelope.
+    """
+    try:
+        return os.path.isfile(path)
+    except (OSError, ValueError):
+        return False
+
+
+def is_dir(path: Path | str) -> bool:
+    """`os.path.isdir`, INCAPABLE OF RAISING -- `is_file`'s sibling, same
+    contract and same two prior copies (`image_cmd` took `str` and caught
+    `(OSError, ValueError)`, `bootstrap_cmd` took `Path` and caught `OSError`).
+
+    NOT the same question as `presets_cmd._is_dir` or
+    `examples_cmd._is_dir_no_follow`, which take an `os.DirEntry` and differ
+    on whether symlinks are followed. Those are a different predicate with a
+    deliberate divergence recorded at each site; they are not copies of this
+    and must not be folded into it.
+    """
+    try:
+        return os.path.isdir(path)
+    except (OSError, ValueError):
+        return False
+
+
+def matches_glob_suffix(name: str, *suffixes: str) -> bool:
+    """True if @name ends in any of @suffixes -- case-SENSITIVELY on POSIX,
+    case-INSENSITIVELY on Windows, matching `Path.glob`'s own
+    `case_sensitive=None` default (platform casing rules) exactly.
+
+    THE one spelling of the casing rule every `Path.glob("*.<ext>")` ->
+    `os.listdir`/`os.scandir` swap in this tree needs (tan-cli#1127 review
+    round 2, then tan-cli#1132). Swapping a glob for a listing plus a plain
+    `name.endswith(suffix)` silently NARROWS the match on Windows: a
+    `Foo.YAML` board file, or a `prj.CONF` Kconfig fragment, that `glob`
+    used to enumerate there becomes invisible, and nothing at the call site
+    announces the change. Three call sites share this one rule rather than
+    re-deriving it per swap -- `new_som_cmd._is_yaml_board_file`,
+    `commands/build/configure_inputs`'s fragment/overlay walk, and
+    `model/analyze._resolve_table`'s support-table listing.
+
+    @suffixes are case-folded here, so a caller may spell them either way;
+    what varies by platform is only whether @name is folded to match.
+    """
+    if os.name == "nt":
+        return name.lower().endswith(tuple(s.lower() for s in suffixes))
+    return name.endswith(suffixes)
+
+
+def rejected_sdk_root_message(sdk_root: str, consequence: str) -> str:
+    """The `<command>.sdk-root-unresolved` message for a `--sdk-root` the
+    loader-marker check REJECTED, naming the value the caller typed.
+
+    `--sdk-root` is TERMINAL (I-31), so a path without `scripts/alp_project.py`
+    resolves to nothing rather than falling through to a lower tier. Five
+    commands (`generate`, `model build`, `new-som`, `pinmux`, `validate`) still
+    dropped the rejected path on the floor, and four of those (all but
+    `pinmux`) answered with the SAME string they use when no flag was given at
+    all -- "Use --sdk-root, place the project near an alp-sdk checkout, ...",
+    i.e. recommending the flag the caller had just passed -- with the failing
+    value nowhere in the envelope and nowhere in the stderr text either.
+    `pinmux` used a message of its own with the same gap (tan-cli#497 defect
+    7). A user who typos `--sdk-root ~/alp-sdk-typo` was told to pass
+    `--sdk-root`, and could not see WHICH path had been rejected or why, on the
+    one surface that knew both.
+
+    `consequence` is the caller's own "and so this is what you got instead"
+    clause, because it differs per command (no pinmux table read, nothing
+    generated, nothing validated) and is the half a reader acts on. The
+    remediation clause is deliberately NOT carried into it: naming the rejected
+    path IS the remediation here.
+
+    The no-flag branch is deliberately left alone at every call site. There is
+    no typed value to name on it, and for `presets` its exact string is
+    byte-pinned by the `presets-no-sdk` golden envelope.
+
+    tan-cli#620 landed a same-named helper in `tan/commands/sdk_cmd.py` with
+    a byte-identical body, and the note here asking for the two to be
+    collapsed sat unexecuted for four releases (tan-cli#815). They are one
+    function now: `sdk_cmd` imports this one. The direction is the only one
+    that cannot cycle -- `tan.core` imports no command module (see the module
+    docstring).
+    """
+    marker = "/".join(SDK_MARKER)
+    return (
+        f'alp-sdk root is unresolved: --sdk-root "{sdk_root}" is not an alp-sdk '
+        f"checkout ({marker} not found under it). {consequence}"
+    )
+
+
+def yaml_kind(value: Any) -> str:
+    """A short YAML-ish type name for an error message -- not a claim of
+    matching serde's exact wording (see `diff_cmd`'s module docstring for the
+    scope note this inherits).
+
+    `bool` is tested BEFORE `int`, and that order is load-bearing rather than
+    stylistic: `bool` is a subclass of `int` in Python, so the reverse order
+    reports every `true`/`false` in a board.yaml as "a number".
+    """
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "a boolean"
+    if isinstance(value, (int, float)):
+        return "a number"
+    if isinstance(value, str):
+        return "a string"
+    if isinstance(value, list):
+        return "a sequence"
+    if isinstance(value, dict):
+        return "a mapping"
+    return type(value).__name__