tan-cli 0.7.0__py3-none-any.whl

tan/core/venv.py

@@ -0,0 +1,332 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Workspace-venv resolution, shared by every command that spawns a tool the
+`tan bootstrap` venv owns.
+
+Port of `crates/tan-cli/src/venv.rs`. `west` normally lives ONLY inside the
+bootstrapped venv -- nothing activates it for a GUI-launched editor, so the
+ambient PATH has no `west` at all. This module is what lets `tan` find it
+anyway.
+
+Moved here from `tan.commands.build_cmd` (tan-cli#289): `_find_workspace_venv`
+was private to that module but already imported across two others
+(`west_forward_cmd.py`, and indirectly `generate_cmd.py`/`model_cmd.py`/
+`monitor_cmd.py`/`new_som_cmd.py` via `_planner_python`) -- and three more
+consumers (`build.execute`'s slice dispatch, `flash_cmd`'s tool gate and
+spawn) needed the SAME search wired in rather than a second copy of it. This
+is the one shared module `flash_cmd.py`'s own docstring asked for.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from tan.core.bootstrap import VenvLayout, manifest_points_at, venv_layout
+
+
+def _resolve_layout(venv: Path) -> VenvLayout | None:
+    """Which bin directory actually has `west`, POSIX first -- the SAME
+    directory-wins rule creation already applies
+    (`bootstrap_cmd.Workspace.venv_bin`/`venv_present`), so a
+    Git-Bash/MSYS-created `Scripts/` venv (or a `bin/` venv found on a
+    Windows host) that bootstrap accepted is not invisible here. `None` when
+    `west` is present under neither layout.
+
+    Deliberately NOT `venv_layout(os.name == "nt")` (host-only): that was
+    tan-cli#291 -- bootstrap already derives the executable NAMES from the
+    winning directory (`core.bootstrap.venv_exe_names`), not the host, and
+    resolution disagreeing let a venv bootstrap just populated be invisible
+    to `build`/`flash`. The Rust oracle (`crates/tan-cli/src/venv.rs`) is
+    still host-only; tan-cli#291 identifies that as a latent oracle bug this
+    port inherited, not a divergence to keep copying now that creation has
+    already fixed it on its side (`3879cae`, tan-cli#289).
+    """
+    for is_windows in (False, True):
+        layout = venv_layout(is_windows)
+        if (venv / layout.bin_dir / layout.west).is_file():
+            return layout
+    return None
+
+
+def find_workspace_venv(start: str, sdk_root: str | None) -> Path | None:
+    """Locate the west-capable workspace `.venv`, mirroring Rust's
+    `find_workspace_venv` but resolving the bin-dir layout directory-wins
+    (see `_resolve_layout`) rather than host-only: gated on `west` actually
+    being present under EITHER layout (not just the directory existing), in
+    this order:
+
+      1. a `.venv` in the project tree, searched from `start` upward;
+      2. the workspace venv derived from `$ZEPHYR_BASE`
+         (`<ZEPHYR_BASE>/../.venv`), manifest-guarded against `sdk_root` (see
+         `_zephyr_base_venv`, tan-cli#292 consequence 2);
+      3. the SDK's canonical `<sdk-parent>/.venv` (post-alp-sdk#782) or the
+         legacy `<sdk-parent>/zephyrproject/.venv`.
+
+    `None` when none resolve (CI, an activated venv, the contract harness).
+
+    **tan-cli#495 defect 1: step 1 skips an ancestor that IS a west topdir
+    whose manifest is not alp-sdk's.** Step 1 used to accept any `.venv` with
+    a `west` in it, with no `sdk_root` involvement at all, while the sibling
+    resolver `west_workspace_dir` (below) rejects that same ancestor via its
+    tan-cli#307 `manifest_ok` guard -- so on a dirty host the two DISAGREED:
+    `tan build` spawned the ancestor venv's `west` with `cwd` pinned to the
+    correct workspace, and baked the ancestor venv's `python` into every
+    Zephyr slice as `-DPython3_EXECUTABLE`. That interpreter has none of
+    `zephyr/scripts/requirements.txt`, so `west build` died inside Zephyr's
+    own CMake configure naming Zephyr rather than tan -- the exact class
+    tan-cli#307 closed for the topdir, mirrored onto the binary. Worse when
+    the ancestor is a FULL Zephyr venv: no failure at all, just a silent
+    build against a different Zephyr's pinned requirements.
+
+    Deliberately NOT a naive mirror of #307's guard: `manifest_points_at` is
+    False for a project directory with no `.west` at all, so requiring it
+    outright would reject the SUPPORTED project-local `.venv` -- the exact
+    shape #307's own e2e test plants at `build_root/.venv`. The guard is
+    therefore conditional on the candidate's directory actually HOLDING a
+    `.west`: a directory that claims to be a west topdir must be the right
+    one, and a directory that claims nothing is judged on its `.venv` alone,
+    exactly as before.
+    """
+    directory: Path | None = Path(start)
+    while directory is not None:
+        candidate = directory / ".venv"
+        if _resolve_layout(candidate) is not None and _not_a_foreign_topdir(directory, sdk_root):
+            return candidate
+        parent = directory.parent
+        directory = parent if parent != directory else None
+
+    zephyr_base = os.environ.get("ZEPHYR_BASE")
+    if zephyr_base:
+        candidate = _zephyr_base_venv(Path(zephyr_base), sdk_root)
+        if candidate is not None:
+            return candidate
+
+    if sdk_root is not None:
+        parent = Path(sdk_root).parent
+        for workspace in (parent, parent / "zephyrproject"):
+            candidate = workspace / ".venv"
+            if _resolve_layout(candidate) is not None:
+                return candidate
+
+    return None
+
+
+def _not_a_foreign_topdir(directory: Path, sdk_root: str | None) -> bool:
+    """Whether `directory` may supply the workspace venv (tan-cli#495 defect 1).
+
+    True in the two cases that carry no claim to check -- `sdk_root` did not
+    resolve, so there is nothing to verify against (the same "nothing to check"
+    fallback `_zephyr_base_venv` and `west_workspace_dir.manifest_ok` already
+    apply), or `directory` is not a west topdir, which is the ordinary
+    project-local `.venv`. False ONLY for a directory that really is a west
+    topdir whose manifest does not point at `sdk_root`: that one is a different
+    workspace, and its venv is a different Zephyr's.
+
+    **Topdir-ness is `.west/config`, not the `.west` DIRECTORY.** An earlier
+    cut tested `(directory / ".west").is_dir()` and broke `tan doctor`'s
+    `venvProvenance` check outright: tan writes its OWN provenance record to
+    `<workspace>/.west/tan-workspace-sdk` (`bootstrap_cmd.
+    record_workspace_sdk`), so a workspace carrying that record but no west
+    config -- every workspace between `record_workspace_sdk` and a completed
+    `west init` -- has a `.west` directory that is not a topdir. It was judged
+    foreign, its venv was refused, and the check vanished from the report
+    instead of passing. `manifest_points_at` reads `.west/config`, so keying on
+    that same file is what makes the guard and its verdict agree.
+    """
+    if sdk_root is None or not (directory / ".west" / "config").is_file():
+        return True
+    return manifest_points_at(directory, Path(sdk_root))
+
+
+def _zephyr_base_venv(zephyr_base: Path, sdk_root: str | None) -> Path | None:
+    """Step 2 of `find_workspace_venv`: `zephyr_base`'s PARENT's `.venv`, but
+    only when it is both west-capable AND (when `sdk_root` resolved) its
+    workspace manifest is verifiably alp-sdk's -- port of the SAME guard
+    `_zephyr_base_workspace` already applies to the topdir search
+    (tan-cli#61), which this venv search lacked (tan-cli#292 consequence 2,
+    kept consistent with the tan-cli#301 fix one layer up: both now source
+    "which Zephyr/venv" from the RESOLVED workspace rather than a bare
+    `$ZEPHYR_BASE` read).
+
+    Without this, a stale exported `$ZEPHYR_BASE` naming an unrelated Zephyr
+    workspace shadowed the canonical `<sdk-parent>/.venv` (step 3) even when
+    the caller passed an explicit `--sdk-root` -- reproduced against the
+    published v0.5.0-rc2 asset on a clean host with no alp-sdk checkout
+    anywhere (tan-cli#278). `sdk_root` absent means there is nothing to
+    verify against, so the old unconditional accept stands, exactly as
+    `_zephyr_base_workspace` does.
+    """
+    workspace = zephyr_base.parent
+    candidate = workspace / ".venv"
+    if _resolve_layout(candidate) is None:
+        return None
+    if sdk_root is not None:
+        if not manifest_points_at(workspace, Path(sdk_root)):
+            return None
+    return candidate
+
+
+def venv_bin_dir(start: str, sdk_root: str | None) -> Path | None:
+    """The west-capable workspace venv's executable directory (`bin` or
+    `Scripts`, chosen directory-wins -- see `_resolve_layout`, tan-cli#291).
+    This is the handle a spawning command needs: the directory to look tool
+    names up in, and the directory to put on the child's PATH. `None` when no
+    west-capable venv resolves."""
+    venv = find_workspace_venv(start, sdk_root)
+    if venv is None:
+        return None
+    layout = _resolve_layout(venv)
+    assert layout is not None  # find_workspace_venv only returns what _resolve_layout accepted
+    return venv / layout.bin_dir
+
+
+def west_workspace_dir(start: str, sdk_root: Path | None) -> Path | None:
+    """Port of `workspace.rs::west_workspace_dir`: the directory holding
+    `.west/` that a `west alp-*` extension command -- and `tan flash`'s
+    spawned children (tan-cli#289/#61), and (tan-cli#307) `tan build`'s own
+    `west build` children -- must run from. Discovered only from a workspace
+    manifest, never the app dir alone. Checked in order: the project tree
+    upward (manifest-verified against `sdk_root` when one resolved --
+    tan-cli#307, see `_manifest_ok` below), `$ZEPHYR_BASE/..`
+    (manifest-verified the same way), then the SDK-derived layouts
+    (`<sdk-parent>` and the legacy `<sdk-parent>/zephyrproject`, never
+    manifest-checked -- they are already anchored on `sdk_root` itself, with
+    nothing independent left to verify). `None` when nothing resolves -- the
+    caller then keeps the old app-dir cwd, matching the oracle exactly.
+
+    **tan-cli#307: the upward walk is manifest-guarded too, not just
+    `$ZEPHYR_BASE`.** A project sitting inside a directory that ALSO holds an
+    unrelated `.west` (a second Zephyr checkout, a vendor SDK, an old
+    workspace) used to have that ancestor win here purely because it sits
+    closer to `start` than the workspace `tan bootstrap` actually created
+    elsewhere -- the same class of bug tan-cli#61/#292 already fixed for the
+    `$ZEPHYR_BASE` candidate, now closed for the plain upward walk too.
+
+    **Moved here from `tan.commands.west_forward_cmd` (tan-cli#289 review).**
+    `flash_cmd.py` needed the SAME resolver `west_forward_cmd.py` already
+    had -- a second copy risked the two disagreeing the moment one changed,
+    the exact class of bug `find_workspace_venv` (above) already exists to
+    avoid. `west_forward_cmd` keeps a `_west_workspace_dir` alias bound to
+    this function for its own call site and its existing tests; a THIRD,
+    partial copy still lives in `tan.commands.doctor_cmd._resolve_
+    west_workspace_dir` and is a follow-up, not retired here.
+    """
+
+    def is_workspace(d: Path) -> bool:
+        return (d / ".west").is_dir()
+
+    def manifest_ok(d: Path) -> bool:
+        """`sdk_root` absent means there is nothing to verify against, so
+        `d` is accepted unconditionally -- the same "nothing to check"
+        fallback every other candidate in this function already applies."""
+        if sdk_root is None:
+            return True
+        return manifest_points_at(d, sdk_root)
+
+    directory: Path | None = Path(start)
+    while directory is not None:
+        if is_workspace(directory) and manifest_ok(directory):
+            return directory
+        parent = directory.parent
+        directory = parent if parent != directory else None
+
+    zephyr_base = os.environ.get("ZEPHYR_BASE")
+    if zephyr_base:
+        found = _zephyr_base_workspace(Path(zephyr_base), sdk_root)
+        if found is not None:
+            return found
+
+    if sdk_root is not None:
+        parent = sdk_root.parent
+        for workspace in (parent, parent / "zephyrproject"):
+            if is_workspace(workspace):
+                return workspace
+
+    return None
+
+
+def _zephyr_base_workspace(zephyr_base: Path, sdk_root: Path | None) -> Path | None:
+    """Step 2 of `west_workspace_dir`: port of `workspace.rs::zephyr_base_workspace`.
+    `zephyr_base`'s PARENT, but only when it is both a west workspace AND (when
+    `sdk_root` resolved) its manifest is verifiably alp-sdk's -- a stock/unrelated
+    Zephyr checkout's parent is a west workspace by the bare `.west`-dir test
+    alone, yet carries no alp-sdk extension commands at all. `sdk_root` absent
+    means there is nothing to verify against, so the old unconditional accept
+    stands rather than refusing a workspace this call can't check.
+    """
+    workspace = zephyr_base.parent
+    if not (workspace / ".west").is_dir():
+        return None
+    if sdk_root is not None:
+        if not manifest_points_at(workspace, sdk_root):
+            return None
+    return workspace
+
+
+def tool_in_venv(bin_dir: Path, tool: str) -> str | None:
+    """Resolve `tool` INSIDE an already-located venv bin dir: returns its
+    absolute path when it is really a file there. `.exe` is appended when
+    `bin_dir` IS the Windows-layout dir (its name matches
+    `venv_layout(True).bin_dir`, i.e. `Scripts`) unless the caller already
+    spelled it -- keyed on the directory that won (tan-cli#291), not
+    `os.name`: `bin_dir` is whatever `_resolve_layout`'s directory-wins probe
+    picked, which can be `Scripts/` on a POSIX-reporting host or `bin/` on
+    Windows when that is the layout actually on disk. `None` means "this venv
+    does not provide that tool" -- the caller then keeps its PATH behaviour
+    instead of spawning a path that doesn't exist."""
+    name = tool
+    if bin_dir.name == venv_layout(True).bin_dir and not tool.lower().endswith(".exe"):
+        name = f"{tool}.exe"
+    candidate = bin_dir / name
+    return str(candidate) if candidate.is_file() else None
+
+
+def west_program(start: str, sdk_root: str | None) -> str:
+    """Resolve the `west` program to launch: the west-capable workspace
+    venv's `west` binary (see [`find_workspace_venv`]), falling back to
+    `"west"` on PATH when none resolve (CI, an activated venv, the contract
+    harness) -- behaving exactly as before in those environments. Mirrors
+    Rust's `west_program`."""
+    bin_dir = venv_bin_dir(start, sdk_root)
+    if bin_dir is None:
+        return "west"
+    return tool_in_venv(bin_dir, "west") or "west"
+
+
+def venv_python(start: str, sdk_root: str | None) -> str | None:
+    """The west-capable workspace venv's `python` (see
+    [`find_workspace_venv`]), mirroring Rust's `venv_python`. `None` when no
+    workspace venv resolves, or the one that does has no `python` binary --
+    the caller then keeps its own PATH-name fallback rather than spawning a
+    path that doesn't exist.
+
+    Forward-slashed: a caller substitutes this verbatim into `${PYTHON}`,
+    which lands in a `-DPython3_EXECUTABLE=<...>` CMake `-D` argument, and a
+    Windows backslash there is an escape character (alp-sdk#849).
+    """
+    bin_dir = venv_bin_dir(start, sdk_root)
+    if bin_dir is None:
+        return None
+    resolved = tool_in_venv(bin_dir, "python")
+    return resolved.replace("\\", "/") if resolved is not None else None
+
+
+def prepend_path(env: dict[str, str], directory: Path) -> dict[str, str]:
+    """Put `directory` at the FRONT of `env`'s `PATH`, mirroring Rust's
+    `prepend_path`. Returns a NEW dict -- `env` itself is never mutated, so a
+    caller holding onto the original (e.g. `dict(os.environ)`) is unaffected."""
+    existing = env.get("PATH", "")
+    joined = os.pathsep.join([str(directory), existing]) if existing else str(directory)
+    return {**env, "PATH": joined}
+
+
+def with_venv_on_path(env: dict[str, str], tool: str) -> dict[str, str]:
+    """When `tool` resolved to an absolute (venv) path, prepend its
+    directory to `env`'s `PATH` -- mirroring Rust's `with_venv_on_path`. The
+    `alp-*`/`west` program spawned at that path may itself shell a nested
+    `west`/`bitbake`, which resolves purely via PATH. A bare tool name (the
+    PATH fallback) is left untouched, matching the oracle's early return for
+    a non-absolute `tool`."""
+    bin_path = Path(tool)
+    if not bin_path.is_absolute():
+        return env
+    return prepend_path(env, bin_path.parent)

tan/core/west_patches.py

@@ -0,0 +1,143 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Pure decisions for `tan bootstrap`'s `zephyr/patches.yml` phase (tan-cli#1296).
+
+No IO here: `tan.commands.bootstrap_patches` owns every spawn and feeds the
+results through these functions, so the exit-code contract of alp-sdk's
+`scripts/verify_west_patches.py` lives in exactly one testable place.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+from dataclasses import dataclass
+
+#: The verifier's exit codes (its module docstring is the authority).
+VERIFY_APPLIED = 0
+#: Everything this workspace carries is patched, but a module `patches.yml`
+#: names is not checked out here, so it could not be inspected. Normal for a
+#: narrow workspace -- a warning, never a failure.
+VERIFY_UNCHECKED = 3
+#: Nothing could be inspected (no workspace, unreadable/empty `patches.yml`).
+VERIFY_UNRUNNABLE = 2
+
+#: Bounds for the output excerpt put into an issue message.
+_TAIL_LINES = 12
+_TAIL_CHARS = 1500
+
+
+def classify_verify(returncode: int | None) -> str:
+    """`"applied"` / `"unchecked"` / `"unapplied"` / `"unrunnable"` for one run
+    of the verifier, before OR after the per-module applies.
+
+    `"unrunnable"` is exit 2 ("nothing could be inspected": no workspace,
+    unreadable `patches.yml`) or `None` (the verifier never launched). It is NOT
+    "unapplied": the patch state is unknown, and saying "not applied" would send
+    the reader to the wrong place. Re-verifying after the applies matters
+    because `west patch apply` exiting 0 is not evidence it applied anything
+    (it exits 0 on a missing `patches.yml`, an empty patch list, and an
+    unresolvable `module:`).
+    """
+    if returncode == VERIFY_APPLIED:
+        return "applied"
+    if returncode == VERIFY_UNCHECKED:
+        return "unchecked"
+    if returncode == VERIFY_UNRUNNABLE or returncode is None:
+        return "unrunnable"
+    return "unapplied"
+
+
+def parse_unapplied(stdout: str) -> list[str]:
+    """Module names from `--list-unapplied` (one per line), de-duplicated in
+    first-seen order. Blank lines are ignored."""
+    seen: dict[str, None] = {}
+    for line in stdout.splitlines():
+        name = line.strip()
+        if name:
+            seen.setdefault(name, None)
+    return list(seen)
+
+
+def output_tail(text: str) -> str:
+    """The last few lines of child output, bounded, for an issue message --
+    the cause (`patch does not apply`, a `pykwalify` ImportError) is at the
+    end, so the head is what gets dropped."""
+    lines = [line.rstrip() for line in text.strip().splitlines() if line.strip()]
+    tail = "\n".join(lines[-_TAIL_LINES:])
+    return tail[-_TAIL_CHARS:]
+
+
+# ---------------------------------------------------------------------------
+# Workspace patch CHECK (tan-cli#1376): `tan doctor` / `tan build` ask the SAME
+# verifier "is `zephyr/patches.yml` applied" without applying anything.
+# ---------------------------------------------------------------------------
+
+#: One failing line of the verifier's stderr: `  ABSENT      <patch rel path>`.
+_FAILURE_LINE = re.compile(r"^\s+(ABSENT|DRIFTED|UNRESOLVED)\s+(\S+)\s*$")
+
+
+@dataclass(frozen=True)
+class UnappliedPatch:
+    """One patch the verifier reports as not applied. `verdict` is the
+    verifier's own word (`ABSENT`/`DRIFTED`/`UNRESOLVED`); `patch` is the path
+    under `zephyr/patches/` it prints (e.g. `hal_alif/0001-....patch`)."""
+
+    verdict: str
+    patch: str
+
+
+def parse_unapplied_patches(stderr: str) -> list[UnappliedPatch]:
+    """The patches named by the verifier's failure report, in report order."""
+    found: list[UnappliedPatch] = []
+    for line in stderr.splitlines():
+        m = _FAILURE_LINE.match(line)
+        if m is not None:
+            found.append(UnappliedPatch(m.group(1), m.group(2)))
+    return found
+
+
+def describe_unapplied(patches: list[UnappliedPatch], modules: list[str]) -> str:
+    """`hal_alif/0001-x.patch (ABSENT), ...` plus the modules to patch."""
+    names = ", ".join(f"{p.patch} ({p.verdict})" for p in patches) or "unnamed patches"
+    where = f" in module(s) {', '.join(modules)}" if modules else ""
+    return f"{names}{where}"
+
+
+def patch_fix_text(modules: list[str], workspace_dir: str) -> str:
+    """The exact remedy: `tan bootstrap` applies exactly the unapplied modules
+    (verify, `west patch --dst-module <m> apply`, re-verify). The per-module
+    west form is the manual equivalent; a bare `west patch apply` is NOT
+    offered because it re-applies already-patched modules and fails."""
+    manual = (
+        "; ".join(f"west patch --dst-module {m} apply" for m in modules)
+        or "west patch --dst-module <module> apply"
+    )
+    return f"run `tan bootstrap` (or, from {workspace_dir}: {manual})"
+
+
+def cache_key(patches_yml: bytes, heads: dict[str, str]) -> str:
+    """Stable digest of (`patches.yml` bytes, every workspace module's HEAD)."""
+    h = hashlib.sha256()
+    h.update(hashlib.sha256(patches_yml).digest())
+    for path in sorted(heads):
+        h.update(f"\0{path}\0{heads[path]}".encode())
+    return h.hexdigest()
+
+
+def zephyr_base_note(env_value: str | None, workspace_zephyr: str | None) -> str | None:
+    """Message when `$ZEPHYR_BASE` is set and names a different tree than the
+    resolved workspace's `zephyr/`; `None` otherwise. tan never honours the
+    override, so the user must hear it is being ignored."""
+    if not env_value or workspace_zephyr is None:
+        return None
+
+    def norm(p: str) -> str:
+        return os.path.normcase(os.path.realpath(p))
+
+    if norm(env_value) == norm(workspace_zephyr):
+        return None
+    return (
+        f"$ZEPHYR_BASE={env_value} is ignored: tan always builds with the resolved west "
+        f"workspace's zephyr ({workspace_zephyr}). To build against another tree, run "
+        "tan from that workspace or bootstrap it."
+    )

tan/core/west_workspace_refusal.py

@@ -0,0 +1,159 @@
+"""tan-cli#1429: refuse a `west build` slice up front when nothing will find a
+west workspace for it, instead of letting west fail with its own
+`west: unknown command "build"; do you need to run this inside a workspace?`.
+
+The shape the issue reproduced: `--sdk-root` names an alp-sdk checkout that is
+NOT the manifest project of any west workspace tan can see (a sibling git
+worktree such as `~/.cache/sdk-dev-2784`), and the app lives outside every
+workspace tree (`/tmp/...`). `tan.core.venv.west_workspace_dir` then returns
+`None`, so `execute_slices` keeps the slice's own cwd (tan-cli#307's fallback),
+and west -- finding no `.west` above that cwd -- never loads the `build`
+extension at all. The envelope carried only the generic `build.slice-failed`.
+
+**Keyed on what WEST will do, not on what tan resolved.** `workspace_dir is
+None` alone is not a failure: an app inside some workspace tree still builds,
+because west's own ancestor walk finds that `.west` without tan's manifest
+guard (the "move it under the workspace and it builds" observation in the
+issue), and an ambient `ZEPHYR_BASE` gives west a second place to look. The
+refusal therefore fires only when neither the spawn cwd nor the spawn env's
+`ZEPHYR_BASE` has a `.west` on any ancestor -- the case where west cannot
+succeed. Anything less certain is left to west exactly as before.
+
+**Reusing a workspace is deliberately not attempted.** tan has no record that
+maps an SDK checkout to a workspace (`.west/tan-workspace-sdk` maps the other
+way and sits inside the workspace), so picking one would be a guess -- the
+thing tan-cli#307/#61/#292's manifest guard exists to refuse.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from tan.core.bootstrap import get_manifest_path
+
+#: The marker `build_cmd._workspace_unresolved_issues` matches to promote the
+#: refused slice's reason into the coded `build.workspace-unresolved` issue,
+#: the same idiom as `tan.core.plan_exec.CROSS_DRIVE_MSG`.
+WORKSPACE_UNRESOLVED_MSG = "no west workspace resolves for this build"
+
+
+@dataclass(frozen=True)
+class WorkspaceRefusal:
+    """`message` carries absolute paths for this run's stdout and envelope;
+    `manifest_message` is the short form `system-manifest.yaml` keeps, without
+    the host's directory layout (same split as `CrossDriveRefusal`)."""
+
+    message: str
+    manifest_message: str
+
+
+def west_ancestor(start: Path) -> Path | None:
+    """The nearest directory at or above `start` holding a `.west` directory,
+    or `None`. Mirrors west's own `west_topdir` walk: unguarded, because west
+    does not check which manifest a `.west` belongs to. `start` is resolved
+    (symlinks followed) because west walks from `os.getcwd()`, which POSIX
+    reports as the real path."""
+    start = Path(start).resolve()
+    for directory in (start, *start.parents):
+        if (directory / ".west").is_dir():
+            return directory
+    return None
+
+
+def workspace_unresolved_refusal(
+    workspace_dir: Path | None,
+    args: list[str],
+    spawn_cwd: Path,
+    zephyr_base: str | None,
+    sdk_root: Path | None,
+) -> WorkspaceRefusal | None:
+    """`None` unless this `west build` slice cannot find a workspace.
+
+    `zephyr_base` is the value the SPAWN's env carries, not `os.environ`'s.
+    `sdk_root` absent is never refused: without it there is no checkout to
+    name, and no `tan bootstrap --sdk-root` remedy to give.
+    """
+    if workspace_dir is not None or sdk_root is None or not args or args[0] != "build":
+        return None
+    if west_ancestor(spawn_cwd) is not None:
+        return None
+    # A relative ZEPHYR_BASE is resolved by west against the spawn cwd.
+    if zephyr_base and west_ancestor(Path(spawn_cwd) / zephyr_base) is not None:
+        return None
+    message = (
+        f"{WORKSPACE_UNRESOLVED_MSG} -- `west build` would run from `{spawn_cwd}`, "
+        f"which has no `.west` on any ancestor; {_unresolved_facts(zephyr_base, sdk_root)}. "
+        f"west would stop with `unknown command \"build\"`. {_remedies(sdk_root)}"
+    )
+    return WorkspaceRefusal(message, f"{WORKSPACE_UNRESOLVED_MSG} (run `tan bootstrap`)")
+
+
+def _unresolved_facts(zephyr_base: str | None, sdk_root: Path) -> str:
+    zephyr_base_fact = (
+        f"ZEPHYR_BASE `{zephyr_base}` has no `.west` above it either"
+        if zephyr_base
+        else "ZEPHYR_BASE is unset"
+    )
+    sdk_parent = sdk_root.parent
+    return (
+        f"{zephyr_base_fact}; and neither `{sdk_parent}` nor "
+        f"`{sdk_parent / 'zephyrproject'}` (next to the SDK root `{sdk_root}`) holds a `.west`"
+    )
+
+
+def _remedies(sdk_root: Path) -> str:
+    return (
+        f"Run `tan bootstrap --sdk-root {sdk_root}` to create a workspace for this "
+        f"checkout, or set ZEPHYR_BASE to an existing workspace's `zephyr/` -- that "
+        f"builds against that workspace's Zephyr revision and patches, which need "
+        f"not match this checkout's `west.yml`."
+    )
+
+
+def manifest_project(topdir: Path) -> Path | None:
+    """The manifest project `<topdir>/.west/config` names, or `None` when the
+    config is missing or names none."""
+    try:
+        config = (topdir / ".west" / "config").read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    rel = get_manifest_path(config)
+    return topdir / rel.strip() if rel else None
+
+
+def unresolved_workspace_verdict(
+    start: Path, zephyr_base: str | None, sdk_root: Path
+) -> tuple[str, str]:
+    """tan-cli#1432: `tan doctor`'s `workspace` verdict when tan resolved no
+    workspace for `sdk_root`, as `(status, detail)`, agreeing with what
+    `tan build` will then do from `start`.
+
+    `warn` when west's own unguarded walk still lands on a `.west` -- above
+    `start` (west uses it; the build succeeds against THAT workspace's Zephyr),
+    or above `zephyr_base` (west's fallback, which is not verified to reach
+    the `build` extension, hence "may"). `fail` otherwise, naming the same
+    facts and remedies as `build.workspace-unresolved`.
+    """
+    sdk_root = Path(sdk_root)
+    found = west_ancestor(start)
+    lead = f"west will use `{found}`, a `.west` above `{Path(start).absolute()}`"
+    if found is None and zephyr_base:
+        # As `workspace_unresolved_refusal`: west resolves a relative
+        # ZEPHYR_BASE against the cwd it runs in, which is `start`.
+        found = west_ancestor(Path(start) / zephyr_base)
+        lead = f"west may fall back to `{found}`, a `.west` above ZEPHYR_BASE `{zephyr_base}`"
+    if found is None:
+        return "fail", (
+            f"no Zephyr workspace for the SDK root `{sdk_root}`: `{Path(start).absolute()}` has "
+            f"no `.west` on any ancestor; {_unresolved_facts(zephyr_base, sdk_root)}, so "
+            f"a `west build` slice is refused as `build.workspace-unresolved`. {_remedies(sdk_root)}"
+        )
+    names = manifest_project(found)
+    manifest = f"names `{names}` as its manifest" if names else "names no manifest project"
+    return "warn", (
+        f"no workspace has the SDK root `{sdk_root}` as its manifest, but {lead}, which "
+        f"{manifest} -- a build uses that workspace's Zephyr revision and patches, which "
+        f"need not match this checkout's `west.yml`. Run `tan bootstrap --sdk-root "
+        f"{sdk_root}` for a workspace of its own."
+    )