tan-cli 0.7.0__py3-none-any.whl

tan/commands/build/host_python.py

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The `${PYTHON}` a `tan build` bakes into its slices (tan-cli#1317).
+
+Split out of `build_cmd._build`. The resolver itself is `tan.core.host_python`,
+shared with `tan doctor`'s `hostPython`; the FLOOR is doctor's own EFFECTIVE
+floor (`tan.core.python_floor.effective_python_floor`), never a second constant.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from tan.core import host_python
+from tan.core.plan_tokens import TOKEN_PYTHON
+from tan.core.python_floor import effective_python_floor, read_manifest_floors
+from tan.core.sdk_discovery import _planner_python_resolution
+from tan.core.venv import west_workspace_dir
+
+
+@dataclass(frozen=True)
+class BuildPython:
+    python: str
+    #: Why no interpreter qualified (`None` when one did / none was needed).
+    refusal: str | None
+    #: Cores whose pre-substitution command/env uses `${PYTHON}`.
+    users: frozenset[str]
+
+
+def _effective_floor(build_root: str, sdk_root: str | None) -> tuple[int, int]:
+    """Doctor's EFFECTIVE floor, via the shared pure `tan.core.python_floor`
+    (same inputs `tan doctor` feeds it: the resolved workspace's `zephyr/`,
+    else `$ZEPHYR_BASE`; the SDK manifest's two floors)."""
+    ws = west_workspace_dir(build_root, Path(sdk_root) if sdk_root else None)
+    zephyr_base = str(ws / "zephyr") if ws is not None else os.environ.get("ZEPHYR_BASE")
+    manifest_floor, zephyr_manifest_floor = read_manifest_floors(sdk_root)
+    return effective_python_floor(manifest_floor, zephyr_base, zephyr_manifest_floor)[0]
+
+
+def resolve_build_python(plan, plan_text: str, build_root: str, sdk_root: str | None) -> BuildPython:
+    fallback, used_venv = _planner_python_resolution(build_root, sdk_root)
+    users = frozenset(
+        sl.core_id
+        for sl in plan.slices
+        if TOKEN_PYTHON in f"{sl.command!r}{sl.env!r}{sl.env_append_path!r}"
+    )
+    needs = TOKEN_PYTHON in plan_text and not used_venv
+    floor = _effective_floor(build_root, sdk_root) if needs else (0, 0)
+    python, refusal = host_python.build_interpreter(
+        fallback if used_venv else None, fallback, needs, floor
+    )
+    return BuildPython(python, refusal, users)
+
+
+def refusal_message(refusal: str) -> str:
+    return (
+        refusal + " Install it and put it first on PATH, or run `tan bootstrap` "
+        "to create a workspace venv; `tan doctor` reports the same interpreter."
+    )

tan/commands/build/link_stale.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+"""tan-cli#1350: switching board.yaml `diagnostics.link: itcm` back to `auto`
+in an already-configured build dir must not keep linking at the ITCM.
+
+Zephyr resolves `EXTRA_DTC_OVERLAY_FILE` with `zephyr_get(... CACHE ...)`
+(`cmake/modules/configuration_files.cmake`): a `-DEXTRA_DTC_OVERLAY_FILE=...`
+from an earlier configure is stored in `CMakeCache.txt` and read back on every
+later configure that does not pass the variable itself. With the knob off the
+plan carries no `-DEXTRA_DTC_OVERLAY_FILE`, so the cached
+`<build>/alp-link-itcm.overlay` is still applied -- and the overlay file itself
+is still on disk from the earlier materialise -- and the image silently links
+at 0x0 with `ok: true`. (`EXTRA_CONF_FILE` is not affected: every plan re-passes
+it.)
+
+[`stale_itcm_overlay_reset`] is the fix, run before each Zephyr configure:
+when the slice's command does NOT carry the ITCM overlay, delete any leftover
+`alp-link-itcm.*` artefact and, if the cache still names the overlay, return
+`-UEXTRA_DTC_OVERLAY_FILE`. The WHOLE `EXTRA_DTC_OVERLAY_FILE` cache entry is
+unset when our overlay appears anywhere in it -- harmless, because tan never
+passes any other `EXTRA_DTC_OVERLAY_FILE`; an entry that never names our
+overlay is left alone.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from tan.envelope import Issue
+
+_OVERLAY = "alp-link-itcm.overlay"
+_ARTEFACT_GLOB = "alp-link-itcm.*"
+
+
+def stale_itcm_overlay_reset(cwd: Path, args: list[str]) -> tuple[list[str], list[Issue]]:
+    """`(extra_cmake_args, issues)` -- empty when nothing is stale or when the
+    slice IS itcm-targeted (its command names the overlay itself)."""
+    if any(_OVERLAY in a for a in args):
+        return [], []
+    removed: list[str] = []
+    for stale in sorted(Path(cwd).glob(_ARTEFACT_GLOB)):
+        try:
+            stale.unlink()
+            removed.append(stale.name)
+        except OSError:
+            pass  # best-effort; the -U below is what protects the link
+    try:
+        cache = (Path(cwd) / "build" / "CMakeCache.txt").read_text(
+            encoding="utf-8", errors="replace")
+    except OSError:
+        cache = ""
+    cached = any(
+        line.startswith("EXTRA_DTC_OVERLAY_FILE") and _OVERLAY in line
+        for line in cache.splitlines()
+    )
+    if not cached:
+        return [], []
+    note = (
+        "this slice is no longer linked for the ITCM (`diagnostics.link` is "
+        f"not `itcm`) but its cached configure still names {_OVERLAY}"
+        + (f"; removed stale {', '.join(removed)}" if removed else "")
+        + " -- unsetting EXTRA_DTC_OVERLAY_FILE so it links for MRAM again"
+    )
+    return ["-UEXTRA_DTC_OVERLAY_FILE"], [Issue("build.configure-cache-reset", "info", note)]
+
+
+def insert_after_separator(args: list[str], extra: list[str]) -> list[str]:
+    """`args` with `extra` placed immediately after the first `--` (before any
+    `-D`), or appended when there is no `--`. A `-U` placed before a `-D` of the
+    same cache key is applied first, so the later `-D` always survives."""
+    if not extra:
+        return list(args)
+    out = list(args)
+    try:
+        at = out.index("--") + 1
+    except ValueError:
+        at = len(out)
+    out[at:at] = extra
+    return out

tan/commands/build/manifest.py

@@ -0,0 +1,428 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Post-build output seam for `execute_slices`: write the `system-
+manifest.yaml` the downstream `tan run`/`tan flash`/`tan size`/`tan image`
+contract reads, and resolve the real on-disk `zephyr.elf` a slice produced.
+
+Port of `crates/tan-cli/src/commands/build/execute/manifest.rs`. What's
+ported: the post-build `write_post_build_manifest` seam and its two in-memory
+signals (`write_failed_reason` / `native_sim_target`), `resolve_zephyr_artefact`'s
+default-nested-build-dir artefact resolution, the SDK-identity stamp
+(`sdk_stamp_path`/`read_sdk_stamp`/`write_sdk_stamp`/`cmake_cache_configured`)
+the sdk-switch-pristine guard in `execute.py` reads and writes (issue #52),
+and (tan-cli#309) the Zephyr-boilerplate-loaded guard (tan-cli #97 upstream)
+[`zephyr_boilerplate_loaded`] -- `execute.py`'s status assembly applies it.
+
+**Why `sdk_root`/`board_yaml` stay ACCEPTED overrides here rather than always
+required.** The Rust oracle's `write_post_build_manifest` takes a
+`ProjectContext` its caller (`crates/tan-cli/src/commands/build/execute/mod.rs`)
+already resolved. This port's real caller, `tan.commands.build_cmd._dispatch` /
+`_build`, now threads its own already-resolved `--sdk-root` straight through
+(`execute_slices(..., sdk_root=sdk_root)` -> [`write_post_build_manifest`]) --
+mirroring the oracle's `ProjectContext` exactly. The fallback below (the plan's
+own `boardYaml` field plus [`tan.core.sdk_discovery.resolve_sdk_root_ladder`]'s
+full precedence chain) stays for any OTHER caller of `execute_slices` that
+passes no `sdk_root` at all (every test in this port's own suite does exactly
+that), so the write is never permanently unreachable just because a caller
+omitted the override.
+"""
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from tan.commands.build.materialise import MaterialiseError, confine_to_build_root
+from tan.core.sdk_discovery import resolve_sdk_root_ladder
+from tan.core.system_manifest import (
+    SliceRunResult,
+    SystemManifestError,
+    overlay_run_results_raw,
+    parse_system_manifest,
+    parse_system_manifest_raw,
+    serialize_system_manifest_raw,
+)
+
+__all__ = [
+    "PostBuildManifest",
+    "build_dir_overridden",
+    "cmake_cache_configured",
+    "read_sdk_stamp",
+    "resolve_zephyr_artefact",
+    "sdk_stamp_path",
+    "write_post_build_manifest",
+    "write_sdk_stamp",
+    "zephyr_boilerplate_loaded",
+]
+
+
+@dataclass(frozen=True)
+class PostBuildManifest:
+    """Outcome of [`write_post_build_manifest`] -- the two independent,
+    IN-MEMORY signals `tan run` decides host-vs-hardware and flash-safety
+    from (see `tan.core.run`'s module doc). Neither field is ever derived by
+    re-reading the on-disk file afterward. Port of `crates/tan-cli/.../
+    execute/manifest.rs::PostBuildManifest`."""
+
+    #: `None` when the on-disk file write succeeded; otherwise why it didn't.
+    #: Never flips the build's own exit code -- only gates `tan run --flash`.
+    write_failed_reason: str | None
+    #: Whether THIS run's freshly emitted SDK system-manifest projection
+    #: declares a `native_sim` slice -- independent of `write_failed_reason`
+    #: (the emit and the file write are separate steps; a write failure must
+    #: not erase a target the emit already established). `None` only when the
+    #: emit itself failed or didn't parse -- no signal at all, not "not
+    #: native_sim".
+    native_sim_target: bool | None
+
+
+def _native_sim_target_from_yaml(yaml_text: str) -> bool | None:
+    """Whether THIS run's freshly emitted system-manifest YAML declares a
+    `native_sim` slice. `None` only when `yaml_text` doesn't parse (no signal
+    at all); a manifest with no `native_sim` slice is `False`, not `None`.
+    Port of `crates/tan-cli/.../execute/manifest.rs::native_sim_target_from_yaml`."""
+    from tan.core.run import native_sim_slice  # local: avoids a core<->core cycle at import time
+
+    try:
+        manifest = parse_system_manifest(yaml_text)
+    except SystemManifestError:
+        return None
+    return native_sim_slice(manifest) is not None
+
+
+def write_post_build_manifest(
+    *,
+    sdk_root: str | None,
+    board_yaml: str | None,
+    base: str,
+    plan_build_root: str,
+    results: Sequence[SliceRunResult],
+    plain_route: tuple[str, str] | None = None,
+) -> PostBuildManifest:
+    """Write `<base>/<plan_build_root>/system-manifest.yaml` after a build:
+    fetch the plan-time projection from the SDK (`--emit system-manifest`),
+    overlay this run's per-slice status, serialize, and write. Best-effort --
+    a failure here never flips the build's own exit code (the slices already
+    ran; this is a post-build convenience write) -- but every failure branch
+    reports `write_failed_reason` rather than failing silently.
+
+    `native_sim_target` is derived from the SDK emit BEFORE the file write is
+    even attempted, so it survives a write failure intact -- this is what lets
+    `tan run` decide from THIS build's own outcome instead of a later disk
+    read. Port of `crates/tan-cli/.../execute/manifest.rs::write_post_build_manifest`.
+    """
+    try:
+        dest_dir = confine_to_build_root(Path(base), plan_build_root)
+    except MaterialiseError as err:
+        # KNOWN STRING DIVERGENCE (deliberate, not fixed): the oracle
+        # (`manifest.rs::write_post_build_manifest`) guards `plan.build_root`
+        # with the narrower `tan_core::is_plain_relative` shape check and
+        # reports `"unsafe build_root `{plan.build_root}`"` on failure. This
+        # port reuses `confine_to_build_root` -- the SAME resolve-and-contain
+        # guard `materialise_plan` and this module's own `execute.py` slice-
+        # cwd confinement already share -- which is a STRONGER check (it
+        # also catches drive-relative/rooted Windows shapes a syntactic
+        # `is_plain_relative` component scan would reject differently) but
+        # reports a different message: `"path `{rel}` would escape the build
+        # root `{root}`"`. No caller asserts the exact wording (verified:
+        # no test in this port's suite matches either string), so the
+        # divergence is recorded here rather than forking a third
+        # `plan_build_root`-only guard duplicating `confine_to_build_root`'s
+        # logic for a Minor, message-only difference.
+        return PostBuildManifest(write_failed_reason=err.message, native_sim_target=None)
+
+    effective_sdk_root = sdk_root
+    effective_board_yaml = board_yaml
+    if effective_sdk_root is None and effective_board_yaml:
+        # The FULL ladder (`--sdk-root` > project pin > global default >
+        # positional walk), not the positional walk alone: this fallback only
+        # fires for a caller of `execute_slices` that passed no `sdk_root`
+        # (every test in this port's own suite), and the positional walk
+        # alone would let the post-build manifest record a DIFFERENT SDK root
+        # than `resolve_sdk_root_ladder` resolved for the build itself the
+        # moment a project pin or machine-global default was in play.
+        # Imported at module level (tan-cli#408): `resolve_sdk_root_ladder`
+        # moved to `tan.core.sdk_discovery`, which `build_cmd.py` (and this
+        # module's own `tan.commands.build.execute` ancestor) no longer sit
+        # upstream of, so the import that used to be circular here is not
+        # any more.
+
+        # `_broken_pin` unused: this fallback only fires for a caller that
+        # passed no `sdk_root` at all (test-only, per the docstring above) --
+        # the real `tan build` path already resolved (and, since tan-cli#263
+        # review, already reported) the project pin at its own call site
+        # before ever reaching here, and `PostBuildManifest` has no issues
+        # channel to carry a second copy through.
+        discovered = resolve_sdk_root_ladder(None, Path(effective_board_yaml).parent).path
+        effective_sdk_root = str(discovered) if discovered else None
+
+    if effective_sdk_root is not None and not effective_board_yaml and plain_route is None:
+        # A build with no board.yaml has nothing to project the manifest from
+        # (the plain `tan build --board` route has its own writer, below).
+        return PostBuildManifest(
+            write_failed_reason="the plan has no board.yaml to project it from",
+            native_sim_target=None,
+        )
+
+    if effective_sdk_root is None or (not effective_board_yaml and plain_route is None):
+        return PostBuildManifest(
+            write_failed_reason=(
+                "no alp-sdk checkout resolved for the post-build system-manifest emit"
+            ),
+            native_sim_target=None,
+        )
+
+    # Refuse to BIND a root that is not an alp-sdk checkout. `_planner_emit`
+    # calls `bind_sdk_root(root)` and then imports `tan.planner`, and that
+    # binding is process-global, first-bind-wins by design: `tan/planner/
+    # paths.py` freezes `REPO = sdk_root()` at module scope and a dozen planner
+    # functions take `metadata_root: Path = METADATA_ROOT` as a default
+    # argument, so both freeze at import time.
+    #
+    # Binding a non-SDK path can never produce a manifest, but it is far from
+    # harmless. `tan/planner/slugs.py` reads
+    # `metadata/registries/peripheral-kconfig.json` at module scope, so the
+    # import dies PARTWAY: Python evicts `tan.planner` and `tan.planner.slugs`
+    # but leaves `tan.planner.paths` cached with `REPO` frozen to the bogus
+    # root. The `except Exception` below then swallows that failure -- this
+    # write is best-effort by design and must never escape -- so the caller
+    # sees success while the process is left holding a planner frozen against
+    # a tree that is not an SDK at all.
+    #
+    # Checking first is cheaper than unwinding after, and uses the same
+    # `scripts/alp_project.py` marker `resolve_sdk_root_ladder` already treats
+    # as the definition of "this is an alp-sdk checkout".
+    if not (Path(effective_sdk_root) / "scripts" / "alp_project.py").is_file():
+        return PostBuildManifest(
+            write_failed_reason=(
+                f"resolved alp-sdk root {effective_sdk_root} has no "
+                f"scripts/alp_project.py, so it is not an alp-sdk checkout; "
+                f"skipping the post-build system-manifest emit rather than "
+                f"binding the planner to it"
+            ),
+            native_sim_target=None,
+        )
+
+    try:
+        from tan.planner_root import emit as _planner_emit
+    except ImportError as err:  # pragma: no cover -- planner absent from this build
+        return PostBuildManifest(
+            write_failed_reason=f"planner unavailable: {err}", native_sim_target=None
+        )
+    try:
+        if plain_route is not None:
+            # tan-cli#1370: no board.yaml to project from -- a one-slice
+            # manifest from the board target's SoM preset instead.
+            from tan.planner_root import bind_sdk_root
+
+            bind_sdk_root(effective_sdk_root)
+            from tan.planner.plain_slice import plain_system_manifest
+
+            yaml_text = plain_system_manifest(
+                plain_route[0],
+                Path(effective_sdk_root) / "metadata",
+                fallback_core_id=plain_route[1],
+                elf_path=next((r.output_artefact for r in results if r.output_artefact), None),
+            )
+        else:
+            yaml_text = _planner_emit(
+                "system-manifest", root=effective_sdk_root, board_yaml=Path(effective_board_yaml)
+            )
+    except Exception as err:  # noqa: BLE001 -- best-effort write, never escapes
+        return PostBuildManifest(
+            write_failed_reason=f"{type(err).__name__}: {err}", native_sim_target=None
+        )
+
+    # THIS run's own target signal -- computed from the emit, independent of
+    # whether the file write below then succeeds.
+    native_sim_target = _native_sim_target_from_yaml(yaml_text)
+
+    try:
+        raw = parse_system_manifest_raw(yaml_text)
+        overlay_run_results_raw(raw, results)
+        out = serialize_system_manifest_raw(raw)
+    except SystemManifestError as err:
+        return PostBuildManifest(
+            write_failed_reason=err.message, native_sim_target=native_sim_target
+        )
+    except Exception as err:  # noqa: BLE001 -- best-effort write, never escapes
+        # `serialize_system_manifest_raw` (`yaml.safe_dump`) is called OUTSIDE
+        # any `try` in the oracle's own terms too -- `rewrite_manifest_yaml`
+        # returns `Result<String, String>` for every branch, including the
+        # dumper's own failure (e.g. a `!!binary` node PyYAML's SafeDumper
+        # cannot represent). Uncaught here, that would escape
+        # `write_post_build_manifest`, escape `execute_slices`, and abort a
+        # build whose slices already ran -- breaking the documented
+        # best-effort contract this function's own docstring states.
+        return PostBuildManifest(
+            write_failed_reason=f"{type(err).__name__}: {err}",
+            native_sim_target=native_sim_target,
+        )
+
+    dest = dest_dir / "system-manifest.yaml"
+    try:
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        # newline="" -- PRESERVE the LF `yaml.safe_dump` always emits, rather
+        # than Python's default universal-newline translation (CRLF on
+        # Windows), which made this contract file diverge byte-for-byte from
+        # the oracle's `std::fs::write` (raw bytes, no translation). Same
+        # convention already documented at materialise.py:63 and
+        # image_cmd.py:319-330.
+        dest.write_text(out, encoding="utf-8", newline="")
+    except OSError as err:
+        return PostBuildManifest(
+            write_failed_reason=str(err), native_sim_target=native_sim_target
+        )
+
+    return PostBuildManifest(write_failed_reason=None, native_sim_target=native_sim_target)
+
+
+def build_dir_overridden(cmd_args: Sequence[str]) -> bool:
+    """True when the slice's argv redirects west's build dir away from the
+    default nested `<cwd>/build` (`-d <dir>`, `--build-dir <dir>`, or
+    `--build-dir=<dir>`) -- the one case [`resolve_zephyr_artefact`]'s default
+    path can't follow. Port of `crates/tan-cli/.../execute/manifest.rs::
+    build_dir_overridden`."""
+    return any(
+        a == "-d" or a == "--build-dir" or a.startswith("--build-dir=") for a in cmd_args
+    )
+
+
+def resolve_zephyr_artefact(
+    slice_cwd: Path, cmd_args: Sequence[str]
+) -> tuple[str | None, str | None]:
+    """After a slice builds `ok`, resolve the real `zephyr.elf` west produced
+    and its build dir. West's default output is a nested `build/` under the
+    slice's run cwd, so the elf lands at `<cwd>/build/zephyr/zephyr.elf`.
+    Returned ABSOLUTE (lexically, via `os.path.abspath` -- matching
+    `_abs_posix`'s convention elsewhere in this port -- never resolved through
+    a symlink) so every downstream consumer uses the path verbatim. `(None,
+    None)` when the slice's own command redirects the build dir
+    (`-d`/`--build-dir`) -- west then wrote somewhere other than the default
+    nested path, so the default location can't be trusted.
+
+    Deliberately NOT mtime-gated -- see the Rust oracle's own docstring on
+    why: a repeat `west build` with nothing to rebuild leaves `zephyr.elf`'s
+    mtime unchanged, so an mtime gate would drop a perfectly valid artefact on
+    every no-op/incremental rebuild. `is_file()` at the default path is
+    sufficient on its own. Port of `crates/tan-cli/.../execute/manifest.rs::
+    resolve_zephyr_artefact`."""
+    if build_dir_overridden(cmd_args):
+        return None, None
+    west_build = slice_cwd / "build"
+    elf = west_build / "zephyr" / "zephyr.elf"
+    if elf.is_file():
+        return os.path.abspath(str(elf)), os.path.abspath(str(west_build))
+    return None, None
+
+
+#: Filename of the tan-owned SDK-identity stamp (issue #52). Lives INSIDE
+#: west's own nested build dir (`<cwd>/build`, not `<cwd>` itself), so wiping
+#: that dir on a mismatch retires the stamp atomically -- it can never outlive
+#: or misdescribe a build dir that no longer exists. Port of
+#: `crates/tan-cli/.../execute/manifest.rs::sdk_stamp_path`'s hard-coded name.
+_SDK_STAMP_FILE = ".tan-sdk-root"
+
+
+def sdk_stamp_path(slice_cwd: Path) -> Path:
+    """Path of the tan-owned SDK-identity stamp for one slice."""
+    return slice_cwd / "build" / _SDK_STAMP_FILE
+
+
+def read_sdk_stamp(slice_cwd: Path) -> str | None:
+    """The SDK identity key recorded in the stamp file, if any. `None` covers
+    "never stamped", "unreadable", AND "unreadable as UTF-8" -- all three
+    read as "no signal", which `sdk_stamp_action` treats as a mismatch on an
+    already-configured dir. The value is whatever [`write_sdk_stamp`] wrote
+    -- the bare `--sdk-root` path on an older stamp, or
+    `tan.core.plan_exec.sdk_stamp_key`'s `<root>@<sdkCommit>` form once the
+    plan carries a commit -- this function does not itself parse or care
+    which. Port of `manifest.rs::read_sdk_stamp`, whose `std::fs::
+    read_to_string` folds invalid-UTF-8 into the SAME `io::Error` a missing
+    file raises, one `.ok()`; `UnicodeDecodeError` is a `ValueError`, not an
+    `OSError`, so `except OSError` alone let a corrupt (non-UTF-8)
+    `.tan-sdk-root` escape this function as an uncaught exception -- verified
+    to reach past `execute_slices`, whose own module docstring promises no
+    escaping exception."""
+    try:
+        return sdk_stamp_path(slice_cwd).read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def write_sdk_stamp(slice_cwd: Path, key: str) -> None:
+    """Write the stamp BEFORE the tool is spawned (see the executor call
+    site): a mid-configure failure still stamped correctly, since the dir
+    really was configured against `key` regardless of whether the build
+    finishes. `key` is `tan.core.plan_exec.sdk_stamp_key`'s output. Raises
+    `OSError` on failure -- the caller treats the write as best-effort (a
+    write failure just means the next run may treat this dir as unstamped:
+    fails toward a spurious rebuild, not toward trusting a stale one). Port
+    of `manifest.rs::write_sdk_stamp`."""
+    path = sdk_stamp_path(slice_cwd)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(key, encoding="utf-8")
+
+
+def cmake_cache_configured(slice_cwd: Path) -> bool:
+    """Whether west has ever configured this slice's build dir (`<cwd>/build/
+    CMakeCache.txt`) -- the "was this dir ever configured" signal
+    `sdk_stamp_action` needs before it treats a missing stamp as stale. Port
+    of `manifest.rs::cmake_cache_configured`."""
+    return (slice_cwd / "build" / "CMakeCache.txt").is_file()
+
+
+def _dir_shows_zephyr(directory: Path) -> bool:
+    """The two per-directory signals behind [`zephyr_boilerplate_loaded`]:
+    a `ZEPHYR_BASE:` entry in `directory`'s own `CMakeCache.txt` (the primary
+    signal -- what `find_package(Zephyr)` caches, verified against a real
+    `<slice>/build/CMakeCache.txt`; a plain host configure never writes one),
+    OR a `zephyr/` subdirectory (Zephyr's boilerplate binary dir, kept as an
+    OR fallback so the guard can only ever fail a build it is SURE about).
+    Port of `manifest.rs::dir_shows_zephyr`, whose `std::fs::read_to_string`
+    folds invalid-UTF-8 into the SAME `io::Error` a missing file raises
+    (`.is_ok_and(...)` then just falls through to the `zephyr/` fallback);
+    `UnicodeDecodeError` is a `ValueError`, not an `OSError`, so `except
+    OSError` alone let a non-UTF-8 `CMakeCache.txt` escape this function as
+    an uncaught exception -- the same lesson `read_sdk_stamp` above already
+    records for the sibling `.tan-sdk-root` read."""
+    try:
+        cache = (directory / "CMakeCache.txt").read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        cache = ""
+    if any(line.startswith("ZEPHYR_BASE:") for line in cache.splitlines()):
+        return True
+    return (directory / "zephyr").is_dir()
+
+
+def zephyr_boilerplate_loaded(slice_cwd: Path) -> bool:
+    """tan-cli#309 (upstream tan-cli #97): whether this slice's build dir
+    shows that Zephyr's CMake boilerplate actually ran -- the signal behind
+    the `os: zephyr` guard `execute.py`'s status assembly applies.
+
+    The reported defect: a project whose `CMakeLists.txt` never calls
+    `find_package(Zephyr ...)` still configures and links fine under `west
+    build -b <board>` (CMake only emits a *dev* warning about the missing
+    `project()` call), so a core declared `os: zephyr` produced a host
+    binary and the executor reported it `[+] ok`. The board name is never
+    even validated, because nothing loaded the code that would validate it.
+
+    Checked one level down too (not just `<slice_cwd>/build` itself),
+    because `--sysbuild` nests the real per-image Zephyr builds one
+    directory deeper under its own superbuild -- Zephyr's own
+    `share/sysbuild/CMakeLists.txt` calls `find_package(Sysbuild ...)`, not
+    `find_package(Zephyr)`, so a sysbuild top level carries neither signal
+    and only the nested per-image build does. One level is enough (sysbuild
+    nests per-image, not recursively).
+
+    Callers must skip this check when [`build_dir_overridden`] -- west then
+    wrote somewhere this can't see, the same refusal [`resolve_zephyr_artefact`]
+    already makes. Port of `manifest.rs::zephyr_boilerplate_loaded`."""
+    build = slice_cwd / "build"
+    if _dir_shows_zephyr(build):
+        return True
+    try:
+        children = [p for p in build.iterdir() if p.is_dir()]
+    except OSError:
+        return False
+    return any(_dir_shows_zephyr(child) for child in children)

tan/commands/build/materialise.py

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Write every artefact the plan carries under `build_root` -- BEFORE any
+slice runs. That ordering is the stated precondition of the plan's
+slice-independence invariant: `sharedArtefacts` and every slice's
+`configArtefacts` must all exist on disk before dispatch starts, or
+concurrent slice execution (planned later) would race a slice reading a
+config file its own materialise step hasn't written yet.
+
+Mirrors `tan-cli/src/commands/build/materialise.rs`'s `MaterialiseError`
+(one type, two failure shapes -- an unsafe path, or an I/O error) rather than
+letting either escape as a bare exception."""
+from pathlib import Path
+from typing import Any
+
+from tan.core.build_plan import BuildPlan
+
+
+class MaterialiseError(ValueError):
+    """A structured, coded materialise failure. Subclasses `ValueError` (not
+    a plain `Exception`) so `except ValueError` -- the shape a caller reaches
+    for around "a plan-supplied path was bad" -- still catches it; `.code`/
+    `.message` are there for a caller that wants to fold it into the
+    `(code, message)` envelope contract instead (mirrors `PlanParseError`,
+    `TokenSubstitutionError`)."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+def confine_to_build_root(build_root: Path, rel: str) -> Path:
+    """Resolve `rel` under `build_root`, refusing anything that escapes it.
+
+    Plans are trusted input, but a plan-supplied relative path (an
+    artefact's `path`, or -- reused by `execute.py` -- a slice command's
+    `cwd`) must never let `build_root / rel` land outside `build_root`.
+    `Path.is_absolute()` alone is not enough to guard against this on
+    Windows: a drive-relative `C:foo` or a rooted `\\foo` is NOT
+    `is_absolute()`, yet joining either onto `build_root` discards part or
+    all of it (`PurePath.__truediv__` replaces the base outright once the
+    right-hand side supplies its own root/drive) -- exactly the shape that
+    let a path escape silently. Resolving both sides and requiring
+    containment catches every one of these shapes (verified empirically:
+    `..`, a bare posix `/x`, `C:x`, and `\\x` all resolve outside
+    `build_root.resolve()`), not just the lexical `..` case.
+    """
+    root = build_root.resolve()
+    target = (build_root / rel).resolve()
+    if target != root and root not in target.parents:
+        raise MaterialiseError(
+            "build.path-escape",
+            f"path `{rel}` would escape the build root `{root}`",
+        )
+    return target
+
+
+def _write(build_root: Path, artefact: dict[str, Any]) -> Path:
+    rel = artefact["path"]
+    target = confine_to_build_root(build_root, rel)
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(artefact.get("contents", ""), encoding="utf-8", newline="")
+    except OSError as err:
+        # Permission denied, a Windows path over MAX_PATH, a parent that's
+        # actually a file, target itself being a directory (an empty/`.`
+        # artefact path) -- every write-time OSError, never a bare traceback.
+        raise MaterialiseError(
+            "build.artefact-write-failed", f"failed to write `{rel}`: {err}"
+        ) from err
+    return target
+
+
+def materialise_plan(plan: BuildPlan, build_root: Path) -> list[Path]:
+    """Write ALL `sharedArtefacts`, then every slice's `configArtefacts`, and
+    only then return. Callers must not start any slice before this returns --
+    that ordering is the whole point (see module docstring)."""
+    written = [_write(build_root, a) for a in plan.shared_artefacts]
+    for sl in plan.slices:
+        written.extend(_write(build_root, a) for a in sl.config_artefacts)
+    return written