tan-cli 0.7.0__py3-none-any.whl

tan/core/som_buildability.py

@@ -0,0 +1,204 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Whether a SoM's hw_rev -- explicit, or (absent that) its DEFAULT -- is
+buildable, read directly off the alp-sdk metadata tree, without importing
+`tan.planner` (see `tan/core/example_catalog.py`'s own docstring for why:
+`tan.planner.paths` binds `REPO = sdk_root()` at import time, so pulling it
+into `init_cmd` before an SDK is even resolved raises `PlannerRootError`).
+
+tan-cli#743. `tan init --template minimal-app --som <sku>` for a SoM whose
+default hw_rev is not buildable (a `reserved`/`tbd` revision) exits 0 and scaffolds a project whose FIRST `tan validate`
+hard-errors::
+
+    sdk-compat: SoM <sku> hw_rev '<rev>' exists but is not buildable
+    (status: 'tbd').
+
+`init` never writes an explicit `hw_rev:` into a scaffolded `minimal-app`/
+vendored-template board.yaml, so the value `validate` refuses there is the
+one the SDK loader falls back to -- `hw_rev or
+som_preset.get("default_hw_rev")` (`scripts/alp_orchestrate/loader.py:1241`
+and siblings) -- i.e. the SoM preset's OWN `default_hw_rev:`. `validate` is
+not wrong here: the fact is real and correctly published (the family's
+`metadata/e1m_modules/<family>/hw-revisions.yaml` `<rev>: {status: tbd}`). The
+defect is that `init` stays silent about a fact it could have read from the
+exact same preset it already resolved -- so this module reads that one fact
+(the SKU's effective hw_rev + the family's declared status for it) so `init`
+can warn about it instead.
+
+tan-cli#1008 review majors 1+2: an `--from-example`/`--topology` copy can
+carry an EXPLICIT `hw_rev:` of its own (`tan/core/scaffold.vendored_som`
+reads it off the planned board.yaml) -- the original example's own revision,
+or one that survived an INTRA-family retarget (`retarget_board_yaml_som`
+only drops the sibling `hw_rev:` on a CROSS-family retarget -- review round
+4 -- since within one family the value is still a real, declared revision
+for the new SKU too). `hw_rev_not_buildable`'s caller passes that explicit
+value through when there is one, so the pair this module judges (and the
+warning names) is always the one actually written to disk, never a value
+inferred from `--som`/`DEFAULT_SOM_SKU` alone.
+
+WHY A WARNING AND NOT A REFUSAL: `minimal-app` is deliberately the one
+template every OTHER template's own refusal message names as the escape
+hatch -- "Use --template minimal-app, which is vendor-neutral and scaffolds
+any SoM" (`tan/core/scaffold.py`'s vendored-scaffold refusal text). If this
+check also refused, a SoM in `status: preliminary` would have no self-contained
+scaffolding path at all -- worse than the silent defect it replaces. This
+mirrors `example_catalog.unsupported_som`'s own precedent (warn, still
+write) for the identical reason: refusing there "made `tan init
+--from-example` unusable for nearly the whole AEN family, which is worse
+than the original defect".
+
+Deliberately duplicates the tiny SKU -> family-directory map
+`scripts/alp_project_loader._sku_family` also carries (`AEN`/`V2N`/`V2M`
+-> `aen`/`v2n`/`v2n-m1`) and the buildable-status set
+`scripts/alp_orchestrate/sdk_compat._NOT_BUILDABLE_STATUSES` (`reserved`,
+`tbd`, or a missing `status:` key) rather than importing either: neither
+module is on `sys.path` for a `tan init --template` invocation, which reads
+`--sdk-root` only as a metadata SOURCE, never as an importable package.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Optional
+
+#: Mirrors `scripts/alp_project_loader._SKU_FAMILY` / `_sku_family` verbatim.
+_SKU_FAMILY = re.compile(r"^E1M-(AEN|V2N|V2M)")
+_FAMILY_DIR = {"AEN": "aen", "V2N": "v2n", "V2M": "v2n-m1"}
+
+#: Mirrors `scripts/alp_orchestrate/sdk_compat._NOT_BUILDABLE_STATUSES`
+#: verbatim (alp-sdk #1025): `reserved`, `tbd`, and a missing `status:` key
+#: are all refused; every other declared status is buildable.
+_NOT_BUILDABLE_STATUSES = frozenset({"reserved", "tbd"})
+
+
+class HwRevNotBuildable:
+    """The hw_rev a scaffolded board.yaml resolves to (its own explicit
+    `hw_rev:`, or -- absent that -- the SoM preset's `default_hw_rev:`), and
+    why `tan validate` will refuse it.
+
+    `has_buildable_alternative` -- tan-cli#1008 review minor -- is whether
+    the SAME family table declares at least one OTHER hw_rev whose status
+    permits a build: the "or until board.yaml names a buildable `hw_rev:`
+    explicitly" remedy is only real advice when this is true. A family that
+    publishes exactly one hw_rev, and that one not buildable, would make the
+    clause advice that reproduces the identical refusal, rc 2, every time."""
+
+    __slots__ = ("sku", "hw_rev", "status", "has_buildable_alternative")
+
+    def __init__(
+        self, sku: str, hw_rev: str, status: Optional[str], has_buildable_alternative: bool
+    ) -> None:
+        self.sku = sku
+        self.hw_rev = hw_rev
+        self.status = status
+        self.has_buildable_alternative = has_buildable_alternative
+
+
+def _safe_load_mapping(path: Path) -> Optional[dict]:
+    """`yaml.safe_load(path)`, or None for every reason a caller here must
+    treat as "nothing to check" rather than an error: absent, unreadable,
+    unparseable, or parsed to something other than a mapping.
+
+    Imports PyYAML lazily, inside the call, not at module scope: this module
+    is reached from `init_cmd`, which `tan/cli.py` static-imports on EVERY
+    invocation, and `tests/gates/test_cli_import_is_lean.py` (tan-cli#810)
+    pins PyYAML as loaded only by `new_som_cmd`/`kconfig_cmd`'s single-use
+    paths -- a module-scope `import yaml` here would load it on `tan
+    --version` too.
+
+    tan-cli#1116 review round 2: `UnicodeDecodeError` is caught alongside
+    `OSError` -- it is a `ValueError`, not an `OSError`, so a non-UTF-8
+    `hw-revisions.yaml` used to raise raw past `hw_rev_not_buildable`'s own
+    written "Never raises" contract (measured escaping through that real
+    caller before this fix).
+    """
+    import yaml
+
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+    try:
+        doc = yaml.safe_load(text)
+    except yaml.YAMLError:
+        return None
+    return doc if isinstance(doc, dict) else None
+
+
+def hw_rev_not_buildable(
+    sdk_root: Path, sku: str, hw_rev: Optional[str] = None
+) -> Optional[HwRevNotBuildable]:
+    """Whether `hw_rev` -- or, when `None`/empty, `sku`'s own
+    `default_hw_rev:` -- is buildable per its family's `hw-revisions.yaml`.
+    Returns None for "nothing to report" -- covering every reason a caller
+    here must NOT warn over, deliberately mirroring
+    `example_catalog.unsupported_som`'s own contract:
+
+      * `sku` doesn't match the known SoM SKU pattern at all,
+      * no SoM preset file for `sku` in this checkout,
+      * `hw_rev` is `None`/empty and the preset declares no (or a malformed)
+        `default_hw_rev:` to fall back to,
+      * no family `hw-revisions.yaml` table (an in-development family with
+        nothing to check against yet),
+      * the family table doesn't declare `hw_rev` as a key at all --
+        existence is `revision_known()`'s question
+        (`tan/planner/sdk_compat.py`), not this one's; an unknown revision
+        has no status to have read, so there is nothing here to judge,
+      * the declared status permits a build.
+
+    Never raises: a scaffold must not fail because a metadata file could
+    not be read.
+    """
+    match = _SKU_FAMILY.match(sku)
+    family_dir = _FAMILY_DIR.get(match.group(1)) if match else None
+    if family_dir is None:
+        return None
+
+    preset = _safe_load_mapping(sdk_root / "metadata" / "e1m_modules" / f"{sku}.yaml")
+    if preset is None:
+        return None
+    if not hw_rev:
+        hw_rev = preset.get("default_hw_rev")
+    if not isinstance(hw_rev, str) or not hw_rev:
+        return None
+
+    table = _safe_load_mapping(
+        sdk_root / "metadata" / "e1m_modules" / family_dir / "hw-revisions.yaml"
+    )
+    if table is None:
+        return None
+    revisions = table.get("hw_revisions")
+    if not isinstance(revisions, dict):
+        return None
+    entry = revisions.get(hw_rev)
+    if not isinstance(entry, dict):
+        # Mirrors `alp_orchestrate/sdk_compat.revision_buildable` verbatim: a
+        # key present but not a dict (None, a bare string, ...) is a
+        # malformed entry, not an absent one -- it has no status, so it is
+        # not buildable. Only a truly absent key stays "nothing to judge"
+        # (unknown, `revision_known()`'s question).
+        if hw_rev not in revisions:
+            return None
+        return HwRevNotBuildable(sku, hw_rev, None, _has_other_buildable(revisions, hw_rev))
+
+    status = entry.get("status")
+    if isinstance(status, str) and status not in _NOT_BUILDABLE_STATUSES:
+        return None
+    return HwRevNotBuildable(
+        sku, hw_rev, status if isinstance(status, str) else None,
+        _has_other_buildable(revisions, hw_rev),
+    )
+
+
+def _has_other_buildable(revisions: dict, hw_rev: str) -> bool:
+    """Whether `revisions` (the family's `hw_revisions:` map) declares any
+    key OTHER than `hw_rev` whose `status:` permits a build -- the fact that
+    decides whether "or name a buildable `hw_rev:` explicitly" is real
+    advice or a dead end (tan-cli#1008 review minor)."""
+    return any(
+        other_rev != hw_rev
+        and isinstance(other_entry, dict)
+        and isinstance(other_entry.get("status"), str)
+        and other_entry.get("status") not in _NOT_BUILDABLE_STATUSES
+        for other_rev, other_entry in revisions.items()
+    )

tan/core/som_schema_version.py

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The one SoM-preset `schema_version` this tan reads, and the message for a
+preset it skips because it declares another.
+
+alp-sdk#2024 moved every `metadata/e1m_modules/*.yaml` preset to
+`schema_version: 2` (`som-preset-v2.schema.json`, `write_authority` required,
+`npu_population` removed). tan-cli#1297 moved tan's readers with it, and every
+one of them refuses a preset declaring anything else rather than guessing at a
+shape it does not know. Against an SDK that predates #2024 (released alp-sdk
+`v0.16.0` and older) that refusal reaches EVERY preset, so `tan presets`
+listed `skus: []` and `tan size` reported every budget as `unreadable SoM
+preset`, with nothing saying why. `skipped_presets_message` is the why: one
+sentence, shared by both commands so they cannot word the same fact two ways.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+#: The one `schema_version:` a SoM preset may declare.
+#: `som-preset-v2.schema.json` pins it `const: 2`.
+SOM_SCHEMA_VERSION = 2
+
+#: The upstream change that introduced v2, named in the message so a reader
+#: can tell "old SDK" from "broken preset".
+_V2_ORIGIN = "alp-sdk#2024"
+
+
+def is_supported_som_schema_version(version: object) -> bool:
+    """True only for the bare integer `SOM_SCHEMA_VERSION`. `bool` is excluded
+    explicitly: `True == 1` and `isinstance(True, int)` both hold in Python."""
+    return isinstance(version, int) and not isinstance(version, bool) and version == SOM_SCHEMA_VERSION
+
+
+def _remedy(versions: list[object]) -> str:
+    ints = [v for v in versions if isinstance(v, int) and not isinstance(v, bool)]
+    if ints and len(ints) == len(versions) and max(ints) < SOM_SCHEMA_VERSION:
+        return (
+            f"the bound alp-sdk predates som-preset v{SOM_SCHEMA_VERSION} "
+            f"({_V2_ORIGIN}); point --sdk-root at an alp-sdk whose "
+            f"metadata/schemas/ ships som-preset-v{SOM_SCHEMA_VERSION}.schema.json, "
+            "or use a tan release that matches this SDK"
+        )
+    if ints and len(ints) == len(versions) and min(ints) > SOM_SCHEMA_VERSION:
+        return "the bound alp-sdk is newer than this tan; upgrade tan"
+    return "fix the preset's schema_version or use an alp-sdk whose presets match this tan"
+
+
+def skipped_presets_message(subject: str, versions: Iterable[object]) -> str:
+    """`<subject> declare(s) schema_version <v[, v...]> (this tan reads
+    som-preset schema_version 2): <remedy>.`
+
+    *subject* names what was skipped ("12 SoM presets under <dir>", "the SoM
+    preset for E1M-AEN801"); *versions* is every skipped preset's declared
+    value, duplicates allowed -- they are collapsed, in first-seen order, and
+    an absent key reads as `None`, exactly what the preset said."""
+    seen = list(versions)
+    shown = ", ".join(dict.fromkeys(repr(v) for v in seen))
+    return (
+        f"{subject}: schema_version {shown} (this tan reads "
+        f"som-preset schema_version {SOM_SCHEMA_VERSION}) -- {_remedy(seen)}."
+    )

tan/core/subprocess_env.py

@@ -0,0 +1,201 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The one shared rule for building a subprocess child's environment.
+
+**Every spawn site under `python/tan/` must route its `env=` through
+[`spawn_env`] (or, for a caller that already owns its own mutable base dict,
+[`restore_ld_library_path`] directly) rather than build one by hand.**
+tan-cli#992 is what happens when that is left to 25 independent call sites
+instead: one gets it right and the other 24 leak.
+
+## The rule
+
+PyInstaller's Linux ONEDIR bootloader points `LD_LIBRARY_PATH` at the frozen
+app's own bundled `_internal/` lib dir -- so the FROZEN `tan` binary finds its
+OWN bundled shared libraries -- and stashes the caller's original value in
+`LD_LIBRARY_PATH_ORIG` before doing so. Every child process `tan` spawns
+(`west`, `git`, `dxcom`, a J-Link tool, and everything THOSE spawn in turn) is
+a SYSTEM program, never a bundled one, so unless the spawn site restores
+`LD_LIBRARY_PATH_ORIG` before spawning, that child inherits tan's bundled path
+ahead of the system one and can silently resolve one of tan's own bundled
+shared libraries instead of the host's -- only surfacing when the two
+versions actually disagree in a way that breaks something.
+
+Measured, tan-cli#990/#992, on real CI: `tan bootstrap` spawned `west sdk
+install`, which shelled `tar --xz`, which loaded tan's bundled
+`liblzma.so.5` (older than the host's) ahead of the system one and failed
+outright:
+
+    xz: /home/runner/.local/bin/tan-cli-lib/_internal/liblzma.so.5:
+    version `XZ_5.4' not found (required by xz)
+    /usr/bin/tar: Child returned status 1
+
+`LD_LIBRARY_PATH_ORIG` is the PREFERRED trigger: it is PyInstaller's own
+marker that its bootloader modified `LD_LIBRARY_PATH` for THIS process, and
+it carries the exact value to restore.
+
+**It is not the ONLY trigger, and tan-cli#1189 is what that cost.** Until
+then this module treated an absent `ORIG` as proof that no override had
+happened -- "a frozen run whose `LD_LIBRARY_PATH_ORIG` is absent" was listed
+as a host that never had the problem. Measured on a bare `ubuntu:24.04`, the
+identical `liblzma.so.5` failure came back with tan-cli#992's fix in place,
+so on that host the restore did not fire. A host with no `LD_LIBRARY_PATH`
+of its own is precisely the host where the bundle becomes the ONLY entry on
+the child's search path -- the worst case, not the safe one.
+
+So the second trigger is the fact that does not depend on the bootloader
+having recorded anything: is the bundle dir ([`_frozen_bundle_dir`], i.e.
+`sys._MEIPASS` on a frozen run) currently ON `LD_LIBRARY_PATH`? Both
+triggers are still false on `python -m tan` from source (this repo's own
+dev/CI/test runs, where `sys.frozen` is unset) and on macOS/Windows
+(`LD_LIBRARY_PATH` is not their loader variable), so this still never
+touches a host that never had the problem -- and it still never guesses at a
+fallback value: with no `ORIG`, the only defensible restore is REMOVAL.
+
+Lifted out of `tan.commands.bootstrap_cmd.Runner._env`, which worked out this
+rule first (tan-cli#990) but was exactly one spawn site out of ~25 under
+`python/tan/` -- this module is the ONE place the rule is written down,
+per tan-cli#992. `Runner._env` itself now calls [`restore_ld_library_path`]
+rather than carrying its own copy of the restore logic.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Mapping
+
+
+def _frozen_bundle_dir() -> str | None:
+    """The directory a PyInstaller ONEDIR bootloader puts on
+    `LD_LIBRARY_PATH` so the frozen binary finds its OWN shared libraries --
+    `sys._MEIPASS`, which for a onedir freeze is the `_internal/` tree.
+    `None` on a source run (this repo's own dev/CI/test runs), where
+    `sys.frozen` is unset and there is no bundle to strip."""
+    if not getattr(sys, "frozen", False):
+        return None
+    bundle = getattr(sys, "_MEIPASS", None)
+    return bundle if isinstance(bundle, str) and bundle else None
+
+
+def _without_bundle_dir(value: str, bundle: str) -> str | None:
+    """`value` (an `os.pathsep`-joined search path) with every entry that IS
+    `bundle` removed -- or `None` when `bundle` does not appear in it at all,
+    which is the caller's signal that there is nothing to undo.
+
+    Compared with `os.path.normpath`, so a trailing slash or a `./` segment
+    cannot smuggle the bundle past the match. Empty entries are dropped from
+    the result: stripping the bundle out of `"<bundle>"` or
+    `"<bundle>:<bundle>"` must not leave a bare `":"`, which some loaders
+    read as "search the current directory" -- the same hazard the
+    `orig == ""` branch below is written to avoid."""
+    entries = value.split(os.pathsep)
+    target = os.path.normpath(bundle)
+    if not any(entry and os.path.normpath(entry) == target for entry in entries):
+        return None
+    kept = [entry for entry in entries if entry and os.path.normpath(entry) != target]
+    return os.pathsep.join(kept)
+
+
+def ld_library_path_needs_restore() -> bool:
+    """Would a child spawned from THIS process inherit the frozen bundle's
+    lib dir on `LD_LIBRARY_PATH`?
+
+    The predicate a caller uses to decide whether it may skip building a
+    child environment at all. `bootstrap_cmd.Runner._env` is the one such
+    caller: it returns `None` (meaning `subprocess.run(env=None)`, "inherit
+    this process's unrestored environment") on its fast path, and that fast
+    path is only safe when this returns `False`."""
+    if os.environ.get("LD_LIBRARY_PATH_ORIG") is not None:
+        return True
+    bundle = _frozen_bundle_dir()
+    if bundle is None:
+        return False
+    current = os.environ.get("LD_LIBRARY_PATH")
+    if not current:
+        return False
+    return _without_bundle_dir(current, bundle) is not None
+
+
+def _restore_from_orig(env: dict[str, str], orig: str) -> None:
+    """The bootloader recorded a marker, so restore exactly what it saved.
+
+    POPS the key rather than setting `""` when the host had no
+    `LD_LIBRARY_PATH` before the bootloader touched it -- some dynamic
+    loaders read an explicit empty value as "search the current directory",
+    which is worse than the key being absent."""
+    if orig:
+        env["LD_LIBRARY_PATH"] = orig
+    else:
+        env.pop("LD_LIBRARY_PATH", None)
+
+
+def _strip_bundle_dir(env: dict[str, str]) -> None:
+    """No marker was recorded -- remove the bundle dir from `LD_LIBRARY_PATH`
+    if it is on it (tan-cli#1189).
+
+    Deliberately does NOT invent a replacement value: with no
+    `LD_LIBRARY_PATH_ORIG` the only defensible restore is REMOVAL. A frozen
+    run whose path does not carry the bundle is left completely alone -- the
+    bootloader never touched it, so neither does this."""
+    bundle = _frozen_bundle_dir()
+    if bundle is None:
+        return
+    current = os.environ.get("LD_LIBRARY_PATH")
+    if not current:
+        return
+    stripped = _without_bundle_dir(current, bundle)
+    if stripped is None:
+        return
+    if stripped:
+        env["LD_LIBRARY_PATH"] = stripped
+    else:
+        env.pop("LD_LIBRARY_PATH", None)
+
+
+def restore_ld_library_path(env: dict[str, str]) -> None:
+    """Mutate `env` IN PLACE: undo the frozen bootloader's `LD_LIBRARY_PATH`
+    override, reading the REAL process environment (`os.environ`) -- never
+    `env` itself, which may already be a partially-built child env with no
+    such key.
+
+    A no-op on every host that never had the problem: a source run, macOS,
+    Windows, or a frozen run where the bundle is not on the search path.
+
+    Two triggers, not one -- see this module's docstring for why an absent
+    `LD_LIBRARY_PATH_ORIG` is NOT proof that no override happened
+    (tan-cli#1189), and [`_restore_from_orig`] / [`_strip_bundle_dir`] for
+    what each arm does."""
+    orig = os.environ.get("LD_LIBRARY_PATH_ORIG")
+    if orig is not None:
+        _restore_from_orig(env, orig)
+        return
+    _strip_bundle_dir(env)
+
+
+def spawn_env(
+    overrides: Mapping[str, str] | None = None,
+    *,
+    base: Mapping[str, str] | None = None,
+) -> dict[str, str]:
+    """The `env=` every subprocess spawn in `tan` hands its child: a fresh
+    copy of `base` (`os.environ` when not given) with
+    [`restore_ld_library_path`] applied, then `overrides` layered on top.
+
+    `base`, when given, is typically an already-adjusted mapping a caller
+    built for its own reasons (e.g. `with_venv_on_path`'s PATH prepend) --
+    `spawn_env` copies it rather than mutating it, then applies the SAME
+    restore on top, so a caller can freely compose
+    `with_venv_on_path(spawn_env(), tool)` or
+    `spawn_env(base=with_venv_on_path(dict(os.environ), tool))`
+    interchangeably; the two touch disjoint keys (`PATH` vs
+    `LD_LIBRARY_PATH`) so the order never matters.
+
+    Always returns an explicit `dict`, never `None`:
+    `subprocess.run(env=None)` means "inherit this process's own
+    (unrestored) environment", which is exactly the leak this module exists
+    to close -- no call site may spawn with an implicit/`None` environment.
+    """
+    env = dict(base) if base is not None else dict(os.environ)
+    restore_ld_library_path(env)
+    if overrides:
+        env.update(overrides)
+    return env

tan/core/sysbuild_image.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Re-derive the sysbuild image prefix of a slice's per-core `alp.conf` after
+token substitution (alp-sdk#866, consumer side).
+
+On a `--sysbuild` slice the planner passes the per-core `alp.conf` as
+`-D<image>_EXTRA_CONF_FILE=<build>/alp.conf`, where `<image>` is the
+basename of the app directory handed to `west build` -- sysbuild's own name
+for the application image (`get_filename_component(app_name ${APP_DIR}
+NAME)`). The planner computes that basename from the directory it EMITTED
+in. A tokened plan's app dir is `${PROJECT_ROOT}/...`, so the same plan run
+from a differently-named project root (`tan build --plan-from plan.json
+--execute` in `/b/bar` for a plan emitted in `/a/foo`) names image `foo`
+while sysbuild builds image `bar`: Zephyr ignores the unknown
+`foo_EXTRA_CONF_FILE` and the image builds WITHOUT its per-core
+configuration, with no error. alp-sdk's own orchestrator comment says a
+consumer that relocates the project root must re-derive the prefix; this is
+that re-derivation. `tan/planner/orchestrator.py` is an upstream mirror and
+stays as emitted.
+
+Rewrite, not refuse: the arg is identified by its VALUE (this slice's own
+`<buildDir>/alp.conf`), not by its prefix, so retargeting it to the image
+sysbuild will actually build is unambiguous, and the right prefix is a pure
+function of the substituted command. Refusing would make every relocated
+tokened plan for a `boot:`/OTA project unbuildable, when the planner already
+said exactly how to fix it. Any other `-D<x>_EXTRA_CONF_FILE` (one naming
+`mcuboot`, say) is not this slice's `alp.conf` and is left alone.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import replace
+
+from tan.core.build_plan import BuildPlan, Slice, SliceCommand
+
+_IMAGE_SCOPED = re.compile(r"^-D(?P<image>[^=]+)_EXTRA_CONF_FILE=(?P<value>.*)$", re.S)
+
+#: `west build` options that take a separate value -- skipped when locating
+#: the positional app-dir argument (same set alp-sdk's seam1 comparator uses).
+_OPTIONS_WITH_VALUE = frozenset({"-b", "-d", "-p"})
+
+
+def west_app_dir_basename(args: list[str]) -> str | None:
+    """Basename of `west build`'s app-dir argument: the first non-option arg
+    after `build`, or `None` when there is none."""
+    try:
+        i = args.index("build") + 1
+    except ValueError:
+        return None
+    while i < len(args) and args[i].startswith("-"):
+        i += 2 if args[i] in _OPTIONS_WITH_VALUE else 1
+    if i >= len(args) or args[i] == "--":
+        return None
+    name = args[i].replace("\\", "/").rstrip("/").rsplit("/", 1)[-1]
+    return name or None
+
+
+def _is_slice_alp_conf(value: str, build_dir: str) -> bool:
+    v = value.replace("\\", "/")
+    b = build_dir.replace("\\", "/").rstrip("/")
+    return v == f"{b}/alp.conf" or v.endswith(f"/{b}/alp.conf")
+
+
+def rescope_command(command: SliceCommand, build_dir: str) -> SliceCommand:
+    """`command` with its per-core `-D<image>_EXTRA_CONF_FILE` renamed to the
+    image `west build` will create; unchanged when not sysbuild, when the app
+    dir is unknown, or when the prefix already matches."""
+    args = command.args
+    if "--sysbuild" not in args:
+        return command
+    image = west_app_dir_basename(args)
+    if image is None:
+        return command
+    new_args = []
+    for arg in args:
+        m = _IMAGE_SCOPED.match(arg) if isinstance(arg, str) else None
+        if m and m.group("image") != image and _is_slice_alp_conf(m.group("value"), build_dir):
+            arg = f"-D{image}_EXTRA_CONF_FILE={m.group('value')}"
+        new_args.append(arg)
+    if new_args == args:
+        return command
+    return replace(command, args=new_args)
+
+
+def rescope_sysbuild_extra_conf(plan: BuildPlan) -> BuildPlan:
+    """`plan` with every slice's command passed through `rescope_command`."""
+    slices: list[Slice] = []
+    for sl in plan.slices:
+        if sl.command is None:
+            slices.append(sl)
+            continue
+        cmd = rescope_command(sl.command, sl.build_dir)
+        slices.append(sl if cmd is sl.command else replace(sl, command=cmd))
+    return replace(plan, slices=slices)