@salesforce/afv-skills 1.59.0 → 1.61.0

package/skills/agentforce-d360-analyze/scripts/tests/test_default_target_org.py

@@ -0,0 +1,432 @@
+"""``--org`` is optional: entry points fall back to the sf CLI default org.
+
+Covers ``dc.default_target_org`` (mocked at the subprocess boundary) and the
+three user entry points that take ``--org`` — ``discover_sessions``,
+``fetch_dc`` and ``resolve_session`` — with and without an explicit alias.
+
+``default_target_org`` runs the show-access-token capability preflight
+(``sf org auth show-access-token --help``) before ``sf config get``, so every
+fake here routes by argv: the preflight gets real-shaped USAGE help (or a
+"command missing" answer), and ``sf config get`` gets the canned payload.
+"""
+from __future__ import annotations
+
+import io
+import json
+import subprocess
+import unittest
+from types import SimpleNamespace
+from unittest import mock
+
+from . import _bootstrap  # noqa: F401  — sys.path setup
+
+import dc  # type: ignore
+import discover_sessions  # type: ignore
+import fetch_dc  # type: ignore
+import resolve_session  # type: ignore
+from .fixtures.synthetic_session import IDS  # type: ignore
+from .test_fetch_dc_main import _MainHarness as _FetchHarness  # type: ignore
+
+_CONFIG_ARGV = ["sf", "config", "get", "target-org", "--json"]
+_PREFLIGHT_ARGV = ["sf", "org", "auth", "show-access-token", "--help"]
+# Shape of real ``--help`` output (sf CLI 2.150.6).
+_REAL_HELP = "USAGE\n  $ sf org auth show-access-token -o <value> [--json]\n"
+_UPGRADE_MSG = "Upgrade/reinstall Salesforce CLI"
+_NO_ORG_MSG = "no --org given and no default target org set"
+
+
+def _config_payload(value: str | None) -> str:
+    entry = {"name": "target-org", "location": "Local", "success": True}
+    if value is not None:
+        entry["value"] = value
+    return json.dumps({"status": 0, "result": [entry], "warnings": []})
+
+
+def _cp(stdout: str) -> SimpleNamespace:
+    return SimpleNamespace(returncode=0, stdout=stdout, stderr="")
+
+
+def _sf_run(value: str | None = None, *, config=None, preflight: str = "ok",
+            calls: list | None = None):
+    """subprocess.run stand-in routing by argv.
+
+    ``preflight``: "ok" → real USAGE help; "nonzero" → the CLI rejects the
+    unknown command (CalledProcessError); "no-usage" → exit 0 without the
+    USAGE line (an old CLI echoing a not-found notice).
+    ``config``: a callable/exception overriding the ``sf config get`` answer;
+    default is the canned payload for ``value``. ``calls`` records argv.
+    """
+    def fake_run(argv, **kwargs):
+        if calls is not None:
+            calls.append((argv, kwargs))
+        if argv == _PREFLIGHT_ARGV:
+            if preflight == "ok":
+                return _cp(_REAL_HELP)
+            if preflight == "nonzero":
+                raise subprocess.CalledProcessError(
+                    returncode=127, cmd=argv,
+                    stderr="Warning: show-access-token is not a sf command.",
+                )
+            if preflight == "no-usage":
+                return _cp("Command org:auth:show-access-token not found.")
+            raise AssertionError(f"bad preflight mode {preflight!r}")
+        if argv == _CONFIG_ARGV:
+            if isinstance(config, BaseException):
+                raise config
+            if callable(config):
+                return config(argv, **kwargs)
+            return _cp(_config_payload(value))
+        raise AssertionError(f"unexpected argv: {argv}")
+    return fake_run
+
+
+def _sf_config_run(value: str | None):
+    """A CLI with a working preflight whose default org is ``value``."""
+    return _sf_run(value)
+
+
+# A CLI lacking show-access-token, in both shapes the preflight rejects.
+_MISSING_CMD_MODES = ("nonzero", "no-usage")
+
+
+class _FreshPreflight(unittest.TestCase):
+    """The preflight caches success process-wide; isolate every test."""
+
+    def setUp(self):
+        dc._show_access_token_capability_ok = False
+        self.addCleanup(setattr, dc, "_show_access_token_capability_ok", False)
+
+
+# -----------------------------------------------------------------------------
+# dc.default_target_org
+# -----------------------------------------------------------------------------
+
+
+class DefaultTargetOrgTests(_FreshPreflight):
+
+    def test_returns_configured_value_with_timeout(self):
+        calls: list = []
+        with mock.patch.object(
+            dc.subprocess, "run", side_effect=_sf_run("my-default", calls=calls),
+        ):
+            self.assertEqual(dc.default_target_org(), "my-default")
+        self.assertEqual([a for a, _ in calls], [_PREFLIGHT_ARGV, _CONFIG_ARGV])
+        config_kwargs = calls[1][1]
+        self.assertTrue(config_kwargs.get("timeout"))
+        self.assertTrue(config_kwargs.get("check"))
+
+    def test_missing_show_access_token_fails_before_config_get(self):
+        for mode in _MISSING_CMD_MODES:
+            with self.subTest(preflight=mode):
+                dc._show_access_token_capability_ok = False
+                calls: list = []
+                with mock.patch.object(
+                    dc.subprocess, "run",
+                    side_effect=_sf_run(None, preflight=mode, calls=calls),
+                ):
+                    with self.assertRaises(SystemExit) as ctx:
+                        dc.default_target_org()
+                msg = str(ctx.exception)
+                self.assertIn("sf org auth show-access-token", msg)
+                self.assertIn(_UPGRADE_MSG, msg)
+                self.assertNotIn(_NO_ORG_MSG, msg)
+                self.assertEqual([a for a, _ in calls], [_PREFLIGHT_ARGV])
+                self.assertFalse(dc._show_access_token_capability_ok)
+
+    def test_preflight_cached_across_default_org_and_resolve_org(self):
+        calls: list = []
+        base = _sf_run("my-default", calls=calls)
+
+        def fake_run(argv, **kwargs):
+            if argv[:3] == ["sf", "org", "display"]:
+                calls.append((argv, kwargs))
+                return _cp(json.dumps({"result": {"instanceUrl": "https://x"}}))
+            if argv[:4] == ["sf", "org", "auth", "show-access-token"] and "--help" not in argv:
+                calls.append((argv, kwargs))
+                return _cp(json.dumps({"result": {"accessToken": "TOK"}}))
+            return base(argv, **kwargs)
+
+        with mock.patch.object(dc.subprocess, "run", side_effect=fake_run):
+            org = dc.default_target_org()
+            self.assertEqual(dc.default_target_org(), org)
+            self.assertEqual(dc.resolve_org(org), ("https://x", "TOK"))
+        argvs = [a for a, _ in calls]
+        self.assertEqual(argvs[0], _PREFLIGHT_ARGV)
+        self.assertEqual(argvs.count(_PREFLIGHT_ARGV), 1, argvs)
+
+    def test_empty_result_raises_clear_error(self):
+        payloads = [
+            _config_payload(None),                      # key unset
+            _config_payload(""),                        # blank value
+            json.dumps({"status": 0, "result": []}),    # no entries
+            json.dumps({"status": 0}),                  # no result at all
+        ]
+        for payload in payloads:
+            with self.subTest(payload=payload):
+                with mock.patch.object(
+                    dc.subprocess, "run",
+                    side_effect=_sf_run(config=lambda *a, _p=payload, **k: _cp(_p)),
+                ):
+                    with self.assertRaises(SystemExit) as ctx:
+                        dc.default_target_org()
+                msg = str(ctx.exception)
+                self.assertIn("no --org given and no default target org set", msg)
+                self.assertIn("sf config set target-org <alias>", msg)
+
+    def test_sf_failure_raises_redacted_error(self):
+        err = subprocess.CalledProcessError(
+            returncode=1, cmd=_CONFIG_ARGV,
+            stderr='boom Authorization: Bearer 00DSECRET!tok "accessToken": "00DLEAK"',
+        )
+        with mock.patch.object(dc.subprocess, "run", side_effect=_sf_run(config=err)):
+            with self.assertRaises(SystemExit) as ctx:
+                dc.default_target_org()
+        msg = str(ctx.exception)
+        self.assertIn("no --org given and no default target org set", msg)
+        self.assertIn("sf config get target-org", msg)
+        self.assertIn("boom", msg)
+        self.assertNotIn("00DSECRET", msg)
+        self.assertNotIn("00DLEAK", msg)
+        self.assertIn("<redacted>", msg)
+
+    def test_sf_missing_raises_clear_error(self):
+        # No sf at all: the preflight is the first call and reports it.
+        calls: list = []
+
+        def fake_run(argv, **kwargs):
+            calls.append(argv)
+            raise FileNotFoundError("sf")
+
+        with mock.patch.object(dc.subprocess, "run", side_effect=fake_run):
+            with self.assertRaises(SystemExit) as ctx:
+                dc.default_target_org()
+        self.assertIn("sf CLI not found on PATH", str(ctx.exception))
+        self.assertEqual(calls, [_PREFLIGHT_ARGV])
+
+    def test_sf_vanishes_before_config_get_raises_clear_error(self):
+        with mock.patch.object(
+            dc.subprocess, "run", side_effect=_sf_run(config=FileNotFoundError("sf")),
+        ):
+            with self.assertRaises(SystemExit) as ctx:
+                dc.default_target_org()
+        self.assertIn("sf CLI not found on PATH", str(ctx.exception))
+
+    def test_timeout_raises_clear_error(self):
+        with mock.patch.object(
+            dc.subprocess, "run",
+            side_effect=_sf_run(
+                config=subprocess.TimeoutExpired(cmd=_CONFIG_ARGV, timeout=30),
+            ),
+        ):
+            with self.assertRaises(SystemExit) as ctx:
+                dc.default_target_org()
+        msg = str(ctx.exception)
+        self.assertIn("`sf config get target-org` timed out", msg)
+        self.assertIn(_NO_ORG_MSG, msg)
+
+    def test_non_json_output_raises_clear_error(self):
+        with mock.patch.object(
+            dc.subprocess, "run",
+            side_effect=_sf_run(config=lambda *a, **k: _cp("Warning: not json")),
+        ):
+            with self.assertRaises(SystemExit) as ctx:
+                dc.default_target_org()
+        self.assertIn("non-JSON", str(ctx.exception))
+
+
+# -----------------------------------------------------------------------------
+# discover_sessions
+# -----------------------------------------------------------------------------
+
+
+class DiscoverSessionsOrgDefaultTests(_FreshPreflight):
+
+    def _run(self, *argv: str, run_side_effect):
+        with mock.patch.object(discover_sessions.sys, "argv",
+                               ["discover_sessions.py", *argv]):
+            with mock.patch.object(dc.subprocess, "run",
+                                   side_effect=run_side_effect) as run:
+                with mock.patch.object(
+                    discover_sessions, "resolve_org",
+                    return_value=("https://x", "T"),
+                ) as resolve:
+                    with mock.patch.object(discover_sessions, "post", return_value=[]):
+                        with mock.patch("sys.stdout", io.StringIO()) as out:
+                            rc = discover_sessions.main()
+        return rc, run, resolve, out.getvalue()
+
+    def test_no_org_uses_default_target_org(self):
+        rc, run, resolve, out = self._run(
+            "--grep", "refund", "--limit", "5",
+            run_side_effect=_sf_config_run("def-org"),
+        )
+        self.assertEqual(rc, 2)  # zero rows
+        self.assertEqual(
+            [c.args[0] for c in run.call_args_list], [_PREFLIGHT_ARGV, _CONFIG_ARGV],
+        )
+        resolve.assert_called_once_with("def-org")
+        self.assertIn("def-org", out)
+
+    def test_explicit_org_wins_and_helper_not_called(self):
+        with mock.patch.object(discover_sessions, "default_target_org") as helper:
+            rc, run, resolve, _ = self._run(
+                "--org", "explicit-org",
+                run_side_effect=AssertionError("sf must not be called"),
+            )
+        self.assertEqual(rc, 2)
+        helper.assert_not_called()
+        run.assert_not_called()
+        resolve.assert_called_once_with("explicit-org")
+
+    def test_no_org_and_no_default_exits_with_clear_message(self):
+        with self.assertRaises(SystemExit) as ctx:
+            self._run(run_side_effect=_sf_config_run(None))
+        self.assertIn("no --org given and no default target org set", str(ctx.exception))
+
+    def test_no_org_on_cli_lacking_show_access_token_reports_upgrade(self):
+        # No default org AND no show-access-token: the upgrade message wins,
+        # `sf config get` is never run, and no org resolution is attempted.
+        for mode in _MISSING_CMD_MODES:
+            with self.subTest(preflight=mode):
+                dc._show_access_token_capability_ok = False
+                calls: list = []
+                with mock.patch.object(discover_sessions.sys, "argv",
+                                       ["discover_sessions.py"]):
+                    with mock.patch.object(
+                        dc.subprocess, "run",
+                        side_effect=_sf_run(None, preflight=mode, calls=calls),
+                    ):
+                        with mock.patch.object(discover_sessions, "resolve_org") as resolve:
+                            with self.assertRaises(SystemExit) as ctx:
+                                discover_sessions.main()
+                msg = str(ctx.exception)
+                self.assertIn(_UPGRADE_MSG, msg)
+                self.assertNotIn(_NO_ORG_MSG, msg)
+                self.assertNotIn(_CONFIG_ARGV, [a for a, _ in calls])
+                self.assertEqual([a for a, _ in calls], [_PREFLIGHT_ARGV])
+                resolve.assert_not_called()
+
+
+# -----------------------------------------------------------------------------
+# fetch_dc
+# -----------------------------------------------------------------------------
+
+
+class FetchDcOrgDefaultTests(_FreshPreflight):
+
+    _BASE = ["fetch_dc.py", "--session", IDS.SID, "--no-assemble", "--no-render"]
+
+    def test_no_org_uses_default_target_org(self):
+        captured = {}
+
+        def capture(ctx):
+            captured.update(ctx)
+            ctx["org_id_15"] = IDS.ORG_ID_15
+            ctx["agent_api_name"] = IDS.AGENT_API
+            ctx["agent_version"] = IDS.AGENT_VERSION
+
+        with _FetchHarness():
+            with mock.patch.object(fetch_dc, "_run_waterfall", side_effect=capture):
+                with mock.patch.object(dc.subprocess, "run",
+                                       side_effect=_sf_config_run("def-org")) as run:
+                    with mock.patch.object(fetch_dc.sys, "argv", list(self._BASE)):
+                        rc = fetch_dc.main()
+                fetch_dc.preflight_dc_access.assert_called_once_with(IDS.SID, "def-org")
+        self.assertEqual(rc, 0)
+        self.assertEqual(
+            [c.args[0] for c in run.call_args_list], [_PREFLIGHT_ARGV, _CONFIG_ARGV],
+        )
+        self.assertEqual(captured["org_alias"], "def-org")
+
+    def test_explicit_org_wins_and_helper_not_called(self):
+        with _FetchHarness():
+            with mock.patch.object(fetch_dc, "default_target_org") as helper:
+                with mock.patch.object(
+                    fetch_dc.sys, "argv", [*self._BASE, "--org", "explicit-org"],
+                ):
+                    rc = fetch_dc.main()
+                fetch_dc.preflight_dc_access.assert_called_once_with(
+                    IDS.SID, "explicit-org",
+                )
+        self.assertEqual(rc, 0)
+        helper.assert_not_called()
+
+    def test_no_default_routes_through_dc_access_denied(self):
+        with _FetchHarness(is_tty=False):
+            with mock.patch.object(dc.subprocess, "run",
+                                   side_effect=_sf_config_run(None)):
+                with mock.patch.object(fetch_dc.sys, "argv", list(self._BASE)):
+                    with mock.patch("sys.stdout", io.StringIO()) as out:
+                        rc = fetch_dc.main()
+            fetch_dc.preflight_dc_access.assert_not_called()
+        self.assertEqual(rc, fetch_dc.EXIT_DC_ACCESS_DENIED)
+        payload = json.loads(out.getvalue().strip().splitlines()[-1])
+        self.assertEqual(payload["status"], "DC_ACCESS_DENIED")
+        self.assertEqual(payload["reason"], "no_org")
+        self.assertIn("no default target org set", payload["detail"])
+
+    def test_no_org_on_cli_lacking_show_access_token_reports_upgrade(self):
+        # Headless contract is unchanged (DC_ACCESS_DENIED, exit 10, same
+        # reason code the explicit-org preflight failure already uses), but the
+        # detail is the upgrade message and `sf config get` never runs.
+        for mode in _MISSING_CMD_MODES:
+            with self.subTest(preflight=mode):
+                dc._show_access_token_capability_ok = False
+                calls: list = []
+                with _FetchHarness(is_tty=False):
+                    with mock.patch.object(
+                        dc.subprocess, "run",
+                        side_effect=_sf_run(None, preflight=mode, calls=calls),
+                    ):
+                        with mock.patch.object(fetch_dc.sys, "argv", list(self._BASE)):
+                            with mock.patch("sys.stdout", io.StringIO()) as out:
+                                rc = fetch_dc.main()
+                    fetch_dc.preflight_dc_access.assert_not_called()
+                self.assertEqual(rc, fetch_dc.EXIT_DC_ACCESS_DENIED)
+                payload = json.loads(out.getvalue().strip().splitlines()[-1])
+                self.assertEqual(payload["status"], "DC_ACCESS_DENIED")
+                self.assertIn(_UPGRADE_MSG, payload["detail"])
+                self.assertNotIn(_NO_ORG_MSG, payload["detail"])
+                self.assertEqual([a for a, _ in calls], [_PREFLIGHT_ARGV])
+
+
+# -----------------------------------------------------------------------------
+# resolve_session (live lookup only needs an org on a disk miss)
+# -----------------------------------------------------------------------------
+
+
+class ResolveSessionOrgDefaultTests(unittest.TestCase):
+
+    _MSG = "0Mw000000000000"
+
+    def _run(self, *argv: str):
+        with mock.patch.object(resolve_session.sys, "argv",
+                               ["resolve_session.py", "--id", self._MSG, *argv]):
+            with mock.patch.object(resolve_session, "resolve_from_disk", return_value=None):
+                with mock.patch.object(
+                    resolve_session, "resolve", return_value="resolved-uuid",
+                ) as resolve:
+                    with mock.patch("sys.stdout", io.StringIO()) as out:
+                        rc = resolve_session.main()
+        return rc, resolve, out.getvalue()
+
+    def test_disk_miss_without_org_uses_default(self):
+        with mock.patch.object(
+            resolve_session, "default_target_org", return_value="def-org",
+        ) as helper:
+            rc, resolve, out = self._run()
+        self.assertEqual(rc, 0)
+        helper.assert_called_once_with()
+        resolve.assert_called_once_with(self._MSG, org="def-org")
+        self.assertIn("resolved-uuid", out)
+
+    def test_explicit_org_wins_and_helper_not_called(self):
+        with mock.patch.object(resolve_session, "default_target_org") as helper:
+            rc, resolve, _ = self._run("--org", "explicit-org")
+        self.assertEqual(rc, 0)
+        helper.assert_not_called()
+        resolve.assert_called_once_with(self._MSG, org="explicit-org")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/agentforce-d360-analyze/scripts/tests/test_discover_sessions.py

@@ -399,7 +399,7 @@ class RenderPickerTests(unittest.TestCase):
 class MainTests(unittest.TestCase):
 
     def _argv(self, *extra: str) -> list[str]:
-        # `--org` is required; everything else has a default or is optional.
+        # Explicit `--org` so no test shells out for the sf default target org.
         return ["discover_sessions.py", "--org", "my-org", *extra]
 
     def test_main_exit_zero_when_rows_returned(self):

package/skills/agentforce-d360-analyze/scripts/tests/test_resolve_session_main.py

@@ -5,7 +5,7 @@ Argparse-driven — exercises every branch:
 - --disk-only hit / miss
 - live path with --org
 - disk-first fallback when no --org
-- not-found-no-org error
+- not-found-no-org error (no sf default target org either)
 """
 from __future__ import annotations
 
@@ -135,14 +135,20 @@ class DiskFirstFallbackTests(unittest.TestCase):
         self.assertIn(IDS.SID, h.stdout.getvalue())
 
     def test_disk_miss_no_org_returns_two_with_hint(self):
-        # No --org AND disk miss → exit 2 + helpful stderr.
+        # No --org, disk miss, AND no sf default target org → exit 2 +
+        # helpful stderr.
         with _MainHarness(
             argv=["--id", "0Mw000000000000"],
         ) as h:
-            rc = resolve_session.main()
+            with mock.patch.object(
+                resolve_session, "default_target_org",
+                side_effect=SystemExit("no --org given and no default target org set"),
+            ):
+                rc = resolve_session.main()
         self.assertEqual(rc, 2)
         self.assertIn("not found on disk", h.stderr.getvalue())
         self.assertIn("--org <alias> required", h.stderr.getvalue())
+        self.assertIn("no default target org set", h.stderr.getvalue())
 
 
 if __name__ == "__main__":

package/skills/agentforce-d360-analyze/scripts/tests/test_skill_md_prefix_block.py

@@ -0,0 +1,176 @@
+"""Run SKILL.md's "## Resolving the script prefix" bash block under bash and zsh.
+
+The block is the contract the agent executes verbatim, so these tests extract
+it from SKILL.md (no copy to drift) and run it under ``env -i`` against fake
+install layouts, then call ``python3 "$prefix/fetch_dc.py"`` the way every
+later SKILL.md invocation does. The stub fetch_dc.py records its own path so
+the test can assert which copy actually ran.
+
+Scenarios: scripts at the candidate root (shipped layout), scripts only under
+``<candidate>/artifacts/scripts/`` (ADK eval staging layout) via an exported
+SKILL_ROOT and via the install-root probe, root preferred over its own
+artifacts/, candidate order preserved, and nothing found (guard message).
+"""
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+_SKILL_NAME = "agentforce-d360-analyze"
+
+
+def _find_skill_md() -> Path:
+    # contributed-skills: <skill>/scripts/tests/ -> <skill>/SKILL.md
+    # outputs/unified-sors: <skill>/artifacts/scripts/tests/ -> <skill>/SKILL.md
+    for parent in Path(__file__).resolve().parents:
+        candidate = parent / "SKILL.md"
+        if candidate.is_file():
+            return candidate
+    raise FileNotFoundError("SKILL.md not found above " + __file__)
+
+
+def _extract_prefix_block(skill_md: str) -> str:
+    section = skill_md.split("## Resolving the script prefix", 1)[1]
+    match = re.search(r"```bash\n(.*?)\n```", section, re.S)
+    if match is None:
+        raise ValueError("no ```bash block under '## Resolving the script prefix'")
+    return match.group(1) + "\n"
+
+
+_FETCH_STUB = """\
+import json, os, sys
+with open({record!r}, "a") as fh:
+    fh.write(json.dumps({{"path": os.path.realpath(__file__),
+                         "argv": sys.argv[1:]}}) + "\\n")
+"""
+
+# Appended after the extracted block: report what it resolved, then invoke the
+# entry script exactly as the rest of SKILL.md does.
+_EPILOGUE = """
+printf 'SKILL_ROOT=%s\\nprefix=%s\\n' "$SKILL_ROOT" "$prefix"
+python3 "$prefix/fetch_dc.py" --session probe-test
+"""
+
+
+class PrefixBlockTest(unittest.TestCase):
+    SHELLS = [s for s in ("bash", "zsh") if shutil.which(s)]
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.block = _extract_prefix_block(_find_skill_md().read_text())
+
+    def setUp(self) -> None:
+        self.tmp = Path(tempfile.mkdtemp(prefix="d360-prefix-test-"))
+        self.addCleanup(shutil.rmtree, self.tmp, True)
+        self.record = self.tmp / "calls.jsonl"
+        self.home = self.tmp / "home"
+        self.home.mkdir()
+        self.bin = self.tmp / "bin"
+        self.bin.mkdir()
+        (self.bin / "python3").symlink_to(sys.executable)
+        self.script = self.tmp / "block.sh"
+        self.script.write_text(self.block + _EPILOGUE)
+
+    # -- helpers ---------------------------------------------------------
+
+    def _make_scripts(self, root: Path) -> Path:
+        scripts = root / "scripts"
+        scripts.mkdir(parents=True)
+        (scripts / "fetch_dc.py").write_text(_FETCH_STUB.format(record=str(self.record)))
+        return scripts
+
+    def _run(self, shell: str, skill_root: str | None):
+        if self.record.exists():
+            self.record.unlink()
+        env = {"PATH": f"{self.bin}:/usr/bin:/bin", "HOME": str(self.home)}
+        if skill_root is not None:
+            env["SKILL_ROOT"] = skill_root
+        cmd = ["env", "-i", *(f"{k}={v}" for k, v in env.items()),
+               shell, str(self.script)]
+        proc = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=60, cwd=self.tmp,
+        )
+        calls = []
+        if self.record.exists():
+            calls = [json.loads(l) for l in self.record.read_text().splitlines()]
+        return proc, calls
+
+    def _assert_resolved(self, proc, calls, root: Path) -> None:
+        self.assertEqual(proc.returncode, 0, proc.stderr)
+        self.assertIn(f"SKILL_ROOT={root}\n", proc.stdout)
+        self.assertIn(f"prefix={root}/scripts\n", proc.stdout)
+        self.assertEqual(len(calls), 1, calls)
+        self.assertEqual(
+            calls[0]["path"], str((root / "scripts" / "fetch_dc.py").resolve())
+        )
+        self.assertEqual(calls[0]["argv"], ["--session", "probe-test"])
+
+    # -- scenarios -------------------------------------------------------
+
+    def test_shells_available(self) -> None:
+        self.assertIn("bash", self.SHELLS)
+
+    def test_a_shipped_layout_exported_root(self) -> None:
+        root = self.tmp / "skill"
+        self._make_scripts(root)
+        for shell in self.SHELLS:
+            with self.subTest(shell=shell):
+                self._assert_resolved(*self._run(shell, str(root)), root)
+
+    def test_b_scripts_only_under_artifacts_of_exported_root(self) -> None:
+        staged = self.tmp / "staged" / _SKILL_NAME
+        self._make_scripts(staged / "artifacts")
+        (staged / "SKILL.md").write_text("# staged\n")
+        for shell in self.SHELLS:
+            with self.subTest(shell=shell):
+                self._assert_resolved(
+                    *self._run(shell, str(staged)), staged / "artifacts"
+                )
+
+    def test_c_artifacts_found_via_install_root_probe(self) -> None:
+        staged = self.home / ".claude" / "skills" / _SKILL_NAME
+        self._make_scripts(staged / "artifacts")
+        for shell in self.SHELLS:
+            with self.subTest(shell=shell):
+                self._assert_resolved(
+                    *self._run(shell, None), staged / "artifacts"
+                )
+
+    def test_d_candidate_root_preferred_over_its_artifacts(self) -> None:
+        root = self.tmp / "skill"
+        self._make_scripts(root)
+        self._make_scripts(root / "artifacts")
+        for shell in self.SHELLS:
+            with self.subTest(shell=shell):
+                self._assert_resolved(*self._run(shell, str(root)), root)
+
+    def test_e_earlier_candidate_artifacts_beats_later_candidate_root(self) -> None:
+        staged = self.tmp / "staged" / _SKILL_NAME
+        self._make_scripts(staged / "artifacts")
+        self._make_scripts(self.home / ".claude" / "skills" / _SKILL_NAME)
+        for shell in self.SHELLS:
+            with self.subTest(shell=shell):
+                self._assert_resolved(
+                    *self._run(shell, str(staged)), staged / "artifacts"
+                )
+
+    def test_f_no_scripts_anywhere_reports_guard_message(self) -> None:
+        empty = self.tmp / "empty" / _SKILL_NAME
+        (empty / "artifacts").mkdir(parents=True)
+        for shell in self.SHELLS:
+            with self.subTest(shell=shell):
+                proc, calls = self._run(shell, str(empty))
+                self.assertEqual(proc.returncode, 1)
+                self.assertIn(f"{_SKILL_NAME}: scripts not found", proc.stderr)
+                self.assertNotIn("prefix=", proc.stdout)
+                self.assertEqual(calls, [])
+
+
+if __name__ == "__main__":
+    unittest.main()